@geraldmaron/construct 1.0.16 → 1.0.18

package/lib/init-unified.mjs

@@ -283,20 +283,26 @@ function parseWithDocs(value) {
     return LANE_ORDER;
   }
   
-  const lanes = value.split(',').map(v => v.trim().toLowerCase());
-  const validLanes = lanes.filter(lane => LANE_ORDER.includes(lane));
-  
-  // Map common aliases
-  const mapped = validLanes.map(lane => {
-    if (lane === 'adr') return 'adrs';
-    if (lane === 'rfc') return 'rfcs';
-    if (lane === 'runbook') return 'runbooks';
-    if (lane === 'postmortem') return 'postmortems';
-    if (lane === 'prd') return 'prds';
-    return lane;
-  });
-  
-  return [...new Set(mapped)]; // dedupe
+  // Map singular aliases to canonical lane keys BEFORE validating, so
+  // `--with-docs=adr,rfc` resolves rather than being silently filtered out.
+  const ALIASES = { adr: 'adrs', rfc: 'rfcs', runbook: 'runbooks', postmortem: 'postmortems', prd: 'prds', brief: 'briefs', memo: 'memos', changelog: 'changelogs', meeting: 'meetings', note: 'notes' };
+
+  const requested = value.split(',').map(v => v.trim().toLowerCase()).filter(Boolean);
+  const resolved = [];
+  const unknown = [];
+  for (const lane of requested) {
+    const canonical = ALIASES[lane] || lane;
+    if (LANE_ORDER.includes(canonical)) resolved.push(canonical);
+    else unknown.push(lane);
+  }
+
+  // Surface typo'd lanes loudly instead of dropping them silently; valid lanes
+  // still proceed so one bad token does not abort init.
+  if (unknown.length) {
+    console.warn(`Warning: ignoring unknown --with-docs lane(s): ${unknown.join(', ')}. Valid lanes: ${LANE_ORDER.join(', ')}`);
+  }
+
+  return [...new Set(resolved)]; // dedupe
 }
 
 function inferProjectName(targetPath) {
@@ -741,8 +747,6 @@ This project enforces documentation quality:
 }
 
 function preflight(target) {
-  console.log('[TRACE init:pre-flight]');
-  
   // Check git repo
   try {
     execSync('git rev-parse --show-toplevel', { cwd: target, stdio: 'ignore' });
@@ -797,6 +801,14 @@ async function main() {
 
   const { clean } = preflight(target);
 
+  // Interactive sessions check machine prerequisites up front and offer to run
+  // `construct install` before any scaffolding, so a missing dependency is
+  // surfaced at the start rather than midway. Non-interactive runs rely on
+  // preflight's git check and stay silent so CI/tests are unaffected.
+  if (interactive && process.stdin.isTTY) {
+    await checkPrerequisites();
+  }
+
   if (!quiet) {
     console.log(`Initializing Construct in ${path.relative(process.cwd(), target) || "."}`);
   }
@@ -1037,7 +1049,6 @@ async function main() {
   // so the user can inspect what's watched and edit the file directly. Empty
   // parentDirs is the correct default: the inbox watcher always scans
   // .cx/inbox/ and docs/intake/ (when present); extra dirs are opt-in.
-  console.log('[TRACE init:intake-ask]');
 
   const intakeConfig = (await askIntakeCollection(target, skipInteractive)) ?? { parentDirs: [], maxDepth: 4 };
   // When a custom intake surface was detected, default includeProjectInbox
@@ -1063,8 +1074,6 @@ async function main() {
   }
   
   // Ask about documentation system
-  console.log('[TRACE init:docs-ask]');
-  
   const { lanes, withArchitecture, withReadme, docsPreset: userDocsPreset } = await askDocumentationQuestions();
   
   // Create README.md if requested or missing
@@ -1072,9 +1081,7 @@ async function main() {
   if (withReadme || !fs.existsSync(readmePath)) {
     writeIfMissing(readmePath, buildProjectReadme(projectName));
   }
-  
-    console.log('[TRACE init:docs-write]');
-  
+
   // Create documentation system if lanes specified
   if (lanes.length > 0) {
     // Filter out lanes that the project already covers elsewhere
@@ -1195,19 +1202,22 @@ async function main() {
     console.log('  NEXT STEPS');
     console.log('═══════════════════════════════════════════════════════════');
     console.log('');
-    console.log('1. Review AGENTS.md');
+    // Number steps from a running counter so the list stays sequential when
+    // the optional intake step is absent (was: hard-coded 1,2,4 → a visible gap).
+    let step = 0;
+    console.log(`${++step}. Review AGENTS.md`);
     console.log('   Operating rules and guidelines for this project');
     console.log('');
-    console.log('2. Edit plan.md');
+    console.log(`${++step}. Edit plan.md`);
     console.log('   Add your current work and tasks');
     console.log('');
     if (lanes.includes('intake')) {
-      console.log('3. Use Intake');
+      console.log(`${++step}. Use Intake`);
       console.log('   Drop files in .cx/inbox/ for processing');
       console.log('   Run: construct intake');
       console.log('');
     }
-    console.log('4. Start working');
+    console.log(`${++step}. Start working`);
     console.log('   Address @construct in your editor to begin');
     console.log('');
   }

package/lib/intake/classify.mjs

@@ -90,6 +90,9 @@ const FILENAME_HINTS = [
   { re: /eval|metric|benchmark/i, intakeType: 'eval-finding' },
   { re: /-bug\b|\bbug-/i, intakeType: 'bug' },
   { re: /runbook/i, intakeType: 'ops' },
+  { re: /^memo[-_]|[-_]memo\b/i, intakeType: 'memo' },
+  { re: /transcript|meeting-notes|standup|stand-up/i, intakeType: 'transcript' },
+  { re: /dataset|raw-?data|data-?dump|\.csv$|\.tsv$/i, intakeType: 'raw-data' },
 ];
 
 // Title-level family terms by intakeType. When the doc's H1 contains a
@@ -105,6 +108,9 @@ const TITLE_FAMILY = {
   'eval-finding': /^#\s*(eval(uation)?(\s+finding)?\b|benchmark)/im,
   bug: /^#\s*(bug\s+report|defect)\b/im,
   ops: /^#\s*(runbook|operations\s+guide)\b/im,
+  memo: /^#\s*(memo|decision\s+memo|status\s+update)\b/im,
+  transcript: /^#\s*(transcript|meeting\s+(notes|minutes)|call\s+notes)\b/im,
+  'raw-data': /^#\s*(dataset|raw\s+data|data\s+export)\b/im,
 };
 
 // Title-lock returns the highest confidence the classifier emits because

package/lib/intake/tables/rnd.mjs

@@ -22,6 +22,9 @@ export const INTAKE_TYPES = [
   'ops',
   'security',
   'legal-compliance',
+  'memo',
+  'transcript',
+  'raw-data',
   'unknown',
 ];
 
@@ -170,6 +173,36 @@ export const CLASSIFICATION_TABLE = [
     risk: 'low',
     requiresApproval: false,
   },
+  {
+    intakeType: 'memo',
+    keywords: ['memo', 'decision memo', 'for your information', 'fyi', 'action item', 'action items', 'status update', 'weekly update', 'announcement', 'heads up', 'team update', 'decided to', 'proposal to'],
+    rdStage: 'artifact',
+    primaryOwner: 'docs-keeper',
+    recommendedChain: ['docs-keeper', 'reviewer'],
+    recommendedAction: 'summarize',
+    risk: 'low',
+    requiresApproval: false,
+  },
+  {
+    intakeType: 'transcript',
+    keywords: ['transcript', 'webvtt', 'meeting notes', 'meeting minutes', 'minutes of', 'attendees', 'call notes', 'stand-up notes', 'standup notes', 'recording of', 'speaker 1', 'speaker 2'],
+    rdStage: 'signal',
+    primaryOwner: 'researcher',
+    recommendedChain: ['researcher', 'data-analyst'],
+    recommendedAction: 'summarize',
+    risk: 'low',
+    requiresApproval: false,
+  },
+  {
+    intakeType: 'raw-data',
+    keywords: ['dataset', 'raw data', 'data dump', 'csv export', 'data export', 'column names', 'field names', 'rows and columns', 'records export', 'telemetry export', 'json export'],
+    rdStage: 'research',
+    primaryOwner: 'data-analyst',
+    recommendedChain: ['data-analyst', 'data-engineer'],
+    recommendedAction: 'summarize',
+    risk: 'low',
+    requiresApproval: false,
+  },
 ];
 
 export default { INTAKE_TYPES, STAGES, CLASSIFICATION_TABLE, UNKNOWN_TRIAGE };

package/lib/mcp/server.mjs

@@ -56,6 +56,7 @@ import {
   profileCreate, profileArchive, sandboxList, learningStatus,
   knowledgeGraphAsk,
 } from './tools/profile.mjs';
+import { modelResolve, triageRecommend, workflowInvoke, capabilityDescribe } from './tools/embedded-contract.mjs';
 
 const DEFAULT_ROOT_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 const ROOT_DIR = resolve(process.env.CX_TOOLKIT_DIR || DEFAULT_ROOT_DIR);
@@ -1044,6 +1045,70 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
       },
     },
+    {
+      name: 'model_resolve',
+      description: 'Resolve which model an embedded Construct workflow should use given the host/IDE provider context. Precedence: host model → same-provider-family fallback → Construct tier default → structured config error. Never reads or returns credential values (requiresCredential is a boolean) and never claims unverified provider health. Read-only; performs no writes.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          workflow_type: { type: 'string', description: 'Workflow type hint (e.g. evidence-ingest, prd-draft, architecture-review). Selects a tier when requested_tier is absent.' },
+          requested_tier: { type: 'string', enum: ['reasoning', 'standard', 'fast'], description: 'Desired tier; overrides the workflow-type hint.' },
+          host: { type: 'string', description: 'Host/IDE identifier (advisory).' },
+          host_model: { type: 'string', description: 'Model the host is currently using (e.g. anthropic/claude-sonnet-4-6).' },
+          host_provider: { type: 'string', description: 'Provider family the host uses, when no host_model is given.' },
+          capabilities: { type: 'array', items: { type: 'string' }, description: 'Optional required capabilities; unverifiable ones are returned as warnings.' },
+          allow_cross_provider_fallback: { type: 'boolean', description: 'Permit falling back outside the host provider family (default false).' },
+        },
+      },
+    },
+    {
+      name: 'triage_recommend',
+      description: 'Classify an artifact and return a role-aware plan (primary owner, role chain with rationale, suggested skills, evidence requirements, expected outputs, approval requirements, risks, next steps, canExecute) WITHOUT enqueuing or executing. Classification confidence is reported distinctly from any generation confidence. Read-only; performs no durable write.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          input: { type: 'string', description: 'Artifact text to classify (meeting notes, bug report, proposal, etc.). Provide this OR file_path.' },
+          file_path: { type: 'string', description: 'Path to a file to extract and classify (PDF/Office via docling, audio/video via whisper, transcripts, plain text). Used when input is absent.' },
+          source_path: { type: 'string', description: 'Optional filename/source hint to aid classification.' },
+          artifact_type: { type: 'string', description: 'Optional artifact-type hint (advisory).' },
+          domain: { type: 'string', description: 'Optional broad domain hint.' },
+          desired_outcome: { type: 'string', description: 'Optional desired outcome (advisory).' },
+          constraints: { type: 'array', items: { type: 'string' }, description: 'Optional constraints (advisory).' },
+          available_roles: { type: 'array', items: { type: 'string' }, description: 'Restrict the plan to these role ids; dropped roles are reported as warnings.' },
+        },
+      },
+    },
+    {
+      name: 'workflow_invoke',
+      description: 'Invoke a named Construct workflow (roles/skills) non-interactively and return a provenanced execution plan: selected roles, rationale, applied skills, resolved model, evidence requirements, output contract, risks, and a traceId. Construct returns the orchestration plan; the host runtime performs specialist reasoning. Durable writes occur ONLY when approval_mode is allow-durable-write; proposal-only and requires-human-approval perform no durable writes.',
+      inputSchema: {
+        type: 'object',
+        required: ['workflow_type'],
+        properties: {
+          workflow_type: { type: 'string', description: 'One of: evidence-ingest, proposal-review, prd-draft, architecture-review, risk-review, research-synthesis.' },
+          input: { type: 'string', description: 'Artifact text the workflow operates on. Provide this OR file_path.' },
+          file_path: { type: 'string', description: 'Path to a file to extract (docling/whisper/transcript) and operate on, used when input is absent.' },
+          context: { type: 'object', description: 'Optional structured context; keys matching evidence requirements mark them satisfied.' },
+          role_strategy: { type: 'string', enum: ['auto', 'explicit', 'constrained'], description: 'auto = default chain; explicit = use requested_roles; constrained = default chain intersected with requested_roles.' },
+          requested_roles: { type: 'array', items: { type: 'string' }, description: 'Role ids for explicit/constrained strategies.' },
+          approval_mode: { type: 'string', enum: ['proposal-only', 'requires-human-approval', 'allow-durable-write'], description: 'Gate for durable writes (default: the workflow type default).' },
+          trace: { type: 'boolean', description: 'Emit a traceId for provenance correlation (default true).' },
+          host: { type: 'string', description: 'Host/IDE identifier (advisory).' },
+          host_model: { type: 'string', description: 'Model the host uses, for model resolution.' },
+          host_provider: { type: 'string', description: 'Provider family the host uses, for model resolution.' },
+        },
+      },
+    },
+    {
+      name: 'capability_describe',
+      description: 'Describe what this Construct install can do: versions, contract interfaces (CLI/MCP/SDK), roles, skills, workflows, schemas, models/providers, policies, telemetry posture, and plugins. Read-only and secret-free — provider entries carry env-key names and a configured boolean only, never credential values. Reads live registries so the published contract cannot drift from reality.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          root_dir: { type: 'string', description: 'Optional Construct install root (default: server toolkit dir).' },
+        },
+      },
+    },
   ],
 }));
 
