@awebai/oats 0.22.19 → 0.23.1

package/docs/first-team.md

@@ -1,21 +1,22 @@
 # Run your first OATS team
 
-Start with one repository and one small, real task. An OATS soul keeps the
-role and knowledge; an instance gets a working session and a Git worktree.
-Review its work, let it promote useful notes, then retire the instance.
+Start with one repository and one small, real task. A soul keeps the role and
+curated skills; an instance gets a working session and repository view. With OKF
+v2, expertise lives in external owned nodes, not the soul or task branch.
 
-This guide follows the published **0.22.0** path exercised on 2026-09-05
-with `oats.dev` 1.0.0, `oats.okf` 1.4.1, `oats.aweb` 1.8.0, and
-`oats.authoring` 1.0.0. The [qualification example](first-team-demo.md)
-records the actual tasks and outcomes. Existing OAS users should follow
-[the migration guide](migration-from-oas.md) first.
+> This guide targets the **v0.23.1 integration of published OKF 2.0.0**, whose
+> published kernel prerequisite is OATS >=0.23.0. Check the matching framework
+> release availability before installation; see [release notes](release-notes/v0.23.1.md).
+> The [qualification example](first-team-demo.md) records real **v1** tasks on
+> earlier versions, not v2 acceptance. Existing knowledge needs
+> [v1 preservation and cutover](knowledge-migration.md), not fresh initialization.
 
 ## Install and choose a scope
 
-Have Node.js 22+, Git, tmux, and an authenticated agent runtime available.
-Launch Pi or Claude Code once yourself to confirm that your chosen model
-works. The current OKF package runs its harvester in **Pi**, including when
-its working agent uses Claude Code, so this configuration needs Pi too.
+Install matching published kernel and Pi adapter releases. Have Node.js 22+, Git, tmux and an authenticated working runtime
+available. OKF's independent worker can use Pi, Claude or Codex; authenticate
+that selected runtime too. Plain-directory knowledge needs no Git/gh, although
+this guide's coding worktree does need Git.
 
 ```bash
 npm install -g @awebai/oats@latest
@@ -23,150 +24,186 @@ pi install npm:@awebai/oats-pi@latest
 node --version
 tmux -V
 oats version
-```
-
-Install matching kernel and adapter versions from the same release.
-
-Use a repository with an initial Git commit. Keep your normal working
-changes committed or otherwise accounted for before giving an agent work.
-The commands below run from that repository:
-
-```bash
 cd /path/to/project
-oats init --package oats.dev --config default
+oats init --raw
+oats install git:github.com/awebai/oats-okf@v2.0.0
 oats list
 ```
 
-Initialization acquires the package closure and writes an editable
-`oats-config.yaml` plus an exact lock. It does not create a team account or
-approve executable hooks. `oats.dev` is our reference development policy;
-edit its team name and provider choices for your own project.
+Use a repository with an initial commit for this coding-worktree example.
+Raw initialization writes editable configuration with integrations disabled;
+installation separately acquires the published OKF 2.0.0 closure and exact lock.
+Neither step approves hooks, authenticates a runtime or joins a team. Inspect
+the acquired version before continuing. An existing development template or
+lock may still select v1: follow explicit preservation/update/cutover instead
+of applying fresh initialization or carrying v1 knowledge settings into v2.
 
-For several repositories, initialize their common workspace directory
-instead. Run create/spawn/retire with `--dir /path/to/workspace/project` for
-the repository that owns the soul. `oats status --team` at the workspace
-shows the combined roster, but that does not select a repository for spawn.
+For several repositories initialize their common workspace, then select the
+repository owning the soul with `--dir /path/to/workspace/project` for
+create/spawn/retire. A team roster does not select a work repository for spawn.
 
-## Set the model and connect messaging
+## Configure explicit knowledge and optional messaging
 
 Edit the existing entries in `oats-config.yaml`; do not append a second
-`capabilities` block. Set `team.name` to your own team. If you already use
-aw, set `team.id` to its exact existing ID so instances join that team.
-
-Under `capabilities.layers`, configure the model your Pi installation can
-actually use. This example was used in our qualification; replace the
-model if you authenticate through another provider:
+`capabilities` map. This example targets only the source soul for knowledge:
 
 ```yaml
-knowledge:
-  capability: oats.okf
-  from: installed
-  settings:
-    harvest-model: openai-codex/gpt-5.5
-messaging:
-  capability: oats.aweb
-  from: installed
-  global: true
-  souls:
-    memory-harvest: false
-tasks: none
+agent-types:
+  developers:
+    description: Coding experts
+capabilities:
+  layers:
+    knowledge:
+      capability: oats.okf
+      from: installed
+      souls:
+        backend-expert:
+          enabled: true
+          settings:
+            bindings-file: /absolute/config/okf-bindings.json
+            harvest-runtime: pi
+    messaging: none
+    tasks: none
 ```
 
