@geraldmaron/construct 1.2.2 → 1.3.0

package/lib/mcp/tools/find-tool.mjs

@@ -0,0 +1,86 @@
+/**
+ * lib/mcp/tools/find-tool.mjs — find_tool: intent-driven tool discovery.
+ *
+ * Ranks the tool catalog against a natural-language query so an agent that knows
+ * what it wants to do, but not the exact tool name, gets the right tools with
+ * their schemas. Hybrid scoring: normalized BM25 (always, offline) merged with
+ * local-embedding cosine when a real semantic model is available. Degraded
+ * hashing embeddings are ignored so they cannot pollute the lexical ranking.
+ */
+import { rankByBm25, cosineSimilarity } from '../../storage/embeddings.mjs';
+
+let toolVectorCache = null;
+
+function buildCorpus(toolDefs) {
+  return toolDefs.map((t) => ({
+    name: t.name,
+    description: t.description || '',
+    inputSchema: t.inputSchema,
+    text: `${t.name} ${t.description || ''}`,
+  }));
+}
+
+async function mergeCosine(scoreMap, corpus, query, env) {
+  const { embedText, embedBatch } = await import('../../storage/embeddings-engine.mjs');
+  const q = await embedText(query, { env });
+
+  // A degraded result means the real model was unavailable and hashing stood in;
+  // those vectors carry no semantic signal, so leave the BM25 ranking unmerged.
+
+  if (q?.degraded || !q?.embedding) return;
+
+  // Embed the catalog once per process: the tool set is static for the server's
+  // lifetime, so size-equality is a sufficient cache key. If tools ever become
+  // dynamic (MCP list_changed), this needs a real version key. embedBatch
+  // degrades all-or-nothing, so one degraded vector means the whole batch fell
+  // back to hashing — skip the merge rather than mix real and hashed vectors.
+
+  if (!toolVectorCache || toolVectorCache.size !== corpus.length) {
+    const vecs = await embedBatch(corpus.map((c) => c.text), { env });
+    if (vecs.some((v) => v?.degraded)) return;
+    toolVectorCache = new Map(corpus.map((c, i) => [c.name, vecs[i].embedding]));
+  }
+  for (const c of corpus) {
+    const cos = cosineSimilarity(q.embedding, toolVectorCache.get(c.name) || []);
+    if (cos > 0.05) scoreMap.set(c.name, Math.max(scoreMap.get(c.name) || 0, cos));
+  }
+}
+
+export async function findTool(args = {}, { toolDefs = [], env = process.env } = {}) {
+  const query = String(args.query || args.intent || '').trim();
+  if (!query) return { error: 'find_tool requires a `query` describing what you want to do.' };
+  const limit = Math.min(Math.max(Number(args.limit) || 5, 1), 20);
+
+  const corpus = buildCorpus(toolDefs);
+
+  // BM25 is unbounded; normalize against its own max so it merges fairly with
+  // cosine on [0,1].
+
+  const bm25 = rankByBm25(corpus, query, { limit: 20 });
+  const bm25Max = bm25[0]?.score || 1;
+  const scoreMap = new Map();
+  for (const d of bm25) scoreMap.set(d.name, Math.min(d.score / bm25Max, 1));
+
+  try {
+    await mergeCosine(scoreMap, corpus, query, env);
+  } catch {
+    /* embeddings unavailable — BM25-only is the offline-safe path */
+  }
+
+  const byName = new Map(corpus.map((c) => [c.name, c]));
+  const tools = [...scoreMap.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, limit)
+    .map(([name, score]) => ({
+      name,
+      description: byName.get(name).description,
+      inputSchema: byName.get(name).inputSchema,
+      score: Number(score.toFixed(3)),
+    }));
+
+  return {
+    query,
+    tools,
+    note: 'Invoke a result with { name: "call", arguments: { tool: "<name>", args: {…} } }, or call it directly if it is already a flat tool.',
+  };
+}

package/lib/mcp/tools/orchestration-run.mjs