@@ -1121,6 +1186,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     else if (name === 'sandbox_list') result = sandboxList();
     else if (name === 'learning_status') result = learningStatus(args);
     else if (name === 'knowledge_graph_ask') result = knowledgeGraphAsk(args);
+    else if (name === 'model_resolve') result = modelResolve(args);
+    else if (name === 'triage_recommend') result = await triageRecommend(args);
+    else if (name === 'workflow_invoke') result = await workflowInvoke(args);
+    else if (name === 'capability_describe') result = capabilityDescribe(args);
     else result = { error: `Unknown tool: ${name}` };
   } catch (err) {
     result = { error: err.message ?? String(err) };

package/lib/mcp/tools/embedded-contract.mjs

@@ -0,0 +1,77 @@
+/**
+ * lib/mcp/tools/embedded-contract.mjs — MCP surface for the Embedded Contract Layer.
+ *
+ * Thin adapters that translate MCP tool arguments into the embedded-contract
+ * core calls and return the same versioned envelope the CLI-JSON and SDK
+ * surfaces emit. No business logic lives here — it delegates to
+ * lib/embedded-contract/* so the three surfaces stay structurally identical.
+ */
+
+import { wrapContractResult } from '../../embedded-contract/envelope.mjs';
+import { resolveEmbeddedModel as resolveModelCore } from '../../embedded-contract/model-resolve.mjs';
+import { recommendPlan as recommendPlanCore } from '../../embedded-contract/triage.mjs';
+import { invokeWorkflow as invokeWorkflowCore } from '../../embedded-contract/workflow-invoke.mjs';
+import { buildCapabilityContract } from '../../embedded-contract/capability.mjs';
+import { resolveInput } from '../../embedded-contract/ingest.mjs';
+
+async function ingestArgs(args) {
+  if (args.input || !args.file_path) return { input: args.input, ingestion: undefined };
+  const resolved = await resolveInput({ filePath: args.file_path });
+  return { input: resolved.text, ingestion: resolved.error ? { ...(resolved.ingestion || {}), error: resolved.error } : resolved.ingestion };
+}
+
+function csv(value) {
+  if (Array.isArray(value)) return value;
+  if (typeof value === 'string' && value.trim()) return value.split(',').map((s) => s.trim()).filter(Boolean);
+  return undefined;
+}
+
+export function modelResolve(args = {}) {
+  const request = {
+    workflowType: args.workflow_type,
+    requestedTier: args.requested_tier,
+    host: args.host,
+    hostModel: args.host_model,
+    hostProvider: args.host_provider,
+    capabilities: csv(args.capabilities),
+    allowCrossProviderFallback: Boolean(args.allow_cross_provider_fallback),
+  };
+  return wrapContractResult(resolveModelCore(request), { surface: 'mcp' });
+}
+
+export async function triageRecommend(args = {}) {
+  const { input, ingestion } = await ingestArgs(args);
+  const request = {
+    input,
+    ingestion,
+    sourcePath: args.source_path || args.file_path,
+    artifactType: args.artifact_type,
+    domain: args.domain,
+    desiredOutcome: args.desired_outcome,
+    constraints: csv(args.constraints),
+    availableRoles: csv(args.available_roles),
+  };
+  return wrapContractResult(recommendPlanCore(request), { surface: 'mcp' });
+}
+
+export async function workflowInvoke(args = {}) {
+  const { input, ingestion } = await ingestArgs(args);
+  const request = {
+    workflowType: args.workflow_type,
+    input,
+    ingestion,
+    context: args.context,
+    roleStrategy: args.role_strategy,
+    requestedRoles: csv(args.requested_roles),
+    approvalMode: args.approval_mode,
+    trace: args.trace !== false,
+    host: args.host,
+    hostModel: args.host_model,
+    hostProvider: args.host_provider,
+  };
+  return wrapContractResult(await invokeWorkflowCore(request), { surface: 'mcp' });
+}
+
+export function capabilityDescribe(args = {}) {
+  return wrapContractResult(buildCapabilityContract({ rootDir: args.root_dir }), { surface: 'mcp' });
+}

package/lib/model-router.mjs

@@ -418,6 +418,46 @@ export function resolveTiersForPrimary(primaryModelId) {
   return family.resolve({ reasoning: undefined, standard: undefined, fast: undefined });
 }
 
+// Credential detection here is env-only — no network or process probe — so
+// callers (embedded model resolution, capability discovery) stay synchronous
+// and deterministic, and never expose a key value, only its presence.
+
+function familyDescriptor(family, env) {
+  const requiresEnv = PROVIDER_ENV_MAP[family.id] || (Array.isArray(family.requiresEnv) ? family.requiresEnv : []);
+  const local = family.local === true;
+  const configured = local || requiresEnv.some((key) => {
+    const value = env?.[key];
+    return typeof value === "string" && value.length > 0;
+  });
+  return {
+    id: family.id,
+    label: family.label,
+    local,
+    requiresEnv,
+    tiers: family.resolve({}),
+    configured,
+  };
+}
+
+/**
+ * Describe the provider family a model id belongs to, including which env keys
+ * confirm credentials and whether they are present. Returns null when no family
+ * matches.
+ */
+export function describeModelFamily(modelId, { env = process.env } = {}) {
+  const family = matchProviderFamily(modelId);
+  if (!family) return null;
+  return familyDescriptor(family, env);
+}
+
+/**
+ * Describe every provider family. Resolves a host-supplied provider id and
+ * enumerates model availability for the embedded contract layer.
+ */
+export function listModelFamilies({ env = process.env } = {}) {
+  return PROVIDER_FAMILY_TIERS.map((family) => familyDescriptor(family, env));
+}
+
 /**
  * Read the OpenRouter API key from the OpenCode config file.
  */

package/lib/op-log.mjs

@@ -0,0 +1,61 @@
+/**
+ * lib/op-log.mjs — per-operation structured log file for long-running CLI ops.
+ *
+ * Commands like `dev`, `install`, `init`, and `sync` keep their human-facing
+ * output on stdout (println/ok/warn). This module adds a parallel machine log:
+ * one JSONL file per run at `<home>/.cx/<op>-<timestamp>.log`, every line
+ * stamped with a shared correlation id (`op_id`) so a failed run can be
+ * reconstructed after the fact and concurrent runs never interleave
+ * ambiguously. It reuses `makeLogger` from lib/logger.mjs for the line format.
+ *
+ * Writes are synchronous (an open fd + writeSync), not a buffered stream:
+ * CLI ops routinely end in process.exit(), and a buffered stream can drop its
+ * tail before the event loop drains it. Synchronous append loses nothing.
+ *
+ * Best-effort by contract: if the log dir can't be created or the file can't
+ * open, the returned handle silently no-ops. Logging must never break the
+ * operation it observes.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+import { makeLogger, newRequestId } from './logger.mjs';
+
+const NOOP_LOGGER = Object.freeze({ debug() {}, info() {}, warn() {}, error() {} });
+
+export function startOpLog(op, { homeDir = os.homedir(), env = process.env, now = new Date() } = {}) {
+  const id = newRequestId();
+  const dir = path.join(homeDir, '.cx');
+  const stamp = now.toISOString().replace(/[:.]/g, '-');
+  const logPath = path.join(dir, `${op}-${stamp}.log`);
+
+  let fd = null;
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    fd = fs.openSync(logPath, 'a');
+  } catch {
+    fd = null;
+  }
+
+  // Adapt the fd to the minimal stream surface makeLogger needs: a sync write.
+  const stream = fd === null ? null : { write: (line) => { try { fs.writeSync(fd, line); } catch { /* best-effort */ } } };
+  const log = stream
+    ? makeLogger({ env, stream }).child({ op, op_id: id })
+    : NOOP_LOGGER;
+
+  log.info('op.start', { pid: process.pid });
+
+  return {
+    id,
+    logPath: fd === null ? null : logPath,
+    event: (name, fields = {}) => log.info(name, fields),
+    warn: (name, fields = {}) => log.warn(name, fields),
+    error: (name, fields = {}) => log.error(name, fields),
+    close: (status = 'ok', fields = {}) => {
+      log.info('op.end', { status, ...fields });
+      if (fd !== null) { try { fs.closeSync(fd); } catch { /* already closed */ } fd = null; }
+    },
+  };
+}

