@awebai/oats 0.23.0 → 0.23.1

package/docs/integrations.md

@@ -43,6 +43,8 @@ capabilities:
     knowledge:
       capability: oats.okf
       from: installed
+      settings:
+        bindings-file: /absolute/config/okf-bindings.json
     messaging:
       capability: oats.aweb
       from: installed
@@ -65,7 +67,7 @@ capabilities:
 CLI equivalents:
 
 ```bash
-oats use oats.okf --global
+oats use oats.okf --global --settings bindings-file=/absolute/config/okf-bindings.json
 oats use oats.aweb --type product-agents
 oats use oats.linear --type product-agents
 oats use none --layer tasks        # leave an inherited slot deliberately unfilled
@@ -78,11 +80,14 @@ is different from a soul whose type restricts its reach.
 
 ## Bundled integrations
 
-**`oats.okf`** fills `knowledge`: OKF soul bundles, instance `STATE.md`,
-`log.md`, and `notes/`, the `okf` and `memory-harvest` skills, and
-`oats okf harvest`, which promotes pending notes after a commit through the
-capability-defined `memory-harvest` soul. Its scaffold and spawn hooks own
-memory mechanics; the kernel stays knowledge-format agnostic.
+**`oats.okf` v2** fills `knowledge`: external owned OKF bases, immutable
+reader views, instance `STATE.md`/`log.md`/`notes/`, durable notes-and-record
+custody and an independent directory worker. Git delivery is PR-only; plain
+directory delivery is recoverable and needs no Git/gh. Explicit bindings,
+`soul/okf.json` and accepted base metadata are required before a working source
+can spawn. `owns`/`reads` are responsibility/context, not ACLs. See
+[knowledge](knowledge.md) for the **prepared** version scope, provisioning and
+commands, and [migration](knowledge-migration.md) before updating v1.
 
 **`oats.aweb`** fills `messaging`: mints an instance identity at spawn,
 removes it at retire, contributes the aweb messaging and team skills, wires
@@ -117,13 +122,15 @@ kernel only through `OATS_CLI_BIN` and the JSON envelope, never by importing
 kernel files. Never name target souls in the manifest; targeting belongs to
 configuration.
 
-**Knowledge.** Scaffold the soul's store on `soul-scaffold`; create instance
-ephemeral state on `spawn`; teach the read side (index-first, selective,
-binding) in the inject and skill; ship a harvester as a capability-defined
-soul and a command that spawns it attached to the source instance's tree;
-route promotions by custody (commit, pull request, or direct edit); apply the
-promotion doctrine in the contract; and, once the `harvest` event exists,
-declare it instead of relying on the instance to call the command.
+**Knowledge.** Each capability owns its complete runtime and format, including
+reader/capture instructions, judgment and provider-native delivery. Do not
+assume a soul bundle, attached worker, Git store or mandatory shared harvester.
+The optional [authoring guide](knowledge-capability-authoring.md) describes the
+reference model and how to adapt or replace it. OKF v2 is one implementation:
+explicit external ownership, instructional read-only sources, evidence custody
+outside disposable homes, independent workers, PR-only Git and recoverable
+non-Git publication. Existing lifecycle hooks and supported CLI/scheduler
+commands implement it; no proposed universal `harvest` event is required.
 
 **Communication.** Mint an address on `spawn` with a `required` hook and
 remove it on `retire`; supply the roster; teach send, reply, chat, and "read
@@ -140,40 +147,33 @@ Test an integration as a capability package: acquire, lock, trust, activate,
 spawn, retire, with the golden fixtures as the behavior oracle for the kernel
 side.
 
-## oats.okf harvest settings (1.5.1)
+## oats.okf v2 settings and recovery
 
-The harvester can use a different harness from the source instance. Select one
-that is installed and authenticated on the host where the harvest runs:
+V2 requires `bindings-file`, an absolute path to capability-owned JSON. Paths
+inside it resolve from that file's directory. The source soul needs stable
+`owner`, `owns` and `reads` declarations; every referenced accepted node must
+exist and match its owner. Acquisition/activation never bootstraps a knowledge
+base. If activating globally, provision each working soul first or target only
+ready sources.
 
 ```bash
