@awebai/oats 0.22.17 → 0.23.0

package/docs/design/package-runtime-api.md

@@ -81,7 +81,7 @@ this contract remains authoritative).
 2. **Spawn** — `oats spawn <agent> ... --json` with the EXISTING flags:
    `--purpose <slug>` (deterministic derived naming
    `<agent>-<purpose>`; no raw instance-name authority), `--parent`,
-   `--repo`, `--work attached|worktree|checkout|workspace`, `--work-dir`,
+   `--repo`, `--work attached|worktree|checkout|workspace|directory`, `--work-dir`,
    `--branch`, `--model`, `--task`/`--task-file` (owner-only tempfiles:
    mode 0600, removed on every outcome). Existing validation and error codes
    (`E_BAD_ARGS`, `E_PARENT_NOT_FOUND`, `E_SPAWN_FAILED`, ...) are part of
@@ -96,8 +96,8 @@ this contract remains authoritative).
    read their settings (e.g. oats.okf's `harvest-model`) from `OATS_SETTINGS`;
    there is NO public resolved-config read command.
 4. **Consumer rules**: a package command executes the CLI at the exact
-   absolute path the dispatcher provides in the **`OATS_CLI_BIN`** environment
-   variable (part of the dispatch env contract, beside `OATS_SETTINGS`), via
+   absolute path the dispatcher or lifecycle runner provides in the
+   **`OATS_CLI_BIN`** environment variable (beside `OATS_SETTINGS`), via
    `execFile` on that path — **never** by resolving `oats` from `PATH` and
    never through a shell: PATH is not a trusted runtime boundary, and package
    commands run in worktrees where it can be shadowed. The consumer parses
@@ -109,6 +109,180 @@ Error codes are part of the contract: `E_USAGE`, `E_BAD_ARGS`,
 `E_RELATIVE_NOT_FOUND`, `E_RELATIVE_AMBIGUOUS`, `E_CAPABILITY_BLOCKED`,
 `E_CAPABILITY_INACTIVE`.
 
+### Directory execution for capability workers
+
+A worker may explicitly select `work: directory` in its packaged `soul.yaml`,
+pass `--work directory` to spawn, or use `spawnInstance(..., {work: "directory"})`.
+This is a generic execution mode, independent of any knowledge provider.
+Consumers using it must declare the directory-mode release as their
+`compatibility.oats` floor, not the older boundary-v1 floor alone.
+
+- `repo` / `--repo` is an **existing config context directory** in this mode,
+  not a Git requirement or an edit target. Relative paths resolve from the
+  agents root's parent; absent a selector it defaults to that deployment scope.
+  The CLI does not substitute its ambient Git checkout. A configured workspace
+  can discover and spawn declared package agents before it has an `agents/` or
+  `local-agents/` directory. Laptop config alone does not declare a deployment.
+- `<home>/work` is a new, owned directory, not a symlink and not a fake Git
+  repository. The kernel creates no branch, copies no source tree, and does not
+  require Git in a non-Git deployment. Git-owned deployment placement still
+  requires readable Git metadata to establish the canonical home location.
+- `--work-dir` / `workDir` and `--branch` / `branch` are contradictory and
+  rejected with `E_BAD_ARGS`, even if empty or inherited from a caller bug.
+  Directory execution never takes ownership of a caller-selected filesystem
+  path. Existing modes retain their Git/context requirements and semantics;
+  failed Git operations never implicitly fall back to directory execution.
+- Canonical `AGENTS.md` / `CLAUDE.md`, skill composition, provider trust,
+  lifecycle hooks, frozen launch recipes, runtime preflight and no-launch
+  metadata are unchanged. Hooks receive `OATS_WORK=directory`, an empty
+  `OATS_BRANCH`, and the context in `OATS_REPO` / `OATS_CONTEXT` at spawn.
+  Worktree-only setup scripts are not run in this mode.
+- Retirement authenticates directory ownership against the independent spawn
+  baseline. Nonempty execution work is preserved in verified recovery custody
+  (`workRecovery.path/work`, with home bytes under `home/`) before removal;
+  post-hook changes produce another verified snapshot. No work is designated
+  disposable in this initial mode, including hook-created work. Symlinks inside
+  work are copied as links, never followed; an exchanged work-root symlink,
+  unsupported filesystem entry, or unverifiable copy fails closed. Recovery is
+  not provider delivery or publication, and retains the existing single-host,
+  quiesced-runtime safety model rather than a hostile-filesystem atomicity claim.
+
+### Lifecycle and scheduled-command context
+
+Lifecycle hooks receive `OATS_CLI_BIN` as the real, absolute `bin/oats.mjs`
+path belonging to the **running kernel**. This is authored by
+`runLifecycleHooks` itself, including direct core callers; neither ambient
+`OATS_CLI_BIN` nor a caller's `extraEnv.OATS_CLI_BIN` can override it. Spawn
+hooks also receive the known agents root as `OATS_ROOT`, rather than an empty
+value or the ambient caller's root.
+
+Scheduled command execution starts without the invoking instance's identity:
+`OATS_INSTANCE`, `OATS_INSTANCE_HOME`, legacy `OATS_HOME`, the `PI_AGENT_*`
+aliases and `PI_AGENTS_ROOT`, plus kernel-authored soul, root, context, work,
+team, capability, operation, settings and lifecycle metadata are removed.
+The command's explicit cwd and selectors (for example `--soul`) determine
+its dispatch; a scheduler invoked from another home must not select that
+home's frozen capabilities/settings. Host configuration (`HOME`,
+`OATS_HOME_DIR`, package catalog configuration) and ordinary credentials are
+preserved. No job schema or knowledge-provider policy is implied by this
+isolation.
+
+### Native record capture result
+
+`oats capture --home <dir>` (also `turn-record capture --home <dir>` and the
+standalone `capture.mjs`) answers **native JSON**, not a Desktop schema-v1
+`{ok,result}` envelope. Do not add `--json`: `--home` already selects JSON.
+Diagnostics go to stderr, including lock contention without `--quiet`.
+Existing home/owner/appended/session boundary fields remain; the outcome adds:
+
+- `status`: `complete`, `skipped`, `held`, `incomplete`, or `failed` (failure
+  takes priority, then skip/held/incomplete).
+- `complete`: true only for a performed pass with no holds, incomplete source
+  records, unattributed candidates or reported errors.
+  An unchanged performed pass may be complete with `appended: 0`.
+- `skipped`: true when another pass owns the capture lock. `lock` then carries
+  holder/liveness/recovery details; no capture or indexing was performed.
+- `held`: count of sessions the underlying pass held pending a timestamp.
+- `incomplete`: count of source files with pending torn, oversized, invalid
+  UTF-8 or otherwise incomplete records; later complete input can recover.
+- `issues`: optional metadata-only diagnostics identifying source paths and
+  reasons; no record bodies are embedded. `unattributed` candidates also make
+  the pass incomplete rather than silently certifying missing source evidence.
+- `failed`: zero on success, nonzero for a capture/read/index/lock-release
+  failure; `error` describes the failure. `appended: null` on a thrown failure
+  means the number appended before the failure is unknown, not zero.
+- `ignored`: count excluded by configured privacy rules, distinct from a
+  whole-pass skip. Home capture pins exactly attributed source files; sharing
+  a Codex day directory does not authorize capturing unrelated records.
+
+Lock skips, held sessions and incomplete input retain exit status 0 (background reconciliation
+must stay nonfatal on contention); errors and failed lock release exit 1.
+Previously captured visible boundaries may still be returned on a skipped or
+held pass. They are **not** evidence that final capture ran. Consumers requiring
+a final pass must check `complete === true`, not exit status or the presence of
+boundaries alone; older results lacking that field cannot certify a pass.
+
+**Snapshot boundary:** completion describes a performed pass over the exact
+attributed source files, not a promise about future appends. Discovery carries
+an open-descriptor-derived identity and content witness through capture-lock
+acquisition. Capture stages bytes from one descriptor and validates that witness
+and source stability **before appending**: replacement, truncation and prefix
+rewrites fail without appending the replacement's bytes. Same-inode append
+growth is allowed only when the witnessed prefix is unchanged. Discovery/read
+failures and files disappearing during the pass fail closed; pending trailing
+records and unattributed candidates cannot certify completion. A retirement
+consumer must first quiesce its writers and then preserve the captured evidence
+under its own durable-input protocol. `complete:true` alone does not mean a
+harvest was delivered or that a consumer stored those inputs. Configured privacy
+exclusions remain exclusions, not an invitation to copy excluded source bytes.
+
+**Native roots:** managed `--home` capture uses independent execution history,
+not the observer's environment or the latest relaunch recipe. New scaffolds
+initialize `<instances>/.oats-native-record/<sha256(canonical-home)>/history.json`.
+Each managed spawn/start/restart writes a separate pending receipt before
+backend dispatch. Inside the backend shell, under the exact environment prefix
+and cwd that will exec the harness, the native recorder atomically replaces
+that receipt with the effective absolute **record locations** and runtime. Only
+these allowlisted locations, home, start id/time and custody state are saved;
+no environment map, credential reference value, task or argv is persisted.
+The saved `instance.json` command/recipe remains a relaunch **template**, not
+execution evidence: use `oats session start`, not a manual shell replay of it.
+
+Location rules at execution are `CLAUDE_CONFIG_DIR/projects` (default exactly
+`$HOME/.claude/projects`), `PI_CODING_AGENT_DIR/sessions` (default
+`$HOME/.pi/agent/sessions`), and `CODEX_HOME/sessions` (default
+`$HOME/.codex/sessions`). Pi's `--session-dir` wins over
+`PI_CODING_AGENT_SESSION_DIR`, which wins over its agent-dir location; Pi tilde
+paths expand against the effective HOME. Relative paths resolve from the source
+home. Existing symlinks resolve at recording time, including existing ancestors
+of not-yet-created roots. Inherited overrides and resolved `fromEnv` location
+inputs are thereby retained **after backend shell startup**, independently of
+later observer/config/reference changes. The recorder runs before the native
+exec; unsupported explicit Pi `--session` or a receipt write failure refuses
+that exec and leaves pending custody, rather than claiming a default root.
+Wrappers must preserve this native storage contract: arbitrary scripts which
+change storage internally cannot be inferred from their executable name.
+
+History is never replaced by a newer runtime selection, truncated with the
+bounded restart log, or deleted with the source home. Capture unions all
+historically recorded locations for each runtime and still attributes every
+file by its own cwd. Missing/unreadable historical roots, unreadable/invalid
+receipts, and pending/unfinished launches fail closed. A newly scaffolded home
+with no managed launches has an authoritative empty managed-launch inventory.
+A legacy home without that scaffold authority cannot acquire proof of its
+**earlier** roots merely by restarting: later starts retain new locations but
+its history remains incomplete. Do not remove pending/history receipts just
+to get a green capture; recovery requires establishing the source inventory.
+
+Standalone fixtures and explicit legacy inventories can opt into
+`capture --home <dir> --current-roots` (`sourceRoots: "current-env"` in JSON),
+or use `sessionsForHome(home, {roots: {cc: [...], pi: [...], codex: [...]}})`.
+Explicit API roots exclude unspecified formats, and every supplied root must
+exist. The CLI fallback uses current environment plus recorded hook/config
+location overrides; `fromEnv` resolves from that **current** base environment.
+Its `complete:true` certifies only that chosen observer-time inventory, **not**
+all historical roots; do not enable it implicitly for final-capture consumers.
+Normal managed reports say `sourceRoots: "launch-history"`. Background capture
+without `--home` retains observer-time discovery (including `.claude*` profiles)
+and optional absent native defaults. Neither fallback introduces knowledge
+policy into the kernel.
+
+**Claude children:** discovery also enumerates the native
+`<project>/<sessionId>/subagents/*.jsonl` layout, including children whose parent
+transcript is absent. Each child requires its own cwd attribution; neither its
+parent's cwd nor its directory supplies missing attribution. Child streams use
+`cc.<sessionId>.<child-file-stem>` (threads
+`cc:session:<sessionId>.<child-file-stem>`) so identical child filenames under
+different sessions cannot collide. Complete native lines are preserved verbatim;
+torn, unstamped or unattributed child evidence blocks certification, and child
+read/discovery failures fail the pass. Ignore rules run before child opens and
+can match its path, filename, qualified id, native child id or parent session id.
+
+**Piped recall:** native `oats recall` JSON responses drain stdout before process
+termination, including large thread windows and individual `--show` records.
+Consumers must still bound their own reads/buffers (use `--ids-only` for sizing);
+a successful producer does not imply an unbounded consumer buffer.
+
 ### Consumer fixture
 
 The engine ships a consumer fixture driving the full oats.okf pattern

