@awebai/oats 0.22.17 → 0.23.0

package/docs/design/2026-09-13-knowledge-implementation.md

@@ -0,0 +1,127 @@
+# Knowledge implementation plan
+
+Status: implementation authorized by the human on 2026-09-13, including main
+pushes and framework/OKF releases. Execute bounded batches with adversarial
+review after approximately every two new commits, including fix commits.
+The [location contract](2026-09-13-knowledge-location-contract.md) and its
+[reference-theory boundary](../../agents/oats-expert/soul/knowledge/decisions/provider-neutral-knowledge-and-harvest.md)
+remain the architectural context. This document resolves implementation choices
+under that authorization; it does not impose OKF policy on other integrations.
+
+## First delivery
+
+- Canonical reference theory and injection/skill authoring guidance.
+- An optional, installed-artifact-usable `knowledge-theory-expert`.
+- Default OKF with working Git and ordinary directory custody. Omnigraph is an
+  authoring example, not a dependency or a required first implementation.
+- Explicit external base/node ownership and initial reads; independent,
+  automatically requested per-source harvest; preserved evidence before
+  retirement; Git deliveries always PRs; no Git dependency for directory mode.
+- Explicit migration with preservation and cutover, never silently discarding
+  an old soul bundle or treating a missing base as empty knowledge.
+
+## Follow-on phase — after this implementation is complete
+
+The human additionally requested a dedicated OATS knowledge Git repository and
+an expertise-oriented soul reorganization. The [accepted follow-on plan](../../agents/oats-expert/soul/knowledge/decisions/expert-souls-and-knowledge-rebuild.md)
+records the intended overall/kernel/Desktop/market/onboarding roles, the ban on
+engineer-role souls, strict audit of existing knowledge and pending notes,
+rejection of obsolete OAS material and code duplication, and safe cutover.
+This is a curated rebuild, not a bulk migration. The human subsequently allowed
+the separate repository shell to be provisioned under temporary personal
+ownership pending organization transfer. Do not migrate the corpus, rename
+live souls, or remove source knowledge before implementation verification.
+
+## Implementation choices
+
+1. **Capability-owned configuration.** Initially accept one absolute
+   `bindings-file` setting, avoiding ambiguous relative-setting provenance.
+   Paths inside it resolve from that file's directory. The document contains
+   version, durable state directory, named Git/directory bases and cadence.
+2. **Capability-owned soul declarations.** Use `soul/okf.json` rather than
+   teaching the kernel an OKF-specific nested YAML schema. It declares stable
+   owner identity, `owns` and `reads`. Accepted bases carry matching identity
+   and node ownership metadata. No knowledge content resides in the soul.
+3. **One link namespace per OKF base.** Nodes are owned, nonoverlapping
+   subdirectories. Reads are selective, index-first and non-mutating. Every
+   configured base is discoverable; `reads` is not an ACL.
+4. **Durable per-source input.** Keep copied evidence, note hashes, bounded
+   record content, frozen destinations and processing receipts outside source
+   homes/worktrees and accepted bases. Separate capture, delivered judgment,
+   and accepted/reader-visible state. No automatic evidence garbage collection
+   in the first implementation.
+5. **Directory custody is real.** Independent workers must not require a fake
+   Git repository. Add only the generic non-Git execution support actually
+   needed; preserve work-mode, trust and retirement safety.
+6. **Delivery.** Git workers edit their own accepted-baseline checkout and
+   produce a verified PR receipt. Directory workers stage changes and publish
+   with baseline checks, coordination and crash-recoverable receipts. Never
+   downgrade Git failures into direct writes. Initial directory coordination
+   is single-host/cooperative, not a distributed-lock claim.
+7. **Automation.** Reuse generic scheduler command jobs for per-source work;
+   retain pending work after its source is gone. Source registration is
+   automatic; host timer installation is an explicit setup action. Retire
+   captures/enqueues, not synchronously waits for model judgment or GitHub.
+8. **Optional authoring distribution in this repository.** Ship a dedicated
+   `oats.knowledge-theory` package under `oats-package/`, using an enumerated
+   self-contained capability subtree. This keeps release scope to the two
+   authorized repositories and avoids pretending an edit to the bundled
+   `oats.authoring` changes its separately released catalog package. The new
+   package supplies the expert and authoring skill/reference closure, has no
+   knowledge-layer binding or mandatory injection, and does not depend on OKF.
+   **Release channel: Git, not npm.** The npm kernel ships public docs and the
+   CLI but excludes `oats-package/` entirely: npm omits symlinks and therefore
+   cannot carry the canonical source `CLAUDE.md -> AGENTS.md`. Do not ship a
+   partial copy, synthesize source aliases on acquisition, weaken the source
+   rule, or change generic installed-artifact integrity semantics. Acquire with
+   `oats install git:github.com/awebai/oats@v0.23.0`, then explicitly target
+   `oats.knowledge-theory` with `oats use ... --soul <author-soul>`. The default
+   Git package path selects the self-contained subtree and exact-locks its
+   commit. A catalog pin can follow only after that immutable tag exists.
+9. **Minimal generic fixes.** Hooks must receive the running kernel's absolute
+   CLI path; scheduled dispatch must not inherit another instance's identity;
+   final record capture must distinguish completion from a skipped/held pass.
+   Do not add a knowledge registry or compulsory reference doctrine to core.
+
+## Source and delivery discipline
+
+The standalone OKF repository's enumerated runtime subtree is
+`oats-package/capabilities/oats-okf/`. Its published `v1.6.1` is the starting
+baseline; stale unenumerated duplicates are not implementation targets. The
+framework's bundled copy is synchronized only at integration, with parity tests.
+Existing release tags are immutable.
+
+Implementation helpers edit explicitly assigned files and do not commit,
+push, change branches or release. The maintainer integrates small commits and
+runs exact-range adversarial review every two commits, closing blocking
+findings before dependent work advances. Reviews cover product boundary,
+correctness, security and release/merge readiness, not just test results.
+
+## Verification and release gates
+
+- Standalone tests exercise its actual exported payload, not stale root copies.
+- Framework tests include generic non-Git execution, hook/dispatch identity,
+  capture-completeness and alternative-provider isolation.
+- Real temporary Git repositories test embedded/dedicated Git knowledge; real
+  directories outside Git test directory custody, concurrent updates and crash
+  recovery. Failed/uncertain publication stays recoverable.
+- Source deletion and name reuse cannot lose or misattribute pending evidence.
+- Installed-artifact acquire/lock/trust/activate/scaffold/retire probes validate
+  the complete expert curriculum and OKF's real compatibility floor. The kernel
+  tarball must exclude the optional Git package while retaining public docs.
+  Its installed CLI acquires the exact complete theory Git fixture via direct
+  and catalog sources, verifies the tracked alias survives unchanged, removes
+  the fixture checkout, and tests local reference closure and alternative-theory
+  isolation. Generated instance aliases remain ordinary kernel behavior.
+- A fresh selected-runtime instance must answer from delivered knowledge without
+  the source home/transcript. Scaffolding alone is not this learning gate.
+- Run strict knowledge validation, all affected tests, full framework gates,
+  tarball smoke, and a final cross-repository adversarial review before release.
+
+Version targets are provisional: framework 0.23.0 for generic support, OKF 2.0.0
+for breaking external-knowledge custody, optional theory package 1.0.0, then a
+framework patch for catalog/payload updates if required. The prerequisite
+0.23.0 keeps bundled OKF and its catalog pin at 1.6.1; standalone OKF 2.0.0
+follows rather than creating a prerequisite release cycle. Publish dependency
+sources before advancing catalog pins; follow actual current release scripts,
+not historical instructions contradicted by the implemented release lane.