@@ -1,123 +1,161 @@
 /**
- * lib/mcp/tools/orchestration-run.mjs — MCP client for the local orchestration daemon.
+ * lib/mcp/tools/orchestration-run.mjs — MCP entry for Construct orchestration.
  *
- * Executes a real multi-specialist run by driving the daemon's HTTP API
- * (ADR-0022), so MCP hosts with no subagent primitive — VS Code/Copilot, Cursor —
- * reach orchestrated outcomes through a tool they actually expose: the engine
- * owns orchestration; this tool is the thin client. The daemon URL resolves from
- * dashboard state (else the default loopback port) and the bearer token from
- * ~/.construct/config.env. When the daemon is unreachable the tool fails fast
- * with an actionable error rather than silently degrading to a single-persona
- * pass — the absence of an executable path is made loud, not hidden.
+ * Runs a real multi-specialist orchestration so MCP hosts with no subagent
+ * primitive (VS Code/Copilot, Cursor) reach orchestrated outcomes through a tool
+ * they already expose. The engine is the in-process orchestration runtime
+ * (lib/orchestration/runtime.mjs) — solo runs need no daemon, no port, no token
+ * (ADR-0022: the engine owns orchestration; ADR-0041 owned loop). When
+ * CONSTRUCT_ORCHESTRATION_URL points at a remote/team orchestration service the
+ * same call is proxied over HTTP instead, with the bearer token resolved from the
+ * Construct env (CONSTRUCT_ORCHESTRATION_TOKEN / CONSTRUCT_DASHBOARD_TOKEN), not
+ * from the dashboard server.
  */
 
-import { readDashboardState } from '../../service-manager.mjs';
-import { getDashboardToken } from '../../server/auth.mjs';
+import { runOrchestration, startRun, getRun, getRuns } from '../../orchestration/runtime.mjs';
 
 const TERMINAL = ['completed', 'completed-with-failures', 'cancelled', 'error'];
 