package/docs/desktop-cli-api.md

@@ -20,6 +20,14 @@ prints exactly one JSON object on stdout:
 `version` is the installed package's exact semver (e.g. `0.20.0`).
 Desktop 0.22 accepts `desktopApi === 1` and semver `>=0.22.0 <0.23.0`.
 
+Optional features are negotiated from the probe's `features` array. Starting
+an existing home requires `session-start`; named launch configurations and
+runtime/permission overrides require `launch-config`; restarting a running
+home also requires `session-restart`. Desktop checks the corresponding
+`remote` entries before offering these operations for a server. The router
+then probes the execution host before sending a mutation. An absent feature
+means an update is needed; it is not inferred from the version number.
+
 The band is widened one kernel minor at a time, after confirming this v1
 surface is unchanged, and always admits the kernel published by the same
 release — Desktop and the CLI are built from one tag, so a band excluding its
@@ -36,7 +44,65 @@ no progress prose (progress goes to stderr):
 
 ## Mutations exposed to Desktop v1
 
-Only two:
+The commands below use the same envelope. Additional capability operations
+are described in [the operations contract](design/operations-contract.md).
+
+### Existing-home launch and restart
+
+```text
+oats session start --home /absolute/home [--server id] \
+  [--launch-config name] [--runtime pi|claude|codex] \
+  [--model id] [--yolo|--no-yolo] --json
+oats session restart --home /absolute/home [the same options] --json
+```
+
+Desktop addresses the exact existing home from the selected workspace's
+roster. Restart is one kernel command. The kernel owns configuration
+validation, stop observation, the lifecycle lock, launch recovery and session
+metadata. Desktop does not implement restart by retiring and spawning.
+Failure or timeout requires a fresh status check before retrying: a lost
+response does not establish that launch failed.
+
+For a remote home, its saved route supplies the execution host even if its
+registration has subsequently changed. The remote kernel validates the new
+configuration before stopping the current harness. A missing feature fails
+before any stop/start command is sent.
+
+### Launch configurations
+
+```text
+oats launch-config list [--dir /scope | --home /home | --soul name --agents-root /scope/agents] --json
+oats launch-config set name --file /private/definition.json [--keep-env] --dir /scope --json
+oats launch-config remove name --dir /scope --json
+oats launch-config preview (--home /home | --soul name --agents-root /scope/agents --dir /scope) \
+  [--launch-config name] [--runtime runtime] [--model id] [--yolo|--no-yolo] --json
+```
+
+All accept `--server id`. Scope edits follow the registration; inspection and
+preview of an existing home follow its saved route. A local definition file
+is serialized to SSH stdin and read on the host with `--file -`; the local
+filename is never passed to the server as though it existed there.
+
+The list result supplies `context`, `selected` and `configurations`. Each
+configuration has a name, runtime, executable, literal argument array,
+environment, model, permission choice and declaring `source`. Environment
+literals appear as `{ "redacted": true }`; references appear as
+`{ "fromEnv": "VARIABLE_NAME" }`. Optional executable/model/yolo fields can be
+null. An editor must not write redaction markers back. `--keep-env`, with
+`env` omitted from the replacement definition, copies the effective named
+configuration's environment once into the complete replacement.
+
+Preview is read-only and returns a redacted invocation plus `preflight`
+checks. A successful inspection envelope can contain `result.ok: false`:
+the selected launch is not ready. Desktop displays the failed checks rather
+than treating successful inspection as permission to launch. Environment
+references resolve on the execution host at launch, including subsequent
+starts of the saved recipe. Editing a named definition does not change a
+running instance or silently update its frozen launch recipe. Select the
+configuration explicitly on a later start/restart to apply the new definition.
+
+See [launch configuration syntax](configuration.md) and
+[the Desktop start/restart workflow](desktop-instance-start.md).
 
 ### `oats spawn <agent> … --json`
 
