@awebai/oats 0.48.0 → 0.49.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/bin/oats.mjs +226 -14
  2. package/docs/capabilities.md +256 -8
  3. package/docs/capability-manifest.schema.json +18 -5
  4. package/docs/configuration.md +6 -0
  5. package/docs/desktop-cli-api.md +368 -31
  6. package/docs/desktop.md +72 -5
  7. package/docs/execution-targets.md +17 -2
  8. package/docs/implementation.md +62 -1
  9. package/docs/integrations.md +7 -5
  10. package/docs/knowledge.md +167 -197
  11. package/docs/official-catalog.md +2 -2
  12. package/docs/packages.md +8 -8
  13. package/docs/release-notes/v0.49.0.md +770 -0
  14. package/docs/schedules.md +62 -39
  15. package/docs/servers.md +7 -0
  16. package/docs/souls-and-instances.md +381 -53
  17. package/docs/workspaces.md +2 -2
  18. package/injects/work-checkout.md +17 -11
  19. package/injects/work-worktree.md +19 -13
  20. package/lib/capability-contract.mjs +100 -11
  21. package/lib/capability-show.mjs +5 -2
  22. package/lib/core.mjs +1109 -321
  23. package/lib/instance-events.mjs +6 -3
  24. package/lib/instance-git.mjs +11 -5
  25. package/lib/instance-inspect.mjs +14 -3
  26. package/lib/instance-lifecycle.mjs +106 -16
  27. package/lib/instance-resolution.mjs +15 -3
  28. package/lib/launch-prompt-policy.mjs +17 -3
  29. package/lib/packages.mjs +1 -0
  30. package/lib/real-path.mjs +27 -0
  31. package/lib/resolve.mjs +4 -4
  32. package/lib/retire-output.mjs +6 -1
  33. package/lib/schedule.mjs +1 -0
  34. package/lib/servers.mjs +32 -6
  35. package/lib/tree-copy.mjs +18 -7
  36. package/lib/triggers.mjs +201 -65
  37. package/lib/workspace.mjs +20 -5
  38. package/lib/worktree-hooks.mjs +392 -0
  39. package/lib/worktree.mjs +655 -0
  40. package/package-catalog.json +1 -1
  41. package/package.json +1 -1
package/docs/knowledge.md CHANGED
@@ -2,65 +2,63 @@
2
2
 
3
3
  The **knowledge slot** gives a working soul durable, reviewed expertise:
4
4
  decisions and their rationale, rejected alternatives, discovered limits. The
5
- kernel owns the slot, its configuration and command dispatch; the capability
6
- that fills it owns the format, the instructions and how knowledge is promoted.
7
- The model is in [Knowledge, instances and evolving expertise](knowledge-theory.md).
5
+ kernel owns slot selection, composition and command dispatch; the capability
6
+ owns its knowledge format, instructions and promotion procedure. The model is
7
+ in [Knowledge, instances and evolving expertise](knowledge-theory.md).
8
8
 