-function resolveDaemon(env = process.env) {
-  const state = readDashboardState();
-  const base = (env.CONSTRUCT_ORCHESTRATION_URL || state?.url || `http://${env.BIND_HOST || '127.0.0.1'}:${env.PORT || '4242'}`).replace(/\/$/, '');
-  return { base, token: getDashboardToken(), daemonRunning: Boolean(state) };
+function shapeRun(run) {
+  return {
+    runId: run.runId,
+    status: run.status,
+    executionMode: run.execution?.executionMode,
+    degraded: run.execution?.degraded ?? false,
+    degradationReason: run.execution?.degradationReason ?? null,
+    intent: run.plan?.intent ?? null,
+    track: run.plan?.track ?? null,
+    suggestedWorkflowType: run.plan?.suggestedWorkflowType ?? null,
+    researchExecutionPolicy: run.plan?.researchExecutionPolicy ?? null,
+    specialists: run.plan?.specialists ?? [],
+    tasks: (run.tasks || []).map((t) => ({
+      id: t.id, role: t.role, status: t.status, executor: t.executor,
+      output: t.output ?? null, reasoning: t.reasoning ?? null, error: t.error ?? null,
+    })),
+  };
+}
+
+function toRequest(args) {
+  return {
+    request: args.request,
+    workflowType: args.workflow_type,
+    requestedStrategy: args.requested_strategy ?? 'auto',
+    host: args.host,
+    hostModel: args.host_model,
+    hostProvider: args.host_provider,
+    fileCount: args.file_count,
+    moduleCount: args.module_count,
+  };
 }
 
-// A reachability failure is the fail-fast signal MCP hosts need: report how to
-// start the engine instead of letting the host fall back to a manual pass.
+// A remote orchestration service is opt-in: only when CONSTRUCT_ORCHESTRATION_URL
+// is set (team / enterprise). The token comes from the Construct env, not from
+// the dashboard server, so the in-process default path carries no dashboard coupling.
+
+function remoteService(env) {
+  const url = env.CONSTRUCT_ORCHESTRATION_URL;
+  if (!url) return null;
+  const token = env.CONSTRUCT_ORCHESTRATION_TOKEN || env.CONSTRUCT_DASHBOARD_TOKEN || null;
+  return { base: url.replace(/\/$/, ''), token };
+}
 
 function unreachable(base, detail) {
   return {
-    error: `Orchestration daemon not reachable at ${base}: ${detail}. Start it with \`construct dashboard\`, then retry. The engine runs orchestration; this host is a thin client (ADR-0022).`,
-    daemon: base,
+    error: `Remote orchestration service not reachable at ${base}: ${detail}. Unset CONSTRUCT_ORCHESTRATION_URL to run in-process, or start the service and retry.`,
+    service: base,
     failFast: true,
   };
 }
 
-export async function orchestrationRun(args = {}, { fetchImpl = fetch, env = process.env } = {}) {
-  const {
-    request,
-    workflow_type,
-    requested_strategy = 'auto',
-    worker_backend,
-    host,
-    host_model,
-    host_provider,
-    file_count,
-    module_count,
-    wait = true,
-    timeout_ms = 120000,
-  } = args;
-
-  if (!request || typeof request !== 'string') return { error: 'Missing "request" string describing the work to orchestrate.' };
-
-  const { base, token } = resolveDaemon(env);
-  const headers = { 'Content-Type': 'application/json', ...(token ? { Authorization: `Bearer ${token}` } : {}) };
-  const body = JSON.stringify({
-    request,
-    workflowType: workflow_type,
-    requestedStrategy: requested_strategy,
-    workerBackend: worker_backend,
-    host,
-    hostModel: host_model,
-    hostProvider: host_provider,
-    fileCount: file_count,
-    moduleCount: module_count,
-  });
+export async function orchestrationRun(args = {}, { env = process.env, cwd = process.cwd(), fetchImpl = fetch } = {}) {
+  const { request, worker_backend, wait = true, timeout_ms = 120000 } = args;
+  if (!request || typeof request !== 'string') {
+    return { error: 'Missing "request" string describing the work to orchestrate.' };
+  }
+
+  const reqObj = toRequest(args);
+  const remote = remoteService(env);
+  if (remote) return runViaService(remote, reqObj, { wait, timeout_ms, workerBackend: worker_backend, fetchImpl });
+
+  const opts = { env, cwd, workerBackend: worker_backend, fetchImpl };
+  try {
+    if (!wait) {
+      const planned = await startRun(reqObj, opts);
+      return { runId: planned.runId, status: planned.status, executionMode: planned.execution?.executionMode, poll: 'orchestration_status with run_id' };
+    }
+    return shapeRun(await runOrchestration(reqObj, opts));
+  } catch (err) {
+    return { error: `Orchestration failed: ${err.message}`, failFast: true };
+  }
+}
+
+export async function orchestrationStatus(args = {}, { env = process.env, cwd = process.cwd(), fetchImpl = fetch } = {}) {
+  const { run_id, limit = 20 } = args;
+  const remote = remoteService(env);
+  if (remote) return statusViaService(remote, { run_id, limit }, { fetchImpl });
+  try {
+    if (run_id) {
+      const run = await getRun(cwd, run_id, { env });
+      return run || { error: `No run found with id ${run_id}.` };
+    }
+    return await getRuns(cwd, { env, limit });
+  } catch (err) {
+    return { error: `Failed to read orchestration runs: ${err.message}` };
+  }
+}
+
+// Remote (team / enterprise) HTTP path. Reached only when CONSTRUCT_ORCHESTRATION_URL
+// is set; the wire shape matches the standalone orchestration service's
+// /api/orchestration/runs contract (ADR-0022).
 
+async function runViaService(remote, reqObj, { wait, timeout_ms, workerBackend, fetchImpl }) {
+  const { base, token } = remote;
+  const headers = { 'Content-Type': 'application/json', ...(token ? { Authorization: `Bearer ${token}` } : {}) };
+  const body = JSON.stringify({ ...reqObj, workerBackend });
   let started;
   try {
     const res = await fetchImpl(`${base}/api/orchestration/runs`, { method: 'POST', headers, body });
     if (res.status === 401 || res.status === 403) {
-      return { error: `Daemon rejected the request (HTTP ${res.status}). The dashboard token is missing or wrong — check CONSTRUCT_DASHBOARD_TOKEN in ~/.construct/config.env.`, daemon: base, failFast: true };
+      return { error: `Remote service rejected the request (HTTP ${res.status}). Set CONSTRUCT_ORCHESTRATION_TOKEN (or CONSTRUCT_DASHBOARD_TOKEN).`, service: base, failFast: true };
     }
     const envelope = await res.json();
-    if (!res.ok) return { error: `Daemon error (HTTP ${res.status}): ${envelope.error || 'unknown'}`, daemon: base };
+    if (!res.ok) return { error: `Remote service error (HTTP ${res.status}): ${envelope.error || 'unknown'}`, service: base };
     started = envelope.data;
   } catch (err) {
     return unreachable(base, err.message);
   }
 
   if (!wait) {
-    return { runId: started.runId, status: started.status, executionMode: started.execution?.executionMode, daemon: base, poll: 'orchestration_status with run_id' };
+    return { runId: started.runId, status: started.status, executionMode: started.execution?.executionMode, service: base, poll: 'orchestration_status with run_id' };
   }
 
   const deadline = Date.now() + timeout_ms;
   let run = started;
   while (!TERMINAL.includes(run.status)) {
     if (Date.now() > deadline) {
-      return { runId: started.runId, status: run.status, timedOut: true, daemon: base, note: 'Run is still executing; poll it with orchestration_status.' };
+      return { runId: started.runId, status: run.status, timedOut: true, service: base, note: 'Run is still executing; poll it with orchestration_status.' };
     }
     await new Promise((r) => setTimeout(r, 250));
     try {
       const res = await fetchImpl(`${base}/api/orchestration/runs/${encodeURIComponent(started.runId)}`, { headers });
       const envelope = await res.json();
-      if (!res.ok) return { error: `Daemon error while polling (HTTP ${res.status}): ${envelope.error || 'unknown'}`, runId: started.runId, daemon: base };
+      if (!res.ok) return { error: `Remote service error while polling (HTTP ${res.status}): ${envelope.error || 'unknown'}`, runId: started.runId, service: base };
       run = envelope.data;
     } catch (err) {
-      return { error: `Lost connection to the daemon while polling run ${started.runId}: ${err.message}`, runId: started.runId, daemon: base, failFast: true };
+      return { error: `Lost connection to the remote service while polling run ${started.runId}: ${err.message}`, runId: started.runId, service: base, failFast: true };
     }
   }
-
-  return {
-    runId: run.runId,
-    status: run.status,
-    executionMode: run.execution?.executionMode,
-    degraded: run.execution?.degraded ?? false,
-    degradationReason: run.execution?.degradationReason ?? null,
-    tasks: (run.tasks || []).map((t) => ({ id: t.id, role: t.role, status: t.status, executor: t.executor, output: t.output ?? null, reasoning: t.reasoning ?? null, error: t.error ?? null })),
-    daemon: base,
-  };
+  return { ...shapeRun(run), service: base };
 }
 
-export async function orchestrationStatus(args = {}, { fetchImpl = fetch, env = process.env } = {}) {
-  const { run_id, limit = 20 } = args;
-  const { base, token } = resolveDaemon(env);
+async function statusViaService(remote, { run_id, limit }, { fetchImpl }) {
+  const { base, token } = remote;
   const headers = token ? { Authorization: `Bearer ${token}` } : {};
   const path = run_id ? `/api/orchestration/runs/${encodeURIComponent(run_id)}` : `/api/orchestration/runs?limit=${encodeURIComponent(limit)}`;
   try {
     const res = await fetchImpl(`${base}${path}`, { headers });
     const envelope = await res.json();
-    if (!res.ok) return { error: `Daemon error (HTTP ${res.status}): ${envelope.error || 'unknown'}`, daemon: base };
+    if (!res.ok) return { error: `Remote service error (HTTP ${res.status}): ${envelope.error || 'unknown'}`, service: base };
     return envelope.data;
   } catch (err) {
     return unreachable(base, err.message);

package/lib/mcp/tools/project.mjs

@@ -5,13 +5,14 @@
  * All tools are synchronous except where noted. Requires ROOT_DIR and homedir from the caller.
  */
 import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { loadRegistry } from '../../registry/loader.mjs';
 import { join, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import { execSync } from 'node:child_process';
 import { loadConstructEnv } from '../../env-config.mjs';
 import { inspectContextState } from '../../context-state.mjs';
 import { loadWorkflow, summarizeWorkflow, inspectWorkflowHealth } from '../../workflow-state.mjs';
-import { readCurrentModels, resolveExecutionContractModelMetadata, selectModelTierForWorkCategory } from '../../model-router.mjs';
+import { resolveExecutionContractModelMetadata, selectModelTierForWorkCategory } from '../../model-router.mjs';
 import { buildPublicHealthSurface } from '../../status.mjs';
 import { doctorRoot } from '../../config/xdg.mjs';
 
@@ -282,7 +283,7 @@ export function projectContext(args, { ROOT_DIR }) {
   const has_context_file = contextInspection.hasFile;
   const workflow = loadWorkflow(cwd);
   const mergedEnv = loadConstructEnv({ rootDir: ROOT_DIR, homeDir: homedir(), env: process.env });
-  const registry = readJSON(join(ROOT_DIR, 'specialists', 'registry.json')) ?? {};
+  const registry = loadRegistry({ rootDir: ROOT_DIR });
   const executionContractModel = resolveExecutionContractModelMetadata({
     envValues: mergedEnv,
     registryModels: registry.models ?? {},
@@ -324,7 +325,7 @@ export function workflowStatus(args, { ROOT_DIR }) {
   const workflow = loadWorkflow(cwd);
   const workflowHealth = inspectWorkflowHealth(workflow, { cwd });
   const mergedEnv = loadConstructEnv({ rootDir: ROOT_DIR, homeDir: homedir(), env: process.env });
-  const registry = readJSON(join(ROOT_DIR, 'specialists', 'registry.json')) ?? {};
+  const registry = loadRegistry({ rootDir: ROOT_DIR });
   const executionContractModel = resolveExecutionContractModelMetadata({
     envValues: mergedEnv,
     registryModels: registry.models ?? {},

package/lib/mcp/tools/{profile.mjs → scope.mjs}

@@ -1,7 +1,7 @@
 /**
- * lib/mcp/tools/profile.mjs — MCP wrappers for the org-profile + learning surfaces.
+ * lib/mcp/tools/scope.mjs — MCP wrappers for the org-scope + learning surfaces.
  *
- * Bridges PR #67 capabilities (profiles, outcomes, sandboxes, knowledge_add,
+ * Bridges PR #67 capabilities (scopes, outcomes, sandboxes, knowledge_add,
  * learning status) so subagents talking through the construct-mcp server can
  * read the same state the CLI exposes. Operator-only surfaces (optimize_apply,
  * optimize_rollback) remain CLI-only and are not registered here.
@@ -9,7 +9,7 @@
  * Pattern: each export is a thin schema-validated wrapper around the existing
  * lib/* function the CLI already uses. Errors return `{ error: string }` so
  * the MCP dispatcher hands a structured failure back instead of crashing.
- * Destructive operations (profile_archive) require `confirm: true`, matching
+ * Destructive operations (scope_archive) require `confirm: true`, matching
  * the storage_reset / delete_ingested_artifacts pattern in tools/storage.mjs.
  */
 import { resolve } from 'node:path';
@@ -17,17 +17,17 @@ import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 
 import {
-  loadProfile,
-  listProfiles,
-  loadCustomProfile,
-  resolveActiveProfile,
-} from '../../profiles/loader.mjs';
+  loadScope,
+  listScopes,
+  loadCustomScope,
+  resolveActiveScope,
+} from '../../scopes/loader.mjs';
 import {
-  createDraftProfile,
+  createDraftScope,
   listDrafts,
-  archiveProfile,
-  profileHealth,
-} from '../../profiles/lifecycle.mjs';
+  archiveScope,
+  scopeHealth,
+} from '../../scopes/lifecycle.mjs';
 import { recordOutcome } from '../../outcomes/record.mjs';
 import { aggregateOutcomes, readSummary } from '../../outcomes/aggregate.mjs';
 import { addResearchFinding } from '../../knowledge/research-store.mjs';
@@ -38,73 +38,75 @@ function cwdOf(args) {
   return args && args.cwd ? resolve(String(args.cwd)) : process.cwd();
 }
 
-// Read-only: active profile.
+// Read-only: active scope.
 
-export function profileShow(args = {}) {
+export function scopeShow(args = {}) {
   const cwd = cwdOf(args);
-  const profile = resolveActiveProfile(cwd, args.id ? String(args.id) : null);
+  const scope = resolveActiveScope(cwd, args.id ? String(args.id) : null);
   return {
-    id: profile.id,
-    displayName: profile.displayName ?? profile.id,
-    tagline: profile.tagline ?? null,
-    custom: profile.custom === true,
-    roles: Array.isArray(profile.roles) ? profile.roles : [],
-    departments: Array.isArray(profile.departments)
-      ? profile.departments.map((d) => ({ id: d.id, displayName: d.displayName, roleCount: Array.isArray(d.roles) ? d.roles.length : 0 }))
+    id: scope.id,
+    displayName: scope.displayName ?? scope.id,
+    tagline: scope.tagline ?? null,
+    custom: scope.custom === true,
+    roles: Array.isArray(scope.roles) ? scope.roles : [],
+    teams: Array.isArray(scope.teams)
+      ? scope.teams.map((t) => ({ id: t.id, name: t.name, roleCount: Array.isArray(t.roles) ? t.roles.length : 0 }))
       : [],
+    experimental: scope.experimental === true,
     intake: {
-      types: profile.intake?.types ?? [],
-      stages: profile.intake?.stages ?? [],
+      types: scope.intake?.types ?? [],
+      stages: scope.intake?.stages ?? [],
     },
-    docTemplates: profile.docTemplates ?? [],
-    hooks: profile.hooks ?? null,
-    rebrand: profile.rebrand ?? null,
+    docTemplates: scope.docTemplates ?? [],
+    hooks: scope.hooks ?? null,
+    rebrand: scope.rebrand ?? null,
   };
 }
 
 // Read-only: catalog summary.
 
-export function profileList() {
+export function scopeList() {
   return {
-    profiles: listProfiles().map((id) => {
-      const p = loadProfile(id);
+    scopes: listScopes().map((id) => {
+      const p = loadScope(id);
       return p
         ? {
             id: p.id,
             displayName: p.displayName ?? p.id,
             tagline: p.tagline ?? null,
             roleCount: Array.isArray(p.roles) ? p.roles.length : 0,
-            departmentCount: Array.isArray(p.departments) ? p.departments.length : 0,
+            teamCount: Array.isArray(p.teams) ? p.teams.length : 0,
+            experimental: p.experimental === true,
           }
         : { id, error: 'failed to parse' };
     }),
   };
 }
 
-// Read-only: drafts + custom profile under .cx/.
+// Read-only: drafts + custom scope under .cx/.
 
-export function profileDrafts(args = {}) {
+export function scopeDrafts(args = {}) {
   const cwd = cwdOf(args);
   const drafts = listDrafts(cwd).map((d) => ({
     id: d.id,
     dir: d.dir,
-    hasProfile: d.hasProfile,
+    hasScope: d.hasScope,
     hasBrief: d.hasBrief,
   }));
-  const custom = loadCustomProfile(cwd);
+  const custom = loadCustomScope(cwd);
   return {
     drafts,
     custom: custom ? { id: custom.id, displayName: custom.displayName ?? custom.id } : null,
   };
 }
 
-// Read-only: per-profile health rollup.
+// Read-only: per-scope health rollup.
 
-export function profileHealthTool(args = {}) {
+export function scopeHealthTool(args = {}) {
   const cwd = cwdOf(args);
-  const id = args.id ? String(args.id) : resolveActiveProfile(cwd).id;
+  const id = args.id ? String(args.id) : resolveActiveScope(cwd).id;
   const windowDays = Number.isFinite(args.window_days) ? Number(args.window_days) : 30;
-  return { id, windowDays, ...profileHealth(cwd, id, { windowDays }) };
+  return { id, windowDays, ...scopeHealth(cwd, id, { windowDays }) };
 }
 
 // Read-only: outcomes rollup. Optional aggregate=true rebuilds _summary.json.
@@ -129,7 +131,7 @@ export function outcomesRecord(args = {}) {
   if (!args.role || typeof args.success !== 'boolean') {
     return { error: 'outcomes_record requires role:string and success:boolean' };
   }
-  const profile = args.profile ? String(args.profile) : resolveActiveProfile(cwd)?.id;
+  const profile = args.profile ? String(args.profile) : resolveActiveScope(cwd)?.id;
   const file = recordOutcome(cwd, {
     role: String(args.role),
     intakeId: args.intake_id ? String(args.intake_id) : null,
@@ -167,16 +169,16 @@ export async function knowledgeAdd(args = {}) {
   }
 }
 
-// Mutating, gated: scaffold a draft profile.
+// Mutating, gated: scaffold a draft scope.
 
-export function profileCreate(args = {}) {
+export function scopeCreate(args = {}) {
   if (args.confirm !== true) {
-    return { error: 'profile_create requires confirm=true to scaffold files' };
+    return { error: 'scope_create requires confirm=true to scaffold files' };
   }
   const cwd = cwdOf(args);
-  if (!args.id) return { error: 'profile_create requires id:string' };
+  if (!args.id) return { error: 'scope_create requires id:string' };
   try {
-    const res = createDraftProfile({
+    const res = createDraftScope({
       cwd,
       id: String(args.id),
       displayName: args.display_name ? String(args.display_name) : undefined,
@@ -196,17 +198,17 @@ export function profileCreate(args = {}) {
   }
 }
 
-// Mutating, gated, destructive: archive a curated profile.
+// Mutating, gated, destructive: archive a curated scope.
 
-export function profileArchive(args = {}) {
+export function scopeArchive(args = {}) {
   if (args.confirm !== true) {
-    return { error: 'profile_archive requires confirm=true (destructive: moves files into archive/profiles/)' };
+    return { error: 'scope_archive requires confirm=true (destructive: moves files into archive/scopes/)' };
   }
   if (!args.id || !args.reason || String(args.reason).trim().length < 8) {
-    return { error: 'profile_archive requires id:string and reason:string (>=8 chars)' };
+    return { error: 'scope_archive requires id:string and reason:string (>=8 chars)' };
   }
   try {
-    return { ok: true, ...archiveProfile({ id: String(args.id), reason: String(args.reason) }) };
+    return { ok: true, ...archiveScope({ id: String(args.id), reason: String(args.reason) }) };
   } catch (err) {
     return { error: err.message ?? String(err) };
   }
@@ -258,11 +260,11 @@ export function learningStatus(args = {}) {
     }
   } catch { /* best effort */ }
 
-  const profile = resolveActiveProfile(cwd);
+  const scope = resolveActiveScope(cwd);
   const outcomes = readSummary(cwd) || { roles: {} };
 
   return {
-    profile: { id: profile.id, displayName: profile.displayName ?? profile.id, custom: profile.custom === true },
+    scope: { id: scope.id, displayName: scope.displayName ?? scope.id, custom: scope.custom === true },
     observations,
     research: { count: researchCount },
     outcomes,