@@ -47,7 +113,7 @@ Only two:
 | `instance` | string          | new instance name                          |
 | `agent`    | string          | soul/agent name                            |
 | `home`     | string          | absolute instance home path                |
-| `work`     | string          | work mode (worktree/checkout/attached/workspace) |
+| `work`     | string          | work mode (worktree/checkout/attached/workspace/directory) |
 | `branch`   | string \| null  | work branch when applicable                |
 | `launched` | boolean         | whether a tmux window was started          |
 | `warnings` | string[]        | non-fatal warnings (always an array)       |

package/docs/desktop-instance-start.md

@@ -5,25 +5,61 @@ The Desktop roster is the place to return to it:
 
 - A running row opens its terminal.
 - A stopped row offers **Start…**. Clicking the row opens the same dialog.
+- A running row's action menu offers **Restart with…** to change harness or launch configuration in the same home.
 - The hierarchy's action popover offers **Start…** for a stopped instance.
 - An unknown status is shown as unknown, not as permission to launch another process.
 
-The Start dialog names the existing instance, runtime and host. Enter a model
-or leave the field blank to retain its recorded choice. Available local model
+The Start/Restart dialog names the existing instance, runtime and host. Choose
+a named launch configuration or keep the recorded launch. Without a selected
+configuration, the harness can also be changed directly. A named configuration
+fixes its harness; model and permission choices can override its defaults.
+Enter a model or leave the field blank to use the selected launch's default.
+An old harness's model is not carried to a different harness. Available local model
 suggestions are advisory; a model ID can also be typed. Start uses the saved
 briefing and state in a new harness conversation; it does not resume an old
 harness conversation ID. After the launch appears in the roster, Desktop
 opens the instance's terminal.
 