-oats use oats.okf --settings harvest-runtime=claude
+oats use oats.okf --soul domain-expert --settings bindings-file=/absolute/config/okf-bindings.json harvest-runtime=claude
 ```
 
-- `harvest-runtime: pi | claude | codex` defaults to `pi`.
-- `harvest-model` is an optional pin, for example to use a cheaper model.
-  When omitted, each harness uses its configured default. Pi accepts
-  provider/model patterns. Claude and Codex require a native model name
-  (for example `sonnet` or `gpt-5.5`), without a Pi provider prefix.
-
-These settings apply to note and record harvests, including deferred retirement
-and remote harvests. For a remote instance, configure its host's knowledge
-binding; the local viewer does not supply its own provider credentials.
-
-If a record harvester was spawned but did not advance its watermark, planning
-the same windows again warns with that instance and the boundary IDs and skips
-another spawn. Inspect the previous attempt first. `oats okf harvest
---from-record --force` retries those windows explicitly; it still refuses to
-start a second harvester while the first one's home exists. The check uses the
-existing prepared watermark file and does not treat a successful spawn as
-completed learning.
-
-## oats.okf 1.5.2
-
-`okf harvest` exits non-zero when it reports a failure (the plain and the
-`--json` forms alike). A leftover `memory-harvest/<slug>` branch from a merged
-promotion is deleted before the next workspace-mode harvest; an unmerged one
-refuses the harvest and names the remedy. `oats okf harvest --help` prints
-usage and never spawns.
+- `harvest-runtime: pi | claude | codex` defaults to `pi`, independently of the
+  source. Select an installed/authenticated runtime on the execution host.
+- `harvest-model` optionally pins its model. Omitted models use the harness
+  default; native Claude/Codex names are not Pi provider-prefixed patterns.
+- Old record-window settings and `--from-record --force` recovery are not v2
+  interfaces. Every capture takes notes **and** record; use durable run receipts
+  and explicit `retry`/`complete` reconciliation, never old watermark moves.
+
+For remote sources, configure custody and credentials on their execution host,
+not the viewer. One source job continues from stable deployment context after
+retirement, subject to current activation/trust. Timer installation requires
+explicit consent. `inspect` is read-only and combines identity-guarded live
+memory with durable receipts; `--source` remains usable after home deletion.
+[Command and recovery details](knowledge.md#inspection-and-operator-commands).
 
 ## oats.aweb late joins (1.10.3)
 

package/docs/knowledge-capability-authoring.md

@@ -31,14 +31,14 @@ 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
+optional expert payload. The catalog selects `oats.knowledge-theory` 1.0.0
+from the already-published framework v0.23.0 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:
+Select a deployment scope explicitly and acquire the published source, then
+opt in for an author soul:
 
 ```bash
 oats install git:github.com/awebai/oats@v0.23.0 --dir /path/to/scope
@@ -46,9 +46,12 @@ 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 `oats.knowledge-theory` catalog shortcut uses that same published v0.23.0
+source. The current authoring-reference patch is package 1.0.1: once framework
+v0.23.1 is published, an explicit initial Git acquisition at that tag selects
+the patch instead. It does not silently change the catalog's 1.0.0 selection
+or an existing lock. 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.

package/docs/knowledge-migration.md

