@awebai/oats 0.29.4 → 0.30.0

package/capabilities/oats-okf/lib/binding-wire.mjs

@@ -1,5 +1,4 @@
 import { TextDecoder } from 'node:util';
-import { validateInvocationShape } from './invocation-shape.mjs';
 import { tmpdir } from 'node:os';
 import { isAbsolute, join, resolve } from 'node:path';
 import { fs, safePath } from './io.mjs';
@@ -14,7 +13,7 @@ import {
   renderKnowledgeRuntime,
   sameJson,
 } from './portable-binding.mjs';
-import { validateBindings } from './config.mjs';
+import { declaration as soulDeclaration, loadBindings, validateBindings } from './config.mjs';
 import { stageBase, validateBase } from './stores.mjs';
 
 export const BINDING_WIRE_LIMITS=Object.freeze({bytes:1024*1024,depth:32,entries:16384});
@@ -254,14 +253,20 @@ export function loadInvocationKnowledgeBinding(env=process.env) {
 // binding.reasons (byte-exact) — the manifest test pins that.
 const checkReasons=Object.freeze({
   'action:not-admitted':'check action is not an admitted knowledge operation',
-  'bindings:invalid':'bound runtime bindings file is missing or invalid',
+  'settings:missing':'OKF settings missing bindings-file: set settings.oats.okf bindings-file, or deactivate oats.okf',
+  'soul:missing':'OKF soul declaration missing: create okf.json for this soul, or deactivate oats.okf',
+  'harvest-runtime:missing':settingMessages['harvest-runtime:missing'],
+  'harvest-runtime:invalid':settingMessages['harvest-runtime:invalid'],
+  'harvest-model:invalid':settingMessages['harvest-model:invalid'],
+  'binding:not-configured':'OKF binding missing or invalid: provision soul OKF declaration and bindings file, or deactivate oats.okf',
+  'bindings:invalid':'OKF bindings file missing or invalid: repair configured bindings file, or deactivate oats.okf',
   'bases:too-many':'more than 64 git knowledge bases declared',
   'base:stage-failed':'declared knowledge base could not be staged from its git source',
   'base:not-validated':'declared knowledge base is not a validated knowledge tree',
   'base:owner-unmet':'knowledge base owner or remote custody requirement not met',
   'base:source-mismatch':'staged git source does not match the declared knowledge base',
   'runtime:command-missing':'harvest runtime command is not installed on this host',
-  'runtime:not-qualified':'harvest runtime could not be qualified against the accepted bases',
+  'runtime:not-qualified':'harvest runtime is not qualified: install/configure the selected harvest runtime or set harvest off',
 });
 function problem(code,reason) {
   if(reason===undefined) return {code};
@@ -276,15 +281,40 @@ function providerActionName(action) {
   if(typeof action.name==='string' && action.name.startsWith('okf:')) return action.name.slice(4);
   return null;
 }
+function readinessRuntime(settings,env=process.env) {
+  if(Object.hasOwn(settings,'bindings-file')) {
+    try {
+      if(typeof settings['bindings-file']!=='string' || !absolute(settings['bindings-file'])) return {problem:problem('needs-configuration','settings:missing')};
+      if(settings.harvest!==undefined && !['on','off'].includes(settings.harvest)) return {problem:problem('needs-configuration','runtime:not-qualified')};
+      if(settings.harvest!=='off') {
+        if(settings['harvest-runtime']===undefined) return {problem:problem('needs-configuration','harvest-runtime:missing')};
+        if(!['pi','claude','codex'].includes(settings['harvest-runtime'])) return {problem:problem('needs-configuration','harvest-runtime:invalid')};
+        if(settings['harvest-model']!==undefined && (typeof settings['harvest-model']!=='string' || !settings['harvest-model'].trim())) return {problem:problem('needs-configuration','harvest-model:invalid')};
+      }
+      const bindings=loadBindings(settings['bindings-file']);
+      if(!env.OATS_SOUL) return {problem:problem('needs-configuration','soul:missing')};
+      const decl=soulDeclaration(env.OATS_SOUL);
+      return {runtime:{descriptorFile:bindings.file,bindings:{version:1,stateDir:bindings.stateDir,bases:bindings.bases},declaration:decl}};
+    } catch(error) {
+      const message=String(error?.message || '');
+      if(error?.code==='E_CONFIG' && /okf\.json|soul has no/.test(message)) return {problem:problem('needs-configuration','soul:missing')};
+      return {problem:problem('needs-configuration','bindings:invalid')};
+    }
+  }
+  if(settings.schemaVersion!==undefined) {
+    try { return {runtime:bindingPayload(settings,{diagnoseSettings:true}).runtime}; }
+    catch(error) {if(['invalid-binding','needs-configuration'].includes(error?.wireCode)) return {problem:problem('needs-configuration','binding:not-configured')};throw error;}
+  }
+  return {problem:problem('needs-configuration','settings:missing')};
+}
 function checkPhase(req) {
-  keys(req.input,['binding','context','action','invocation'],['binding','context','action'],'check input');
+  keys(req.input,['context','action'],['context','action'],'check input');
   if(!obj(req.input.context) || !obj(req.input.action)) wireError('invalid-binding');
-  if(Object.hasOwn(req.input,'invocation')) validateInvocationShape(req.input.invocation,{capability:CAPABILITY,context:req.input.context,action:req.input.action});
-  const {runtime}=bindingPayload(req.input.binding,{diagnoseSettings:true}),action=req.input.action,name=providerActionName(action);
-  const harvestInvocation=req.input.invocation;
-  const admittedHarvest=name==='harvest' && action.kind==='operation' && action.slot==='knowledge' && action.name==='harvest'
-    && harvestInvocation?.subject.kind==='persistent' && harvestInvocation.instance!==null && !!harvestInvocation.intent;
-  if(name && (unsupportedCapturedCommands.has(name) || name==='run-source' || (name==='harvest' && !admittedHarvest))) return {status:'needs-configuration',problems:[problem('provider-not-qualified','action:not-admitted')]};
+  const action=req.input.action,name=providerActionName(action);
+  const prepared=readinessRuntime(req.settings);
+  if(prepared.problem) return {status:'needs-configuration',problems:[prepared.problem]};
+  const runtime=prepared.runtime;
+  if(name && (unsupportedCapturedCommands.has(name) || name==='run-source' || name==='harvest')) return {status:'needs-configuration',problems:[problem('provider-not-qualified','action:not-admitted')]};
   if(action.kind==='hook' && action.name==='soul-scaffold') return {status:'ready',problems:[]};
   let bindings;try{bindings=validateBindings(runtime.bindings,runtime.descriptorFile);}catch{return {status:'needs-configuration',problems:[problem('needs-configuration','bindings:invalid')]};}
   const accepted={},gitBases=Object.entries(bindings.bases).filter(([,base])=>base.kind==='git');
@@ -296,14 +326,16 @@ function checkPhase(req) {
       stage=base.kind==='directory'?'validate':'stage';
       accepted[alias]=(base.kind==='directory'?validateBase(base.path,base):stageBase(base,join(scratch,alias),{alias})).meta;
     }
-    stage='runtime';
-    checkKnowledgeRuntime({rendered:runtime,accepted});
+    if(req.settings.harvest!=='off') {
+      stage='runtime';
+      checkKnowledgeRuntime({rendered:runtime,accepted});
+    }
   } catch(error) {
-    if(error.code==='E_COMMAND') return {status:'unavailable',problems:[problem('provider-unavailable','runtime:command-missing')]};
+    if(error.code==='E_COMMAND') return {status:'needs-configuration',problems:[problem('needs-configuration','runtime:command-missing')]};
     if(error.code==='E_OWNER') return {status:'needs-configuration',problems:[problem('provider-not-qualified','base:owner-unmet')]};
     if(error.code==='E_CONFIRM') return {status:'needs-configuration',problems:[problem('provider-not-qualified','base:source-mismatch')]};
     if(['E_BASE','E_VALIDATION','E_DIRECTORY_GIT'].includes(error.code)) return {status:'needs-configuration',problems:[problem('provider-not-qualified',stage==='stage'?'base:stage-failed':'base:not-validated')]};
-    if(stage==='runtime') return {status:'unavailable',problems:[problem('provider-unavailable','runtime:not-qualified')]};
+    if(stage==='runtime') return {status:'needs-configuration',problems:[problem('needs-configuration','runtime:not-qualified')]};
     return {status:'unavailable',problems:[problem('provider-unavailable')]};
   } finally {
     if(scratch) fs.rmSync(scratch,{recursive:true,force:true});

package/capabilities/oats-okf/lib/inspection.mjs

@@ -53,10 +53,8 @@ function liveHome(source,status) {
     return {available:false,reason:'unverified-home',error:{code:e.code || 'E_SOURCE',message:e.message}};
   }
 }
-export function workingDocuments(source,status=loadStatus(source)) {
-  const before=liveHome(source,status),observedAt=new Date().toISOString();
-  const unavailable=state=>({liveMemory:{available:false,reason:state.reason,observedAt,...(state.error?{error:state.error}:{})},documents:[]});
-  if(!before.available) return unavailable(before);
+/** The home's working memory (STATE.md, log.md, notes/*.md), each capped. */
+function homeDocuments(home) {
   const documents=[];
   const doc=(label,file)=>{
     const content=regular(file,DOCUMENT_BYTES);
@@ -64,9 +62,9 @@ export function workingDocuments(source,status=loadStatus(source)) {
   };
   let error;
   try {
-    doc('Working state (STATE.md)',join(source.home,'STATE.md'));
-    doc('Log (log.md)',join(source.home,'log.md'));
-    const notes=safePath(join(source.home,'notes'));
+    doc('Working state (STATE.md)',join(home,'STATE.md'));
+    doc('Log (log.md)',join(home,'log.md'));
+    const notes=safePath(join(home,'notes'));
     function walk(dir,prefix='') {
       let entries;try {entries=fs.readdirSync(dir,{withFileTypes:true});} catch(e) {if(e.code==='ENOENT') return;throw e;}
       for(const entry of entries.sort((a,b)=>a.name<b.name?-1:a.name>b.name?1:0)) {
@@ -79,6 +77,13 @@ export function workingDocuments(source,status=loadStatus(source)) {
     }
     walk(notes);
   } catch(e) {error=e;}
+  return {documents,error};
+}
+export function workingDocuments(source,status=loadStatus(source)) {
+  const before=liveHome(source,status),observedAt=new Date().toISOString();
+  const unavailable=state=>({liveMemory:{available:false,reason:state.reason,observedAt,...(state.error?{error:state.error}:{})},documents:[]});
+  if(!before.available) return unavailable(before);
+  const {documents,error}=homeDocuments(source.home);
   const after=liveHome(source,loadStatus(source));
   if(!after.available) return unavailable(after);
   if(before.dev!==after.dev || before.ino!==after.ino) return unavailable({reason:'home-changed'});
@@ -117,3 +122,17 @@ export function inspect(source) {
     acceptedView:source.acceptedView,legacyLocalView:legacy,status,scheduler:health,liveMemory:working.liveMemory,documents
   };
 }
+/** okf 4.0.3: inspect a harvest-off home (consultSource): its declaration, the
+ *  bases it reads, and its own working memory. There is no source, custody or
+ *  schedule to report; `oats okf bases` shows the accepted state it reads. */
+export function inspectConsultOnly(source) {
+  const {documents,error}=homeDocuments(source.home),observedAt=new Date().toISOString();
+  if(error) fail(error.code==='E_PATH'?'E_PATH':'E_INSPECT_FAILED',error.message);
+  const path=join(source.home,'knowledge');let legacy=null;
+  try {const stat=fs.lstatSync(path);legacy={status:'legacy-local-view',path,ignored:true,...(stat.isSymbolicLink()?{symlink:true}:{}),note:'okf 3.0.0 ignores this okf 2.x snapshot and reads knowledge remotely; it is safe to delete by hand'};} catch(e) {if(!missing(e)) throw e;}
+  return {
+    summary:`OKF harvest off for this instance (${source.harvest.reason}): no source is registered and nothing is captured; ${documents.length} working-memory documents${legacy?'; legacy-local-view ./knowledge/ (ignored, safe to delete)':''}`,
+    source:null,harvest:source.harvest,owns:source.decl.owns,reads:source.decl.reads,bases:source.bindings.bases,
+    acceptedView:null,legacyLocalView:legacy,status:null,scheduler:null,liveMemory:{available:true,reason:'live',observedAt},documents
+  };
+}

package/capabilities/oats-okf/lib/sources.mjs

@@ -108,14 +108,28 @@ function finishRegistration(source) {
   scheduleSource(source);return source;
 }
 /** Harvest off (okf 4.0.0): no source, no custody, no schedule. The home keeps
- *  a small record so retire knows there is nothing to capture. */
+ *  a small record so retire knows there is nothing to capture, and (4.0.3) the
+ *  soul's declaration, so consultation works without a source. */
 function harvestOff(home,sw,extra={}) {
-  const record={version:1,harvest:'off',reason:sw.reason,rows:sw.rows,warnings:sw.warnings,at:new Date().toISOString()};
+  const record={version:1,harvest:'off',reason:sw.reason,rows:sw.rows,warnings:sw.warnings,...(extra.decl?{decl:extra.decl}:{}),at:new Date().toISOString()};
   atomic(instanceRecordPath(home),JSON.stringify(record,null,2)+'\n');
   ensureInstanceKnowledge(home);
   return {harvestOff:true,switch:sw,home,...extra};
 }
 export const harvestOffRecord = home => fs.existsSync(instanceRecordPath(home))?readJSON(instanceRecordPath(home)):null;
+/** okf 4.0.3: what a harvest-off home consults. Consultation never depends on
+ *  the harvest switch: such a home has no registered source by design, so it
+ *  reads its soul's declaration (recorded at spawn; the kernel's OATS_SOUL for
+ *  a home spawned before 4.0.3) and the deployment's bindings as they are now.
+ *  Nothing is registered, captured or scheduled. */
+export function consultSource(home) {
+  home=safePath(home);
+  const record=harvestOffRecord(home);
+  if(!record) fail('E_SOURCE',`no okf source for ${home}: it was not spawned with oats.okf as its knowledge capability`);
+  const decl=record.decl || (process.env.OATS_SOUL?declaration(fs.realpathSync(process.env.OATS_SOUL)):fail('E_OATS_SOUL_MISSING','OATS_SOUL is not set; oats.okf commands run only under the OATS kernel'));
+  const work=fs.existsSync(join(home,'work'))?fs.realpathSync(join(home,'work')):join(home,'work');
+  return {home,work,decl,bindings:loadBindings(undefined,{sourceHome:home,sourceWork:work}),harvest:{status:'off',reason:record.reason,at:record.at}};
+}
 /** The source's tasks provider (its instance.json tasks-layer capability), or null. */
 function tasksProvider(meta) {
   const row=Array.isArray(meta?.capabilities)?meta.capabilities.find(c=>c && c.layer==='tasks' && typeof c.id==='string'):null;

package/capabilities/oats-okf/lib/worker.mjs

@@ -37,7 +37,7 @@ export function completionCommand(source,id,judgmentFile) {return command(source
 // It homes in agents/oats-okf--knowledge-harvester/. Its instances get an
 // exact --name okf-harvester-<run> (50 characters): a derived
 // <agent>-<purpose> name would exceed the kernel's 64-character cap.
-export const HARVESTER_SOUL='oats.okf/knowledge-harvester',HARVESTER_AGENT='oats-okf--knowledge-harvester',HARVESTER_TEAM='okf';
+export const HARVESTER_SOUL='oats.okf/knowledge-harvester',HARVESTER_AGENT='oats-okf--knowledge-harvester';
 export const harvesterInstance=id=>`okf-harvester-${id}`;
 /** The harvester's own completion and status commands (oats.okf-harvest). The
  *  completion wrapper runs this source's frozen `oats okf complete` from the
@@ -47,15 +47,6 @@ export function harvesterCommands(source,id) {
   return {complete:['oats','okf-harvest','complete',...tail,'--judgment','<absolute-judgment.json>'].map(quote).join(' '),
     status:['oats','okf-harvest','harvest-status',...tail].map(quote).join(' ')};
 }
-/** The messaging capability the harvester soul resolves (from spawn --preview),
- *  so it can join the okf team; null when it resolves none. */
-function harvesterMessaging(source) {
-  try {
-    const preview=oats(['spawn',HARVESTER_SOUL,'--dir',source.context,'--preview','--json'],source.context,{timeout:90000});
-    const row=(Array.isArray(preview?.modules)?preview.modules:[]).find(m=>m?.layer==='messaging' && typeof m.name==='string');
-    return {messaging:row?row.name:null};
-  } catch(e) {return {messaging:null,error:`${e.code || 'E_RUNTIME'}: ${e.message}`};}
-}
 export function runSource(source,{noLaunch=false,manual=false,capturedInvocation,nativeRequest}={}) {
   const plan=capturedSource(source)?qualifyCapturedWorker(source,{context:capturedInvocation,nativeRequest}):null;
   if(!plan) requireQualifiedHelper(source);
@@ -117,7 +108,7 @@ function spawnWorker(source,run,{parent=false}={}) {
     task=`Process only durable OKF run ${id}. Load the knowledge-harvest skill first.${recovery}\n\n${evidence}\n\nWrite ./work/judgment.json per the skill, then execute the completion command below, replacing only the quoted placeholder with the absolute judgment file path (shell-quote it). A successful command, not this task, is the delivery receipt. On failure retain the worker and report it; do not self-retire. On success report receipt then retire normally.\n\n${complete}\n`;
   } else {
     const cmd=harvesterCommands(source,id);
-    task=`Process only durable OKF run ${id}. Load the knowledge-harvest skill first.${recovery}\n\n${evidence}\n\nWrite ./work/judgment.json per the skill, then run the completion command below, replacing only the quoted placeholder with the absolute judgment file path (shell-quote it). It runs this source's frozen completion in the source deployment. A successful command, not this task, is the delivery receipt. On failure keep your home and report it; do not retire.\n\nAfter a successful completion, stay alive in the okf team until your PR is merged or closed. On every wake run the status command first, and retire only when it says retire or max-age. Never close the PR yourself.\n\nComplete: ${cmd.complete}\nStatus:   ${cmd.status}\n`;
+    task=`Process only durable OKF run ${id}. Load the knowledge-harvest skill first.${recovery}\n\n${evidence}\n\nWrite ./work/judgment.json per the skill, then run the completion command below, replacing only the quoted placeholder with the absolute judgment file path (shell-quote it). It runs this source's frozen completion in the source deployment. A successful command, not this task, is the delivery receipt. On failure keep your home and report it; do not retire.\n\nAfter a successful completion, stay alive until your PR is merged or closed. On every wake run the status command first, and retire only when it says retire or max-age. Never close the PR yourself.\n\nComplete: ${cmd.complete}\nStatus:   ${cmd.status}\n`;
   }
   const taskFile=join(dirname(runPath(source,id)),'TASK.md');
   const actualTask=run.capturedWorker?task.replace('On success report receipt then retire normally.',`On success report the actual receipt and include run ${id} in your final assistant reply. RETAIN this home/history. Public captured retirement is not qualified; never use legacy retirement or self-retire.`) :task;
@@ -143,11 +134,9 @@ function spawnWorker(source,run,{parent=false}={}) {
   const args=['spawn',HARVESTER_SOUL,'--name',harvesterInstance(id),'--dir',source.context,harnessFlag(source),source.execution.runtime,'--no-launch','--task-file',taskFile,'--json'];
   if(source.execution.model) args.push('--model',source.execution.model);
   if(parent) args.push('--parent',source.instance);
-  // Join the okf team through the soul's messaging capability, as a trigger
-  // spawn does; without one the harvester cannot talk to the maintainer.
-  const team=harvesterMessaging(source);
-  if(team.messaging) args.push('--provider',team.messaging,`join=${HARVESTER_TEAM}`);
-  run.team={team:HARVESTER_TEAM,messaging:team.messaging,...(team.error?{error:team.error}:{})};
+  // okf 4.0.2: no team join. The harvester lives in the deployment's default
+  // team, where the maintainer reaches it; a deployment that wants it in
+  // another team opts in locally, as for any soul.
   try {
     run.worker=oats(args,source.context,{timeout:90000});
     if(!run.worker.instance || !run.worker.home) fail('E_RUNTIME','spawn receipt lacks worker identity');

package/capabilities/oats-okf/oats.json

@@ -1,7 +1,7 @@
 {
   "capability": "oats.okf",
   "command": "okf",
-  "version": "4.0.1",
+  "version": "4.0.4",
   "compatibility": {
     "oats": ">=0.29.0"
   },
@@ -82,14 +82,17 @@
       "setting harvest-runtime must be pi, claude or codex",
       "setting harvest-model must be null or a non-empty string",
       "check action is not an admitted knowledge operation",
-      "bound runtime bindings file is missing or invalid",
+      "OKF settings missing bindings-file: set settings.oats.okf bindings-file, or deactivate oats.okf",
+      "OKF soul declaration missing: create okf.json for this soul, or deactivate oats.okf",
+      "OKF binding missing or invalid: provision soul OKF declaration and bindings file, or deactivate oats.okf",
+      "OKF bindings file missing or invalid: repair configured bindings file, or deactivate oats.okf",
       "more than 64 git knowledge bases declared",
       "declared knowledge base could not be staged from its git source",
       "declared knowledge base is not a validated knowledge tree",
       "knowledge base owner or remote custody requirement not met",
       "staged git source does not match the declared knowledge base",
       "harvest runtime command is not installed on this host",
-      "harvest runtime could not be qualified against the accepted bases"
+      "harvest runtime is not qualified: install/configure the selected harvest runtime or set harvest off"
     ]
   },
   "inject": "injects/okf.md",

package/capabilities/oats-okf-harvest/bin/okf-harvest.mjs

@@ -74,7 +74,7 @@ export function complete(flags, env = process.env) {
   let answer; try { answer = JSON.parse(r.stdout); } catch { /* below */ }
   if (answer?.schemaVersion === 1 && answer.ok === true) return { deployment: source.context, ...answer.result };
   const code = answer?.error?.code || 'E_COMPLETE', message = answer?.error?.message || (r.error?.message || r.stderr || `exit ${r.status}`).trim();
-  if (INACTIVE.has(code)) fail('E_SOURCE_INACTIVE', `oats.okf cannot run for source soul ${source.agent} in ${source.context} (${code}: ${message}). Nothing was published: report this to the okf team and your operator, and stay.`, { cause: code });
+  if (INACTIVE.has(code)) fail('E_SOURCE_INACTIVE', `oats.okf cannot run for source soul ${source.agent} in ${source.context} (${code}: ${message}). Nothing was published: report this to your operator, and stay.`, { cause: code });
   fail(code, `${message} (completion ran in ${source.context}; keep your home and report)`);
 }
 /** "7d" | "48h" | "90m" | seconds → milliseconds. */
@@ -112,7 +112,7 @@ export function harvestStatus(flags, env = process.env, { now = Date.now(), view
   if (!judged || pending.length) { action = age >= limit ? 'max-age' : 'stay'; reason = !judged ? 'the run is not completed yet' : `destinations not delivered: ${pending.map((d) => d.alias).join(', ')}`; }
   else if (open.length) { action = age >= limit ? 'max-age' : 'stay'; reason = `open PR: ${open.map((d) => d.pr.url).join(', ')}`; }
   else { action = 'retire'; reason = destinations.some((d) => d.pr) ? 'every PR is merged or closed' : 'no PR was needed (no-change or directory publication)'; }
-  if (action === 'max-age') reason += `; older than harvester-max-age (${Math.round(limit / 3600000)}h): tell the okf team and retire, never close the PR`;
+  if (action === 'max-age') reason += `; older than harvester-max-age (${Math.round(limit / 3600000)}h): tell your operator and retire, never close the PR`;
   return { run: run.id, status: run.status, ageSeconds: Math.round(age / 1000), maxAgeSeconds: limit / 1000, destinations, action, reason };
 }
 function text(event, r) {

package/capabilities/oats-okf-harvest/oats.json

@@ -1,18 +1,18 @@
 {
   "capability": "oats.okf-harvest",
   "command": "okf-harvest",
-  "version": "4.0.1",
+  "version": "4.0.4",
   "compatibility": {
     "oats": ">=0.29.0"
   },
-  "description": "The OKF knowledge harvester: judges one source instance's captured notes and session transcript by the OKF promotion doctrine, opens the labelled harvest PR with its provenance block, and stays in the okf team until the PR is merged or closed.",
+  "description": "The OKF knowledge harvester: judges one source instance's captured notes and session transcript by the OKF promotion doctrine, opens the labelled harvest PR with its provenance block, and stays alive until the PR is merged or closed.",
   "requires": [
     { "command": "gh", "why": "read the harvest PR's state (harvest-status)" }
   ],
   "settings": {
     "harvester-max-age": {
       "default": "7d",
-      "description": "How long a harvester stays alive waiting for its PR (a duration like 7d, 48h or 90m, or seconds). At max-age it tells the okf team and retires; it never closes the PR."
+      "description": "How long a harvester stays alive waiting for its PR (a duration like 7d, 48h or 90m, or seconds). At max-age it tells its operator and retires; it never closes the PR."
     }
   },
   "skills": [

package/capabilities/oats-okf-harvest/skills/knowledge-harvest/SKILL.md

@@ -5,8 +5,8 @@ description: >-
   durable run's input fully (notes AND the captured transcript windows), cite
   the turn ids relied on, extract task references, judge with knowledge-theory,
   stage edits on the owned nodes, complete with `oats okf-harvest complete`
-  (which opens the labelled PR with its provenance block), then stay alive in
-  the okf team until the PR is merged or closed. Use when TASK.md names an OKF
+  (which opens the labelled PR with its provenance block), then stay alive
+  until the PR is merged or closed. Use when TASK.md names an OKF
   run, when a maintainer messages about your harvest PR, on every wake while
   your PR is open, and for operator-requested rejudgment.
 ---
@@ -126,13 +126,13 @@ publishes:
 
 A failed or uncertain completion is NOT success. Keep your home and work,
 report the recovery need, and stay. If it reports that the source's oats.okf
-is not active or not trusted in its deployment, report exactly that to the
-okf team and your operator, and stay: nothing was published. Never run
+is not active or not trusted in its deployment, report exactly that to
+your operator, and stay: nothing was published. Never run
 `git push` or `gh pr create` by hand; never rerun a failed delivery by hand.
 
 ## 6. Stay alive until the PR is merged or closed
 
-After a PR opens you stay **alive and idle** in the okf team: the maintainer
+After a PR opens you stay **alive and idle**: the maintainer
 may ask about your judgment.
 
 - **On every wake** (a message, a human, a resumed session), first run
@@ -142,7 +142,7 @@ may ask about your judgment.
   - `retire`: every PR is merged or closed, or the run needed none (no-change,
     directory publication). Report the outcome, then retire (the oats skill);
   - `max-age`: the run is older than `harvester-max-age` (default 7 days).
-    Tell the okf team the PR is still open and that you are retiring, then
+    Tell your operator the PR is still open and that you are retiring, then
     retire. **Never close the PR yourself.**
 - **Messages** (C4, subject prefix `okf:` plus the PR URL):
   - `okf: question <PR>`: answer from your judgment and the evidence, citing

package/capabilities/oats-okf-maintenance/bin/okf-maintenance.mjs

@@ -137,10 +137,10 @@ export function notifyHarvester(flags, env = process.env, { view = viewPr } = {}
     'amend-request': `An amendment request on your harvest PR ${pr.url}: see the okf-review comment and reply with the change you would make.`,
     amended: `I amended your harvest PR ${pr.url}; see the okf-review comment.`,
   }[flags.state];
-  return { to: h.alias || h.instance, instance: h.instance, alias: h.alias, team: 'okf', subject: `okf: ${flags.state} ${pr.url}`, body, send: 'send this with your messaging capability in the okf team' };
+  return { to: h.alias || h.instance, instance: h.instance, alias: h.alias, subject: `okf: ${flags.state} ${pr.url}`, body, send: 'send this with your messaging capability' };
 }
 function text(event, r) {
-  if (event === 'notify-harvester') return `to: ${r.to} (team okf)\nsubject: ${r.subject}\n\n${r.body}`;
+  if (event === 'notify-harvester') return `to: ${r.to}\nsubject: ${r.subject}\n\n${r.body}`;
   const lines = [`${r.pr.url} ${r.pr.state}${r.pr.draft ? ' (draft)' : ''} ${r.pr.head}@${String(r.pr.headSha).slice(0, 12)} → ${r.pr.base} [${r.pr.labels.join(', ')}]`];
   lines.push(r.provenance.valid ? `provenance: run ${r.provenance.value.run}, source ${r.provenance.value.source.soul}/${r.provenance.value.source.instance}, harvester ${r.harvester.alias || r.harvester.instance}` : `provenance INVALID: ${r.provenance.problems.join('; ')}`);
   if (r.tasks) lines.push(`tasks: ${r.tasks.refs.join(', ') || '(none)'} — ${r.tasks.note}`);

package/capabilities/oats-okf-maintenance/injects/maintainer.md

@@ -9,4 +9,4 @@ first, and judge by **knowledge-theory**.
   silently. A PR that would supersede a human-accepted decision gets
   `okf-needs-human` and a human, not a merge.
 - Settle the PR (merge, amend and merge, request changes, close), notify the
-  harvester in the okf team, then retire.
+  harvester, then retire.

package/capabilities/oats-okf-maintenance/oats.json

@@ -1,11 +1,11 @@
 {
   "capability": "oats.okf-maintenance",
   "command": "okf-maintenance",
-  "version": "4.0.1",
+  "version": "4.0.4",
   "compatibility": {
     "oats": ">=0.29.0"
   },
-  "description": "The OKF knowledge maintainer: reviews one harvest PR by the OKF promotion doctrine, situates it in the base, amends and merges or closes it, never silently supersedes a human-accepted decision, and notifies the harvester in the okf team.",
+  "description": "The OKF knowledge maintainer: reviews one harvest PR by the OKF promotion doctrine, situates it in the base, amends and merges or closes it, never silently supersedes a human-accepted decision, and notifies the harvester.",
   "requires": [
     { "command": "gh", "why": "read, comment on, amend and merge the harvest PR" },
     { "command": "git", "why": "check out the knowledge-base PR" }

package/capabilities/oats-okf-maintenance/skills/knowledge-review/SKILL.md

@@ -7,7 +7,7 @@ description: >-
   through your tasks capability when you can, judge by knowledge-theory, then
   merge, amend and merge, request changes from the harvester, or close — never
   superseding a human-accepted decision silently. Use when TASK.md names a
-  knowledge-base PR, when a harvester answers you in the okf team, or when a
+  knowledge-base PR, when a harvester answers you, or when a
   trigger re-runs you on a PR you may already have reviewed.
 ---
 

package/capabilities/oats-okf-maintenance/skills/okf-trigger-setup/SKILL.md

@@ -6,7 +6,7 @@ description: >-
   (`oats-triggers/okf-harvest-review.yaml` in a member repo, `from:
   oats.okf:harvest-review`, with `runsOn` naming the one host and `owner` the
   GitHub account that can merge on the knowledge-base repo), or locally with
-  `oats trigger add` for a machine-private setup. Covers the okf team, the
+  `oats trigger add` for a machine-private setup. Covers messaging, the
   self-approval limit and `oats trigger test`. Use when setting up knowledge
   operations, when harvest PRs are not being reviewed, when moving the
   reviewer to another host, or when asked whether a host may run the
@@ -17,7 +17,7 @@ description: >-
 
 The trigger makes a harvest PR get reviewed: when a PR labelled `okf-harvest`
 opens on the knowledge-base (KB) repository, the host tick spawns a new
-`oats.okf/knowledge-maintainer` in the `okf` team to review it. It runs on one
+`oats.okf/knowledge-maintainer` to review it. It runs on one
 machine, acting as one GitHub account, and that account must be able to
 **merge** on the KB repository.
 
@@ -43,28 +43,16 @@ the reviewer's account are the same GitHub account, then either:
 
 Say which one applies when you report the setup.
 
-## 3. The okf team
+## 3. Messaging
 
-The package souls carry `team: okf`. The workspace must declare it, with its
-messaging mapping. Messaging is aweb (`oats.aweb`, the workspace default);
-it needs oats.aweb 1.15.0 or later, which honours the `join=okf` the
-harvester spawn and the trigger's `teams: [okf]` pass:
+The harvester and the maintainer message each other through the soul's
+messaging capability (`oats.aweb`, the workspace default). Both live in the
+deployment's default team, like every instance: there is no okf team to
+declare or map. A deployment that wants them in another team opts them in
+locally, as for any soul.
 
-```yaml
-# oats-workspace.yaml
-teams:
-  okf: { description: Knowledge operations }
-defaults:
-  messaging: { oats.aweb: { from: package } }
-messaging:
-  byTeam:
-    okf: { team: aweb:<your-org>.okf }
-```
-
-Another messaging provider works the same way if it honours `join`.
-
-Without it, the souls list with `E_TEAM_UNKNOWN`, and the harvester and the
-maintainer cannot message each other.
+Without a messaging capability they cannot message each other: the
+maintainer's notices and questions do not reach the harvester.
 
 ## 4. Declare it in the workspace (the default)
 
@@ -126,7 +114,7 @@ oats trigger status
 
 - `oats trigger test` checks gh auth and where its credential comes from, the
   repository and your merge permissions, the soul, its messaging capability,
-  the okf team, the host/owner match, and what would fire now. It spawns
+  the host/owner match, and what would fire now. It spawns
   nothing. It must pass before you report the setup done; fix what it names.
 - **Credentials reach the tick through the host timer, not your shell.** A
   `GH_TOKEN` exported in your shell does not reach it; `gh auth login` with the

package/capabilities/oats-workspace-experts/injects/oats-experts.md

@@ -0,0 +1,26 @@
+## Working on the OATS framework repository (this workspace's experts)
+
+This is the OATS-repo-specific part of the expert role. It lives in the oats repo (a private
+capability, `oats.workspace-experts`, assigned to this workspace's expert souls), not in
+the generic engineering package.
+
+**Surfaces and their developers.** To drive development, launch the developer that owns
+the surface; for work across surfaces, one developer per surface.
+
+| Surface | Paths | Developer soul | Expert |
+|---|---|---|---|
+| Kernel & CLI | `lib/`, `bin/`, `docs/*.schema.json` | `oats-kernel-developer` | `oats-kernel-expert` |
+| Desktop app & server | `packages/desktop/` (not views) | `oats-desktop-developer` | `oats-desktop-expert` |
+| Desktop design | `packages/desktop/renderer/` views, styles, copy | `oats-desktop-designer` | `oats-desktop-expert` |
+| Provider packages | `oats-aweb`, `oats-okf`, and the other package repos | `oats-integrations-developer` | `integrations-expert` (and the package's own expert) |
+| Docs & skills | `docs/`, `oats-package/`, `skills/` | the developer of the surface they document | the owning expert |
+
+**Your own worktrees.** You may drive a piece of work in your own session instead of
+launching a developer, when that's the better call (a small cross-cutting change, a spike,
+a release PR). Use your work-mode briefing's extra worktrees, named for the surface
+(`.work-kernel`, `.work-desktop`, `.work-docs`), with the developer's discipline, including
+the adversarial review loop. Launching a developer is still the default.
+
+**Delivery.** Every change reaches main by a PR. The owning expert lands it (opens it,
+answers reviews, gets it merged). In this repository, merges are done by the maintainer
+(`oats-expert`), so getting its approval is part of landing.

package/capabilities/oats-workspace-experts/oats.json

@@ -0,0 +1,9 @@
+{
+  "capability": "oats.workspace-experts",
+  "private": true,
+  "version": "1.0.0",
+  "compatibility": { "oats": ">=0.29.0" },
+  "description": "The OATS framework repository's part of the expert role: which developer soul owns each surface, when an expert drives work in its own worktrees, and how changes land here (PRs merged by the maintainer, oats-expert). Assigned to this workspace's expert souls, beside oats.engineering-expert.",
+  "requires": [],
+  "inject": "injects/oats-experts.md"
+}