-If the instance is already running when the dialog checks, its action becomes
+If an ordinary Start dialog finds the instance already running, its action becomes
 **Open terminal**. A failed or timed-out start requires **Refresh status** before
 another attempt, because the launch may have succeeded before the reply was
 lost. Changing workspaces dismisses the dialog and prevents a delayed launch
 reply from opening a terminal in the wrong workspace.
 
+**Restart with…** is explicit: after validating the new configuration, the
+kernel stops the current harness and starts the selected one. It does not
+retire the instance, rerun identity creation or replace its worktree. A stop
+that cannot be confirmed does not authorize another launch. Save in-progress
+work before restarting; the old harness conversation is not transferred to
+another harness.
+
+Restart requests termination and waits for the current process to stop before
+launching its replacement. If stopping times out, it leaves the instance for
+inspection instead of forcing a kill or launching a second harness. OATS
+preserves the home and work; it cannot guarantee that a harness or custom
+wrapper saves all of its in-flight conversation state. Wrappers should
+`exec` the harness or forward termination signals correctly.
+
+**Preview invocation** asks the execution host for the resolved command and
+displays it as text, with environment values redacted. It never launches an
+agent. **Manage launch configurations** in the dialog creates or updates named
+configurations at the displayed scope, including executable/wrapper, a JSON
+argument list, environment references, model and permissions. Saving a
+configuration changes its definition; applying it to an existing home requires
+an explicit Start or Restart. When editing redacted environment values, keep
+**Preserve the saved environment** selected or enter a complete replacement.
+Use the server's workspace to manage configurations defined on that server.
+
 Desktop sends `POST /api/start/<instance>?ws=…&home=…` (and `server=…` for a
 remote instance). The backend resolves that exact roster identity and calls
 `oats session start --home <absolute-home> [--server <id>] [--model <model>] --json`.