-The `oats.okf` 1.4.1 default harvester model is
-`github-copilot/gpt-5.5`; it will not work without that provider. The
-messaging exclusion above keeps temporary harvesters from creating aliases
-while an identity-retirement issue is being corrected. Workers still get
-messaging identities. With a `souls` exclusion, state `global: true`
-explicitly so scope-level commands such as `oats aweb setup` stay active.
+There is no hardcoded required harvester model in v2: omitted `harvest-model`
+uses the selected runtime's configured default. Choose a model explicitly if
+needed. Source and worker runtimes are independent.
 
-Review and approve the executable capabilities, then check onboarding:
+Review the acquired Git payload and approve executable surfaces:
 
 ```bash
 oats trust oats.okf
-oats trust oats.aweb
-oats aweb setup
-oats doctor
 ```
 
-`oats aweb setup` prints the next step: install the `aw` CLI if needed,
-initialize an identity with `aw init`, then create or join your team. Follow
-that output and rerun setup until it confirms membership. For an existing
-team, join it rather than creating another with the same name. Setup's exit
-status alone does not establish that onboarding finished.
-
-Messaging is optional. To work without it, set `messaging: none`, omit the
-aweb trust/setup commands, and keep the knowledge configuration above.
-Packages, souls, Git worktrees, and local knowledge do not require hosted
-messaging. See [configuration](configuration.md) for other providers.
+Use the catalog Git package, not the bundled npm mirror: npm omits the source
+worker's `CLAUDE.md` symlink, so the mirror is not a self-contained distribution.
+Acquisition alone is not activation or trust.
 
-## Give an instance a real task
+Messaging is optional. If desired, retain/configure the template's `oats.aweb`
+layer, set `team.name` and any existing `team.id`, then review/trust it and run
+`oats aweb setup`. Follow its install, initialization and create/join instructions
+until it confirms membership. Join an existing team rather than duplicating it;
+setup's exit status alone does not establish onboarding completion. A source-only
+knowledge target does not require the service worker to have a messaging identity.
 
-On 0.22.0, create the roster directory first; a fresh-scope creation fix is
-included in 0.22.1.
+## Create the soul and provision an external base
 
 ```bash
-mkdir -p agents
 oats create backend-expert --type developers --repo . --work worktree --runtime pi
 ```
 
-Edit `agents/backend-expert/soul/AGENTS.md` to describe the role, repository
-conventions, and the checks that matter. Review and commit the new soul,
-configuration, lock, generated ignore rules, and adopted template base under
-`.agents/config-templates/adopted/`. A worktree starts from a Git commit;
-uncommitted soul changes are not present on the worker's branch. Keep aw
-credentials out of Git.
+Edit `agents/backend-expert/soul/AGENTS.md` for the role and required checks.
+V2 does not scaffold knowledge in the soul. For a small local first base, create
+`/absolute/config/okf-bindings.json`:
 