package/docs/design/2026-09-13-knowledge-location-contract.md

@@ -0,0 +1,340 @@
+# Knowledge contracts, integrations, and storage
+
+**Status:** architecture proposal for discussion, 2026-09-13. No implementation
+or configuration schema is approved by this document. Accepted direction is
+recorded in [external knowledge custody](../../agents/oats-expert/soul/knowledge/decisions/external-knowledge-custody.md)
+and [provider-neutral knowledge and harvest](../../agents/oats-expert/soul/knowledge/decisions/provider-neutral-knowledge-and-harvest.md).
+This proposal refines the [knowledge and memory direction](2026-09-13-knowledge-and-memory-direction.md).
+
+## 1. Accepted starting points
+
+**Scope:** OATS publishes an opinionated reference knowledge theory; default
+OKF follows it, but other knowledge capabilities may choose different models.
+The location/harvest design below is for this default-theory workstream and
+capabilities that choose to adopt it, not extra kernel requirements.
+
+- All knowledge leaves the soul, including general expertise.
+- Working instances read knowledge and capture memory; they do not promote
+  into the base. For now this is injection guidance, not an OS sandbox.
+- Harvesting is independent of the source instance's execution/work context.
+- Git-committed knowledge updates are PRs.
+- Access rests on users' existing accounts; for GitHub repositories, their
+  GitHub permissions apply. Assume all workspace/team agents can access the
+  configured bases. No new public/private classification or per-agent ACLs.
+- The first working version must cover Git-backed OKF AND a non-Git knowledge
+  store. Non-Git support is not a later optional extension.
+- The reference knowledge/memory theory is independent of concrete storage
+  tools. An integration using a graph store and its CLI can adopt that theory,
+  or choose a different approach; it owns the resulting runtime behavior.
+- OATS supplies canonical authoring docs for knowledge injections and skills,
+  and a `knowledge-theory-expert` agent to help create knowledge capabilities.
+  The expert and full authoring material are planned deliverables, not yet built.
+- Every capability provides its own complete runtime instructions, skills,
+  memory conventions, harvester and related machinery. The kernel does not
+  automatically inject the reference doctrine into every knowledge capability.
+
+The mechanisms below are proposed. In particular, which non-Git implementation
+ships first is not yet settled: directory-backed OKF is the simplest candidate;
+Omnigraph is a concrete alternative to investigate, not an already verified
+integration or an agreed initial dependency.
+
+## 2. Separate the model, the integration, and custody
+
+### OATS reference knowledge/memory model — the recommended approach
+
+- **Instance memory:** task-local state, observations and captured evidence.
+- **Durable knowledge:** expertise that survives an instance, with explicit
+  ownership, provenance, decisions and supersession.
+- **Capture:** preserve observations while doing the work; do not make the
+  working instance hold the promotion bar.
+- **Harvest:** judge candidates against the common doctrine; promote, merge,
+  supersede or drop; preserve exclusions and one authoritative home per claim.
+- **Consultation:** discover relevant prior knowledge before re-deriving it,
+  using progressive disclosure rather than bulk loading.
+
+These meanings do not require Markdown, YAML frontmatter, `index.md`, local
+files, a Git branch, or a particular command. The promotion bar, expertise
+rather than code-description doctrine, and capture/judgment separation remain
+consistent when an author chooses to implement this theory with another tool.
+They are not mandatory policy for a capability that chooses a different model.
+
+### Canonical authoring material and knowledge-theory-expert
+
+OATS maintains the theory in its repository and supplies canonical documentation
+for turning it into working-agent injections, skills and harvester instructions.
+These references explain the concepts, their rationale, expected behaviors and
+examples. An author can point a coding agent at them without needing a special
+runtime dependency.
+
+OATS should also provide `knowledge-theory-expert`. Its job is to:
+
+- explain the reference model and the reasons for its distinctions;
+- help map it to a chosen tool's actual read/write and storage behavior;
+- help author a complete capability, including injections, skills and harvesting;
+- identify gaps or deliberate departures and suggest relevant behavioral tests.
+
+It assists authors; it does not run every harvest, police every capability,
+serve as a required approval gate, or replace the canonical docs. Its package,
+curriculum and instructions are still to design. No agent has been scaffolded
+or spawned as part of this scoping discussion.
+
+### Knowledge capability — a complete runtime implementation
+
+Each capability supplies the complete behavior selected by the deployment:
+its skills, injections, instance memory and capture protocol, native reader
+and writer tools, harvester and judgment instructions where applicable,
+lifecycle contributions, validation and delivery. It is not only an adapter
+under a mandatory OATS-supplied judge.
+
+For example:
+
+- Default OKF authors use the reference theory and ship concrete OKF injection,
+  craft/harvest skills, harvester, hooks and Git/non-Git delivery behavior.
+- An Omnigraph capability author may use the same docs/expert to create the
+  equivalent package around the native CLI and data model.
+- An author choosing a different memory or learning model provides and
+  documents that capability's own runtime instructions instead.
+
+Canonical theory stays in one maintained place, but adopting it does not
+require a mandatory shared runtime injection or harvester skill. Explicit
+resource reuse through supported packaging is fine; mutable documentation is
+not fetched into agents as a hidden policy update. Capability releases own
+changes to the runtime material they supply.
+
+The kernel keeps generic capability/layer/configuration/lifecycle/operation
+and trust contracts. It neither chooses the theory nor implements a universal
+harvester. Existing framework/work-mode rules still apply to every capability.
+
+### Custody — how a write becomes accepted knowledge
+
+Format and delivery are separate choices. OKF does not imply Git:
+
+| Implementation | Read path | Write/delivery path |
+|---|---|---|
+| Git-backed OKF | Accepted revision of an OKF bundle | Independent checkout, validation, PR; accepted after merge |
+| Directory-backed OKF | Configured OKF directory | Coordinated, validated update with an observable durable result; no Git or PR |
+| CLI-backed graph store | Provider-native discovery/query through its CLI | Provider-native writes and confirmation; no invented Git semantics |
+
+A dedicated knowledge repository can be Git-backed; moving out of the code
+repo does not make it non-Git. A non-Git store must work without `.git`, GitHub,
+a branch, a remote, or a PR receipt.
+
+## 3. Base, node, binding
+
+Sections 3–7 describe the proposed default location/harvest design and offer a
+pattern for authors adopting the reference theory. These nouns and shapes are
+not mandatory schema for every knowledge capability.
+
+### Base
+
+A named body of durable knowledge with a canonical provider-resolved location.
+It is not intrinsically an OKF bundle or a repository.
+
+An OKF base maps to a bundle root. A different provider can map a base to its
+native database/space/collection identifier. Only that provider interprets
+its locator, storage structure, validation and consistency behavior.
+
+General expertise, project decisions and team knowledge all live in bases;
+none live inside souls. A project or workspace may consult several bases.
+The invariant is **one authoritative home per concept**, not one required
+physical storage root for everything relevant to a project.
+
+### Node
+
+A logically soul-owned portion of a base, with exactly one owning soul. A soul
+can own nodes in several bases. Ownership is responsibility and harvest
+routing, not an access-control grant. A provider must make the boundary
+addressable; an OKF directory is one representation, not the universal one.
+
+`project/oats-desktop-expert` and `team/oats-desktop-expert` are distinct node
+references. Matching leaf names never merge them. Owner identity must also
+distinguish same-named souls in different repositories; its exact syntax is open.
+
+### Binding
+
+Workspace/project configuration maps logical references to a selected
+integration's concrete locations. A soul declares what it owns and consults,
+without embedding knowledge, physical paths, remote URLs or credentials.
+
+Illustrative soul declarations, not an approved schema:
+
+```yaml
+# oats-desktop-expert/soul.yaml
+knowledge:
+  owns: [project/oats-desktop-expert]
+  reads: [project/oats-expert]
+```
+
+Here `oats-desktop-expert` consults project direction maintained by `oats-expert`
+and accumulates its own durable Desktop expertise. Binding `project` to an
+embedded OKF bundle, a separate OKF repository, or a non-Git store does not
+change the meaning of those declarations.
+
+Aliases are contextual, not global identities. Resolve them before a read or
+harvest; persisted jobs retain the resolved destination so later configuration
+changes cannot redirect pending work. Changing storage providers is an explicit
+migration, not an alias edit that silently converts or copies knowledge.
+
+## 4. Reference-model implementation contract versus concrete location
+
+Do not make a tool pretend to have files or Git metadata. The following is a
+checklist for our default implementation and other capabilities adopting this
+model. It is not a new universal knowledge-provider API, mandatory theoretical
+conformance test, or kernel requirement.
+
+| Concern | Provider-neutral meaning |
+|---|---|
+| Resolve | Map a logical base/node to an unambiguous provider-owned destination and owner |
+| Discover/consult | Give instances a useful entry point and tools to retrieve relevant accepted knowledge |
+| Prepare harvest | Preserve bounded source evidence and resolved destinations independently of the source home |
+| Apply judgment | Let the harvester maintain knowledge using the provider's native authoring tools |
+| Validate | Check the proposed update against the provider's representation and shared semantic requirements |
+| Deliver | Report a durable proposal, an applied update, a no-change result, or a failure; distinguish these |
+| Refresh/inspect | Explain what readers can see, freshness limitations and pending work without guessing from activity |
+
+The resolved descriptor needs a logical reference, provider identity, opaque
+provider locator, node/owner identity, reader/writer instructions or operation
+references, delivery semantics, and binding provenance. A version or receipt
+is provider-native; a Git commit ID is not a required field for every store.
+
+### OKF location examples
+
+| Placement/custody | Canonical location | Bundle root | Read baseline |
+|---|---|---|---|
+| Embedded Git | `https://github.com/example/project.git` | `knowledge/` | Configured accepted branch |
+| Dedicated Git | `https://github.com/example/project-knowledge.git` | `.` | Configured accepted branch |
+| Non-Git directory | Explicit workspace-relative directory, e.g. `./team-knowledge` | That directory | Provider-confirmed current contents |
+
+Git locators include repository, contained root, accepted ref and PR target/head
+route. Directory locators include a resolved path and direct-update custody.
+A future CLI-backed locator uses the actual identifiers supported by that
+provider; do not invent Omnigraph fields or command flags before investigation.
+
+Configuration belongs to the selected knowledge capability's settings and
+existing targeting, not a new mandatory kernel registry. Multiple bases do not
+require multiple active knowledge layers: `oats.okf` can supply both Git and
+directory custody. An Omnigraph integration could replace it in another
+deployment. Simultaneous different integrations in one instance are not assumed
+here; that would need a separate composition decision.
+
+### Resolution and access rules
+
+1. Bind locations explicitly; do not choose from cwd, source work mode, source
+   feature branch or whichever checkout happens to be writable.
+2. Relative paths resolve from their declaring scope, with containment checks.
+3. Missing required bindings or failed access are visible errors; never create
+   an empty substitute or silently choose another base.
+4. Reads do not scaffold nodes. Creation and ownership changes are explicit writes.
+5. Use the user's existing account/access for the selected system. GitHub governs
+   GitHub access; a local directory uses host filesystem access; another tool
+   uses its native authentication. No new OATS permission system is implied.
+6. All configured workspace/team bases are available to its agents. `reads`
+   selects initial context, not an ACL; `owns` selects responsibility/routing.
+   Access to other repositories does not auto-bind them.
+7. A failed Git delivery cannot fall back to direct writes. Tracked knowledge
+   cannot be relabelled local merely to bypass its PR contract.
+8. Defer public/private classification and disclosure routing. Keep the existing
+   secret/credential and third-party-verbatim promotion exclusions.
+
+## 5. Independent harvest, provider-specific writing
+
+A per-source harvest takes preserved evidence, source/soul identity, bounded
+record provenance, claimed note versions, resolved destinations and a stable
+input identifier. It does not rely on the source staying alive or keeping the
+same worktree/branch. Independent execution does not mean context-free evidence.
+
+The reference-model harvester's reasoning is:
+
+1. Consult existing relevant knowledge through the integration's read tools.
+2. Judge the source candidates under the common doctrine.
+3. Select each candidate's owned destination; maintain or supersede existing
+   knowledge rather than creating duplicate descriptions.
+4. Apply changes with the integration's authoring tools, validate, and report
+   the actual delivery outcome. Advance source processing state only under the
+   agreed durable-result protocol.
+
+Concrete writing differs:
+
+- **Git OKF:** worker-owned destination checkout, starting from the accepted
+  branch; knowledge-only PR whether the bundle is embedded or dedicated.
+- **Non-Git OKF candidate:** worker-owned execution context, coordinated edits
+  to the configured directory, validation and recoverable publication. A plain
+  successful edit command alone is not the whole crash/retry contract.
+- **Omnigraph scenario:** the harvester uses Omnigraph's native CLI to consult
+  and write knowledge; working instances use it to retrieve knowledge. How
+  logical nodes, supersession, receipts and consistency map to that CLI must
+  be verified. No command surface or transaction guarantee is assumed here.
+
+The integration manages authenticating through the user's available access;
+credentials do not travel inside harvest evidence. Source retirement preserves
+inputs before removal or reports incomplete retirement. Results are per
+explicit destination; cross-store changes are not assumed atomic.
+
+Provider-neutral orchestration does not mean every backend supports identical
+transactions or review states. Do not report a proposal as applied, a queued
+write as queryable, or a process launch as successful harvesting.
+
+## 6. Visibility, concurrency and validation
+
+For Git OKF, distinguish PR opened, merged, and visible in a refreshed reader.
+For non-Git, distinguish proposed/staged changes if supported, durable application,
+and reader visibility according to the actual provider. A direct local provider
+can have no pending-review phase; it must not fabricate one.
+
+A provider documents its read consistency and available version/freshness
+signals. If it cannot offer snapshots, acknowledge that instead of inventing a
+Git-like revision. Failed or rejected delivery must remain recoverable after
+the source home is gone. Exact watermark and retention mechanics are open.
+
+Concurrency has separate units: source input claims, node updates and storage
+publication. Git requires accepted-head validation across PRs; non-Git files
+need coordinated/recoverable publication; a service needs its actual concurrency
+contract. Test concurrent harvests, retries, and failure after a partial write.
+
+Validate OKF with the OKF validator, including each base's native link namespace.
+A graph integration validates its own representation and logical ownership;
+it does not run a Markdown validator on a service. Default implementations
+must pass behavioral tests for the reference doctrine, provenance, supersession,
+exclusions, one canonical home and consultation by a fresh instance. Authors
+adopting the theory can reuse these tests; a capability choosing a different
+theory is not rejected merely for differing from that model.
+
+## 7. First working version and remaining decisions
+
+There are two related deliverables:
+
+1. **Reference/authoring:** canonical theory and injection/skill guidance plus
+   the `knowledge-theory-expert` agent. Useful without a running OKF deployment.
+2. **Default implementation:** complete capability-owned runtime behavior,
+   applying that theory to working Git and non-Git storage.
+
+**Required:** working Git-backed OKF AND a working non-Git knowledge store.
+A Git-only release with a non-Git interface stub does not satisfy this scope.
+
+Recommendation for the smallest initial implementation: `oats.okf` with Git and
+plain-directory custody. This exercises both paths without introducing an
+unresearched external dependency. The choice is not yet accepted: confirm
+whether the first non-Git implementation should instead be Omnigraph itself.
+An Omnigraph implementation adopting the reference theory should be possible
+without rewriting the theory; this does not oblige every Omnigraph capability
+to adopt it.
+
+Acceptance scenarios use `oats-expert` and `oats-desktop-expert`:
+
+1. Git OKF works both inside the code repo and in a dedicated knowledge repo;
+   harvest runs independently and opens the appropriate knowledge-only PR.
+2. The non-Git implementation persists real harvested knowledge with no Git
+   repository or GitHub dependency, and reports a verifiable result.
+3. In each implementation, a fresh instance answers from accepted knowledge
+   learned by a retired instance, without its home or transcript.
+4. Both preserve the same promotion doctrine, provenance and exclusions, and
+   handle concurrent updates, failed delivery and safe retirement inputs.
+5. A workspace using the OKF integration can consult multiple configured bases
+   without ambiguous ownership or destination selection.
+
+Before implementation, settle the authoring-material and expert delivery shape,
+non-Git backend, binding/schema and ownership identity, delivery/refresh semantics,
+and source input/retention protocol. The kernel stays provider-neutral; each
+capability supplies its complete runtime knowledge behavior. No mandatory shared
+theory-runtime layer, public/private permission model or multi-provider router
+is a prerequisite.