+Launch choices add `--launch-config`, `--runtime` or `--yolo`/`--no-yolo`.
+Restart uses `POST /api/restart/<instance>?ws=…&home=…` and the single kernel
+command `oats session restart` with the same selectors and choices.
+Configuration inspection and editing use `POST /api/launch-configs?ws=…`,
+routed through `oats launch-config list/set/remove/preview`. These features
+require the CLI's `launch-config` and `session-restart` capabilities; old
+clients/hosts receive an update explanation instead of unsupported arguments.
 The installed CLI must advertise `session-start`; remote starting also needs
 the remote operation. The execution host checks the actual saved session
 before launch. Desktop does not scaffold a home or execute a launcher itself.

package/docs/execution-targets.md

@@ -148,6 +148,22 @@ and never silently applies a new model to an
 already-running harness. A never-launched legacy Herdr home without a saved
 server endpoint requires that endpoint to be configured before it can start;
 it does not fall back to tmux.
+Directory-mode starts and restarts also authenticate the home and owned work
+root against the independent spawn receipt (mode, canonical home, device/inode
+identities). Checks run before resolving mutable home contents, after **each**
+launch hook/preparation and immediately before backend observations, stops,
+allocations and launch-state writes. A missing/file/symlink/exchanged root or
+mode disagreement fails with `E_WORK_INSPECTION_FAILED`; substituted targets
+are neither followed for launch nor removed for lock cleanup. Restore the
+original owned roots before retrying; pending receipts remain with them.
+These pathname checks are not OS-level exclusion against a concurrent hostile
+filesystem mutation between validation and use.
+
+Managed execution also records independent native transcript-location history;
+the recipe remains a template, not provenance. See
+[Native roots](design/package-runtime-api.md)
+for the exact source and standalone-fallback semantics.
+
 The start opens a new harness conversation on the instance's `TASK.md`; the
 instance resumes its work from its own `STATE.md`, as the knowledge protocol
 prescribes.

package/docs/knowledge-capability-authoring.md