package/lib/roles/catalog.mjs

@@ -1,9 +1,15 @@
 /**
  * lib/roles/catalog.mjs — role listing and display helpers.
  *
- * Reads specialists/registry.json to produce a list of available roles with
- * optional department grouping and consolidated-role views. Consumed by the
- * `roles:list` CLI command.
+ * Reads the flat `specialists` array in specialists/registry.json to produce the
+ * list of available roles. Each descriptor carries the registry-prefixed display
+ * name (cx-<name>), description, model tier, edit capability, and skill ids — the
+ * shape consumed by the `roles:list` CLI command and the embedded capability
+ * contract (lib/embed/capability.mjs).
+ *
+ * The registry once carried `departments` and `consolidatedRoles` groupings; the
+ * schema since collapsed to a single `specialists` array, so this reader exposes
+ * the flat list only and never invents grouping that has no source.
  */
 
 import { readFileSync } from 'node:fs';
@@ -22,109 +28,34 @@ function loadRegistry() {
 }
 
 /**
- * Return a list of role descriptors.
+ * Return the list of role descriptors from the registry's specialists array.
  *
- * @param {object}  opts
- * @param {boolean} opts.departments   Group by department when true.
- * @param {boolean} opts.consolidated  Return consolidated 12-role view when true.
- * @returns {Array<object>}
+ * @returns {Array<{id:string,name:string,description:string,modelTier:string,internal:boolean,canEdit:boolean,skills:string[]}>}
  */