package/docs/design/launch-configurations.md

@@ -0,0 +1,164 @@
+# Launch configurations and launch recipes
+
+A **launch configuration** is a named way to start a harness, declared per
+scope under `launch-configs:` in `oats-config.yaml` (see
+docs/configuration.md): runtime, an executable, literal arguments,
+environment (literals or `{fromEnv}` references), model, yolo. It is
+independent of any soul; a soul may name one as its default
+(`launch-config:` in soul.yaml, `oats soul set --launch-config`), and a
+spawn, start or restart selects one by name.
+
+A **launch recipe** is what a start is made of, recorded in the instance's
+`instance.json` under `launch` beside the rendered `command`:
+
+```json
+{
+  "version": 1,
+  "runtime": "claude",
+  "launchConfig": "personal", "launchConfigSource": "/scope",
+  "executable": "/scope/tools/claude-wrapper.sh",
+  "executableDeclared": "./tools/claude-wrapper.sh", "executableResolvedFrom": "relative to /scope",
+  "args": ["--settings", "/abs/settings.json"],
+  "env": { "KEY": { "fromEnv": "SRC" }, "LIT": "plain" },
+  "model": "claude-opus-5", "yolo": true,
+  "hooks": {
+    "launch": { "claude": "--dangerously-load-development-channels plugin:aweb-channel@awebai-marketplace" },
+    "env": { "AWEB_DELIVERY": "session" },
+    "contributions": [{ "capability": "oats.aweb", "layer": "messaging", "level": "/scope", "settings": { "delivery": "session" }, "trust": { "trusted": true, "integrity": "sha256-..." }, "launch": { "claude": "..." }, "env": ["AWEB_DELIVERY"] }]
+  },
+  "prompt": { "kind": "task-file", "file": "TASK.md" }
+}
+```
+
+The rendered `command` is produced by one renderer from the recipe. With no
+configuration it is byte-identical to what spawn rendered before recipes
+existed, so an older kernel starts such a home unchanged, and the golden
+matrix freezes that. Configuration `args` go after the runtime's own
+options and before capability launch arguments (for claude and codex the
+`--` separator keeps them from consuming the task; for pi they follow the
+task, like capability arguments). Every argument and literal value is
+single-quoted: spaces, quotes and metacharacters are literal.
+
+## Environment references
+
+`{fromEnv: SRC}` renders as `NAME="$SRC"` in the command: the persisted
+command, the pending receipt and every answer carry the reference, never a
+value. At start the execution host checks each source variable is set
+(`E_LAUNCH_ENV_MISSING` before anything is created or stopped) and hands the
+source variables to the pane only (tmux `-e`; a Herdr launch exports them in
+the launched shell). Literal values are non-secret by contract but no answer
+shows them: `list` and `preview` redact every environment value.
+
+## Selection rules
+
+- A named configuration is a unit. `--launch-config NAME` with a `--runtime`
+  that disagrees with the configuration's runtime is refused
+  (`E_LAUNCH_CONFIG_MISMATCH`) before anything happens; the same runtime may
+  be repeated; `--model` and `--yolo` override the configuration's fields.
+- Without `--launch-config`: a spawn takes the soul's `launch-config` default
+  or none; an existing home keeps its recorded configuration, except that
+  `--runtime` alone deliberately leaves it behind and renders the new
+  runtime's defaults (no old executable or args are carried).
+- Model: explicit, else the configuration's, else on an existing home the
+  recorded model when the runtime is unchanged, else the runtime's native
+  default; a spawn without either resolves the soul's preference for the
+  runtime. A model never crosses runtimes.
+- Executable: the configuration's (bare name on PATH; a path resolved against
+  the declaring scope when relative) or the runtime's default (claude through
+  `oats-claude-config`). It must be a regular executable file; it is never
+  run to probe it. Capability runtime-package requirements are checked with
+  the runtime's default binary, as at spawn.
+
+## Capability boundary
+
+Spawn hooks contribute `launch` arguments keyed by runtime and `env` values.
+Launch arguments are runtime-specific by construction; environment is
+runtime-neutral by contract. The recipe records both with per-capability
+provenance (settings and trust at spawn). A later start on the same runtime
+reuses them. A runtime switch reuses the environment and needs the new
+runtime's launch arguments from the same capabilities: a capability that
+answered arguments for the old runtime and none for the new one refuses the
+switch (`E_LAUNCH_PREPARATION`) with the remedy (change that capability's
+setting, or the provider declares a `launch` hook). Spawn hooks are never
+re-run by a start or restart.
+
+## `oats launch-config preview`
+
+Read-only; nothing is locked or started. `--home ABS` describes an existing
+home under a selection (`selection.source`: `frozen` when nothing was
+selected, `config` when re-resolved, `frozen-command` for a home that
+predates recipes, whose selection needs the restart conversion);
+`--soul NAME [--dir SCOPE] [--agents-root ABS]` describes a new instance.
+Answer: `{context, selected, selection:{source, launchConfig, runtime,
+model, yolo}, runtime, model, modelSource, yolo, launchConfig,
+launchConfigSource, executable:{path, declared, resolvedFrom}, argv,
+environment:[{name, redacted|fromEnv}], command (redacted rendering),
+prompt:{kind:"task-file", file:"TASK.md"}, hooks (redacted),
+preflight:[{check: executable|environment|model|capabilities, ok, detail}],
+ok}`. The TASK body is never included.
+
+## Starting and restarting an existing home
+
+`oats session start --home ABS` runs the recorded recipe as it is (a
+`--model` re-renders the model in place and the recipe follows). With
+`--launch-config`, `--runtime` or `--yolo` the recipe is re-resolved by the
+same planner preview uses, against the home's recorded context, and every
+check runs before anything is observed: the recipe's shape, the executable
+(regular file, executable), the references (set on this host), the
+capabilities' contributions (below), the runtime packages. A recorded
+reference is re-checked on every start path, model-only starts included,
+and the pane receives the source's value under the kernel alias.
+
+`oats session restart --home ABS [same flags] [--stop-grace SECONDS]` stops
+the running harness and starts again in place under the one per-home lock:
+
+1. Every preflight above, first. A refusal leaves the harness running.
+2. The stop: SIGTERM to every process under the pane's launcher (a wrapper
+   that does not exec, the harness, their children), then a bounded wait
+   (default 20 s) for the signalled processes to be gone and the session to
+   read as a bare shell or stopped. Nothing is escalated: a harness still
+   there when the wait ends is reported (`E_SESSION_STOP_FAILED`, with the
+   processes still running) and nothing is launched. Elapsed time is never
+   taken as exit; a turn interruption is never taken as exit.
+3. The in-place start, with the pending receipt carrying the new recipe,
+   runtime and yolo, exactly as a start does; `.oats-restart.json` keeps the
+   stop's facts (what was signalled, when, whether exit was observed).
+
+What the harnesses do on SIGTERM, from their installed sources and
+documentation as read by the operating lead on 2026-09-07 (no live process
+signalled): pi (@earendil-works/pi-coding-agent 0.84.2) registers
+SIGTERM/SIGHUP handlers that end tracked children, dispose extensions and
+exit; Claude Code's documentation makes Ctrl-C state-dependent (interrupt,
+clear, double-press exit) and does not establish that an external SIGTERM
+runs its SessionEnd hook; Codex's documentation establishes no SIGTERM
+cleanup guarantee. So the contract is the request and the observation, not
+a promise that a harness flushes its latest conversation: OATS preserves
+the home, work, identity and notes; an old native conversation's unsaved
+state is the harness's own. Wrappers should exec the harness or forward
+signals. A longer `--stop-grace` can accommodate hook cleanup.
+
+## Homes that predate recipes
+
+A home with a recorded `command` and no `launch` is converted narrowly when
+a start selects something: only the kernel's own generated shapes are
+recognized (identity environment, the binary, the runtime's template
+arguments, `--model`, yolo, the task prompt). Other environment is kept and
+attributed to the capability whose recorded declaration (`environment`,
+`environmentNamespaces` in `capabilityRuntime`) owns it, so a session-delivery
+home switches runtime with its `AWEB_DELIVERY` intact; spawn hooks are never
+re-run. Any other argument is unclassified: the start is refused, naming the
+arguments, unless an active trusted capability declares a `launch` hook that
+prepares the launch anew (then its answer replaces them). The conversion is
+recorded (`launch.legacy`) by the start that uses it.
+
+## The `launch` hook
+
+A capability may declare `hooks.launch`. It runs on a start or restart of an
+existing home (never at spawn, never spawn's identity work), side-effect-free
+by contract, with `OATS_RUNTIME` set to the target runtime and
+`OATS_PREVIOUS_RUNTIME` to the recorded one, and answers `{launch:{<runtime>:
+args}, env:{...}}` for that runtime; its answer replaces the capability's
+recorded contribution. Without it, a capability that contributed
+runtime-specific arguments at spawn cannot follow a runtime change
+(`E_LAUNCH_PREPARATION`), and a capability the scope no longer trusts has its
+recorded arguments withheld the same way.