@awebai/oats 0.24.0 → 0.24.2

package/lib/core.mjs

@@ -51,6 +51,7 @@ import { buildCapturedInvocationContext, withCapturedInvocationContextFile } fro
 import { readCapturedInstanceIndex, readCapturedInstanceMetadata, readCapturedInstanceAuthority, assertCapturedInstanceCustody,
   recordCapturedCustodyFailure, markCapturedNativeScaffold, failCapturedNativeIntent, observeCapturedNativeTarget, setCapturedInstanceStatus, admitCapturedInstanceAction, beginCapturedIntent, settleCapturedIntent } from "./captured-instance-index.mjs";
 import { validateExecutionBinding } from "./schedule-capsule.mjs";
+import { parsePortableSource } from "./source-spec.mjs";
 import { validateIntentRef } from "./captured-admission-shape.mjs";
 export { readCapturedInstanceIndex, readCapturedInstanceMetadata, beginCapturedIntent, settleCapturedIntent };
 export { buildCapturedInvocationContext, withCapturedInvocationContextFile };
@@ -61,6 +62,7 @@ import { validateCapturedLaunchRequest } from "./captured-launch-request.mjs";
 import { validateCapabilityInputDeclarations } from "./capability-inputs.mjs";
 import { validateCapturedSessionBackend, validateCapturedSessionTarget, assertCapturedSessionPlacement } from "./captured-session-backend.mjs";
 import { createRepositoryTransaction } from "./repository-observation.mjs";
+import { inspectPortableOnboarding as inspectOnboarding, describePortableOnboarding } from "./portable-onboarding.mjs";
 import { readLock3 } from "./portable-lock.mjs";
 import { portableScope, portableStateDirectory } from "./portable-state.mjs";
 import { objectAt } from "./portable-shape.mjs";