-export function listRoles({ departments = false, consolidated = false } = {}) {
+export function listRoles() {
   const registry = loadRegistry();
+  const prefix = registry.prefix || 'cx';
+  const specialists = Array.isArray(registry.specialists) ? registry.specialists : [];
 
-  if (consolidated) {
-    const c = registry.consolidatedRoles || {};
-    return (c.roles || []).map((r) => ({
-      id: r.id,
-      absorbs: r.absorbs || [],
-      whenToUse: r.whenToUse || '',
-    }));
-  }
-
-  const agents = Array.isArray(registry.agents)
-    ? registry.agents
-    : Object.values(registry.agents || {});
-
-  if (!departments) {
-    return agents.map((a) => ({
-      id: a.name,
-      name: `cx-${a.name}`,
-      description: a.description || '',
-      internal: !!a.internal,
-    }));
-  }
-
-  // Group by department based on subDepartment membership in registry.departments
-  const depts = registry.departments || {};
-  const grouped = {};
-  for (const [deptId, dept] of Object.entries(depts)) {
-    grouped[deptId] = {
-      name: dept.name || deptId,
-      roles: [],
-    };
-  }
-  grouped._ungrouped = { name: 'Other', roles: [] };
-
-  for (const agent of agents) {
-    let placed = false;
-    for (const [deptId, dept] of Object.entries(depts)) {
-      const subs = dept.subDepartments || {};
-      for (const sub of Object.values(subs)) {
-        if ((sub.roles || []).includes(agent.name) || (sub.roles || []).includes(`cx-${agent.name}`)) {
-          grouped[deptId].roles.push({ id: agent.name, name: `cx-${agent.name}`, description: agent.description || '' });
-          placed = true;
-          break;
-        }
-      }
-      if (placed) break;
-    }
-    if (!placed) {
-      grouped._ungrouped.roles.push({ id: agent.name, name: `cx-${agent.name}`, description: agent.description || '' });
-    }
-  }
-
-  return Object.entries(grouped)
-    .filter(([, g]) => g.roles.length > 0)
-    .map(([id, g]) => ({ departmentId: id, departmentName: g.name, roles: g.roles }));
+  return specialists.map((s) => ({
+    id: s.name,
+    name: `${prefix}-${s.name}`,
+    description: s.description || '',
+    modelTier: s.modelTier || 'standard',
+    internal: !!s.internal,
+    canEdit: !!s.canEdit,
+    skills: Array.isArray(s.skills) ? s.skills : [],
+  }));
 }
 
 /**
  * Format the role list as a human-readable string.
  *
- * @param {object}  opts  Same options as listRoles.
  * @returns {string}
  */
-export function formatRoleList({ departments = false, consolidated = false } = {}) {
-  const roles = listRoles({ departments, consolidated });
-  const lines = [];
-
-  if (consolidated) {
-    lines.push('Consolidated Roles (12-role simplified structure)');
-    lines.push('=================================================');
-    for (const r of roles) {
-      lines.push(`\n${r.id}`);
-      lines.push(`  Absorbs: ${r.absorbs.join(', ')}`);
-      lines.push(`  Use when: ${r.whenToUse}`);
-    }
-    lines.push('');
-    return lines.join('\n');
-  }
-
-  if (departments) {
-    lines.push('Available Roles by Department');
-    lines.push('=============================');
-    for (const group of roles) {
-      lines.push(`\n${group.departmentName}`);
-      for (const role of group.roles) {
-        lines.push(`  ${role.name.padEnd(30)} ${role.description}`);
-      }
-    }
-    lines.push('');
-    return lines.join('\n');
-  }
-
-  lines.push('Available Roles');
-  lines.push('===============');
+export function formatRoleList() {
+  const roles = listRoles();
+  const lines = ['Available Roles', '==============='];
   for (const role of roles) {
     lines.push(`  ${role.name.padEnd(30)} ${role.description}`);
   }