@@ -0,0 +1,138 @@
+# Migrating OKF v1 knowledge to v2
+
+> **Prepared, not a live migration.** These instructions target oats.okf 2.0.0
+> with OATS >=0.23.0 and the prepared framework v0.23.1 integration. Confirm the
+> final standalone source tag and dependencies are published before following
+> the acquisition path. See [release gates](release-notes/v0.23.1.md).
+
+This is **not** `oats migrate`: kernel lock/package migration and
+[OAS name migration](migration-from-oas.md) do not relocate knowledge, establish
+v2 ownership or preserve source cursors. Nor does upgrading npm activate a new
+knowledge layer. V2 uses external accepted bases and independent workers, not
+`soul/knowledge/`, attached harvest commits or source-home watermarks.
+
+## 1. Inventory and preserve before changing activation
+
+- Record each scope's package lock, active knowledge binding, effective settings,
+  soul instructions/skills and current knowledge bytes. Do not hand-edit locks.
+- Inventory live source homes, state/log/notes, v1 current/prepared watermark
+  files, active harvesters, unpublished commits and open PRs. Resolve or preserve
+  in-flight work deliberately; do not run old and new writers concurrently.
+- Back up source material outside disposable homes/worktrees. Keep v1 artifacts
+  available until accepted delivery, owner cutover and fresh-reader verification
+  have succeeded. A successful scaffold or command exit is not learned expertise.
+- Plan the deployment interruption and test the migration on isolated copies.
+  The required v2 spawn hook refuses a legacy `soul/knowledge/`; it never silently
+  substitutes an empty bundle.
+
+After publication, explicitly acquire/update the catalog **Git** package and
+review/re-trust its executable surfaces. An existing exact lock does not advance
+on bare `oats install`. Do not install the npm bundled mirror as a self-contained
+package: npm drops the source worker's canonical `CLAUDE.md` symlink.
+
+## 2. Bind and provision external destinations
+
+Follow [bindings and owner descriptors](knowledge.md#acquire-bind-and-provision-explicitly).
+Choose stable base IDs, stable owner IDs, nonoverlapping node paths and durable
+`stateDir`. `owns` routes responsibility; `reads` chooses starting context, not
+permissions. Confirm aliases and owners explicitly, rather than deriving them
+from an instance branch or name.
+
+Configure the absolute `bindings-file` for each source soul. Remove obsolete v1
+settings such as `record-window-turns` and `record-window-bytes`; v2 accepts only
+`bindings-file`, `harvest-runtime` and `harvest-model`. Provision **empty owned
+nodes** using `oats okf init`. Accept Git initialization through a reviewed PR
+before migration delivery; directory provisioning requires explicit confirmation
+and a genuinely non-Git location.
+
+## 3. Stage and deliver each legacy bundle
+
+From the durable deployment configuration context in an operator shell without
+inherited instance identity, selecting the source soul:
+
+```bash
+oats okf migrate --legacy /absolute/soul/knowledge --base project --node expert --output /absolute/empty-migration-stage --soul domain-expert --json
+# Use the exact migration.json path returned above:
+oats okf migrate --deliver /absolute/state/migrations/UUID/migration.json --soul domain-expert --json
+```
+
+Staging preserves the full original in migration custody, rewrites bundle-root
+Markdown links into the external node namespace and validates the whole base.
+The output must be disjoint from **every** configured accepted base and directory
+coordination artifact. The destination node must be empty; migration refuses
+ambiguous automatic merges.
+
+Delivery follows the actual provider protocol:
+
+- **Git:** a real PR, never a direct push to the accepted branch. Review and merge
+  it, then repeat `migrate --deliver` to confirm merge-visible acceptance.
+- **Directory:** recoverable publication with a cooperative lock, baseline check,
+  journal and validated acceptance receipt. Resolve any journal before proceeding.
+
+A staged bundle, delivered PR or proposed owner mapping is not cutover.
+
+## 4. Deliberate owner cutover
+
+```bash
+oats okf migrate --cutover /absolute/state/migrations/UUID/migration.json --soul-dir /absolute/soul --soul domain-expert --json
+```
+
+Cutover requires accepted delivery, unchanged legacy bytes and current bindings
+still pointing to the frozen delivered base. It verifies accepted readiness,
+node owner/path and delivered content, then renames the old bundle into durable
+custody and updates `soul/okf.json`. It changes no skills and leaves no permanent
+knowledge symlink in the soul. Cross-device rename fails safely: arrange an
+explicit operator cutover rather than deleting originals to force it. An
+incomplete cutover marker blocks new source registration until that recorded
+cutover is retried.
+
+Explicitly review old soul instruction references to `soul/knowledge/`, direct
+promotion and after-commit harvest. Point readers to the capability-provided
+accepted views; ordinary agents capture but never edit accepted knowledge. This
+instruction review is not an automatic rewrite performed by migration.
+
+## 5. Preserve and re-register existing sources
+
+For every surviving v1 source home:
+
+```bash
+oats okf migrate --source-home /absolute/legacy-instance-home --soul domain-expert --json
+```
+
+This copies allowlisted state/log/notes and old cursors into migration custody,
+**deleting nothing**. Old watermarks are retained as evidence, not trusted as v2
+processing proof. After soul migration, explicit `harvest` from that clean deployment context
+re-registers a source,
+captures visible notes and record, and idempotently verifies its per-source job:
+
+```bash
+oats okf harvest --home /absolute/legacy-instance-home --no-launch --soul domain-expert --json
+```
+
+`--no-launch` is a scaffold-only worker request, not a read-only operation: it
+captures and writes durable state/schedule definitions, but starts no model and
+installs no timer. Existing homes retain their composed capability snapshot;
+plan refresh/replacement or dispatch through the deliberately selected v2
+configuration context. Do not assume updating a package rewrites a running
+home's curriculum, trust or native session. Preserve evidence before retiring
+or replacing any old home. Replay may legitimately produce merge/drop judgments.
+
+## 6. Verify before retiring old custody
+
+Inspect the durable source descriptor and its receipts. Confirm frozen owners,
+accepted view paths, captured notes **and full record windows**, processing and
+provider acceptance separately. Verify live inspection only shows the matching
+source's state/log/notes. After safe source retirement, `--source` inspection and
+read/refresh must still work from durable context; new views belong in state,
+not the deleted home or invoking repository.
+
+Enable a host timer only with explicit operator consent after reviewing source
+jobs and available worker runtimes. Existing no-launch sources cannot cause
+scheduled model launches; do not turn an isolated rehearsal into a deployment.
+A source whose final capture is incomplete must retain its home for retry.
+
+Finally start a fresh, deliberately selected runtime instance and verify it can
+find **and use** the accepted lesson without the original source. A no-launch
+reader verifies layout and links, not model learning. Only then consider old
+custody cleanup under an explicit retention decision; v2 does not automatically
+remove preserved evidence, old views, migration archives or unresolved runs.