@@ -111,6 +113,18 @@ export const OATS_VERSION = JSON.parse(readFileSync(join(PKG_ROOT, "package.json
 /** Skills shipped with the kernel. Only oats-getting-started is ambient; spawn composes selected skills locally. */
 export const PACKAGED_SKILLS_DIR = join(PKG_ROOT, "skills");
 
+function soulRequirements(soulDir) {
+  const file = soulDir && join(soulDir, "soul.yaml");
+  return file && existsSync(file) ? withConfigFile(file, () => parseYamlNested(readFileSync(file, "utf8"))).requires : undefined;
+}
+function declaredOperationalCapabilities(soulDir) {
+  const capabilities = soulRequirements(soulDir)?.capabilities ?? {};
+  return ["oats.core", "oats.setup"].filter(id => Object.hasOwn(capabilities, id));
+}
+function legacyOperationalSkills(soulDir) {
+  return declaredOperationalCapabilities(soulDir).length ? [] : ["oats", "oats-config", "oats-packages"].map(name => ({ id: "kernel", path: join(PACKAGED_SKILLS_DIR, name) }));
+}
+
 // ---------- shell helpers ----------
 function sh(cmdline) { return execSync(cmdline, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim(); }
 function shTry(cmdline) { try { return sh(cmdline); } catch { return undefined; } }
@@ -1194,6 +1208,31 @@ export function approveAvailableCapability(deployment, artifactSet, capability,
   return approveAvailableArtifact(deployment, artifactSet, capability, origin, loadRetainedManifest);
 }
 
+/** Public read-only source/workspace inspection through the existing facade.
+ * Owns only transient repository scratch, never deployment state, provisioning,
+ * provider code, approvals or a serialized mutation witness. */
+export function inspectPortableOnboarding(input, { repositoryOptions = {} } = {}) {
+  canonicalJson(input);
+  const directory = mkdtempSync(join(realpathSync(tmpdir()), "oats-source-inspection-")), owned = lstatSync(directory);
+  let repositories, primary;
+  try {
+    repositories = createRepositoryTransaction({ ...repositoryOptions, directory, accessContextKey: repositoryOptions.accessContextKey ?? "native" });
+    return describePortableOnboarding(inspectOnboarding(input, { repositories }));
+  } catch (error) { primary = error; throw error; }
+  finally {
+    try {
+      repositories?.close();
+      const current = lstatSync(directory);
+      if (!current.isDirectory() || current.dev !== owned.dev || current.ino !== owned.ino) throw oatsError("source-incomplete", "inspection scratch ownership changed");
+      removeOwnedStaging(directory);
+    } catch (cleanup) {
+      if (!primary) throw cleanup;
+      const error = new AggregateError([primary, cleanup], "inspection and owned scratch cleanup failed", { cause: primary });
+      error.code = primary.code; error.stagingPath = directory; throw error;
+    }
+  }
+}
+
 /** Explicit new-work preparation, with one frozen repository transaction.
  * This first adapter captures command/curriculum profiles; provider-owned
  * binding or distinct helper policy gaps return needs-configuration, never
@@ -4057,6 +4096,10 @@ export function composeInstanceAgentsMd(soulDir, contextDir, soulName, workMode,
   if (!existsSync(agentsMd)) throw new Error(`canonical soul instructions missing: ${agentsMd}`);
   const resolved = resolveOatsConfig(contextDir, soulName);
   const wanted = [];
+  const declaredOperations = declaredOperationalCapabilities(soulDir);
+  const oatsCoreDeclared = declaredOperations.includes("oats.core");
+  if (declaredOperations.length) resolved.kernelInjection = { inject: undefined,
+    provenance: `declared ${declaredOperations.join(", ")} ${declaredOperations.length === 1 ? "capability" : "capabilities"}` };
   const kernelInject = resolved.kernelInjection?.inject;
   if (kernelInject && existsSync(kernelInject)) wanted.push(["kernel:oats", kernelInject]);
   if (kind === "local") {
@@ -4078,7 +4121,7 @@ export function composeInstanceAgentsMd(soulDir, contextDir, soulName, workMode,
   }
   for (const inj of resolved.injects) wanted.push([`config:${inj.source}`, inj.file]);
   const blocks = wanted.map(([source, file]) => ({ source, file, content: readFileSync(file, "utf8").trim() }));
-  return { text: renderInstructionText(readFileSync(agentsMd, "utf8"), blocks), blocks, resolved };
+  return { text: renderInstructionText(readFileSync(agentsMd, "utf8"), blocks), blocks, resolved, oatsCoreDeclared };
 }
 
 /** The skill entries a tree contributes — THE discovery rule, shared by preflight
@@ -4136,7 +4179,7 @@ export function planInstanceResources({ resolved, soulDir, agent, contextDir, co
     }
   };
 
-  for (const path of [join(PACKAGED_SKILLS_DIR, "oats"), join(PACKAGED_SKILLS_DIR, "oats-config"), join(PACKAGED_SKILLS_DIR, "oats-packages")]) {
+  for (const { path } of legacyOperationalSkills(soulDir)) {
     add({ type: "skill-tree", source: "kernel", declared: basename(path), path: existsSync(path) ? path : undefined });
   }
   const soulSkills = soulDir && join(soulDir, "skills");
@@ -5084,15 +5127,31 @@ export function resolveYolo(value) {
   throw new Error("yolo must be true or false");
 }
 
-export function writeSoul(root, { name, kind, repo, work, runtime, model, yolo, description, type, instructions }) {
+/** Creation chooses a declared source, never acquisition/activation or a made-up
+ * future release. Existing definitions (including deliberate removal) are kept. */
+function defaultOatsCoreRequirement() {
+  const mapping = officialCapabilityPackage("oats.core");
+  const entry = mapping.available && mapping.migratedCapability === "oats.core" && officialPackageCatalog()[mapping.package];
+  if (entry && typeof entry.url === "string" && typeof entry.ref === "string" && entry.ref) {
+    const parsed = parsePortableSource(`git:${entry.url}@${entry.ref}#${entry.path ?? DEFAULT_PACKAGE_PATH}`);
+    return { requires: { capabilities: { "oats.core": { source: `${parsed.source}#${parsed.path}` } } }, notes: [] };
+  }
+  return { requires: undefined, notes: [{ code: "needs-configuration", message: "oats.core has no published revision in the official package catalog; no source was invented. Add its explicit requirement after the catalog entry is available, or use --no-oats-core to opt out at creation." }] };
+}
+
+export function writeSoul(root, { name, kind, repo, work, runtime, model, yolo, description, type, instructions, oatsCore = true }) {
   yolo = resolveYolo(yolo);
+  if (typeof oatsCore !== "boolean") throw oatsError("E_BAD_ARGS", "oatsCore must be a boolean");
   const agentDir = agentDirOf(root, name, kind);
-  const soulDir = soulOf(agentDir);
+  const soulDir = soulOf(agentDir), soulFile = join(soulDir, "soul.yaml");
+  const { requires, notes } = existsSync(soulFile)
+    ? { requires: soulRequirements(soulDir), notes: [] }
+    : oatsCore ? defaultOatsCoreRequirement() : { requires: undefined, notes: [] };
   mkdirSync(soulDir, { recursive: true });
   mkdirSync(join(agentDir, "instances"), { recursive: true });
-  writeFileSync(join(soulDir, "soul.yaml"), yamlFlat({
+  writeFileSync(soulFile, yamlFlat({
     name, kind, description, type, repo, work: work || "checkout", runtime: runtime || "pi", model, yolo,
-  }));
+  }) + (requires === undefined ? "" : `requires: ${JSON.stringify(requires)}\n`));
   const agentsMd = join(soulDir, "AGENTS.md");
   if (instructions !== undefined || !existsSync(agentsMd)) {
     writeFileSync(agentsMd, instructions ?? defaultSoulAgentsMd(name, description));
@@ -5106,7 +5165,7 @@ export function writeSoul(root, { name, kind, repo, work, runtime, model, yolo,
     home: soulDir, instance: name, agentName: name, soulDir,
     contextDir: ctx, workspaceDir: workspaceOf(root), rootDir: root, resolved,
   });
-  return { agentDir, soulDir };
+  return { agentDir, soulDir, ...(notes.length ? { notes } : {}) };
 }
 function defaultSoulAgentsMd(name, description) {
   return `# ${name}
@@ -5128,8 +5187,8 @@ export function createAgent(root, o) {
   // kind: "local" → a FULL soul (memory, skills, instances) under the scope's
   // local-agents/ — uncommitted by contract; otherwise a committed persistent soul.
   const kind = o.local || o.kind === "local" ? "local" : "persistent";
-  const { agentDir } = writeSoul(root, { ...o, name, kind });
-  return { agent: name, kind, soul: soulOf(agentDir) };
+  const { agentDir, notes } = writeSoul(root, { ...o, name, kind });
+  return { agent: name, kind, soul: soulOf(agentDir), ...(notes ? { notes } : {}) };
 }
 
 /** Upsert a local agent soul (from raw instructions or a Claude-style def file).
@@ -5156,13 +5215,13 @@ export function upsertLocalAgent(root, o) {
   const existing = findAgent(root, name);
   if (existing && existing.kind !== "local") throw new Error(`"${name}" is a persistent agent — spawn it instead`);
   if (!existing && instructions === undefined) throw new Error(`local agent "${name}" needs instructions (none on disk yet)`);
-  writeSoul(root, {
-    name, kind: "local",
+  const { notes } = writeSoul(root, {
+    name, kind: "local", oatsCore: o.oatsCore,
     repo: repo ?? existing?.repo, work: work ?? existing?.work,
     runtime: runtime ?? existing?.runtime, model: model ?? existing?.model, yolo: yolo ?? existing?.yolo,
     description: description ?? existing?.description, instructions,
   });
-  return findAgent(root, name);
+  return { ...findAgent(root, name), ...(notes ? { notes } : {}) };
 }
 /** Back-compat alias: older installed capabilities (oats-okf ≤1.3.x) call this. */
 export const upsertTmpAgent = upsertLocalAgent;
@@ -6110,7 +6169,7 @@ export function spawnInstance(root, agent, o = {}) {
   symlinkSync("AGENTS.md", join(home, "CLAUDE.md"));
 
   // Runtime-neutral exact skill materialization. No harness receives ambient workspace/package skills.
-  const sources = [{ id: "kernel", path: join(PACKAGED_SKILLS_DIR, "oats") }, { id: "kernel", path: join(PACKAGED_SKILLS_DIR, "oats-config") }, { id: "kernel", path: join(PACKAGED_SKILLS_DIR, "oats-packages") }];
+  const sources = legacyOperationalSkills(soulDir);
   const soulSkills = join(soulDir, "skills");
   if (existsSync(soulSkills)) sources.push({ id: "soul", path: soulSkills });
   for (const cap of resolvedCfg.capabilities) for (const path of cap.skills || []) sources.push({ id: cap.id, path });
@@ -7121,9 +7180,11 @@ function runtimeAuthorityOf(baseline) {
   return { launched: true, tmux: { session: tmux.session, window: tmux.window, socket: resolve(tmux.socket) } };
 }
 
-/** Session control uses the same independent endpoint receipt as retirement. */
+/** Session control uses the independent endpoint receipt and, for captured
+ * homes, its original incarnation's existing home/work custody. */
 function instanceSessionTarget(home) {
   if (typeof home !== "string" || !isAbsolute(home)) throw oatsError("E_BAD_ARGS", "session needs an absolute instance home");
+  const requestedHome = home;
   home = realPathOrNearest(home);
   let baseline, meta;
   try {
@@ -7132,18 +7193,29 @@ function instanceSessionTarget(home) {
   } catch (e) { throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `cannot read session receipt for ${home}: ${e.message}`); }
   const authority = baseline.version === RETIRE_BASELINE_VERSION && baseline.home === home && runtimeAuthorityOf(baseline);
   if (!authority) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `independent session receipt is missing or invalid for ${home}`);
+  let io;
+  if ([baseline, meta].some(value => ["executionBinding", "incarnationId", "captured"].some(key => Object.hasOwn(value, key)))) {
+    // The independent receipt remains the anchor even if mutable home markers
+    // are removed. Missing/invalid captured evidence never falls back to legacy.
+    validateExecutionBinding(baseline.executionBinding);
+    const { row } = readCapturedInstanceAuthority(baseline.executionBinding.deployment, requestedHome);
+    if (row.incarnationId !== baseline.incarnationId || canonicalJson(row.executionBinding) !== canonicalJson(baseline.executionBinding)) {
+      throw oatsError("E_RUNTIME_AUTHORITY_MISMATCH", "captured incarnation disagrees with independent session receipt");
+    }
+    io = { exec: (...args) => { assertCapturedInstanceCustody(row); return execFileSync(...args); } };
+  }
   const endpointAgrees = authority.sessionTarget
     ? !meta.tmux && ["backend", "binary", "socket", "workspaceId", "paneId", "terminalId", "protocol"].every((key) => meta.sessionTarget?.[key] === authority.sessionTarget[key])
     : !meta.sessionTarget && meta.tmux?.session === authority.tmux?.session && meta.tmux?.window === authority.tmux?.window && resolve(meta.tmux?.socket || ".") === authority.tmux?.socket;
   if (meta.launched !== authority.launched || (authority.launched && !endpointAgrees)) throw oatsError("E_RUNTIME_AUTHORITY_MISMATCH", "instance metadata disagrees with independent session receipt");
-  return { home, target: authority.launched ? authority.sessionTarget || { backend: "tmux", ...authority.tmux } : undefined };
+  return { home, target: authority.launched ? authority.sessionTarget || { backend: "tmux", ...authority.tmux } : undefined, io };
 }
 
 export function inspectInstanceSession(home) {
   if (typeof home === "string" && isAbsolute(home) && !existsSync(home)) return { home: realPathOrNearest(home), backend: null, present: false, state: "stopped" };
   const s = instanceSessionTarget(home);
   if (!s.target) return { home: s.home, backend: null, present: false, state: "not-launched" };
-  try { return { home: s.home, ...inspectSessionTarget(s.target) }; }
+  try { return { home: s.home, ...inspectSessionTarget(s.target, s.io) }; }
   catch (e) { throw oatsError("E_SESSION_UNAVAILABLE", `cannot inspect session: ${e.message}`); }
 }
 
@@ -7157,7 +7229,7 @@ export function inputInstanceSession(home, text) {
   if (typeof text !== "string" || !text.trim() || text.includes("\0") || Buffer.byteLength(text) > 256 * 1024) throw oatsError("E_BAD_ARGS", "session input must be nonempty text without NUL, at most 256 KiB");
   const s = instanceSessionTarget(home);
   if (!s.target) throw oatsError("E_SESSION_NOT_RUNNING", "instance was not launched");
-  try { return { home: s.home, ...inputSessionTarget(s.target, text) }; }
+  try { return { home: s.home, ...inputSessionTarget(s.target, text, s.io) }; }
   catch (e) { throw oatsError("E_SESSION_INPUT_FAILED", `cannot submit session input: ${e.message}`); }
 }
 

package/lib/portable-onboarding.mjs

@@ -189,6 +189,25 @@ export function inspectPortableOnboarding(input, { repositories } = {}) {
   return result;
 }
 
+/** Metadata-only public view, NOT a serialized fresh-inspection witness or a
+ * preparation request. Provider payloads/adoption values have not gone through
+ * their owner's nonsecret classification and must not leak through inspection. */
+export function describePortableOnboarding(inspection) {
+  if (!issued.has(inspection)) throw oatsError("invalid-declaration", "inspection summary requires an issued onboarding view");
+  const reference = value => ({ source: value.source, soul: value.soul, revision: value.revision, alias: value.alias,
+    adoptionPresent: Object.hasOwn(value, "adoption") });
+  const { reference: selected, exports, ...source } = inspection.source;
+  return freezeJson({ ...inspection,
+    source: { ...source, adoptionPresent: Object.hasOwn(selected, "adoption"), exports: {
+      souls: (exports.souls ?? []).map(({ path, definition, description }) => ({ path, definition, ...(description === undefined ? {} : { description }) })),
+      packages: (exports.packages ?? []).map(({ path, description }) => ({ path, ...(description === undefined ? {} : { description }) })),
+      knowledge: (exports.knowledge ?? []).map(({ contract, version }) => ({ contract, version, payloadOmitted: true })),
+    } },
+    workspace: inspection.workspace ? { ...inspection.workspace, imports: inspection.workspace.imports.map(reference) } : null,
+    omitted: { providerPayloads: true, adoptionValues: true },
+  });
+}
+
 /** Ephemeral local root custody, not a new persistent authority/schema. Ordinary
  * project content changes are allowed; replacing the inspected directories or
  * provisioning a previously absent deployment requires a fresh inspection. */

package/lib/prepared-resources.mjs

@@ -23,7 +23,7 @@ export function completePreparedResources({ seed, plan, manifests, mode, deploym
   }
   if (problems.length) return { record: null, problems };
   const snapshot = join(directory, "kernel-resources"); mkdirSync(snapshot); mkdirSync(join(snapshot, "injects"));
-  const kernelSkills = ["oats-portable", "oats-portable-setup", "oats-portable-artifacts"];
+  const kernelSkills = ["oats-portable", "oats-portable-artifacts"];
   const workInjection = (workMode) => workMode === "directory" ? "portable-work-directory.md" : `work-${workMode}.md`;
   const injectionFiles = ["oats-portable.md", "portable-instance-boundary.md", ...kernel.workModes.map(workInjection)];
   // Only known kernel resources, never a sweep of the checkout/node_modules,

package/lib/provider-binding-broker.mjs

@@ -1,6 +1,8 @@
 /** Execute only an approved retained provider command. Preparation does not need
  * a fabricated complete resolution merely to obtain its binding. */
 import { spawnSync } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 import { canonicalJson } from './portable-values.mjs';
 import { objectAt } from './portable-shape.mjs';
 import { validateArtifactSet } from './resolution-shape.mjs';
@@ -12,6 +14,9 @@ import { validateBindingInterface } from './provider-binding.mjs';
 import { BINDING_LIMITS, validateBindingRequest, decodeBindingResponse } from './provider-binding-wire.mjs';
 import { oatsError } from './errors.mjs';
 
+// Same kernel-owned CLI locator as lifecycle hooks; never caller env or PATH.
+const CLI_BIN=fileURLToPath(new URL('../bin/oats.mjs',import.meta.url));
+
 export function invokeProviderBinding(options,codecs) {
   canonicalJson(options);
   objectAt(options,['deployment','artifacts','capability','phase','settings','input','timeoutMs'],['deployment','artifacts','capability','phase','settings','input']);
@@ -46,7 +51,7 @@ export function invokeProviderBinding(options,codecs) {
   const [script,...args]=spec.trim().split(/\s+/),file=codecs.executable(manifest,script);
   if (!file) throw oatsError('resource-not-found','provider codec executable is unavailable');
   const environment=Object.fromEntries(Object.entries(process.env).filter(([key])=>! /^(OATS_|OAS_|PI_)/.test(key)));
-  Object.assign(environment,{OATS_CAPABILITY:capability,OATS_CAPABILITY_ROOT:root,OATS_SETTINGS:canonicalJson(settings,BINDING_LIMITS)});
+  Object.assign(environment,{OATS_CAPABILITY:capability,OATS_CAPABILITY_ROOT:root,OATS_SETTINGS:canonicalJson(settings,BINDING_LIMITS),OATS_CLI_BIN:realpathSync(CLI_BIN)});
   let result;
   try {
     result=spawnSync(process.execPath,[file,...args],{cwd:root,env:environment,input:canonicalJson(request,BINDING_LIMITS),

package/lib/setup-expert-source.mjs

@@ -0,0 +1,76 @@
+/** Read the setup edition as data for a CLASSIC local bootstrap copy.
+ * No provider code, workspace activation, enrollment or captured identity. */
+import { lstatSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, realpathSync, rmSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { parsePortableSoul } from './portable-soul.mjs';
+import { parseRepositorySource, parsePortableSource } from './source-spec.mjs';
+import { createRepositoryTransaction } from './repository-observation.mjs';
+import { createWorkspaceDiscovery } from './workspace-discovery.mjs';
+import { packageIntegrity } from './core.mjs';
+import { oatsError } from './errors.mjs';
+
+export const SETUP_EXPERT = 'oats-setup-expert';
+export const SETUP_CAPABILITIES = Object.freeze(['oats.core', 'oats.setup']);
+const EXPORT = `souls/${SETUP_EXPERT}`;
+function validateEdition(bytes) {
+  const { declaration: soul } = parsePortableSoul(bytes);
+  const required = soul.requires || {}, caps = required.capabilities || {};
+  if (soul.name !== SETUP_EXPERT || soul.work !== 'directory'
+      || Object.keys(required).some(key => key !== 'capabilities')
+      || Object.keys(caps).length !== 2 || SETUP_CAPABILITIES.some(id => caps[id]?.source !== 'repo:oats-package' || Object.keys(caps[id]).some(key => key !== 'source'))
+      || ['knowledge', 'messaging', 'tasks'].some(slot => soul.defaults?.[slot] !== 'none')
+      || Object.keys(soul.defaults || {}).some(key => !['knowledge', 'messaging', 'tasks'].includes(key))
+      || soul.knowledge || soul.teams?.length || soul.resources?.length || soul.yolo === true || soul.backend || soul['launch-config']) {
+    throw oatsError('needs-configuration', 'classic setup bootstrap needs the provider-independent directory edition with only oats.core/oats.setup; use explicit portable preparation for other requirements');
+  }
+  return soul;
+}
+function repositoryRequest(source) {
+  if (typeof source !== 'string' || source.includes('#')) throw oatsError('invalid-source', '--workspace needs a Git repository source, optionally @revision, without a package fragment');
+  try { return { source: parseRepositorySource(source).normalized }; }
+  catch {
+    const parsed = parsePortableSource(source);
+    if (parsed.kind !== 'git') throw oatsError('invalid-source', '--workspace needs an explicit Git repository source');
+    return { source: `git:${parsed.url}`, revision: parsed.selector };
+  }
+}
+
+export function loadSetupExpertEdition(workspace, repositoryOptions = {}) {
+  if (workspace === undefined) {
+    const root = fileURLToPath(new URL(`../${EXPORT}/`, import.meta.url));
+    return { declaration: validateEdition(readFileSync(join(root, 'soul.yaml'))), instructions: readFileSync(join(root, 'AGENTS.md'), 'utf8'),
+      source: { kind: 'packaged-definition', captured: false }, packageIntegrity: null };
+  }
+  const request = repositoryRequest(workspace), scratch = realpathSync(mkdtempSync(join(tmpdir(), 'oats-setup-source-'))), owned = lstatSync(scratch);
+  let transaction;
+  try {
+    transaction = createRepositoryTransaction({ ...repositoryOptions, directory: scratch, accessContextKey: 'explicit-setup-source' });
+    const discovery = createWorkspaceDiscovery(transaction), origin = { kind: 'operator', document: { kind: 'operator', id: 'oats-onboard' }, pointer: '/workspace' };
+    const observed = transaction.observe(request.source, { ...request, origin });
+    const workspaceDoc = transaction.readFile(observed, 'oats-workspace.yaml', { optional: true });
+    const view = workspaceDoc ? discovery.readWorkspace({ ...request, origin }) : null;
+    const reference = view?.parsed.imports.find(item => item.alias === SETUP_EXPERT)
+      ?? { source: request.source, revision: observed.source.commit, soul: EXPORT, alias: SETUP_EXPERT };
+    // A selected workspace import never falls back if its exact source fails.
+    const imported = discovery.importSoul(reference, { origin });
+    if (reference.adoption) throw oatsError('needs-configuration', 'classic setup copies an edition only; provider adoption values require the portable preparation path');
+    const declaration = validateEdition(transaction.readFile(imported.observation, imported.definition).bytes);
+    const projection = join(scratch, 'edition');
+    transaction.materialize(imported.observation, imported.roots, projection);
+    const soulRoot = join(projection, dirname(imported.definition)), body = join(soulRoot, 'AGENTS.md'), alias = join(soulRoot, 'CLAUDE.md');
+    if (!lstatSync(body).isFile() || !lstatSync(alias).isSymbolicLink() || readlinkSync(alias) !== 'AGENTS.md'
+        || readdirSync(soulRoot).some(name => !['soul.yaml', 'AGENTS.md', 'CLAUDE.md'].includes(name))) {
+      throw oatsError('source-incomplete', 'classic setup edition must have canonical AGENTS.md/CLAUDE.md and no omitted private skill or knowledge trees');
+    }
+    return { declaration, instructions: readFileSync(body, 'utf8'), packageIntegrity: packageIntegrity(join(projection, 'oats-package')),
+      source: { kind: 'exported-edition-copy', source: imported.reference.source, revision: imported.observation.source.commit,
+        path: imported.reference.soul, workspaceRevision: view?.source.commit ?? null, captured: false } };
+  } finally {
+    transaction?.close();
+    const current = lstatSync(scratch);
+    if (!current.isDirectory() || current.dev !== owned.dev || current.ino !== owned.ino) throw oatsError('source-unavailable', 'setup source scratch ownership changed');
+    rmSync(scratch, { recursive: true });
+  }
+}

package/package-catalog.json

@@ -1,13 +1,14 @@
 {
+  "policy": "docs/official-marketplace.md",
   "packages": {
     "oats.okf": {
       "url": "https://github.com/awebai/oats-okf.git",
-      "ref": "v2.1.0",
+      "ref": "v2.1.1",
       "path": "oats-package"
     },
     "oats.aweb": {
       "url": "https://github.com/awebai/oats-aweb.git",
-      "ref": "v1.10.3",
+      "ref": "v1.11.0",
       "path": "oats-package"
     },
     "oats.jira": {
@@ -30,9 +31,9 @@
       "ref": "v1.0.0",
       "path": "oats-package"
     },
-    "oats.knowledge-theory": {
+    "oats.framework": {
       "url": "https://github.com/awebai/oats.git",
-      "ref": "v0.23.0",
+      "ref": "oats-framework/v1.1.1",
       "path": "oats-package"
     }
   },
@@ -65,6 +66,9 @@
     "oas.review": {
       "package": "oats.dev",
       "capability": "oats.review"
-    }
+    },
+    "oats.knowledge-theory": "oats.framework",
+    "oats.core": "oats.framework",
+    "oats.setup": "oats.framework"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/oats",
-  "version": "0.24.0",
+  "version": "0.24.2",
   "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
   "keywords": [
     "agents",
@@ -36,6 +36,8 @@
     "docs/",
     "README.md",
     "package-catalog.json",
+    "souls/oats-setup-expert/soul.yaml",
+    "souls/oats-setup-expert/AGENTS.md",
     "packages/record/bin/",
     "packages/record/lib/",
     "packages/record/docs/",

package/skills/oats-config/SKILL.md

@@ -4,17 +4,16 @@ description: >-
   Use only for configuring a legacy uncaptured OATS deployment with the current
   oats-config.yaml cascade, including legacy activation, agent types, targeting,
   overrides, and templates. Triggers: "legacy oats-config", "uncaptured config",
-  "oats use", or "agent type". For portable source/workspace preparation, load
-  oats-portable-setup instead; this legacy policy never fills a captured record.
+  "oats use", or "agent type". This legacy policy is not a portable preparation
+  authority and never fills a captured record.
 ---
 
 # Configuring legacy uncaptured OATS
 
 > **Legacy-only procedure.** The cascading scopes, agent-type targeting and
 > closest-team rules below are compatibility behavior for uncaptured instances.
-> They are not portable composition authorities. Use **oats-portable-setup** for
-> the source/workspace two-authority model and never consult this cascade as a
-> fallback during captured preparation or dispatch.
+> They are not portable composition authorities. Never consult this cascade as
+> a fallback during captured preparation or dispatch.
 
 Config lives in `oats-config.yaml` at laptop (`~`), workspace, and repository
 levels; resolution walks from a soul's repository outward, closest scope wins.

package/skills/oats-portable/SKILL.md

@@ -112,5 +112,4 @@ still refuse. Do not strip selectors or call legacy forms as a workaround. A sca
 may contain external hook effects; preserve it and escalate rather than deleting
 it. A scaffold marked `spawned-launch-pending` is not a running instance.
 
-Use **oats-portable-setup** for preparation and context choices. Use
-**oats-portable-artifacts** for exact approval and retained A/B diagnostics.
+Use **oats-portable-artifacts** for exact approval and retained A/B diagnostics.

package/skills/oats-portable-artifacts/SKILL.md

@@ -59,5 +59,5 @@ or source checkout.
 - Partial or unknown historical evidence is inspectable but never executable.
 - No unattended approval, background refresh, or automatic advancement exists.
 
-Use **oats-portable-setup** to create a new preparation transaction. Use
-**oats-portable** to invoke the resulting exact record.
+Use `oats prepare --help` for new preparation inputs and **oats-portable** to
+invoke the resulting exact record.

package/souls/oats-setup-expert/AGENTS.md

@@ -0,0 +1,60 @@
+# OATS Setup Expert
+
+Help an operator turn an empty deployment into a deliberately configured OATS
+workspace. Explain the next small decision, inspect the existing state, obtain
+approval for effects, and verify the result before moving on. Do not replace
+working deployments or turn setup into an implicit enrollment operation.
+
+## Your supplied procedures
+
+- Load **oats-workspace-setup** for workspace/source discovery and adoption:
+  declare, inspect, prepare, approve, scaffold and start are different steps.
+- Load **oats-config** for version-scoped classic configuration and targeting;
+  never use its cascade to fill a missing captured input.
+- Load **oats-packages** for official package discovery, acquisition, exact locks,
+  executable approval and updates.
+- Load **oats-operate** for lifecycle, directory boundaries and supported CLI
+  operations; load **oats-souls** for source editions, roster and relations.
+
+Use the procedures actually included in your composition. Do not fetch a current
+skill or invent a command when an older installed version lacks a feature.
+
+## Setup sequence
+
+1. Establish the operator's intended deployment, work target and workspace/source
+   separately. Inspect existing configuration, locks and souls before proposing
+   changes. A workspace is a shared definition, not a shared live runtime.
+2. Explain `oats-workspace.yaml` and each member's separate `oats.yaml` exports
+   and backlink. Check reciprocal observations; discovery is neither membership
+   enrollment nor capability activation. Pin imports only after a source is
+   published at a real reviewed revision; never invent a future commit or tag.
+3. Select capabilities and their exact sources with the operator. New souls
+   declare removable `oats.core` explicitly. Do not add knowledge, messaging or
+   tasks merely because the package was discovered or acquired.
+4. Keep package acquisition, executable approval, provider configuration and
+   native account/team authorization distinct. Inspect the exact artifact and
+   its effects before asking for approval. An official catalog entry is not a
+   blanket grant to execute hooks or change credentials.
+5. Use the supported prepare/approve/scaffold/start path for retained portable
+   adoption. Verify complete resources and required provider readiness before
+   native effects. A successful inspection, scaffold or submitted command is
+   not proof of a working session, message delivery or accepted learning.
+
+## Bootstrap and safety boundaries
+
+This setup role has no hard knowledge or messaging dependency: it must be useful
+before OKF or aweb is configured. Its defaults permit none. That does NOT permit
+removing another soul's hard requirements to make a failing launch appear ready.
+
+A classic local bootstrap copy is not a captured preparation or retained source
+identity. Say which path created your current soul and do not claim one path's
+receipts as evidence for the other. Keep a source edition and an operator-local
+configuration distinct; never commit live identities, machine paths, accounts,
+private bindings or credentials into exported source definitions.
+
+Never auto-launch a model session, enable dangerous permissions, enroll an
+identity, install a host service, overwrite an existing soul or migrate knowledge
+without the operator's explicit instruction. Use ordinary native runtime auth;
+missing auth is a human login step, not permission to inspect, copy or wrap
+credentials. Preserve existing instances, pending jobs, locks and failed receipts.
+Report unsupported operations or infrastructure faults instead of bypassing them.

package/souls/oats-setup-expert/soul.yaml

@@ -0,0 +1,14 @@
+schemaVersion: 1
+name: oats-setup-expert
+description: Guide an operator through OATS workspace adoption and explicit capability setup.
+work: directory
+requires:
+  capabilities:
+    oats.core:
+      source: repo:oats-package
+    oats.setup:
+      source: repo:oats-package
+defaults:
+  knowledge: none
+  messaging: none
+  tasks: none

package/skills/oats-portable-setup/SKILL.md

@@ -1,69 +0,0 @@
----
-name: oats-portable-setup
-description: >-
-  Use when preparing a source-complete portable soul for a fresh deployment,
-  selecting a workspace-advertised import, or reasoning about source,
-  deployment, work target, team, adoption, and provider-binding inputs. Triggers:
-  "oats prepare", "portable setup", "import soul by reference", "fresh OATS
-  deployment". Do not use legacy oats-config.yaml cascading as portable policy.
----
-
-# Preparing portable souls
-
-Portable preparation has two policy authorities and one resolver:
-
-1. The soul supplies intrinsic hard requirements and rebindable defaults.
-2. The workspace supplies admission, workspace defaults, imports/adoption,
-   stores, team references, and catalogs.
-3. Explicit operator choices may rebind defaults and bindings but cannot erase
-   hard requirements.
-
-There is no repository-default tier and no agent-type precedence in this model.
-A package source, soul source, deployment/install location, work target, and team
-membership are separate facts. Never derive one from another.
-
-## Implemented preparation
-
-Prepare an explicit source export by reference:
-
-```bash
-oats prepare \
-  --dir <absolute-deployment> \
-  --source <git-repository> --revision <selector> \
-  --export <exported-soul-path> --alias <local-alias> \
-  [--work directory] --json
-```
-
-Prepare an alias advertised by an explicit workspace:
-
-```bash
-oats prepare \
-  --dir <absolute-deployment> \
-  --workspace <git-repository> [--workspace-revision <selector>] \
-  --alias <advertised-alias> [--work directory] --json
-```
-
-Preparation resolves one source observation, retains the required source and
-software trees, resolves provider-owned nonsecret bindings through the same
-choice engine, prepares dedicated compatible helpers, and publishes a complete
-record before returning a resolution. It does not launch, enroll identities,
-create teams, approve executables, or infer a publisher workspace.
-
-## Read the result correctly
-
-- `resolution: null` means no executable captured record was published.
-- `needs-configuration` identifies missing bindings/provider inputs; do not fill
-  them from current config.
-- `approval-required` can accompany a complete retained record; approval remains
-  a separate explicit action.
-- `responsibleHuman: null` means messaging is explicitly disabled.
-- Helper-authored software, knowledge, team, or resource policy currently
-  requires dedicated preparation and refuses instead of inheriting the parent.
-
-## Not yet a public input
-
-An explicit standalone context key, onboarding inspection facade, non-directory
-work-target placement/setup, and managed launch/runtime capture are still being
-integrated. Do not invent flags or derive a standalone key from a path, username,
-source alias, or machine identity. A workspace context and standalone context are
-mutually exclusive.