@awebai/oats 0.22.19 → 0.23.1

package/docs/layers.md

@@ -2,7 +2,9 @@
 
 Status: contracts on paper (migration step 2 of
 [the 2026-09-03 architecture proposal](2026-09-03-architecture-proposal.md)).
-Every section says what is **shipped** today and what is **proposed**. A
+Sections distinguish **shipped**, **prepared** and **proposed** behavior.
+The knowledge section describes the prepared OKF v2 integration; its release
+gates are explicit in [v0.23.1 notes](release-notes/v0.23.1.md). A
 proposed clause describes the contract the kernel will be refactored toward;
 it is not a claim about current behavior, and the shipped documents
 ([souls and instances](souls-and-instances.md),
@@ -127,65 +129,58 @@ kernel's code has no branch that names either.
 
 ## The knowledge contract
 
-**Shipped.** The `knowledge` slot. The bundled implementation is `oats.okf`:
-an OKF bundle under `soul/knowledge/`, per-instance `STATE.md`, `log.md`, and
-`notes/`, the `okf` and `memory-harvest` skills, and `oats okf harvest`, which
-spawns the capability-defined `memory-harvest` soul attached to the source
-instance's work tree. `knowledge: none` is valid and yields no memory files
-and no harvest.
-
-**Contract.** Two sides.
-
-*Read.* An instance can find and consult organizational knowledge,
-index-first and selectively, and is told how by the implementation's injected
-block and skill. Prior decisions, lessons, and playbooks in scope are binding
-context; re-deriving what the soul already knows is a bug. **Proposed:** the
-scope of what an instance may read is decided by its soul type, which needs
-`OATS_SOUL_TYPE` (step 7) before an implementation can act on it.
-
-*Write.* A permitted soul (a harvester type) can promote into the store. The
-format is the implementation's. Delivery matches the soul's custody: a commit
-on the instance's branch for repository-resident souls, a pull request to
-the soul's home repository for workspace-mode souls, direct edits for local
-souls.
-
-*Custody, shipped.* Delivery custody is keyed by where the soul resides: a
-commit on the instance's branch for repository-resident souls, a pull request
-to the soul's home repository for workspace-mode souls, direct edits for local
-souls. That is the only custody the kernel and `oats.okf` implement today.
-
-*Custody scoping, proposed.* The requirement is that repository-specific
-facts never move into a broader scope by default and that a cross-repository
-soul never reads another repository's specifics. The design that meets it
-belongs to the knowledge package, not the kernel. Custody layers (soul-shared,
-workspace overlay, repository overlay) are one candidate; scoping by soul
-type plus residency is another. Nothing here is settled or shipped.
-
-*Promotion doctrine.* What the write side accepts is a decision, not a
-format question. The line is decision versus description. Descriptions of
-how the code fits together go stale and compete with the code; the write
-side rejects them. Decisions, what was chosen, what was rejected, and why,
-cannot be derived from code and are accepted, as are inspiration genealogy
-("took this from X, rejected Y because Z"), process lessons, and maintained,
-timestamped, superseded-on-change slow state about an area. Slow state is
-accepted only with its maintenance discipline: a named owner and an
-update-on-change rule; a slow-state concept nobody maintains is
-indistinguishable from residue and is rejected as such. Task residue
-(pull-request numbers, half-done plans, point-in-time environment facts) dies
-with the instance. One home per decision; split-brain comes from copies. The
-homing rule: architecture facts that several roles need go in repository-
-visible docs and souls point to them; craft decisions scoped to one role go
-in that role's soul; product direction goes in the steward's bundle,
-consulted and never copied. For non-coding specialists none of their
-knowledge is re-derivable from a repository, so those souls are almost pure
-knowledge. See [knowledge theory](knowledge-theory.md) for the derivation.
-
-**Proposed.** The harvester's input widens from the agent's own notes to the
-capture contract (below), so lessons reach the soul even when an agent wrote
-no notes; the promotion doctrine is unchanged, only the input channel widens.
-
-**Test.** A plain-Markdown or wiki-backed implementation beside `oats.okf`,
-each with its own harvester; a soul's `AGENTS.md` unchanged between them.
+**Shipped kernel contract.** Zero or one knowledge capability per soul,
+selected under `capabilities.layers.knowledge`. `none` creates no
+provider memory or harvest flow and does not delete existing state. The kernel
+owns neither the format nor a mandatory promotion doctrine.
+
+**Prepared reference implementation: oats.okf 2.0.0 / framework v0.23.1.**
+All accepted knowledge is external. Explicit bindings name Git or non-Git
+bases; `soul/okf.json` declares stable ownership and read references, while
+`okf-base.json` identifies accepted nodes. Missing configuration or knowledge
+fails working-source spawn, never creates an empty substitute.
+
+*Read.* Sources consult immutable accepted views, index-first and selectively.
+Prior rationale should be consulted rather than re-derived. OKF's `owns` routes
+responsibility and `reads` chooses starting context: neither is an ACL, and all
+configured bases are discoverable/readable. Cannot-write is instruction, not an
+OS sandbox. A directory publication journal blocks fresh views; Git readers see
+only the accepted branch, not an open PR.
+
+*Capture and judgment.* Working agents capture state/log/notes; durable source
+custody also copies full native record windows through the public CLI. A separate
+worker judges from frozen input without needing the source home, worktree or
+model. Source retirement waits for certified capture, not a model or GitHub.
+Workers use independent `directory` execution and never edit source notes or
+soul skills. Existing hooks and per-source command schedules supply this flow;
+the proposed generic `harvest` event above is not implemented or required.
+
+*Delivery custody.* Knowledge placement, not soul residency or work mode,
+determines delivery. All Git bases use verified PR-only delivery with separate
+merge-visible acceptance. Genuine non-Git directories use cooperative locks,
+baseline comparison, journalled publication and validated receipts, without Git
+or gh. There is no direct Git fallback and no cross-base distributed transaction.
+Source descriptors, proposals and processing/delivery/acceptance receipts outlive
+source retirement. Inspection can show matching live Markdown plus durable
+receipts; missing/reused homes cannot supply live memory for an old source.
+
+*Reference promotion doctrine.* OKF accepts durable behavior-changing judgment
+that is not recoverable merely by reading code: rationale, rejected alternatives,
+discovered limits and maintained slow state. It rejects code descriptions, task
+residue, secrets and verbatim third-party messages. Human-accepted decisions keep
+acceptance evidence; maintained state needs an owner and freshness discipline.
+One canonical concept is preferable to copied claims. These are the default
+capability's choices, not a compulsory judge for every knowledge implementation.
+
+See [the runtime guide](knowledge.md) and [v1 migration](knowledge-migration.md)
+for current commands and constraints. The [reference theory](knowledge-theory.md)
+and [authoring curriculum](knowledge-capability-authoring.md) are optional;
+capabilities may adopt, adapt or replace them and own their complete runtime.
+
+**Test.** OKF's Git and directory providers exercise independent custody within
+one capability. A second knowledge capability with a different model remains a
+separate replaceability test; two OKF providers do not prove that test by
+renaming them as two integrations.
 
 ## The tasks contract
 
@@ -260,8 +255,8 @@ them.
 `packages/record` captures Claude Code, Pi, and Codex transcripts plus aw
 client logs. It skips sources matched by the local record's ignore list. It
 stores captured turns in an append-only, content-addressed record with a search
-index (`oats setup`, `oats capture`, `oats recall`). It is not a capability and
-no lifecycle hook knows about it.
+index (`oats setup`, `oats capture`, `oats recall`). It is not a capability. A knowledge capability may consume source-targeted
+capture/recall through the supported CLI boundary, as OKF v2 does.
 
 **Contract.** The format of ephemeral state. Two kinds satisfy it: an agent's
 own notes (its report of what mattered, today created by the knowledge
@@ -340,21 +335,22 @@ bundle.
 
 ## The work target contract
 
-**Shipped.** Four modes decide what `<instance-home>/work` is and what
+**Shipped.** Five modes decide what `<instance-home>/work` is and what
 discipline the instance follows: `worktree` (an isolated branch), `checkout`
-(the shared current branch), `attached` (another instance's tree), and
-`workspace` (the whole team scope, read-only). A config may run a setup
-script inside each fresh worktree. Retirement preserves ordinary work,
+(the shared current branch), `attached` (another instance's tree),
+`workspace` (the whole team scope, read-only), plus explicit `directory`
+(instance-owned non-Git execution for independent workers). A config may run a
+setup script inside each fresh worktree. Retirement preserves ordinary work,
 quarantines incomplete cleanup, and never removes a shared tree. The
 generated instructions state the home/work boundary before the mode block.
 
 **Contract.** The work target is a parameter of instantiation independent of
 where the soul is stored. Each mode is a module that prepares the view,
 states its discipline, and knows how to retire it safely, with the
-retirement baseline and inspection alongside. The four modes stay exactly as
-they are.
+retirement baseline and inspection alongside. The four Git/context modes retain
+their existing semantics; directory execution never acts as an implicit fallback.
 
-**Proposed.** A fifth target, `none`, for instances that operate on nothing
+**Proposed.** An additional target, `none`, for instances that operate on nothing
 (a mail-only agent). It replaces no mode.
 
 **Test.** An instance of one soul spawned with each target, the same soul

package/docs/migration-from-oas.md

@@ -11,6 +11,12 @@ kernel does not read `oas-*` configuration names or `oas.*` capability IDs.
 An unchanged agent-directory layout can make an old scope look familiar
 while its knowledge and messaging configuration remains unmigrated.
 
+> **Separate knowledge cutover:** OAS/package name migration does not migrate
+> soul knowledge, source memory or v1 watermarks to OKF v2. If the selected
+> catalog update acquires OKF 2.0.0, plan [knowledge preservation and cutover](knowledge-migration.md)
+> before activation/spawn. The v2 integration is [prepared](release-notes/v0.23.1.md),
+> not a claim that those dependencies or any deployment have already changed.
+
 ## Upgrade one scope
 
 Finish or preserve active work before changing a daily-use deployment.
@@ -83,4 +89,4 @@ requirement to wait for OATS publication.
 
 See the [0.22.0 release notes](release-notes/v0.22.0.md) for the rename,
 package versions, and compatibility changes, and the
-[first-team qualification](first-team-demo.md) for current operating evidence.
+[first-team qualification](first-team-demo.md) for historical v1 operating evidence.

package/docs/oats-config.schema.json

@@ -63,7 +63,8 @@
         {
           "type": "object",
           "properties": {
-            "setup": { "type": "string", "description": "Env-bootstrap command run inside each new worktree after creation (path relative to this config's directory)." }
+            "setup": { "type": "string", "description": "Env-bootstrap command run inside each new worktree after creation (path relative to this config's directory). Only worktree mode runs setup." },
+            "retirement-disposable": { "type": "array", "items": { "type": "string" }, "description": "Relative disposable roots for worktree retirement. Directory mode has no disposable exemptions." }
           },
           "additionalProperties": false
         }
@@ -160,7 +161,9 @@
       "properties": {
         "worktree": { "$ref": "#/$defs/workMode" },
         "checkout": { "$ref": "#/$defs/workMode" },
-        "attached": { "$ref": "#/$defs/workMode" }
+        "attached": { "$ref": "#/$defs/workMode" },
+        "workspace": { "$ref": "#/$defs/workMode" },
+        "directory": { "$ref": "#/$defs/workMode" }
       },
       "additionalProperties": false
     }

package/docs/packages.md

@@ -391,12 +391,14 @@ for it.
 ### Catalog shape
 
 The official catalog is data (`package-catalog.json`, or the file named by
-`OATS_PACKAGE_CATALOG`):
+`OATS_PACKAGE_CATALOG`). The v0.23.1 integration selects these already-published
+sources; installing a kernel does not advance existing package locks:
 
 ```json
 {
   "packages": {
-    "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v1.4.1", "path": "oats-package" },
+    "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v2.0.0", "path": "oats-package" },
+    "oats.knowledge-theory": { "url": "https://github.com/awebai/oats.git", "ref": "v0.23.0", "path": "oats-package" },
     "oats.dev": { "url": "https://github.com/awebai/oats-dev.git", "ref": "v1.0.0", "path": "oats-package" }
   },
   "capabilities": { "oats.review": "oats.dev" }
@@ -412,6 +414,28 @@ Existing v1 locks and artifacts remain supported until you run guided migration.
 reads; identity mappings need no entry. An alias value may also be spelled
 `{ "package": "<id>" }`.
 
+### OKF v2 and optional theory distribution
+
+The standalone OKF package exports only `oats-package/capabilities/oats-okf/`.
+Use its catalog Git payload after [release gates](release-notes/v0.23.1.md) pass.
+The framework's bundled npm mirror is not a self-contained distribution:
+npm drops the source worker soul's `CLAUDE.md -> AGENTS.md`. It must not be
+advertised as a complete local package or repaired after acquisition to evade
+integrity checks. Git transport preserves the canonical source alias.
+
+The optional `oats.knowledge-theory` package is a separate Git payload in this
+repository's `oats-package/`, excluded from the kernel npm tarball. The catalog
+entry selects published framework v0.23.0, which contains package 1.0.0.
+The source reference patch 1.0.1 is separately available through an explicit
+v0.23.1 Git source after that framework tag is published. It supplies an authoring skill and
+`knowledge-theory-expert`, not a default knowledge-layer binding, runtime judge
+or OKF dependency. Acquiring it does not activate it.
+
+Updating OKF v1 to v2 is a breaking capability change. Preserve existing
+knowledge and source state/cursors, explicitly bind/provision external owners,
+accept provider delivery and perform deliberate cutover. Kernel package/lock
+migration does none of this. See [knowledge migration](knowledge-migration.md).
+
 ## Doctor
 
 `oats doctor` reports, in addition to its capability diagnostics:

package/docs/release-notes/v0.23.0.md

@@ -0,0 +1,93 @@
+# OATS v0.23.0
+
+This is the prerequisite kernel release for capability-owned external knowledge
+and independent harvesting. It adds generic directory work and more reliable
+record capture; it does **not** migrate existing knowledge or select a new
+knowledge integration. The bundled `oats.okf` and official catalog pin remain
+**1.6.1**. OKF 2.0 is a separate, subsequent capability release; no new catalog
+pin or bundled v2 runtime is included here.
+
+## Independent directory work
+
+`work: directory` creates an instance-owned ordinary `work/` directory. It does
+not require a Git repository, branch, worktree, or fabricated commit. Existing
+Git work modes retain their semantics. A capability can use directory workers
+for non-Git knowledge custody without making its storage model a kernel policy.
+
+Directory lifecycle checks reject a replaced, missing or symlinked work root
+before launch, and preserve retryable cleanup obligations when compensation
+cannot finish. Hooks receive the running kernel's CLI path. Generic scheduled
+commands no longer inherit another instance's source identity.
+
+## Evidence capture and recall
+
+Record capture distinguishes completed work from skipped, held, incomplete and
+failed attempts. Capture verifies attributed native transcript identity,
+honors native storage roots and recorded launch environments, and includes
+supported nested Claude subagent transcripts. Uncertain discovery, unreadable
+or replaced sources, incomplete tails and lock failures are not certified as
+complete evidence. Large piped recall responses drain stdout before exiting.
+Managed starts now preserve independent, execution-time native record-location
+history, so a later observer's environment cannot silently redirect capture.
+History survives retirement and is not a knowledge bundle. Older or standalone
+sessions without that authority fail closed on `capture --home`; an operator
+can explicitly use `oats capture --current-roots --home <home>` to inventory the
+currently configured roots, but that does not certify all historical locations.
+
+These are evidence-preservation guarantees, not a claim that a model has learned
+from the captured records.
+
+## Optional knowledge-theory authoring resources
+
+`oats.knowledge-theory` 1.0.0 is an optional **Git-distributed OATS package**
+in this repository's self-contained `oats-package/` subtree. It exports
+`knowledge-theory-expert` and the `knowledge-capability-authoring` skill with
+the complete local reference curriculum. The kernel npm tarball ships public
+docs and the CLI, but **excludes** this optional payload entirely. npm omits
+symlinks; a partial copy without the canonical source alias is not a supported
+package. Acquisition does not synthesize aliases or relax integrity semantics.
+
+After this immutable tag is published, acquire through the normal Git package
+route and explicitly opt in for an author soul:
+
+```bash
+oats install git:github.com/awebai/oats@v0.23.0 --dir /path/to/scope
+oats use oats.knowledge-theory --soul <author-soul> --dir /path/to/scope
+```
+
+The default Git package root is `oats-package/`; acquisition locks the resolved
+commit and alone activates nothing. An official catalog pin can follow only
+after the immutable tag exists. No unpublished theory catalog pin is shipped
+in this prerequisite release.
+
+The package has no knowledge-layer binding, mandatory injection, runtime hook,
+command or dependency on OKF. Authors may adopt, adapt or replace the reference
+model. Each selected knowledge capability owns its runtime, reader/capture,
+judgment and delivery instructions. The first external-knowledge design covers
+Git PR delivery and non-Git directory custody; no framework ACL layer is added.
+
+Canonical references are published under
+[the authoring guide](../knowledge-capability-authoring.md) and
+[the reference model](../knowledge-reference/model.md), with byte-identical
+copies in the Git-packaged skill. Installed instances read those local copies,
+not a source checkout or mutable network documentation. Git transport preserves
+the tracked source `CLAUDE.md -> AGENTS.md`; generated instances receive their
+own canonical alias through the unchanged normal composition path.
+
+## Packaging and compatibility
+
+Kernel, Pi adapter and Desktop versions are aligned at 0.23.0, including both
+lockfiles. Desktop still uses CLI API v1; its accepted kernel band is widened
+to `>=0.22.0 <0.24.0`, retaining support for released 0.22.x kernels.
+
+Local, CI and runnerless release checks share the recursive JavaScript
+inventory, including capability libraries, record and optional package scripts.
+Validation checks the optional theory manifests and canonical curriculum parity.
+Pack checks require public docs and reject any optional package bytes in the
+npm kernel. The installed kernel acquires an exact, self-contained Git fixture
+through direct and catalog routes, checks its tracked source alias, then removes
+the fixture checkout. Probes verify local reference closure, alternative-theory
+isolation, discovery, scaffold and retirement in Git and directory scopes without
+launching models. Publication
+remains gated on the exact tag's build/test/smoke results and Desktop artifacts;
+already-versioned candidates remain safe with `--allow-same-version`.

package/docs/release-notes/v0.23.1.md

@@ -0,0 +1,97 @@
+# OATS v0.23.1 — external OKF v2 integration
+
+This patch integrates the published **oats.okf 2.0.0** Git package, tagged at
+`4b6d861ce44e5662303e150cc85095d0eb00d7e7`, following the published OATS 0.23.0
+prerequisite. The checked-in mirror records verified remote tag/object and
+payload provenance. Updating OATS alone does not change existing exact locks,
+activate capabilities, migrate knowledge or install a host timer.
+
+## External OKF v2 integration
+
+The framework mirror follows the standalone package's **only exported
+capability**, `oats-package/capabilities/oats-okf/`. OATS >=0.23.0 supplies the
+generic directory-work and public capture/recall/CLI boundaries; OKF uses no
+private kernel imports. V0.23.1 prepares the framework catalog for OKF 2.0.0,
+without changing an existing deployment's exact lock or activation.
+
+This is a **breaking capability upgrade**, independently versioned from the
+framework patch:
+
+- Explicit absolute `bindings-file` settings, external Git/directory bases,
+  `soul/okf.json` owner declarations and accepted `okf-base.json` node metadata.
+- Index-first immutable reader views, with an instructional no-write boundary,
+  not an OS sandbox or new ACL. `owns` routes responsibility and `reads` selects
+  starting context; every configured base remains discoverable/readable.
+- Durable per-source notes **and full record windows**, frozen destinations,
+  independent directory workers and source jobs that survive home retirement.
+  Final capture must certify custody before the source home can disappear.
+- Git delivery is PR-only, with verified native commit/push/PR receipts and
+  separate merge-visible acceptance. Plain-directory delivery uses cooperative
+  locks, baseline comparison, a recoverable publication journal and validated
+  receipts, without Git/gh. Multi-base delivery is not a distributed transaction.
+- Working agents capture; service workers judge. No automatic edits to soul
+  skills, direct accepted-base edits by readers or attached source-branch
+  promotion commits.
+
+## Inspection and complete pipe output
+
+The v2 inspection surface restores labeled live `STATE.md`, `log.md` and sorted
+Markdown notes alongside durable processing receipts. Home-pointer and instance
+identity checks prevent a retired, missing, reused or unverified home from
+supplying another source's live documents. `liveMemory` reports availability,
+reason and observation time; durable bindings, registered view receipts and
+scheduler diagnostics remain available independently.
+
+Inspection keeps its explicit **256 KiB per-document preview**, with
+`truncated`/original `bytes` metadata. The complete JSON envelope drains stdout,
+including large documents and receipts. Provider `read` returns full Markdown;
+record transport retains full returned evidence, not an inspection preview.
+Descriptor-selected `read`/`refresh` always writes new immutable views under
+source state, never the invoking repository or a deleted/replacement home.
+
+Regression qualification must retain behavioral coverage, including large
+piped documents, live identity failures, durable inspection after disappearance,
+external view placement and full native record backlog. Scaffold tests establish
+layout/custody, not that a model learned.
+
+## Git distribution, not an npm payload shortcut
+
+Users acquire `oats.okf` through the catalog's exact Git payload and explicitly
+review/trust executable surfaces. The npm bundled mirror is **not a
+self-contained Git distribution**: npm omits the worker soul's tracked
+`CLAUDE.md -> AGENTS.md` symlink. Do not synthesize source aliases, weaken
+integrity rules or advertise copying that mirror as a complete package.
+
+The optional `oats.knowledge-theory` catalog entry uses the already published
+**v0.23.0** source (package 1.0.0), avoiding a forward reference to an unpublished
+tag. The current Git source additionally contains the 1.0.1 authoring-reference
+patch, available through an explicit v0.23.1 Git source after publication.
+Its payload stays in the repository's `oats-package/` Git subtree,
+not the kernel npm tarball. It exports authoring resources and
+`knowledge-theory-expert`, without a knowledge-layer binding, mandatory runtime
+injection or OKF dependency. Canonical references and copied local curriculum
+must stay synchronized. Acquisition alone activates nothing.
+
+## Migration and verification
+
+Follow [the v1 preservation and cutover guide](../knowledge-migration.md):
+inventory active writers, preserve legacy knowledge/state/cursors, provision
+empty owned nodes, stage and deliver through the provider, confirm acceptance,
+then deliberately cut over owner declarations and existing sources. Old
+watermarks are evidence, not v2 processing proof. No automatic migration deletes
+legacy material or leaves a knowledge symlink in the soul.
+
+Qualification includes the standalone suite against the actual published
+minimum kernel, strict byte/mode/symlink mirror verification, framework regression
+and installed-tarball Git acquisition probes. Iterative independent review
+covered custody, interrupted publication, source retirement and rejected-PR
+recovery. Separate real Pi learning after source/transcript deletion and actual
+GitHub PR merge/reconciliation/fresh-view acceptance were verified; scripted
+transport and model-learning evidence are kept distinct.
+
+The normal tag-driven release still gates npm publication on all tests and
+Desktop build/smoke legs. Live deployment and explicit knowledge cutover remain
+separate operations, not side effects of package acquisition.
+
+See [knowledge runtime documentation](../knowledge.md) for settings, lifecycle,
+commands, custody and recovery boundaries.

package/docs/schedules.md

@@ -44,9 +44,10 @@ and no queue.
 - **command** `{id, enabled, cron, tz, kind: "command", cwd, argv}` — runs
   an oats-only argv (`argv[0]` is `oats`, no shell) in `cwd`, which must be
   inside the workspace. The runner parses the command's envelope and tracks
-  any instance it names, so `["oats", "okf", "harvest"]` run in a source
-  instance's home is followed until the harvester it spawned is gone.
-  Command return is not task completion.
+  any instance it names. A provider can return an independent worker launched
+  from durable context; the job follows that worker until its home is gone.
+  Command return is not task completion. Avoid binding durable work to a
+  disposable source-home cwd; see [OKF v2 source jobs](#okf-v2-source-jobs).
 - **wake** `{id, enabled, cron, tz, kind: "wake", home, message}` — every
   due minute inspects the instance at `home` through its session receipts.
   Running: `message` is delivered once with `session input`. Not running
@@ -150,3 +151,41 @@ saves a wake job `wake-<instance>` bound to the new home after the spawn
 succeeded. If the spawn succeeds but the save fails, the spawn result still
 carries the full instance receipt, plus `wakeScheduleError` and a warning;
 the instance is neither hidden nor spawned again.
+
+## OKF v2 source jobs
+
+The [prepared OKF v2 runtime](knowledge.md) registers **one command job per
+source**, not a fleet sweep or a home-bound operation job. It runs from stable
+deployment context with argv equivalent to:
+
+```text
+oats okf run-source --source /absolute/state/sources/UUID/source.json --soul domain-expert --json
+```
+
+The descriptor and captured evidence live outside the disposable source.
+Registration (including explicit harvest after source migration) idempotently
+creates/verifies the definition; setup failures are reported for retry. A
+pre-existing disabled job is not silently re-enabled. Command execution clears
+invoking-instance identity and still passes normal capability activation/trust
+gates after source retirement.
+
+No timer is installed by registering a source or its job. An operator can
+inspect or explicitly install one from deployment context:
+
+```bash
+oats okf inspect --source /absolute/state/sources/UUID/source.json --soul domain-expert --json
+oats okf setup --source /absolute/state/sources/UUID/source.json --soul domain-expert --json
+# Explicit host change; never part of a scaffold-only test:
+oats okf setup --source /absolute/state/sources/UUID/source.json --install-host --soul domain-expert --json
+# Definition-only disable; does not stop a worker or reconcile an executing job:
+oats okf setup --source /absolute/state/sources/UUID/source.json --disable --soul domain-expert --json
+```
+
+Retirement captures/enqueues final evidence and does not synchronously remove
+its job under the scheduler's host lock or wait for a model/GitHub. A drained
+retired source returns empty; disable its job explicitly when appropriate.
+Source no-launch guards prevent automatic model starts, and final capture of
+a no-launch source disables its automatic processing. `inspect` distinguishes
+job definition from actual timer activity; an absent or inactive timer is not
+reported as enabled automation. The scheduler's launch/liveness receipts do not
+replace OKF's processing, delivery and merge-visible acceptance receipts.