@geraldmaron/construct 1.0.3 → 1.0.5

package/bin/construct

@@ -186,14 +186,49 @@ function runNodeScript(scriptPath, args = [], extraEnv = {}) {
 async function cmdStatus() {
   const jsonOutput = restArgsCache.includes('--json');
   const status = await buildStatus({ rootDir: ROOT_DIR, cwd: process.cwd(), homeDir: HOME, env: process.env });
-  
+
   if (jsonOutput) {
     println(JSON.stringify(status, null, 2));
     return;
   }
-  
+
   println(formatStatusReport(status));
-  
+
+  // Append the learning-loops summary so the operator gets a single answer
+  // to "is this thing actually learning?" without remembering a second
+  // command. Cheap: just reads .cx/observations + .cx/outcomes summaries.
+  try {
+    const { resolveActiveProfile } = await import('../lib/profiles/loader.mjs');
+    const { readSummary } = await import('../lib/outcomes/aggregate.mjs');
+    const fs = await import('node:fs');
+    const path = await import('node:path');
+    const cwd = process.cwd();
+    const active = resolveActiveProfile(cwd);
+    const obsIdxPath = path.join(cwd, '.cx', 'observations', 'index.json');
+    let obsTotal = 0;
+    let obs24h = 0;
+    if (fs.existsSync(obsIdxPath)) {
+      const idx = JSON.parse(fs.readFileSync(obsIdxPath, 'utf8'));
+      obsTotal = idx.length;
+      const since = Date.now() - 24 * 60 * 60 * 1000;
+      obs24h = idx.filter((e) => Date.parse(e.createdAt) >= since).length;
+    }
+    const researchDir = path.join(cwd, '.cx', 'knowledge', 'external', 'research');
+    const researchCount = fs.existsSync(researchDir)
+      ? fs.readdirSync(researchDir).filter((f) => f.endsWith('.md')).length
+      : 0;
+    const summary = readSummary(cwd);
+    const outcomeRoles = summary?.roles ? Object.keys(summary.roles).length : 0;
+
+    println('');
+    println('Learning loops');
+    println('──────────────');
+    println(`  Profile          ${active.id} (${active.displayName || ''})`);
+    println(`  Observations     ${obsTotal} total, ${obs24h} in last 24h`);
+    println(`  Research files   ${researchCount}`);
+    println(`  Outcome roles    ${outcomeRoles}`);
+    println(`  Detail:          npm run learning:status`);
+  } catch { /* best-effort surface; never block status */ }
 }
 
 async function cmdShow() {
@@ -421,6 +456,22 @@ async function cmdDoctor() {
   add('Claude Code agents dir', fs.existsSync(path.join(HOME, '.claude', 'agents')), true);
   add('Codex agents dir', fs.existsSync(path.join(HOME, '.codex', 'agents')), true);
   add('Copilot prompts dir', fs.existsSync(path.join(HOME, '.github', 'prompts')), true);
+  add('Cursor MCP config', fs.existsSync(path.join(HOME, '.cursor', 'mcp.json')), true);
+  const vscodeSettingsPaths = process.platform === 'darwin'
+    ? [
+        path.join(HOME, 'Library', 'Application Support', 'Code', 'User', 'settings.json'),
+        path.join(HOME, 'Library', 'Application Support', 'Code - Insiders', 'User', 'settings.json'),
+      ]
+    : process.platform === 'linux'
+      ? [
+          path.join(HOME, '.config', 'Code', 'User', 'settings.json'),
+          path.join(HOME, '.config', 'Code - Insiders', 'User', 'settings.json'),
+        ]
+      : [
+          path.join(process.env.APPDATA ?? path.join(HOME, 'AppData', 'Roaming'), 'Code', 'User', 'settings.json'),
+          path.join(process.env.APPDATA ?? path.join(HOME, 'AppData', 'Roaming'), 'Code - Insiders', 'User', 'settings.json'),
+        ];
+  add('VS Code settings file', vscodeSettingsPaths.some((candidate) => fs.existsSync(candidate)), true);
   add('User config ready', fs.existsSync(getUserEnvPath(HOME)) || fs.existsSync(path.join(HOME, '.construct')), true);
   add('skills/ directory', fs.existsSync(path.join(ROOT_DIR, 'skills')));
   add('rules/common/', fs.existsSync(path.join(ROOT_DIR, 'rules', 'common')));
@@ -3217,6 +3268,27 @@ async function cmdHook(args) {
 const [command, ...rest] = process.argv.slice(2);
 const restArgsCache = rest;
 
+// Parse `--key=value` and repeatable `--source-url=<url>` for `construct knowledge add`.
+function parseKnowledgeAddArgs(args) {
+  const opts = { slug: null, topic: null, confidence: 'inferred', sources: [] };
+  for (const arg of args) {
+    if (arg.startsWith('--slug=')) opts.slug = arg.slice('--slug='.length);
+    else if (arg.startsWith('--topic=')) opts.topic = arg.slice('--topic='.length);
+    else if (arg.startsWith('--confidence=')) opts.confidence = arg.slice('--confidence='.length);
+    else if (arg.startsWith('--source-url=')) opts.sources.push({ url: arg.slice('--source-url='.length) });
+    else if (arg.startsWith('--source=')) { /* tag, ignored for now */ }
+  }
+  return opts;
+}
+
+// Read all of stdin as a UTF-8 string. Returns '' if nothing was piped.
+async function readStdin() {
+  if (process.stdin.isTTY) return '';
+  let raw = '';
+  for await (const chunk of process.stdin) raw += chunk;
+  return raw;
+}
+
 const handlers = new Map([
   // Core
   ['dev', cmdUp],
@@ -3252,6 +3324,24 @@ const handlers = new Map([
   ['handoffs', cmdHandoffs],
   ['headhunt', cmdHeadhunt],
   ['init', cmdInit],
+  ['drop', async (args) => {
+    const { runDropCli } = await import('../lib/drop.mjs');
+    return runDropCli(args, { cwd: process.cwd(), env: process.env });
+  }],
+  ['docs', async (args) => {
+    const sub = args[0];
+    if (!sub || sub === '--help' || sub === '-h') {
+      println('Usage: construct docs <check|verify|update|site>');
+      return;
+    }
+    const rest = args.slice(1);
+    if (sub === 'verify') return cmdDocsVerify(rest);
+    if (sub === 'update') return cmdDocsUpdate(rest);
+    if (sub === 'check') return cmdDocsCheck(rest);
+    if (sub === 'site') return cmdDocsSite();
+    errorln(`Unknown docs subcommand: ${sub}. Available: check, verify, update, site`);
+    process.exit(1);
+  }],
   ['docs:verify', cmdDocsVerify],
   ['init:update', cmdInitUpdate],
   ['models', cmdModels],
@@ -3817,7 +3907,185 @@ const handlers = new Map([
       }
       return;
     }
-    errorln(`Unknown knowledge subcommand: ${sub}. Available: trends, index`);
+    if (sub === 'add') {
+      const opts = parseKnowledgeAddArgs(args.slice(1));
+      if (!opts.slug || !opts.topic) {
+        errorln('Usage: construct knowledge add --source=research --slug=<id> --topic="..." [--confidence=confirmed|inferred|weak] [--source-url=<url>] (body on stdin)');
+        process.exit(1);
+      }
+      const body = await readStdin();
+      if (!body || body.trim().length < 10) {
+        errorln('construct knowledge add: stdin body is empty or too short');
+        process.exit(1);
+      }
+      const { addResearchFinding } = await import('../lib/knowledge/research-store.mjs');
+      try {
+        const { path: outPath, bytes } = await addResearchFinding({
+          cwd: process.cwd(),
+          slug: opts.slug,
+          topic: opts.topic,
+          body,
+          confidence: opts.confidence,
+          sources: opts.sources,
+        });
+        process.stdout.write(`✓ wrote ${outPath} (${bytes} bytes)\n`);
+        return;
+      } catch (err) {
+        errorln(`construct knowledge add: ${err.message}`);
+        process.exit(1);
+      }
+    }
+    errorln(`Unknown knowledge subcommand: ${sub}. Available: trends, index, add`);
+    process.exit(1);
+  }],
+  ['sandbox', async (args) => {
+    const sub = args[0] || 'create';
+    const { createSandbox, listSandboxes, deleteSandbox, pruneSandboxes } = await import('../lib/sandbox.mjs');
+    if (sub === 'create') {
+      const profileArg = args.find((a) => a.startsWith('--profile='));
+      const profile = profileArg ? profileArg.split('=')[1] : null;
+      const { id, path: p } = createSandbox({ profile });
+      process.stdout.write(`✓ created sandbox ${id}\n  path: ${p}\n`);
+      if (profile) process.stdout.write(`  profile: ${profile}\n`);
+      return;
+    }
+    if (sub === 'list') {
+      const all = listSandboxes();
+      if (all.length === 0) { process.stdout.write('  (no sandboxes)\n'); return; }
+      for (const s of all) process.stdout.write(`  ${s.id.padEnd(30)}  ${s.path}\n`);
+      return;
+    }
+    if (sub === 'delete') {
+      const id = args[1];
+      if (!id) { errorln('Usage: construct sandbox delete <id>'); process.exit(1); }
+      process.stdout.write(deleteSandbox(id) ? `✓ removed ${id}\n` : `not found: ${id}\n`);
+      return;
+    }
+    if (sub === 'prune') {
+      const daysArg = args.find((a) => a.startsWith('--days='));
+      const days = daysArg ? Number(daysArg.split('=')[1]) || 7 : 7;
+      const removed = pruneSandboxes({ olderThanDays: days });
+      process.stdout.write(`✓ pruned ${removed} sandbox${removed === 1 ? '' : 'es'} older than ${days} day${days === 1 ? '' : 's'}\n`);
+      return;
+    }
+    errorln(`Unknown sandbox subcommand: ${sub}. Available: create, list, delete, prune`);
+    process.exit(1);
+  }],
+  ['profile', async (args) => {
+    const sub = args[0] || 'show';
+    const { listProfiles, loadProfile, resolveActiveProfile } = await import('../lib/profiles/loader.mjs');
+    if (sub === 'list') {
+      for (const id of listProfiles()) {
+        const p = loadProfile(id);
+        process.stdout.write(`  ${id.padEnd(14)} ${p?.displayName || ''}\n`);
+      }
+      return;
+    }
+    if (sub === 'show') {
+      const active = resolveActiveProfile(process.cwd());
+      process.stdout.write(JSON.stringify({
+        id: active.id,
+        displayName: active.displayName,
+        tagline: active.tagline,
+        roles: active.roles?.length || 0,
+        intakeTypes: active.intake?.types?.length || 0,
+      }, null, 2) + '\n');
+      return;
+    }
+    if (sub === 'set') {
+      const id = args[1];
+      if (!id) { errorln('Usage: construct profile set <id>'); process.exit(1); }
+      const target = loadProfile(id);
+      if (!target) {
+        errorln(`Unknown profile: ${id}. Available: ${listProfiles().join(', ')}`);
+        process.exit(1);
+      }
+      const { findProjectConfigPath, loadProjectConfig, writeProjectConfig, PROJECT_CONFIG_FILENAME } = await import('../lib/config/project-config.mjs');
+      const fsMod = await import('node:fs');
+      const pathMod = await import('node:path');
+      const found = findProjectConfigPath(process.cwd());
+      const cfgPath = found || pathMod.join(process.cwd(), PROJECT_CONFIG_FILENAME);
+      const cfg = found ? (loadProjectConfig(process.cwd()) || { version: 1 }) : { version: 1 };
+      cfg.profile = id;
+      writeProjectConfig(cfgPath, cfg, { validate: true });
+      process.stdout.write(`✓ profile set to ${id} (${target.displayName})\n`);
+      return;
+    }
+    if (sub === 'create') {
+      const id = args[1];
+      if (!id) {
+        errorln('Usage: construct profile create <id> [--display="..."] [--role=<id>...] [--department=<id>:<displayName>...]');
+        process.exit(1);
+      }
+      const displayArg = args.find((a) => a.startsWith('--display='));
+      const displayName = displayArg ? displayArg.split('=')[1] : id;
+      const seedRoles = args
+        .filter((a) => a.startsWith('--role='))
+        .map((a) => a.slice('--role='.length))
+        .filter(Boolean);
+      const seedDepartments = args
+        .filter((a) => a.startsWith('--department='))
+        .map((a) => a.slice('--department='.length))
+        .map((spec) => {
+          const [deptId, deptDisplay] = spec.split(':');
+          return { id: deptId, displayName: deptDisplay || deptId };
+        });
+      const { createDraftProfile } = await import('../lib/profiles/lifecycle.mjs');
+      try {
+        const result = createDraftProfile({ cwd: process.cwd(), id, displayName, seedRoles, seedDepartments });
+        const pathMod = await import('node:path');
+        process.stdout.write(`✓ draft created for ${id}\n`);
+        process.stdout.write(`  brief:        ${pathMod.relative(process.cwd(), result.briefPath)}\n`);
+        process.stdout.write(`  draft:        ${pathMod.relative(process.cwd(), result.draftPath)}\n`);
+        if (result.personaPaths.length) process.stdout.write(`  personas:     ${result.personaPaths.length} scaffold(s) under personas/\n`);
+        if (result.departmentPaths.length) process.stdout.write(`  departments:  ${result.departmentPaths.length} charter(s) under departments/\n`);
+        process.stdout.write(`\nNext steps (in order, per docs/concepts/profile-lifecycle.md):\n`);
+        process.stdout.write(`  1. Discover: dispatch cx-ux-researcher to fill personas/<role>.md from interviews + primary sources.\n`);
+        process.stdout.write(`  2. Frame:    dispatch cx-product-manager to fill departments/<dept>.md charters and the intake taxonomy in profile.json.\n`);
+        process.stdout.write(`  3. Architect: dispatch cx-architect to reconcile role reuse vs new, and to populate departments[].\n`);
+        process.stdout.write(`  4. Validate: dispatch cx-evaluator to run persona-eval and classifier-eval against representative signals.\n`);
+        return;
+      } catch (err) {
+        errorln(err.message);
+        process.exit(1);
+      }
+    }
+    if (sub === 'drafts') {
+      const { listDrafts } = await import('../lib/profiles/lifecycle.mjs');
+      const drafts = listDrafts(process.cwd());
+      if (drafts.length === 0) { process.stdout.write('  (no drafts)\n'); return; }
+      for (const d of drafts) {
+        const flags = [d.hasBrief ? 'brief' : null, d.hasProfile ? 'profile' : null].filter(Boolean).join(', ');
+        process.stdout.write(`  ${d.id.padEnd(20)} ${flags}\n`);
+      }
+      return;
+    }
+    if (sub === 'archive') {
+      const id = args[1];
+      const reasonArg = args.find((a) => a.startsWith('--reason='));
+      const reason = reasonArg ? reasonArg.split('=')[1] : '';
+      if (!id) { errorln('Usage: construct profile archive <id> --reason="..."'); process.exit(1); }
+      const { archiveProfile } = await import('../lib/profiles/lifecycle.mjs');
+      try {
+        const { archived } = archiveProfile({ id, reason });
+        process.stdout.write(`✓ archived ${id} to ${archived}\n`);
+        return;
+      } catch (err) {
+        errorln(err.message);
+        process.exit(1);
+      }
+    }
+    if (sub === 'health') {
+      const id = args[1];
+      if (!id) { errorln('Usage: construct profile health <id> [--days=N]'); process.exit(1); }
+      const daysArg = args.find((a) => a.startsWith('--days='));
+      const windowDays = daysArg ? Number(daysArg.split('=')[1]) || 30 : 30;
+      const { profileHealth } = await import('../lib/profiles/lifecycle.mjs');
+      const report = profileHealth(process.cwd(), id, { windowDays });
+      process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+      return;
+    }
+    errorln(`Unknown profile subcommand: ${sub}. Available: list, show, set, create, drafts, archive, health`);
     process.exit(1);
   }],
 ]);
@@ -3834,6 +4102,13 @@ if (command === '--help' || command === '-h' || command === 'help') {
   process.exit(0);
 }
 
+// Version flags → print version and exit
+if (command === '--version' || command === '-V') {
+  const pkg = JSON.parse(fs.readFileSync(path.join(ROOT_DIR, 'package.json'), 'utf8'));
+  println(`construct v${pkg.version}`);
+  process.exit(0);
+}
+
 const handler = handlers.get(command);
 if (!handler) {
   errorln(`Unknown command: ${command}`);

package/commands/understand/research.md

@@ -1,10 +1,10 @@
 <!--
-commands/understand/research.md — Research a topic — verify facts from primary sources, separate evidence from inference
+commands/understand/research.md. Research a topic. Verify facts from primary sources, separate evidence from inference.
 
-Research a topic — verify facts from primary sources, separate evidence from inference
+Research a topic. Verify facts from primary sources, separate evidence from inference.
 -->
 ---
-description: Research a topic — verify facts from primary sources, separate evidence from inference
+description: Research a topic. Verify facts from primary sources, separate evidence from inference.
 ---
 
 You are Construct. Research: $ARGUMENTS
@@ -20,3 +20,5 @@ Method:
 For each finding: source, date, confidence (confirmed / inferred / weak signal).
 
 Output: FINDINGS (with citations) | INFERENCES (labeled) | GAPS | RECOMMENDATION
+
+Persistence: after producing the output, run `construct knowledge add --source=research --slug=<topic-slug> --topic="<one-line topic>" --confidence=<confirmed|inferred|weak>` and pass the FINDINGS+INFERENCES+GAPS+RECOMMENDATION block on stdin. The store writes a frontmatter-stamped markdown file under `.cx/knowledge/external/research/` and indexes it for future hybrid search. Pass `--source-url=<url>` repeatedly for each cited source (required when confidence=confirmed).

package/db/schema/004_recommendations.sql

@@ -0,0 +1,46 @@
+-- 004_recommendations.sql — Recommendations table for team and enterprise mode.
+-- Solo mode uses the JSONL store under .cx/intake/ instead.
+--
+-- Dedup key is enforced at the (project, dedup_key) level — matches the in-memory
+-- dedup contract in lib/embed/recommendation-store.mjs.
+-- Active recommendations: dismissed_at IS NULL AND superseded_at IS NULL.
+
+create table if not exists construct_recommendations (
+  id text primary key,
+  project text not null,
+  dedup_key text not null,
+  type text not null,
+  title text not null,
+  reason text,
+  lane text,
+  signal_count int not null default 1,
+  total_signal_count int not null default 1,
+  customer_impact int not null default 0,
+  recency_bonus int not null default 0,
+  strategic_bonus int not null default 0,
+  score float not null default 0,
+  priority text not null default 'P3',
+  source_signal_ids jsonb not null default '[]'::jsonb,
+  first_seen timestamptz not null default now(),
+  last_seen timestamptz not null default now(),
+  dismissed_at timestamptz,
+  dismiss_reason text,
+  superseded_at timestamptz,
+  superseded_by_id text,
+  suppressed_until timestamptz,
+  suppress_reason text,
+  updated_at timestamptz not null default now()
+);
+
+create unique index if not exists construct_recommendations_project_dedup_key_idx
+  on construct_recommendations (project, dedup_key);
+
+create index if not exists construct_recommendations_priority_score_idx
+  on construct_recommendations (project, priority, score desc);
+
+create index if not exists construct_recommendations_last_seen_idx
+  on construct_recommendations (project, last_seen desc);
+
+create index if not exists construct_recommendations_active_idx
+  on construct_recommendations (project, dismissed_at)
+  where dismissed_at is null;

package/db/schema/005_strategy.sql

@@ -0,0 +1,21 @@
+-- 005_strategy.sql — Product strategy store for team and enterprise mode.
+-- Solo mode uses ~/.cx/strategy.md instead.
+--
+-- Each row is an immutable version snapshot. The latest version for a project
+-- is the row with the highest version number (or max updated_at when equal).
+-- Callers insert a new row on each write; old versions are retained for history.
+
+create table if not exists construct_strategy (
+  id bigserial primary key,
+  project text not null,
+  content text not null,
+  version int not null default 1,
+  updated_at timestamptz not null default now(),
+  updated_by text
+);
+
+create unique index if not exists construct_strategy_project_version_idx
+  on construct_strategy (project, version);
+
+create index if not exists construct_strategy_project_updated_at_idx
+  on construct_strategy (project, updated_at desc);

package/lib/auto-docs.mjs

@@ -71,7 +71,7 @@ function buildCoreDocsContract() {
     '| `docs/README.md` | Docs index and maintenance contract | Core docs set or maintenance expectations change |',
     '| `docs/concepts/architecture.md` | Canonical architecture and invariants | Runtime shape, contracts, boundaries, or major dependencies change |',
     '',
-    '`plan.md` is a local working document. `construct init` creates it for the active session, but it is gitignored and not committed — durable work belongs in the tracker (Beads or external).',
+    '`plan.md` is a local working document. `construct init` creates it for the active session, but it is gitignored and not committed; durable work belongs in the tracker (Beads or external).',
     '',
     'Tracker hierarchy: external tracker (prefer Beads) for durable work, `plan.md` for the local working plan, and cass-memory via MCP `memory` for cross-session recall.',
     '',
@@ -82,13 +82,13 @@ function buildCoreDocsContract() {
 
 const DIR_DESCRIPTIONS = {
   agents: 'Registry and generated platform adapter chains',
-  apps: 'User-facing apps shipped from this repo (e.g., apps/docs/ — Fumadocs docs site)',
+  apps: 'User-facing apps shipped from this repo (e.g. apps/docs/, the Fumadocs docs site)',
   bin: 'CLI entrypoint (`construct`)',
   claude: 'Claude Code integration (agents, settings template)',
   commands: 'Command prompt assets',
   codex: 'GitHub Copilot / Codex integration',
   docs: 'Architecture notes, runbooks, and documentation contract',
-  telemetry: 'Telemetry backend for agent observability',
+  telemetry: 'Local trace capture and optional telemetry export',
   lib: 'Core runtime: CLI, hooks, MCP, status, sync, workflow',
   opencode: 'OpenCode integration config',
   personas: 'Persona prompt definitions',
@@ -470,4 +470,3 @@ export function buildFumadocsReference({ rootDir } = {}) {
 
   return { written };
 }
-

package/lib/beads-automation.mjs

@@ -22,6 +22,11 @@ const HANDOFFS_DIR = '.cx/handoffs';
 const CONFIRM_TIMEOUT = 60000; // 60 second timeout for confirmation prompts
 const POSITIVE_INTENT = /^(y|yes|yeah|yep|yup|sure|ok|okay|go|proceed|do it)\b/i;
 
+function beadsConfirmEnabled(env = process.env) {
+  const raw = String(env.CONSTRUCT_BEADS_CONFIRM ?? '').trim().toLowerCase();
+  return raw === '1' || raw === 'true' || raw === 'yes' || raw === 'on';
+}
+
 // ---------------------------------------------------------------------------
 // Confirmation Utility
 // ---------------------------------------------------------------------------
@@ -148,14 +153,18 @@ export async function confirmAndCommit({
   }
   console.error('');
 
-  const confirmed = await confirm(
-    'Commit these changes?',
-    { yes, default: 'n' }
-  );
+  if (yes || beadsConfirmEnabled()) {
+    const confirmed = await confirm(
+      'Commit these changes?',
+      { yes, default: 'n' }
+    );
 
-  if (!confirmed) {
-    console.error('[beads] Commit cancelled');
-    return null;
+    if (!confirmed) {
+      console.error('[beads] Commit cancelled');
+      return null;
+    }
+  } else {
+    console.error('[beads] CONSTRUCT_BEADS_CONFIRM is off — committing without interactive prompt.');
   }
 
   runGit(['commit', '-m', message], { cwd });

package/lib/cli-commands.mjs

@@ -79,7 +79,13 @@ export const CLI_COMMANDS = [
     category: 'Core',
     core: true,
     description: 'Sync agent adapters to AI tools',
-    usage: 'construct sync',
+    usage: 'construct sync [--project] [--dry-run] [--no-docs] [--compress-personas]',
+    options: [
+      { flag: '--project', desc: 'Write project-local Claude adapters into the current repo only' },
+      { flag: '--dry-run', desc: 'Preview adapter changes without writing files' },
+      { flag: '--no-docs', desc: 'Skip AUTO docs regeneration after syncing adapters' },
+      { flag: '--compress-personas', desc: 'Write compressed runtime persona prompts without changing the source prompts' },
+    ],
   },
   {
     name: 'intake',
@@ -122,6 +128,50 @@ export const CLI_COMMANDS = [
       { name: 'search <query>', desc: 'Search customer profiles by name/alias' },
     ],
   },
+  {
+    name: 'knowledge',
+    emoji: '🧠',
+    category: 'Work',
+    core: false,
+    description: 'Query, index, or add to the project knowledge base',
+    usage: 'construct knowledge trends|index|add',
+    subcommands: [
+      { name: 'trends', desc: 'Show trend report across observations and artifacts' },
+      { name: 'index', desc: 'Rebuild the local RAG corpus over .cx/ artifacts' },
+      { name: 'add --source=research --slug=<id> --topic="..." [--source-url=<url>]', desc: 'Persist a research finding into .cx/knowledge/external/research/' },
+    ],
+  },
+  {
+    name: 'sandbox',
+    emoji: '🧪',
+    category: 'Core',
+    core: true,
+    description: 'Isolated tmpdir-based environment for QA / specialist dry-runs',
+    usage: 'construct sandbox create|list|delete|prune [--profile=<id>]',
+    subcommands: [
+      { name: 'create [--profile=<id>]', desc: 'Create a new sandbox under ~/.cx/sandboxes/' },
+      { name: 'list', desc: 'List existing sandboxes, newest first' },
+      { name: 'delete <id>', desc: 'Remove one sandbox by id' },
+      { name: 'prune [--days=N]', desc: 'Remove sandboxes older than N days (default 7)' },
+    ],
+  },
+  {
+    name: 'profile',
+    emoji: '🧭',
+    category: 'Core',
+    core: true,
+    description: 'Manage the active org profile and its lifecycle (draft, promote, archive, health)',
+    usage: 'construct profile show|list|set|create|drafts|archive|health',
+    subcommands: [
+      { name: 'show', desc: 'Show the active profile' },
+      { name: 'list', desc: 'List curated profiles' },
+      { name: 'set <id>', desc: 'Switch the active profile (writes construct.config.json)' },
+      { name: 'create <id> [--display="..."]', desc: 'Scaffold a draft profile + requirements brief under .cx/profiles/draft-<id>/' },
+      { name: 'drafts', desc: 'List in-progress draft profiles' },
+      { name: 'archive <id> --reason="..."', desc: 'Move a curated profile into archive/profiles/<id>/' },
+      { name: 'health <id> [--days=N]', desc: 'Per-profile observation + outcome rollup' },
+    ],
+  },
   {
     name: 'workspace',
     emoji: '🏢',
@@ -475,7 +525,7 @@ export const CLI_COMMANDS = [
     category: 'Advanced',
     core: false,
     description: 'Show version',
-    usage: 'construct version',
+    usage: 'construct version | construct --version',
   },
   {
     name: 'cleanup',

package/lib/comment-lint.mjs

@@ -42,7 +42,13 @@ function requiresHeader(rel) {
   if (rel.startsWith('lib/server/static/')) {
     return { required: false, type: null };
   }
-  const type = (jsMatch && ext !== '.html') ? 'js' : (jsMatch || mdMatch) ? 'md' : null;
+  // Markdown files always get markdown-style headers, even if the directory
+  // glob (e.g. ^tests/) primarily targets JS sources. Without this, .md docs
+  // co-located with .mjs tests were forced into /** */ format.
+  let type;
+  if (ext === '.md') type = mdMatch || jsMatch ? 'md' : null;
+  else if (jsMatch && ext !== '.html') type = 'js';
+  else type = (jsMatch || mdMatch) ? 'md' : null;
   return { required: jsMatch || mdMatch, type };
 }
 

package/lib/config/schema.mjs

@@ -20,6 +20,7 @@ export const CONFIG_SCHEMA_VERSION = 1;
 
 export const DEPLOYMENT_MODES = ['solo', 'team', 'enterprise'];
 export const MCP_BROKER_VALUES = ['auto', 'on', 'off'];
+export const DEFAULT_PROFILE_ID = 'rnd';
 
 export const DEFAULT_PROJECT_CONFIG = Object.freeze({
   version: CONFIG_SCHEMA_VERSION,
@@ -31,6 +32,7 @@ export const DEFAULT_PROJECT_CONFIG = Object.freeze({
     tenantId: null,
   }),
   providers: Object.freeze({}),
+  profile: DEFAULT_PROFILE_ID,
   autoEmbed: false,
   telemetry: Object.freeze({
     enabled: true,
@@ -77,6 +79,7 @@ export const FIELD_RULES = {
     },
   },
   providers: { type: 'object', required: false },
+  profile: { type: 'string', required: false, maxLength: 40 },
   autoEmbed: { type: 'boolean', required: false },
   telemetry: {
     type: 'object',