-Then launch one bounded task:
+```json
+{"version":1,"stateDir":"../durable-okf-state","bases":{"team":{"id":"team-knowledge","kind":"directory","path":"../team-knowledge"}}}
+```
+
+Those paths resolve from `/absolute/config`, not the project. Choose durable,
+physical paths outside the source home/worktree and **outside every Git working
+tree**, including ignored directories. State, accepted bases and bindings must
+not overlap. Review [full placement rules](knowledge.md#bindings-document).
+
+Create `/absolute/config/team-nodes.json`:
+
+```json
+{"backend":{"path":"backend","owner":"backend-expert-stable-id"}}
+```
+
+Explicitly provision the new base, refusing any existing destination:
 
 ```bash
-oats spawn backend-expert --purpose first-fix --task "Fix one small issue, run the relevant checks, commit the change, and report what changed. Capture any reusable lesson and harvest it before finishing."
+oats okf init --base team --nodes /absolute/config/team-nodes.json --confirm --soul backend-expert --json
+```
+
+Write `agents/backend-expert/soul/okf.json`:
+
+```json
+{"version":1,"owner":"backend-expert-stable-id","owns":["team/backend"],"reads":[]}
+```
+
+For team-shared Git knowledge instead, follow [Git provisioning](knowledge.md#owner-and-base-descriptors)
+and review/merge its initialization PR before spawning. Git knowledge always
+uses PR delivery, not commits on the coding instance's branch.
+
+Review and commit soul/configuration/lock changes, generated ignore rules and
+the adopted template base under `.agents/config-templates/adopted/`. Keep
+credentials and private durable evidence out of Git. Check `oats doctor --soul
+backend-expert --json`. Configuration and a successful doctor do not substitute
+for accepted-base validation by the required spawn hook.
+
+## Give an instance a real task
+
+```bash
+oats spawn backend-expert --purpose first-fix --task "Fix one small issue, run the relevant checks, commit the code change, and report what changed. Read the relevant accepted knowledge indexes and capture non-obvious lessons in notes."
 oats status --team
 ```
 
-Choose `--runtime claude` at creation for a Claude Code worker. Today its
-first session can require **two interactive confirmations**: folder trust
-and the development-channels confirmation used by the aweb integration.
-Attach to the tmux session printed by spawn and answer them. A created
-window is not evidence that the agent has started working.
+Choose `--runtime claude` or `codex` if preferred. Complete any native folder
+trust, authentication or messaging-plugin confirmations in the printed session.
+A created window is not proof the agent is working.
+
+The instance home is under `agents/<soul>/instances/<instance>/`; `work/` is its
+Git worktree. `knowledge/view.json` identifies immutable accepted snapshots.
+The worker reads indexes selectively, maintains state/log/notes, and never edits
+accepted knowledge. This is instructional, not an OS filesystem sandbox.
+Review its code commits through the repository's ordinary PR workflow.
 
-Each instance has a home under `agents/<soul>/instances/<instance>/`; its
-`work/` directory is the repository worktree. Read the instance's report
-and review its commits there. Agents using aw run coordination commands
-from their own home, which holds their identity.
+## Inspect, judge and retire
 
-## Harvest, review, and retire
+From the source home, read-only inspection shows identity-matching state/log/notes
+plus durable processing receipts:
 
-With OKF active, the worker keeps state and notes in its home. After a
-commit it can run `oats okf harvest` there. If it reports pending notes but
-has not harvested, ask it to do so, or run the command from that instance's
-home yourself. Retirement does not initiate knowledge promotion.
+```bash
+oats okf inspect --json
+```
+
+Spawn registered one per-source command job, but **did not install a host timer**.
+For this first task an operator may request one manual harvest from the source
+home; without `--no-launch` this starts the configured model worker:
+
+```bash
+oats okf harvest --json
+```
 
-The harvester reviews notes, updates the soul's knowledge, and commits the
-promotion into the worker's branch. Let it finish before final review or
-retirement. Review **all** commits, including the promotion, and merge the
-accepted work into the repository's main branch through your normal
-workflow. Then, from the repository scope:
+The worker judges durable notes **and captured record**, in its own directory
+execution space. It leaves live notes and soul skills untouched. Directory
+delivery is recoverable publication with validation and receipts. Git delivery
+requires a real reviewed PR and merge-visible acceptance. Inspect receipts rather
+than equating a worker spawn with learning. See [operator commands](knowledge.md#inspection-and-operator-commands)
+for scaffold-only requests, completion and retry.
+
+Source retirement need not wait for a worker to finish: it must first certify
+final notes/record custody. From the repository scope:
 
 ```bash
 oats retire backend-expert-first-fix
 oats status --team
 ```
 
-Read the retirement result, including any retained home or recovery path.
-With aweb enabled, also inspect `oats aweb roster`: local retirement alone
-is not proof that a remote alias was removed. During the current hosted
-alias-retirement issue, use a fresh purpose for the next instance and have
-the team administrator clear any stale alias before reusing its name.
+Read the retirement result. An uncertified capture retains the home for retry;
+never delete it to bypass recovery. Durable descriptors, evidence and runs survive
+successful retirement. Use `oats okf inspect --source <absolute-source.json>
+--soul backend-expert --json` from deployment context afterward. If messaging is
+active, also verify its retirement receipt and roster rather than assuming local
+cleanup proves identity release.
+
+For automatic future judgment, review [source jobs](schedules.md#okf-v2-source-jobs)
+and explicitly opt into host-timer installation. No-launch tests should never
+install it or enable live model launches.
 
-Start the same soul on the next useful task after its knowledge commit is
-on main. Check that the new instance can find and use the promoted lesson.
-That completes the first lifecycle: useful work, reviewed learning, clean
-local retirement, and a successor with the updated soul.
+After provider acceptance, start a fresh instance of the same soul on a useful
+task. Check that it finds **and uses** the promoted lesson without the original
+source. That is the learning acceptance step; a no-launch reader only verifies
+scaffolding and references.
 
-## Optional conversation record
+## Optional host-wide conversation capture
 
-Knowledge promotion and conversation capture are separate. To enable the
-local transcript record and query it:
+Knowledge judgment and the native conversation record are separate. OKF uses
+source-targeted native capture through the CLI; host-wide watcher/hook setup is
+an additional deliberate operator action:
 
 ```bash
 oats setup
@@ -174,6 +211,5 @@ oats capture --status
 oats recall "a phrase from your completed task"
 ```
 
-Capture reads supported transcripts and aweb logs after setup, subject to
-ignore rules. Native turns are content-addressed; signed aweb messages
-retain their source signatures. See [the turn record](../README.md#the-turn-record).
+Capture respects privacy exclusions. Native turns are content-addressed; signed
+aweb messages retain their source signatures. See [the turn record](../README.md#the-turn-record).

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

@@ -0,0 +1,101 @@
+# 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. 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.
+
+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
+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 `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.
+
+## 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.