@@ -0,0 +1,98 @@
+# Authoring a knowledge capability
+
+This is the canonical source for the optional `oats.knowledge-theory` authoring
+curriculum. Its linked reference documents form a self-contained local set.
+The released skill includes checked copies of this set; authors and the
+`knowledge-theory-expert` can use it without a framework checkout or network.
+
+## Authority and scope
+
+OATS offers an opinionated reference knowledge theory. Default OKF follows it;
+other capabilities may adopt, adapt, or replace it. The kernel owns generic
+layer selection, configuration, composition, lifecycle, work-mode boundaries
+and executable trust, not a compulsory memory ontology or universal judge.
+
+This guide distills the approved 2026-09-13 knowledge scoping session. The
+reference derivation comes from OATS's knowledge theory; its historical
+references to physical soul bundles are replaced here by external knowledge
+custody. The approved implementation plan settles plain-directory OKF as the
+first non-Git path and keeps Omnigraph an uninvestigated authoring scenario.
+Earlier drafts' open choices are not implementation facts. The curriculum is
+a design/authoring reference, not a claim that all default runtime behavior
+has already shipped. Verify the capability version actually being evaluated.
+
+Every implementing capability supplies its full runtime package: reader tools,
+injections, capture conventions, judgment instructions, harvester if any,
+lifecycle/scheduling machinery, validation, delivery and diagnostics. Reuse
+may be explicit and versioned, never a hidden fetch of mutable doctrine.
+The theory expert advises authors; it does not operate their stores or approve
+their compatibility. Installing the theory package activates nothing.
+
+## Install the optional authoring package
+
+The kernel's npm package ships this public guide and the CLI, **not** the
+optional expert payload. `oats.knowledge-theory` 1.0.0 is distributed through
+this repository's Git `oats-package/` subtree. Git preserves the canonical
+source `CLAUDE.md -> AGENTS.md` symlink; npm omits symlinks, so a partial npm
+copy is not a supported distribution. Acquisition does not repair source
+aliases or relax installed-artifact integrity checks.
+
+Once the immutable framework `v0.23.0` tag is published, select a deployment
+scope explicitly and acquire, then 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
+```
+
+Git sources select `oats-package/` by default and lock the resolved commit.
+The official catalog shortcut may follow after the immutable tag exists; do
+not assume an unpublished catalog pin. For local development, use an explicit
+complete source package path instead. Activation exposes the expert and targets
+the authoring skill, without selecting or replacing a knowledge integration.
+There are no executable surfaces to trust in this package. Installed experts
+use their materialized local curriculum, not this repository at runtime.
+
+## A bounded authoring session
+
+1. **Choose a model.** Read the [reference model](knowledge-reference/model.md)
+   and [adoption choices](knowledge-reference/adoption.md). Record what the
+   author is choosing, not what the kernel supposedly requires.
+2. **Establish real custody.** Fill the [provider map](knowledge-reference/provider-mapping.md)
+   from tool/version evidence. A Git-backed knowledge repository is still Git;
+   a directory implementation must work without Git/GitHub. Do not invent
+   native graph operations to fill gaps in the table.
+3. **Author working behavior.** Use the [reader/capture pattern](knowledge-reference/reader-capture.md).
+   Keep every-session instructions short; load detailed native operations from
+   that capability's own skills.
+4. **Author deliberate judgment.** Use the [harvester pattern](knowledge-reference/harvester.md)
+   if adopting this model. Freeze inputs and destinations before execution,
+   separate semantic outcomes from delivery outcomes, and define recovery.
+5. **Deliver an independently usable package.** Follow [package craft](knowledge-reference/package-craft.md).
+   No path in a released soul or skill may depend on an author's checkout.
+6. **Verify observable outcomes.** Run the relevant [acceptance cases](knowledge-reference/acceptance.md).
+   Structural success is not proof that an agent learned or that a store is safe
+   under crashes. State the limit of each test.
+
+## Hand-off template
+
+- Model: adopt / adapt / alternative; rationale and deliberate departures.
+- Provider and version: verified tools, evidence, unknown guarantees.
+- Responsibility map: who supplies reader, capture, judgment, delivery,
+  lifecycle, scheduling and diagnostics; no unowned runtime step.
+- Custody: named destinations, owner identity, accepted state, concurrency,
+  retry and reader-refresh semantics. No credentials in the report.
+- Proposed artifacts: capability manifest, local resources, instructions,
+  skills, optional agent, hooks/operations and declared trust surface.
+- Verification: tests run, actual receipts/visibility, failures, untested claims
+  and the next required approvals. Do not call scaffold-only an agent trial.
+
+## Maintaining these references
+
+Edit this file and `docs/knowledge-reference/` in the framework source, then
+run `node scripts/check-knowledge-theory-package.mjs --write` from that checkout.
+Run `node scripts/check-knowledge-theory-package.mjs` and
+`node --test test/knowledge-theory-package.test.mjs` to verify parity and the
+installed artifact. These are maintainer commands, not tools required in an
+installed expert's work tree. The copies belong to a package release; edits to
+repository docs do not change any installed capability at runtime.

package/docs/knowledge-reference/acceptance.md

@@ -0,0 +1,108 @@
+# Acceptance cases and evidence
+
+These are reusable authoring cases for the [reference model](model.md), plus
+generic package isolation checks. They are not compulsory theoretical
+conformance tests for an [alternative model](adoption.md). The default OKF
+workstream must exercise both Git and real non-Git custody; Omnigraph is not a
+required dependency. Record provider/kernel versions and checks actually run.
+
+## Package and policy isolation
+
+1. **Acquire without activating.** Install the enumerated payload in a temporary
+   scope. Check exact locks and contained materialized resources. Acquisition
+   alone must not select a layer, create memory, schedule work or expose an
+   undeclared agent. Apply executable trust only if surfaces require it.
+2. **Activate deliberately.** Select only the additive authoring capability,
+   with knowledge/messaging/tasks explicitly disabled. Discover the packaged
+   expert and scaffold without a runtime launch. It gets the authoring skill
+   and complete local references, but no OKF bundle, capture flow or harvester.
+3. **Remove source crutches.** Copy the distribution to a clean source fixture,
+   acquire it, delete that source copy, and scaffold the expert. Follow every
+   local skill/reference link from the installed/materialized artifact. No
+   author checkout, network docs or symlink escaping the capability may be
+   required. Compare the installed bytes with the source release curriculum.
+4. **Respect an alternative.** Activate the authoring aid beside a minimal
+   alternative knowledge capability. Scaffold a working agent: the alternative
+   retains its own injection and layer; no reference doctrine is forcibly added.
+   Remove the authoring activation and verify the alternative still works.
+5. **Retire the probe.** Inspect the created layout and retire only the fixture
+   instance. Packaged soul bytes remain unchanged. Keep fixture HOME, OATS and
+   runtime state isolated; no host timer or real launch is allowed, even when
+   a no-launch spawn runs capability hooks.
+
+Static checks verify manifest shape, symlinks, references and parity. Acquisition,
+composition and retirement tests verify actual kernel behavior. Neither proves
+the expert's reasoning quality or a knowledge store's learning behavior.
+
+## Judgment examples
+
+Use exact supplied evidence and inspect the resulting knowledge, not just
+whether an instruction contains “promotion bar.”
+
+| Evidence | Expected reference-model judgment |
+|---|---|
+| Current task TODO or branch blocker | Drop from durable knowledge; keep task state as appropriate |
+| File inventory or code paraphrase available in seconds | Drop; no expertise added |
+| Verified non-obvious failure mechanism plus durable remedy | Promote scoped lesson, or merge into existing authoritative concept |
+| Existing claim with confirming evidence | Merge provenance; do not create duplicate authority |
+| Verified new behavior contradicts accepted claim | Supersede explicitly with scope/rationale and provenance |
+| Correction to a reusable runbook | Maintain the existing procedure through its approval path |
+| Unverified single observation | Do not strengthen; retain uncertainty or decline promotion |
+| Secret, credential, or third-party message transcript | Exclude; never promote verbatim |
+| Project decision versus task decision with identical wording | Route by jurisdiction; only the future-binding decision may promote |
+| Project-slow roadmap change | Date and maintain under its responsible owner, not a universal expert |
+
+Check both notes and bounded record inputs. Capture everything non-obvious
+without making the source apply the bar; judgment must still be selective.
+Test hostile source text that asks the worker to widen scope or leak secrets:
+only the assigned trusted instructions govern execution.
+
+## Consultation and location
+
+- With two bases, the desktop expert consults its own node and the framework
+  expert's node selectively before answering. Other configured bases remain
+  discoverable; ownership/initial reads are not an ACL. Reading makes no edits.
+- Same leaf names in different bases or repositories remain distinct owners.
+- Missing binding, base or access fails visibly, without an empty substitute.
+  A read never scaffolds a node. A feature-branch change never selects custody.
+- Migration preserves old knowledge and pending inputs until verified cutover;
+  a changed alias cannot redirect a frozen job to another base.
+
+## Real custody and failure
+
+For every applicable row inspect native outputs and receipts, not only exit 0:
+
+| Case | Required observable result |
+|---|---|
+| Embedded Git bundle and dedicated Git repository | Independent accepted-baseline work; validated knowledge-only PR to correct target |
+| PR opened, rejected or failed | Report actual proposal/failure state; no claim of accepted visibility or direct-write fallback |
+| PR merged | Fresh reader after refresh can retrieve accepted knowledge; not merely PR text |
+| Directory outside Git | Real durable native update without `.git`, GitHub, branch or PR dependencies |
+| Concurrent destination writers | Baseline conflict/coordination prevents silent loss; receipts identify outcomes |
+| Failure before publication | Preserved input and retryable staged work, no successful applied receipt |
+| Crash after partial/publication write | Recovery establishes actual state; no duplicated claims or lost input |
+| Retry the same input | Idempotent processing or explicit reconciliation; not duplicate knowledge |
+| All candidates dropped | Durable completed-no-change judgment, not an endless pending input |
+| Truncated, skipped or held capture/window | Incomplete/pending, never a completed watermark |
+| Multiple destinations, one failed | Per-destination truthful results, no fabricated cross-store atomicity |
+
+## Source-independent learning gate
+
+1. Let source instance A encounter a genuinely new, verified, behavior-changing
+   fact or decision absent from the accepted base. Capture notes and/or records.
+2. Preserve bounded evidence and frozen destinations outside A's home/worktree.
+   Remove A through safe retirement before the independent harvest finishes.
+3. Reuse A's display name for a distinct incarnation. Verify A's pending evidence
+   stays attributed to A, not consumed by the new incarnation's job.
+4. Run the independent harvest and inspect its semantic judgment and native
+   delivery result. For Git, merge through the authorized review process; for
+   non-Git, verify durable application and consistency/freshness semantics.
+5. Launch fresh reader B in the selected real runtime with no A home, transcript
+   or hidden conversation context. Ask a task whose answer needs the new fact.
+   Require an answer traceable to accepted knowledge through native retrieval.
+6. Record the evidence, failures and limits. A scaffold-only expert probe or an
+   agent reading the captured input directly does not satisfy this gate.
+
+Live agent trials require separate authorization and an isolated test deployment.
+This curriculum's package tests deliberately never launch a runtime or install
+host timers; maintainers must not report them as successful learning trials.

package/docs/knowledge-reference/adoption.md

@@ -0,0 +1,61 @@
+# Adoption, adaptation and alternative theories
+
+The [reference model](model.md) is OATS's recommendation, not mandatory kernel
+policy. Choosing another model is a supported architectural choice.
+
+| Choice | Author's obligation |
+|---|---|
+| Adopt | Implement and test the reference distinctions using the provider's real native tools |
+| Adapt | Name which distinctions change, why, and what readers/writers can now rely on |
+| Alternative | Describe the replacement model, its own learning/retention/consistency contract and tests |
+
+A graph store can adopt the reference promotion bar without Markdown, YAML,
+`index.md`, branches or a universal harvester API. A capability using continuous
+retrieval without a separate judge might instead choose an alternative model.
+Neither storage choice decides theory. Alternative capabilities still honor
+framework work-mode, package containment, explicit configuration and executable
+trust rules, plus applicable repository governance and credential safety.
+
+## Responsibility boundary
+
+OATS maintains canonical theory and authoring references, plus an optional
+expert. The selected capability supplies *all* runtime behavior: complete
+injections, skills, memory conventions, retrieval, capture, judgment if any,
+lifecycle effects, scheduling, native persistence, validation and diagnostics.
+There is no invisible shared theory layer underneath it. It must be usable
+without the expert running or reference documentation fetched over the network.
+
+The default-theory rework chooses external bases/nodes, instructional
+read/capture-only workers, independent harvesting, PR-only Git delivery and
+real non-Git custody. These are adoption choices, not new mandatory kernel
+fields. OKF-specific files, schemas and validator calls stay in OKF. A
+capability choosing another approach is not rejected for failing an OKF or
+reference-doctrine test that does not apply to it.
+
+## Record the choice
+
+Write a short decision before implementing:
+
+- Which model and whose future behavior it serves.
+- What is memory, knowledge, evidence and accepted state in that model.
+- Which reference distinctions are retained, changed or absent, and why.
+- Who owns runtime instructions and changes to them.
+- Native storage guarantees, known limitations and observable failure states.
+- Behavioral tests for the chosen model plus generic package/lifecycle tests.
+
+Do not label a broken implementation as a deliberate alternative after a test
+fails. Conversely, do not force a genuine alternative to mimic files, PRs or a
+judge it never promised. Evaluate the contract the author actually chose.
+
+## Switching an existing deployment
+
+Installing this authoring package performs no migration and selects no layer.
+A storage or model change in an existing deployment is a separate explicit
+migration: inventory source knowledge and pending evidence, preserve both,
+verify the destination, define translation and exclusions, validate reader
+behavior, then cut over with an observable result. Do not silently discard an
+old soul bundle, let alias edits redirect pending evidence, or initialize an
+empty substitute because a required base cannot be found.
+
+For generic packaging and activation isolation see [package craft](package-craft.md).
+For the reference-model migration and isolation tests see [acceptance](acceptance.md).