9
- This page is the operator guide for the default filler, the `oats.okf` package.
10
- Its runtime internals (custody, publication, locks) are in the
11
- [oats-okf README](https://github.com/awebai/oats-okf).
9
+ This is the operator guide for **oats.okf 5.0**. Provider implementation and
10
+ recovery details belong to the [oats-okf README](https://github.com/awebai/oats-okf).
12
11
 
13
12
  | Surface | What it holds |
14
13
  |---|---|
15
- | Accepted bases (Git or directory) | Soul knowledge: OKF concepts in nodes, each node owned by one soul. |
16
- | `souls/<name>/okf.json` | The nodes the soul owns and reads. |
17
- | Instance home: `STATE.md`, `log.md`, `notes/` | Instance knowledge. |
18
- | The bindings file and its `stateDir` | Where each base lives on this machine; durable harvest evidence. |
14
+ | Accepted Git or directory bases | Soul knowledge: OKF concepts in owned nodes. |
15
+ | `souls/<name>/okf.json` | The soul's stable owner and owned/read nodes. |
16
+ | Instance home: `STATE.md`, `log.md`, `notes/` | The instance's working knowledge. |
17
+ | Bindings file and `stateDir` | Host base locations and consultation/binding state, not a harvest queue. |
19
18
 
20
19
  ## Setup
21
20
 
22
21
  ### Pin and select the package
23
22
 
24
- The workspace pins the package and fills the slot for every soul by default:
25
-
26
23
  ```yaml
27
24
  # oats-workspace.yaml (excerpt)
28
25
  packages:
29
- oats.okf: v4.1.1
26
+ oats.okf: v5.0.0
30
27
  defaults:
31
28
  knowledge: { oats.okf: { from: package } }
32
29
  stores:
33
30
  org: git:github.com/acme/knowledge
34
31
  ```
35
32
 
36
- - `oats sync` locks the pin. `oats spawn <soul> --preview --json` shows the
37
- module a soul resolves and its merged `settings.oats.okf`.
38
- - A soul without knowledge says `knowledge: none`.
39
- - `stores:` names the workspace's knowledge repositories; the kernel validates
40
- them as repo refs. oats.okf does not read `stores:`: the bindings file says
41
- where each base lives.
33
+ `oats sync` locks the package. `oats spawn <soul> --preview --json` shows the
34
+ resolved module and merged settings. Membership in the package's repository
35
+ does not supply the package capability: the workspace pin does.
42
36
 
43
- Each machine points the package at its bindings file in `oats-local.yaml`:
37
+ A soul without knowledge says `knowledge: none`. `stores:` names workspace
38
+ repositories; oats.okf reads its **bindings file**, not that block, to locate
39
+ bases. Each deployment supplies host paths, for example:
44
40
 
45
41
  ```yaml
46
- # oats-local.yaml (excerpt)
42
+ # oats-local.yaml (excerpt; replace the example paths)
47
43
  settings:
48
44
  oats.okf:
49
- bindings-file: /Users/ana/.oats/okf-bindings.json
50
- state-dir: /Users/ana/.oats/okf
45
+ bindings-file: /absolute/okf/bindings.json
46
+ state-dir: /absolute/okf/state
51
47
  ```
52
48
 
49
+ Upgrading an existing deployment requires the ordered
50
+ [5.0 cutover](release-notes/v0.49.0.md#oatsokf-50-cutover--order-matters), not
51
+ just editing a version line.
52
+
53
53
  ### Bindings document
54
54
 
55
- Capability-owned JSON at an absolute path; relative paths inside it resolve
56
- from its own directory:
55
+ Capability-owned JSON at an absolute path; relative paths inside resolve
56
+ from the document's directory:
57
57
 
58
58
  ```json
59
59
  {
60
60
  "version": 1,
61
- "stateDir": "../durable-okf-state",
62
- "cron": "*/15 * * * *",
63
- "tz": "UTC",
61
+ "stateDir": "./state",
64
62
  "bases": {
65
63
  "project": {
66
64
  "id": "project-knowledge",
@@ -75,236 +73,208 @@ from its own directory:
75
73
  }
76
74
  ```
77
75
 
78
- - **The `id` must match the base.** The alias (`project`) is yours, and souls'
79
- `okf.json` names it. The `id` must equal the `id` in the base's
80
- `okf-base.json` at its root (here `knowledge/okf-base.json`), or every read
81
- of that base fails with `E_BASE` ("base identity/nodes mismatch").
82
- - **Git bases** (HTTPS, SSH or a durable local repository; `root: "."` for a
83
- dedicated repository) are delivered to only by same-repository PR, through
84
- `git` and `gh`. A URL with embedded credentials is refused.
85
- - **Directory bases** need no Git and must not sit inside a Git working tree.
86
- - **Paths** are physical and nonoverlapping: state outside every base and
87
- instance home, the bindings file outside state and bases.
88
- - `stateDir` holds per-source evidence and the consult cache; `cron` and `tz`
89
- schedule each source's harvest job (defaults shown).
90
- - Every base must be usable at spawn: one bad base blocks every knowledge-slot
91
- spawn on the machine, and the error names its alias.
76
+ - The alias (`project`) is local to the bindings and is named by souls'
77
+ `okf.json`. Its `id` must match `okf-base.json` at the base root or reading
78
+ that base fails with `E_BASE`.
79
+ - Git bases may use HTTPS, SSH or a durable local repository; `root: "."`
80
+ means the whole repository. Embedded credentials are refused. Harvest
81
+ proposals use same-repository GitHub PRs through ordinary `git` and `gh`.
82
+ - Directory bases need no Git and must not sit inside a Git worktree. They
83
+ support consultation and explicit provisioning/migration, **not automatic
84
+ harvest publication**. The 5.0 harvester reports directory harvest as
85
+ unsupported and names the Git/PR remedy.
86
+ - Paths are physical and nonoverlapping: state is outside every base and
87
+ instance home; the bindings document is outside state and bases.
88
+ - `cron` and `tz` are removed: the provider no longer schedules harvest.
89
+ - A bad configured base blocks a knowledge-slot spawn; the error names the
90
+ alias. Spawning never bootstraps an empty accepted base as a fallback.
92
91
 
93
92
  ### Settings
94
93
 
95
- `oats.okf` declares seven settings; the harvester capability declares one.
94
+ The knowledge capability declares four host settings:
96
95
 
97
96
  | Setting | Default | Meaning |
98
97
  |---|---|---|
99
- | `bindings-file` | none (required) | Absolute path of the bindings document. |
100
- | `state-dir` | none | Absolute path; required by the package's readiness check. Evidence lives at the bindings `stateDir`. |
101
- | `harvest` | `off` | The harvest switch, a host setting ([below](#the-harvest-switch)). |
102
- | `harvest-runtime` | `pi` | The harvester's harness: `pi`, `claude` or `codex`. |
103
- | `harvest-model` | the harness default | A model pin for the harvester. |
104
- | `git-timeout` | `600` | Seconds for each remote Git operation. |
105
- | `consult-max-age` | `300` | Seconds a cached accepted commit may age before a consult refetches; `0` always refetches. |
106
- | `harvester-max-age` (`oats.okf-harvest`) | `7d` | How long a harvester waits for its PR before it retires. |
107
-
108
- Host facts go in `oats-local.yaml` `settings.oats.okf`; a soul's `knowledge:`
109
- payload carries only what is true of all its instances, such as
110
- `harvest-runtime` or the harvest opt-out.
98
+ | `bindings-file` | required | Absolute path to the bindings document. |
99
+ | `state-dir` | required by portable binding preparation | Absolute host-owned state location, never derived from an instance home. |
100
+ | `git-timeout` | `600` | Seconds allowed for a remote Git operation. |
101
+ | `consult-max-age` | `300` | Maximum cached accepted-commit age before refetch; `0` always refetches. |
102
+
103
+ Host `harvest`, `harvest-runtime` and `harvest-model` are removed, including
104
+ explicit `harvest: off`. A 4.x **recorded manifest default** is ignored by
105
+ 5.0 readers as nobody's decision, not reinterpreted as an opt-out. Explicit
106
+ removed keys still refuse and name the fix. The harvester has no provider
107
+ runtime/model switch or PR-wait deadline; it uses ordinary kernel/harness
108
+ selection and retires after its handoff.
111
109
 
112
110
  ## The soul's okf.json
113
111
 
114
- Each soul that uses oats.okf has an `okf.json` beside its `soul.yaml`:
112
+ Every working soul using oats.okf has `okf.json` beside `soul.yaml`:
115
113
 
116
114
  ```json
117
115
  { "version": 1, "owner": "domain-expert", "owns": ["project/expert"], "reads": ["project/steward", "team/operations"] }
118
116
  ```
119
117
 
120
- - `owner` is the soul's stable owner ID, which the base's `okf-base.json`
121
- names as the owner of each of its nodes.
122
- - `owns` lists the `alias/node` destinations the harvester may write; `reads`
123
- lists the nodes the soul consults first. **Neither is an access control
124
- list:** every configured base is readable.
125
- - A missing `okf.json`, base metadata or index fails the spawn; nothing is
126
- bootstrapped empty. A legacy `soul/knowledge/` fails it with a migration
127
- diagnostic.
118
+ `owner` is the stable owner ID named by the base metadata. `owns` lists
119
+ `alias/node` proposal destinations; `reads` is the starting consultation
120
+ context. Neither is an access-control list: every configured base is
121
+ readable. Missing declarations, base metadata or indexes refuse spawn;
122
+ legacy soul-local knowledge needs explicit migration, never silent copying.
128
123
 
129
- `oats okf init` creates a base ([operator commands](#operator-level-commands)):
130
- a directory base directly (`--confirm`), a Git base as a proposal (`--output`)
131
- that you merge through a PR.
124
+ `oats okf init` provisions a new directory base with `--confirm`, or stages a
125
+ Git base with `--output` for reviewed delivery. Existing knowledge is never
126
+ overwritten by initialization.
132
127
 
133
128
  ## The harvest switch
134
129
 
135
- Harvest is off unless the **host** switches it on:
130
+ **There is no host harvest switch in 5.0.** The sole remaining choice is the
131
+ soul's opt-out:
136
132
 
137
- | Where | Setting | Effect |
138
- |---|---|---|
139
- | `oats-local.yaml` | `settings.oats.okf.harvest: on` (default `off`) | This host harvests the working souls it spawns. |
140
- | `soul.yaml` | `knowledge: { harvest: off }` | This soul is never harvested. The opt-out is absolute. |
141
-
142
- - A soul can only opt out. A soul's `harvest: on` is ignored with a warning,
143
- and keeps that soul off until the line is removed. An unreadable opt-out
144
- counts as off.
145
- - **Off means no capture at all:** no source, custody or schedule, and no
146
- final capture at retire. A manual `oats okf harvest` answers
147
- `E_HARVEST_OFF`. Consultation works either way.
148
- - On applies to new spawns. Off (host or soul) stops capture at a source's
149
- next scheduled run; evidence already in custody stays.
150
- - `oats okf setup --harvest on|off` writes the host setting;
151
- `oats okf harvest-status` reports the effective value, the row that decided
152
- it and the registered sources.
133
+ ```yaml
134
+ knowledge: { harvest: off }
135
+ ```
153
136
 
154
- ## Knowledge operations
137
+ That soul keeps consultation and working-memory guidance, receives no
138
+ checkpoint-harvest directive, and its material is refused by the
139
+ harvester's required spawn hook. Absence gives the normal proposal flow.
140
+ A soul's `harvest: on` is not a replacement switch. Host cleanup never
141
+ changes the soul declaration. `knowledge: none` removes the layer entirely.
155
142
 
156
- The rationale is in the
157
- [knowledge-operations design record](design/2026-09-26-okf-knowledge-operations.md).
143
+ ## Knowledge operations
158
144
 
159
145
  ### The flow
160
146
 
161
- 1. **Consult.** A working instance reads its soul's bases remotely at their
162
- accepted state (no local copy): at task start, after compaction and before
163
- decisions. It keeps its own `STATE.md`, `log.md` and `notes/`, and never
164
- writes accepted knowledge (an instruction boundary, not a sandbox).
165
- 2. **Capture** (harvest on). Spawn registers a durable source outside the home
166
- and a scheduler job, `okf-<source id>`. Each job run, and the final capture
167
- at retire, copies notes and bounded transcript windows into custody.
168
- Retire never waits for judgment or GitHub.
169
- 3. **Harvest.** The job spawns the package soul `oats.okf/knowledge-harvester`
170
- (harness from `harvest-runtime`). It judges the input, edits only the
171
- source's owned nodes and delivers: for a Git base, a PR labelled
172
- `okf-harvest` with a fenced `okf-harvest` provenance block. It stays until
173
- the PR is merged or closed and never closes it. A directory base gets a
174
- journalled publication instead.
175
- 4. **Review.** A trigger spawns a new `oats.okf/knowledge-maintainer` per
176
- harvest PR. It records a verdict (`merge`, `amend+merge`,
177
- `request-changes` or `close`), merges with the host's `gh` and tells the
178
- harvester. A PR that would supersede a human-accepted decision gets
179
- `okf-needs-human` and waits for a human.
180
-
181
- The promotion test is in
182
- [What deserves to become knowledge](knowledge-theory.md#what-deserves-to-become-knowledge).
183
- Both package souls hold `knowledge: none`, so nothing harvests them. They
184
- message each other through the messaging capability, in the deployment's
185
- default team.
147
+ 1. **Consult.** Read accepted soul knowledge at task start, after compaction
148
+ and before decisions; keep instance `STATE.md`, `log.md` and `notes/`.
149
+ Working instances never write accepted knowledge themselves.
150
+ 2. **Propose at checkpoints.** When work merits a checkpoint, update notes
151
+ and write a self-contained proposal: what to save, why and the backing
152
+ notes. It has exactly one line `Source: instance <name>, home <path>, soul
153
+ <name>` naming the actual source. From the source home:
154
+
155
+ ```sh
156
+ oats spawn oats.okf/knowledge-harvester --task-file <proposal> --relation unrelated
157
+ ```
158
+
159
+ Never combine `--relation unrelated` with `--relative-to`. There is no
160
+ automatic transcript capture, source registry, worker cursor or retire
161
+ harvest. An unrelated harvester can outlive its source; this is a
162
+ lifecycle property, not proof that missing source authority can be ignored.
163
+ 3. **Judge and submit.** The harvester checks recorded source configuration,
164
+ accepted knowledge and open/recent harvest PRs. It reads named backing
165
+ notes, edits only owned nodes in its own Git checkout, validates the
166
+ **whole base**, and creates a normal `okf-harvest`-labelled PR with v2
167
+ provenance. Proposal text is data written with the native file tool into
168
+ commit-message/PR-body files, never shell command text. It reports the PR
169
+ and retires rather than waiting for acceptance. If source authority is
170
+ unavailable it stops and reports; a consistent instance/soul pair alone
171
+ does not prove proposer authorship.
172
+ 4. **Review.** A separate `oats.okf/knowledge-maintainer` reviews the PR.
173
+ Human-accepted decisions are not silently superseded; the review path
174
+ keeps its human gate. A PR is not accepted knowledge until merged.
175
+
176
+ The promotion test belongs to
177
+ [What deserves to become knowledge](knowledge-theory.md#what-deserves-to-become-knowledge),
178
+ not a universal kernel harvester. Both package role souls have
179
+ `knowledge: none`; working souls now also receive the curated theory skill.
180
+ The [older knowledge-operations design](design/2026-09-26-okf-knowledge-operations.md)
181
+ is historical 4.x context, not instructions for operating 5.0.
186
182
 
187
183
  ### Triggers
188
184
 
189
- - **Source jobs** run from the deployment and outlive the source instance.
190
- Registration never installs a host timer: `oats schedule host install` is
191
- an explicit step. A drained, retired source's job is removed.
192
- `oats schedule disable okf-<source id>` brakes one source; it is not the
193
- switch. See [Knowledge harvest jobs](schedules.md#knowledge-harvest-jobs).
194
- - **The review trigger** comes from the package template
195
- `oats.okf:harvest-review`: one workspace file
196
- (`oats-triggers/okf-harvest-review.yaml`, `runsOn` the host, `owner` a
197
- GitHub account that can merge on the knowledge-base repo), or
198
- `oats trigger add --from oats.okf:harvest-review --set repo=github.com/<owner>/<repo>`
199
- on one machine. It is independent of the harvest switch. See
200
- [Triggers](schedules.md#triggers) and
201
- [Workspace triggers and schedules](schedules.md#workspace-triggers-and-schedules).
202
-
203
- The setup procedure is the `okf-trigger-setup` skill. Keep harvest off until
204
- its `oats trigger test` passes.
185
+ Only **PR review** is triggered. Use the package template
186
+ `oats.okf:harvest-review` in a workspace trigger file, or
187
+ `oats trigger add --from oats.okf:harvest-review --set repo=github.com/<owner>/<repo>`.
188
+ The `okf-trigger-setup` skill explains setup and testing. Validate the review
189
+ route with `oats trigger test` before relying on automated review.
190
+
191
+ There are no per-source harvest jobs or host-timer installation steps in
192
+ this provider. See [Knowledge harvest and review](schedules.md#knowledge-harvest-and-review),
193
+ [Triggers](schedules.md#triggers) and
194
+ [Workspace triggers and schedules](schedules.md#workspace-triggers-and-schedules).
205
195
 
206
196
  ### Who gets which okf skills
207
197
 
208
- | Capability | Composed into | Skills | Inject |
209
- |---|---|---|---|
210
- | `oats.okf` | every working soul it serves | [`okf-consultation`](../mirrors/oats-okf/skills/okf-consultation/SKILL.md), [`okf-instance-knowledge`](../mirrors/oats-okf/skills/okf-instance-knowledge/SKILL.md) | Consult soul and instance knowledge; capture with judgment. |
211
- | `oats.okf-harvest` | `oats.okf/knowledge-harvester` | `knowledge-theory`, [`knowledge-harvest`](../mirrors/oats-okf-harvest/skills/knowledge-harvest/SKILL.md), `okf-authoring` | A judge; its staged roots are its only write surface. |
212
- | `oats.okf-maintenance` | `oats.okf/knowledge-maintainer` | `knowledge-theory`, [`knowledge-review`](../mirrors/oats-okf-maintenance/skills/knowledge-review/SKILL.md), `okf-authoring`, [`okf-trigger-setup`](../mirrors/oats-okf-maintenance/skills/okf-trigger-setup/SKILL.md) | One PR per instance; never supersede silently. |
198
+ | Capability | Composed into | Skills |
199
+ |---|---|---|
200
+ | `oats.okf` | Working souls it serves | [`okf-consultation`](../mirrors/oats-okf/skills/okf-consultation/SKILL.md), [`okf-instance-knowledge`](../mirrors/oats-okf/skills/okf-instance-knowledge/SKILL.md), `knowledge-theory` |
201
+ | `oats.okf-harvest` | `oats.okf/knowledge-harvester` | `knowledge-theory`, [`knowledge-harvest`](../mirrors/oats-okf-harvest/skills/knowledge-harvest/SKILL.md), `okf-authoring` |
202
+ | `oats.okf-maintenance` | `oats.okf/knowledge-maintainer` | `knowledge-theory`, [`knowledge-review`](../mirrors/oats-okf-maintenance/skills/knowledge-review/SKILL.md), `okf-authoring`, [`okf-trigger-setup`](../mirrors/oats-okf-maintenance/skills/okf-trigger-setup/SKILL.md) |
213
203
 
214
- Working souls get no promotion doctrine: only the harvester judges and only
215
- the maintainer merges. `knowledge-theory` and `okf-authoring` ship as
216
- identical copies in both role capabilities.
204
+ Only the working soul's eligible **spawn brief** gives the proposal-spawn
205
+ command. Shared consultation injects/skills also reach opted-out souls and
206
+ do not unconditionally direct a harvest.
217
207
 
218
208
  ## Inspection and operator commands
219
209
 
220
- - **From an instance home**, `oats okf …` runs the home's copy of the module
221
- with the settings recorded at spawn.
222
- - **From the deployment directory** (holding `oats-local.yaml`), in a shell
223
- where neither `OATS_INSTANCE_HOME` nor `OATS_HOME` is set (either one pins
224
- the command to that instance home), a capability command runs as the soul
225
- `--soul <name>` names, or without it as the first soul that provides the
226
- namespace ([capabilities.md](capabilities.md), `command`). Inside an instance home, a
227
- `--soul` naming another soul is refused (`E_HOME_MISMATCH`). The kernel resolves the
228
- soul as a spawn would, fetches its module at the locked commit into
229
- `<deployment>/.oats/modules/` and runs it with the soul's merged settings
230
- and `OATS_SOUL`, the soul's source at that commit, with the soul's
231
- `OATS_AGENT` and `OATS_SOUL_ID` as its hooks get them.
232
- An unlocked package is `E_PACKAGE_MISSING` until `oats sync`.
210
+ From an instance home, `oats okf …` runs its copied module and recorded
211
+ settings. Pinning a new package does not replace those modules, hooks,
212
+ skills or briefings; even the old home's readiness/binding checks keep its
213
+ old code. Respawn homes that should adopt the new proposal flow.
233
214
 
234
- ### Consult
215
+ From the deployment directory (holding `oats-local.yaml`), with neither
216
+ `OATS_INSTANCE_HOME` nor `OATS_HOME` set, pass `--soul <name>` or use the
217
+ first soul providing that namespace. The kernel resolves and runs its
218
+ locked module with the selected soul's merged payload. An in-home command
219
+ cannot select a different soul (`E_HOME_MISMATCH`). An unlocked package is
220
+ `E_PACKAGE_MISSING` until sync. See [capability dispatch](capabilities.md).
235
221
 
236
- Consult commands read the accepted state, never an open PR. All take `--json`
237
- and `--fresh` (refetch the accepted branch now):
222
+ ### Consult
238
223
 
239
- ```bash
240
- oats okf bases # accepted commit or digest, freshness, validity
241
- oats okf index [--base ALIAS] [NODE] # owned, then read, nodes' indexes
224
+ ```sh
225
+ oats okf bases
226
+ oats okf index [--base ALIAS] [NODE]
242
227
  oats okf cat --base project /expert/decisions/retry-policy.md [--from PATH]
243
228
  oats okf ls --base project /expert/lessons
244
229
  oats okf links --base project /expert/decisions/retry-policy.md
245
230
  oats okf search backoff [--base ALIAS | --all] [--node NODE] [--regex] [--case-sensitive]
246
231
  ```
247
232
 
248
- - They run from an instance home, or from the deployment with `--soul NAME`
249
- and `--home PATH` or `--source FILE` (the source form works after the
250
- instance retired).
251
- - `/node/x.md` is rooted in the base; paths never leave it. A failed fetch
252
- serves the cached commit with `stale: true`.
253
- - `oats okf read` and `refresh` answer `E_REMOVED`: use `cat` and `index`.
254
- - `okf-consultation` teaches navigation, search and citation.
233
+ Commands accept `--json` and `--fresh`. Run from the home, or select a live
234
+ home with `--home PATH` from an operator scope and the appropriate `--soul`.
235
+ There is no `--source` descriptor path, including after retirement. Paths
236
+ are rooted in the base, never outside it. A failed fetch may serve cached
237
+ accepted bytes marked stale. `read` and `refresh` remain removed: use `cat`
238
+ and `index`. The consultation skill teaches navigation and citation.
255
239
 
256
240
  ### Inspect
257
241
 
258
- ```bash
242
+ ```sh
243
+ oats okf inspect --json
259
244
  oats okf inspect --home /absolute/instance-home --soul domain-expert --json
260
- oats okf inspect --source /absolute/state/sources/UUID/source.json --soul domain-expert --json
261
- oats okf harvest-status --soul domain-expert --json
245
+ oats operation run knowledge:inspect --home /absolute/instance-home --json
262
246
  ```
263
247
 
264
- `inspect` is read-only: frozen `owns`, `reads` and bases, the accepted
265
- resolution registered at spawn, durable receipts (capture, processing,
266
- delivery, acceptance) and scheduler health. A live home adds `STATE.md`,
267
- `log.md` and pending notes (256 KiB preview each, `truncated: true` beyond);
268
- a retired home shows durable records only; a harvest-off home shows its
269
- declaration, bases and working memory. `oats operation run knowledge:inspect
270
- --home PATH --json` is the same view through the generic operation interface.
248
+ The view contains the declaration, configured bases and that home's working
249
+ `STATE.md`, `log.md` and Markdown notes. Each document has a 256 KiB preview
250
+ cap (`truncated: true` beyond it), preserving UTF-8 boundaries. It invents
251
+ no capture/processing/acceptance receipts and has no retired-source view.
252
+ `oats okf bases` reports accepted-state freshness and validity separately.
271
253
 
272
254
  ### Operator-level commands
273
255
 
274
- Run these from the deployment with `--soul <name>`:
256
+ From the deployment, with `--soul <name>`:
275
257
 
276
258
  | Command | Purpose |
277
259
  |---|---|
278
- | `setup --harvest on\|off` | Write `settings.oats.okf.harvest` in `oats-local.yaml`. |
279
- | `setup --source FILE [--enable \| --disable] [--install-host]` | Verify, toggle or host-install a source's job. |
280
- | `run-source --source FILE [--manual] [--no-launch]` | Run a source's job by hand; `--no-launch` stops at a scaffold. |
260
+ | `setup --remove-legacy-settings [--plan] [--json]` | Delete only explicit legacy host harvest keys; guard-exempt, plan read-only. |
281
261
  | `init --base ALIAS --nodes FILE (--confirm \| --output PATH)` | Provision a directory base or stage a Git proposal. |
282
- | `migrate …` | Move a legacy `soul/knowledge/` into a base. |
283
- | `unlock --lock PATH --token TOKEN` | Release a directory-base lock of a dead local process. |
284
-
285
- From an instance home, `oats okf harvest [--no-launch]` captures now and
286
- requests a harvester.
262
+ | `migrate …` | Explicitly migrate legacy soul-local knowledge into a base. |
263
+ | `unlock --lock PATH --token TOKEN` | Release the specified dead local process's directory-base lock. |
287
264
 
288
265
  ### Completion and recovery
289
266
 
290
- The harvester completes its run with `oats okf-harvest complete`, which calls
291
- the source's `oats okf complete`. The operator forms are for recovery:
292
-
293
- ```bash
294
- oats okf complete --source /absolute/state/sources/UUID/source.json --run RUN_UUID [--judgment FILE] --soul domain-expert --json
295
- oats okf retry --source /absolute/state/sources/UUID/source.json [--launch | --rejudge | --run ID --rejudge | --adopt-home PATH] --soul domain-expert --json
296
- ```
297
-
298
- `retry` never discards an uncertain delivery; `--rejudge` keeps old proposals
299
- and refreshes only unresolved destinations. After a PR merges, `complete` for
300
- the run without `--judgment` records acceptance. Never remove a pending
301
- directory journal to force progress. Exact recovery, adoption and migration
302
- procedures are in the
303
- [oats-okf README](https://github.com/awebai/oats-okf#independent-worker-and-completion).
267
+ `harvest`, `run-source`, `complete`, `retry`, `harvest-status`, old source
268
+ selectors and harvest setup switches return actionable removal errors.
269
+ There is no replacement completion/settlement engine. Existing 4.x private
270
+ inputs and open PR obligations must be resolved explicitly under the old
271
+ provider before the pin; they are not deleted or re-imported by 5.0. Follow
272
+ the [ordered cutover](release-notes/v0.49.0.md#oatsokf-50-cutover--order-matters), including the host cleanup
273
+ **after** 5.0 sync and **before** new spawns.
304
274
 
305
275
  ## Without a knowledge capability
306
276
 
307
277
  `knowledge: none`, on a soul or as the workspace default, is valid: no OKF
308
- state, instructions or harvest source. Another capability may fill the slot
309
- with its own model ([authoring guide](knowledge-capability-authoring.md)).
278
+ state, instructions or source. Another capability may fill the slot with
279
+ its own model ([authoring guide](knowledge-capability-authoring.md)).
310
280
  Switching slots migrates and erases nothing.
@@ -10,7 +10,7 @@ or workspace membership alone does not make a package official.
10
10
  | package | release | capabilities | package souls |
11
11
  |---|---|---|---|
12
12
  | `oats.framework` | `oats-framework/v1.8.0` (this repository) | `oats.core`, `oats.setup`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
- | `oats.okf` | `v4.1.1` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
13
+ | `oats.okf` | `v5.0.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
14
  | `oats.aweb` | `v1.23.2` | `oats.aweb` (messaging) | |
15
15
  | `oats.engineering` | `v1.9.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
16
16
  | `oats.authoring` | `v1.0.3` | `oats.authoring` | |
@@ -29,7 +29,7 @@ no lock and adds nothing to an existing workspace.
29
29
  ## Find and use packages
30
30
 
31
31
  - A workspace pins an official package by **bare version** in its
32
- `packages:` map (`oats.okf: v4.1.1`); `oats sync` resolves it through the
32
+ `packages:` map (`oats.okf: v5.0.0`); `oats sync` resolves it through the
33
33
  catalog to an exact commit, fetches it, verifies its integrity and locks it.
34
34
  A package outside the catalog is written `git:<repo>@<ref>`. Pinning does
35
35
  not join a team or adopt the publisher's workspace. See
package/docs/packages.md CHANGED
@@ -44,14 +44,14 @@ whole organisation:
44
44
 
45
45
  ```yaml
46
46
  packages:
47
- oats.okf: v4.1.1 # bare version → the official catalog
47
+ oats.okf: v5.0.0 # bare version → the official catalog
48
48
  acme.tools: git:github.com/acme/tools@v0.4.0 # direct ref: git:<repo>@<tag or full OID>
49
49
  ```
50
50
 
51
- - **Bare version** (`v4.1.1`, `4.1.1`, `1.0.0-rc.1`): the id is looked up in
51
+ - **Bare version** (`v5.0.0`, `5.0.0`, `1.0.0-rc.1`): the id is looked up in
52
52
  the official catalog — `package-catalog.json` in the `oats` repo, or the file
53
53
  named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
54
- convention (`v4.1.1` or `oats-framework/v1.8.0`) and the payload path. An id
54
+ convention (`v5.0.0` or `oats-framework/v1.8.0`) and the payload path. An id
55
55
  the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
56
56
  a package outside the catalog"). The catalog is the reviewed official list
57
57
  ([official-catalog.md](official-catalog.md)) and the only way a
@@ -75,7 +75,7 @@ members:
75
75
  - git:github.com/acme/platform
76
76
  packages:
77
77
  oats.framework: v1.8.0
78
- oats.okf: v4.1.1
78
+ oats.okf: v5.0.0
79
79
  oats.aweb: v1.23.2
80
80
  teams:
81
81
  platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
@@ -105,7 +105,7 @@ decision recorded in the lock.
105
105
  $ oats sync
106
106
  workspace acme (github.com/acme/agents @ 3f2a9c1e)
107
107
  members agents ✓↔ (@ 3f2a9c1e) platform ✓↔ (@ 77c0a1b2) billing ✗ (no-backlink)
108
- packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 4.1.1 ✓ (@ e1d604f7)
108
+ packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.0.0 ✓ (@ 12db7749)
109
109
  changed acme.tools — → 0.4.0 (@ 47f4b816)
110
110
  souls 9 discovered (6 members, 1 external, 2 package, 0 disabled here) · 0 private capabilities
111
111
  teams platform (shared) · this deployment's: oats teams
@@ -160,8 +160,8 @@ same workspace commit hold identical locks.
160
160
  "source": "catalog:oats.okf",
161
161
  "url": "https://github.com/awebai/oats-okf.git",
162
162
  "path": "oats-package",
163
- "version": "4.1.1",
164
- "commit": "e1d604f70c5e4cdc39602095f139383e61f69323",
163
+ "version": "5.0.0",
164
+ "commit": "12db77492d92154099e7f1aad60a98b1d47f6631",
165
165
  "integrity": "sha256-…",
166
166
  "capabilities": ["oats.okf", "oats.okf-harvest", "oats.okf-maintenance"]
167
167
  },
@@ -338,7 +338,7 @@ A soul that names one of the package's capabilities with
338
338
  {
339
339
  "policy": "docs/official-catalog.md",
340
340
  "packages": {
341
- "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v4.1.1", "path": "oats-package" },
341
+ "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.0.0", "path": "oats-package" },
342
342
  "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.8.0", "path": "oats-package" }
343
343
  }
344
344
  }