@geraldmaron/construct 1.2.0 → 1.2.2

package/README.md

@@ -28,7 +28,7 @@ Bootstrap local services (once per machine, opt-in to machine-scope writes):
 construct install --scope=user --yes
 ```
 
-`construct install` defaults to `--scope=project`, which writes nothing and prints scope guidance — see the [footprint contract](#footprint-contract) below or [ADR 0029](docs/adr/0029-install-scopes-and-hook-budgets.md). Use `--scope=user` for machine setup, `--scope=both` for both.
+`construct install` defaults to `--scope=project`, which writes nothing and prints scope guidance — see the [footprint contract](#footprint-contract) below or [ADR 0029](docs/decisions/adr/0029-install-scopes-and-hook-budgets.md). Use `--scope=user` for machine setup, `--scope=both` for both.
 
 Initialize a project:
 
@@ -87,7 +87,7 @@ Pick or change modes with `construct config mode [solo|team|enterprise]`. [Deplo
 
 ## Intake
 
-Anything dropped into `.cx/inbox/` (a bug report, a customer comment, a competitor PDF, a postmortem draft) is classified by the active profile's intake taxonomy. The default `rnd` profile uses bug, user-signal, experiment, architecture, incident, security, requirement, research, ops, eval-finding, launch-asset, legal-compliance. The `operations` profile uses request, incident, ops, security, docs. The `creative` profile uses brief, content-request, asset, experiment, report. The `research` profile uses question, study, synthesis, report.
+Anything dropped into `inbox/` (a bug report, a customer comment, a competitor PDF, a postmortem draft) is classified by the active profile's intake taxonomy. The default `rnd` profile uses bug, user-signal, experiment, architecture, incident, security, requirement, research, ops, eval-finding, launch-asset, legal-compliance. The `operations` profile uses request, incident, ops, security, docs. The `creative` profile uses brief, content-request, asset, experiment, report. The `research` profile uses question, study, synthesis, report.
 
 Each signal gets a primary owner and a recommended handoff chain. Inspect with `construct intake list` and `construct intake show <id>`. Generate a task graph with `construct graph from-intake <id>`. The classifier runs in the daemon and is deterministic. The agent in your editor does the actual analysis. [Intake and triage](https://geraldmaron.github.io/construct/concepts/intake-and-triage).
 
@@ -111,11 +111,11 @@ Construct's writes are scoped and disclosed up front. The default `construct ins
 | Machine | `construct install --scope=user` | `~/.construct/config.env`, `~/.construct/lib` (symlink), `~/.construct/services/`, `~/Library/LaunchAgents/` (macOS), MCP entries in `~/.config/opencode/opencode.json` and `~/.codex/config.toml`, marker block in `~/.claude/CLAUDE.md`, hook injection in `~/.claude/settings.json` (last two require interactive consent or `--yes`) |
 | Never touched | — | Shell rc files (`~/.bashrc`, `~/.zshrc`), npm global config, `git config --global` |
 
-Full table with file:line citations and the per-hook performance budget contract: [Architecture — Footprint contract](https://geraldmaron.github.io/construct/concepts/architecture#footprint-contract) and [ADR 0029](docs/adr/0029-install-scopes-and-hook-budgets.md).
+Full table with file:line citations and the per-hook performance budget contract: [Architecture — Footprint contract](https://geraldmaron.github.io/construct/concepts/architecture#footprint-contract) and [ADR 0029](docs/decisions/adr/0029-install-scopes-and-hook-budgets.md).
 
 ## Learning loops
 
-Construct gets smarter on its own. Every session ends with an automatic capture: tools used, files touched, what the final reply said. That goes into `.cx/observations/` and is searchable from the next session. See [`docs/concepts/learning-loops.mdx`](./docs/concepts/learning-loops.mdx) for what's wired, what's coming, and how to turn pieces off.
+Construct gets smarter on its own. Every session ends with an automatic capture: tools used, files touched, what the final reply said. That goes into `.cx/observations/` and is searchable from the next session. See [`docs/guides/concepts/learning-loops.mdx`](./docs/guides/concepts/learning-loops.mdx) for what's wired, what's coming, and how to turn pieces off.
 
 ## `.cx/` is local-only runtime state
 
@@ -148,7 +148,7 @@ The embed daemon writes its supervisor stdout log to `~/.cx/runtime/embed-daemon
 
 | Command | What it does |
 |---|---|
-| `construct artifact` | Validate typed document artifacts against the release gate |
+| `construct artifact` | Plan or locally execute manifest-backed artifact workflows with execution provenance |
 | `construct ask` | One-shot ask against the active knowledge index |
 | `construct bootstrap` | Import seed observation corpus into local memory store for cold-start acceleration |
 | `construct customer` | Manage customer profiles for product intelligence |
@@ -226,7 +226,7 @@ The embed daemon writes its supervisor stdout log to `~/.cx/runtime/embed-daemon
 | `construct doc` | Verify or inspect auditability stamps on Construct-generated markdown files |
 | `construct docs:check` | Check for missing how-to guides (alias for `docs check`) |
 | `construct docs:reconcile` | Reconcile docs against the registry |
-| `construct docs:site` | Regenerate generated reference pages under docs/reference/ |
+| `construct docs:site` | Regenerate generated reference pages under docs/guides/reference/ |
 | `construct docs:update` | Regenerate AUTO-managed doc regions (alias for `docs update`) |
 | `construct docs:verify` | Validate documentation quality (alias for `docs verify`) |
 | `construct impact` | Change-impact analysis — map changed files to affected tests, capabilities, and workflows |
@@ -257,6 +257,7 @@ The embed daemon writes its supervisor stdout log to `~/.cx/runtime/embed-daemon
 | `construct roles:set` | Activate a role contract |
 | `construct scheduler` | Manage scheduled background jobs (tag-mining, doc-hygiene, skill-rollup) |
 | `construct skills` | Skill relevance detection |
+| `construct sources` | Manage typed integration source targets in construct.config.json |
 | `construct uninstall` | Remove Construct state |
 | `construct update` | Reinstall this checkout |
 | `construct upgrade` | Upgrade to latest npm version |
@@ -268,7 +269,7 @@ The embed daemon writes its supervisor stdout log to `~/.cx/runtime/embed-daemon
 
 - [`CONTRIBUTING.md`](./CONTRIBUTING.md). Branch workflow, gates, review expectations.
 - [`CHANGELOG.md`](./CHANGELOG.md). Release history.
-- [`docs/concepts/architecture.mdx`](./docs/concepts/architecture.mdx). Canonical architecture.
+- [`docs/guides/concepts/architecture.mdx`](./docs/guides/concepts/architecture.mdx). Canonical architecture.
 - [`AGENTS.md`](./AGENTS.md). Agent operating contract.
 
 ## Project structure

package/bin/construct

@@ -38,6 +38,7 @@ import {
   PROJECT_CONFIG_FILENAME,
 } from '../lib/config/project-config.mjs';
 import { validateProjectConfig } from '../lib/config/schema.mjs';
+import { configDir, doctorRoot } from '../lib/config/xdg.mjs';
 import {
   DEPLOYMENT_MODES,
   DEPLOYMENT_MODE_ENV_KEY,
@@ -400,7 +401,7 @@ async function cmdDoctor() {
       }
 
       // .env files
-      for (const envPath of [join(process.cwd(), '.env'), join(homedir(), '.env'), join(homedir(), '.construct', 'config.env')]) {
+      for (const envPath of [join(process.cwd(), '.env'), join(homedir(), '.env'), getUserEnvPath(homedir())]) {
         if (fs.existsSync(envPath)) {
           try {
             const content = fs.readFileSync(envPath, 'utf8');
@@ -500,15 +501,19 @@ async function cmdDoctor() {
 
   const checks = [];
   const add = (label, pass, optional = false) => checks.push({ label, pass, optional });
+  const { isConstructSourceCheckout } = await import('../lib/doctor/source-checkout.mjs');
+  const isSourceCheckout = isConstructSourceCheckout(ROOT_DIR);
   add('registry.json exists', fs.existsSync(path.join(ROOT_DIR, 'specialists', 'registry.json')));
   add('sync-specialists.mjs exists', fs.existsSync(path.join(ROOT_DIR, 'scripts', 'sync-specialists.mjs')));
 
-  // Dashboard static build output. The Next.js app under apps/dashboard
-  // emits a static export into lib/server/static/ via its postbuild script;
-  // an empty static dir means lib/server/index.mjs will serve 404s.
+  // Dashboard static build output is absent from published npm installs.
 
-  const dashboardIndex = path.join(ROOT_DIR, 'lib', 'server', 'static', 'index.html');
-  add('Dashboard built (lib/server/static/index.html)', fs.existsSync(dashboardIndex));
+  if (isSourceCheckout) {
+    const dashboardIndex = path.join(ROOT_DIR, 'lib', 'server', 'static', 'index.html');
+    add('Dashboard built (lib/server/static/index.html)', fs.existsSync(dashboardIndex));
+  } else {
+    add('Dashboard built (skipped — published package)', true, true);
+  }
 
   // Project .gitignore must cover .cx/. Auto-fix via --fix-gitignore.
   // Only checks when cwd looks like a Construct project (has .cx/ or
@@ -588,7 +593,7 @@ async function cmdDoctor() {
   // minute at 50MB, but a freshly-upgraded install with a 34GB legacy
   // log shouldn't wait 60s. --fix-embed-log forces rotation now.
 
-  const embedLogPath = path.join(userHome, '.cx', 'runtime', 'embed-daemon.log');
+  const embedLogPath = path.join(doctorRoot(userHome), 'runtime', 'embed-daemon.log');
   if (fs.existsSync(embedLogPath)) {
     const sizeMb = fs.statSync(embedLogPath).size / 1024 / 1024;
     const FORCE_THRESHOLD_MB = Number(process.env.CONSTRUCT_DOCTOR_EMBED_LOG_FORCE_MB) || 500;
@@ -623,11 +628,11 @@ async function cmdDoctor() {
     'intent-verifications.jsonl',
   ];
   const legacyState = projectScopedNames
-    .map((name) => ({ name, path: path.join(userHome, '.cx', name) }))
+    .map((name) => ({ name, path: path.join(doctorRoot(userHome), name) }))
     .filter((p) => fs.existsSync(p.path) && fs.statSync(p.path).size > 0);
 
   if (legacyState.length > 0 && wantsFixMigrateState) {
-    const archiveDir = path.join(userHome, '.cx', 'legacy');
+    const archiveDir = path.join(doctorRoot(userHome), 'legacy');
     fs.mkdirSync(archiveDir, { recursive: true });
     const ts = new Date().toISOString().replace(/[:.]/g, '-');
     const moved = [];
@@ -735,13 +740,13 @@ async function cmdDoctor() {
     const vscodeSettingsOk = vscodeSettingsPaths.some((candidate) => fs.existsSync(candidate));
     if (vscodeSettingsOk) add('VS Code settings file', true, true);
   }
-  add('User config ready', fs.existsSync(getUserEnvPath(HOME)) || fs.existsSync(path.join(HOME, '.construct')), true);
+  add('User config ready', fs.existsSync(getUserEnvPath(HOME)) || fs.existsSync(configDir(HOME)), true);
   add('skills/ directory', fs.existsSync(path.join(ROOT_DIR, 'skills')));
   add('rules/common/', fs.existsSync(path.join(ROOT_DIR, 'rules', 'common')));
   add('specialists/prompts/ directory', fs.existsSync(path.join(ROOT_DIR, 'specialists', 'prompts')));
   add('Hybrid storage env keys documented', fs.existsSync(path.join(ROOT_DIR, '.env.example')));
-  fs.mkdirSync(path.join(HOME, '.cx', 'performance-reviews'), { recursive: true });
-  add('~/.cx/performance-reviews/ ready', true);
+  fs.mkdirSync(path.join(doctorRoot(), 'performance-reviews'), { recursive: true });
+  add('performance-reviews/ ready', true);
 
   // construct.config.json — optional today (config is permitted to be absent;
   // env vars + defaults still work). The check enforces that when the file
@@ -761,33 +766,29 @@ async function cmdDoctor() {
 
   // Claude Code Stop-hook installation check. The settings template
   // wires several Stop hooks (policy-engine / stop-typecheck /
-  // stop-notify / readme-age-check) that reference
-  // $HOME/.construct/lib/hooks/*. If that path doesn't resolve, every
-  // Stop hook fails silently — including stop-notify, which is what
-  // appends session cost data. Result: the dashboard stops updating
-  // and the user sees stale data. Surface loudly so the fix is one
-  // command away.
+  // stop-notify / readme-age-check) whose commands sync resolves to the
+  // hook lib symlink. If those scripts don't resolve, every Stop hook
+  // fails silently — including stop-notify, which is what appends session
+  // cost data. Result: the dashboard stops updating and the user sees stale
+  // data. Surface loudly so the fix is one command away.
   try {
     const settingsPath = path.join(HOME, '.claude', 'settings.json');
     if (fs.existsSync(settingsPath)) {
       const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
       const stopHooks = settings?.hooks?.Stop || [];
-      const installRoot = path.join(HOME, '.construct', 'lib', 'hooks');
-      const installed = fs.existsSync(installRoot);
+      const installRoot = path.join(configDir(HOME), 'lib', 'hooks');
       const referenced = [];
       for (const group of stopHooks) {
         for (const h of (group?.hooks || [])) {
           const cmd = String(h?.command || '');
-          const m = cmd.match(/\.construct\/lib\/hooks\/([a-zA-Z0-9_-]+\.mjs)/);
+          const m = cmd.match(/(?:^|["\s])(\/[^"\s]*\/lib\/hooks\/[a-zA-Z0-9_-]+\.mjs)/);
           if (m) referenced.push(m[1]);
         }
       }
-      const missing = installed
-        ? referenced.filter((f) => !fs.existsSync(path.join(installRoot, f)))
-        : referenced;
+      const missing = referenced.filter((scriptPath) => !fs.existsSync(scriptPath));
       if (referenced.length > 0 && missing.length > 0) {
         add(
-          `Claude Stop hooks broken: ${missing.length} hook${missing.length === 1 ? '' : 's'} missing in ~/.construct/lib/hooks/. Symlink the install: ln -sfn ${ROOT_DIR}/lib ~/.construct/lib`,
+          `Claude Stop hooks broken: ${missing.length} hook${missing.length === 1 ? '' : 's'} do not resolve. Re-run \`construct install --scope=user\` (symlinks ${ROOT_DIR}/lib → ${installRoot.replace(/\/hooks$/, '')}).`,
           false,
           false,
         );
@@ -858,8 +859,21 @@ async function cmdDoctor() {
     add('Headhunt classifier agents exist in registry', classifierOrphans.length === 0);
     const skillAudit = auditSkills({ rootDir: ROOT_DIR, silent: true });
     add('No declared skills missing on disk', skillAudit.pass, false);
-    const specialistAudit = auditSpecialists({ rootDir: ROOT_DIR, silent: true });
-    add('Specialist/skill audit cross-checks', specialistAudit.pass, false);
+    if (isSourceCheckout) {
+      const specialistAudit = auditSpecialists({ rootDir: ROOT_DIR, silent: true });
+      add('Specialist/skill audit cross-checks', specialistAudit.pass, false);
+
+      // The catalog is the public-service source of truth; doctor joins it to runtime dispatch
+      // and the generated reference so a command that is unroutable or undocumented surfaces here.
+
+      const { buildCliServiceInventory } = await import('../lib/cli-service-inventory.mjs');
+      const cliDrift = buildCliServiceInventory({ rootDir: ROOT_DIR })
+        .filter((entry) => !entry.runnable || !entry.documented);
+      add('Public CLI dispatch/reference parity', cliDrift.length === 0, false);
+    } else {
+      add('Specialist/skill audit cross-checks (skipped — published package)', true, true);
+      add('Public CLI dispatch/reference parity (skipped — published package)', true, true);
+    }
     const { lintResearchRepo } = await import('../lib/research-lint.mjs');
     const researchLintResults = lintResearchRepo({ rootDir: process.cwd() });
     add('Research artifacts meet minimum evidence structure', researchLintResults.every((entry) => entry.errors.length === 0), true);
@@ -1056,7 +1070,7 @@ async function cmdDoctor() {
     }
 
     try {
-      const failuresPath = path.join(HOME, '.cx', 'hook-failures.jsonl');
+      const failuresPath = path.join(doctorRoot(), 'hook-failures.jsonl');
       if (fs.existsSync(failuresPath)) {
         const lines = fs.readFileSync(failuresPath, 'utf8').trim().split('\n').filter(Boolean);
         const cutoff = Date.now() - 24 * 60 * 60 * 1000;
@@ -1502,7 +1516,7 @@ async function cmdMigrate(args) {
 }
 
 async function cmdReview(args) {
-  fs.mkdirSync(path.join(HOME, '.cx', 'performance-reviews'), { recursive: true });
+  fs.mkdirSync(path.join(doctorRoot(), 'performance-reviews'), { recursive: true });
   const sub = args[0];
 
   if (!sub || sub === 'run') {
@@ -1561,17 +1575,18 @@ async function cmdExport(args) {
   const outFlag = args.find((a) => a.startsWith('--output='))?.split('=')[1];
   const detectOnly = args.includes('--detect');
   const figures = !args.includes('--no-figures');
+  const branding = args.includes('--plain') || args.includes('--no-brand') ? 'plain' : 'construct';
 
   const { detect, exportMarkdown, EXPORT_FORMATS } = await import('../lib/document-export.mjs');
 
   if (detectOnly) {
     const format = toFlag || 'pdf';
-    println(JSON.stringify(detect(format), null, 2));
+    println(JSON.stringify(detect(format, process.env, { branding }), null, 2));
     return;
   }
 
   if (!inputPath) {
-    errorln('Usage: construct export <markdown-file> --to=<pdf|docx|html> [--output=<path>] [--figures|--no-figures] [--detect]');
+    errorln('Usage: construct export <markdown-file> --to=<pdf|docx|html> [--output=<path>] [--figures|--no-figures] [--plain] [--detect]');
     process.exit(1);
   }
   if (!toFlag) {
@@ -1586,6 +1601,7 @@ async function cmdExport(args) {
     outputPath: resolvedOut,
     format: toFlag,
     figures: toFlag === 'pdf' ? figures : false,
+    branding,
     repoRoot: ROOT_DIR,
   });
   if (!result.ok) {
@@ -1999,7 +2015,7 @@ async function _cmdPricing(args) {
     const f = describePricingCatalogFreshness();
     if (!f.present) { info(f.message); return; }
     try {
-      const cached = JSON.parse(fs.readFileSync(path.join(HOME, '.cx', 'pricing-cache.json'), 'utf8'));
+      const cached = JSON.parse(fs.readFileSync(path.join(doctorRoot(), 'pricing-cache.json'), 'utf8'));
       const divergences = checkPricingDivergence(cached.models || []);
       if (divergences.length === 0) { info('No pricing divergences (>25%) between LiteLLM and the static fallback.'); return; }
       println(`⚠  ${divergences.length} divergence(s):`);
@@ -2097,15 +2113,13 @@ async function printIntakeHelp() {
   println('  construct intake metrics               Show pipeline volume, velocity, and processing stats.');
   println('  construct intake integrate <id> <system>    Push intake to external system (github, jira, confluence).');
   println('  construct intake integrate <id> <system> --create-issue  Create an issue from the intake packet.');
-  println('  construct intake config               Show current watch dirs + scan depth.');
+  println('  construct intake config               Show the inbox/ drop zone + scan depth.');
   println('  construct intake config set --depth=N [--add-dir=PATH] [--remove-dir=PATH]');
+  println('                                       Update intake config. --depth caps at the hard limit.');
   println('  construct intake extraction-warnings [--since=7d] [--kind=table] [--limit=50]');
   println('                                       Summarize ~/.cx/intake/extraction-warnings.jsonl (dropped content log).');
   println('  construct intake needs-asr list       List audio/video files awaiting ASR transcription.');
   println('  construct intake needs-asr show <id>  Show a specific ASR-pending packet.');
-  println('                                       Update intake config. --depth caps at the hard limit.');
-  println('  construct intake config set --include-project-inbox=on|off');
-  println('  construct intake config set --include-docs-intake=on|off');
 }
 
 function parseKvFlags(args, keys) {
@@ -2599,7 +2613,6 @@ async function cmdIntakeReroute(args, cwd) {
 
 async function cmdIntakeExtractionWarnings(args) {
   const { createReadStream, existsSync } = await import('node:fs');
-  const { homedir } = await import('node:os');
   const { join } = await import('node:path');
   const { createInterface } = await import('node:readline');
 
@@ -2617,7 +2630,7 @@ async function cmdIntakeExtractionWarnings(args) {
     }
   }
 
-  const logPath = join(homedir(), '.cx', 'intake', 'extraction-warnings.jsonl');
+  const logPath = join(doctorRoot(), 'intake', 'extraction-warnings.jsonl');
   if (!existsSync(logPath)) {
     println('No extraction warnings recorded yet.');
     return;
@@ -2668,11 +2681,10 @@ async function cmdIntakeExtractionWarnings(args) {
 
 async function cmdIntakeNeedsAsr(args) {
   const { existsSync, readdirSync, readFileSync } = await import('node:fs');
-  const { homedir } = await import('node:os');
   const { join } = await import('node:path');
 
   const sub = args[0] || 'list';
-  const asrDir = join(homedir(), '.cx', 'intake', 'needs-asr');
+  const asrDir = join(doctorRoot(), 'intake', 'needs-asr');
 
   if (sub === 'list') {
     if (!existsSync(asrDir)) { println('No audio/video files awaiting ASR.'); return; }
@@ -2837,20 +2849,23 @@ async function cmdIntakeConfig(args) {
   const cwd = process.cwd();
 
   const action = args[0];
+
+  // Single-zone model (ADR-0045 §C): the canonical `inbox/` is always watched.
+  // Only maxDepth and additionalDirs are configurable.
+
   if (!action || action === 'show') {
     const cfg = loadIntakeConfig(cwd, process.env);
     const desc = describeIntakeDepth(cfg.maxDepth);
     println(`Intake config (root: ${cwd})`);
     println('');
-    println(`  includeProjectInbox: ${cfg.includeProjectInbox ? 'on' : 'off'} (.cx/inbox)`);
-    println(`  includeDocsIntake:   ${cfg.includeDocsIntake ? 'on' : 'off'} (docs/intake)`);
+    println('  drop zone:           inbox/ (always watched)');
     println(`  maxDepth:            ${cfg.maxDepth} — ${desc.label}`);
     println(`                       ${desc.detail}`);
     println(`  hardMaxDepth:        ${INTAKE_HARD_MAX_DEPTH}`);
     if (cfg.parentDirs.length === 0) {
-      println('  parentDirs:          (none — only the built-in zones are watched)');
+      println('  additionalDirs:      (none — only inbox/ is watched)');
     } else {
-      println('  parentDirs:');
+      println('  additionalDirs:');
       for (const dir of cfg.parentDirs) println(`    - ${dir}`);
     }
     println('');
@@ -2871,12 +2886,6 @@ async function cmdIntakeConfig(args) {
   const depthFlag = tail.find((a) => a.startsWith('--depth='));
   if (depthFlag) patch.maxDepth = Number(depthFlag.split('=')[1]);
 
-  const projectFlag = tail.find((a) => a.startsWith('--include-project-inbox='));
-  if (projectFlag) patch.includeProjectInbox = /^(on|true|1|yes)$/i.test(projectFlag.split('=')[1] || '');
-
-  const docsFlag = tail.find((a) => a.startsWith('--include-docs-intake='));
-  if (docsFlag) patch.includeDocsIntake = /^(on|true|1|yes)$/i.test(docsFlag.split('=')[1] || '');
-
   const addFlags = tail.filter((a) => a.startsWith('--add-dir='));
   const removeFlags = tail.filter((a) => a.startsWith('--remove-dir='));
 
@@ -2889,7 +2898,7 @@ async function cmdIntakeConfig(args) {
   }
 
   if (Object.keys(patch).length === 0) {
-    errorln('Nothing to change. Pass --depth=N, --add-dir=PATH, --remove-dir=PATH, --include-project-inbox=on|off, or --include-docs-intake=on|off.');
+    errorln('Nothing to change. Pass --depth=N, --add-dir=PATH, or --remove-dir=PATH.');
     process.exit(1);
   }
 
@@ -2903,6 +2912,123 @@ async function cmdIntakeConfig(args) {
   }
 }
 
+async function cmdSources(args) {
+  const {
+    validateSourceTargets,
+    normalizeConfigTarget,
+    resolveEffectiveSourceTargetsFromConfig,
+    legacyEnvSourceTargets,
+    SOURCE_PROVIDERS,
+  } = await import('../lib/config/source-targets.mjs');
+  const {
+    loadProjectConfig,
+    writeProjectConfig,
+    findProjectConfigPath,
+    PROJECT_CONFIG_FILENAME,
+  } = await import('../lib/config/project-config.mjs');
+
+  const cwd = process.cwd();
+  const action = args[0] ?? 'list';
+
+  if (action === 'list' || action === 'show') {
+    const { config, path: cfgPath } = loadProjectConfig(cwd, process.env);
+    const configTargets = (config.sources?.targets ?? []).map(normalizeConfigTarget);
+    const envTargets = legacyEnvSourceTargets(process.env);
+    const effective = resolveEffectiveSourceTargetsFromConfig(config, process.env);
+    println(`Source targets (config: ${cfgPath ?? 'default'})`);
+    println('');
+    if (configTargets.length === 0) println('  (no targets in construct.config.json)');
+    for (const t of configTargets) {
+      println(`  ${t.id} · ${t.provider} · ${JSON.stringify(t.selector)}`);
+    }
+    if (envTargets.length) {
+      println('');
+      println('Legacy env targets (merged at runtime):');
+      for (const t of envTargets) {
+        println(`  ${t.id} · ${t.provenance} · ${t.provider} · ${JSON.stringify(t.selector)}`);
+      }
+    }
+    println('');
+    println(`Effective targets: ${effective.length}`);
+    return;
+  }
+
+  if (action === 'validate') {
+    const loaded = loadProjectConfig(cwd, process.env);
+    const targetErrors = validateSourceTargets(loaded.raw?.sources?.targets ?? loaded.config?.sources?.targets ?? []);
+    const all = [...(loaded.errors ?? []), ...targetErrors];
+    if (!all.length) {
+      info(`${loaded.path ?? PROJECT_CONFIG_FILENAME}: source targets valid`);
+      return;
+    }
+    errorln(`Source target validation failed (${all.length}):`);
+    for (const e of all) errorln(`  - ${e}`);
+    process.exit(1);
+  }
+
+  if (action === 'add') {
+    const provider = args[1];
+    const id = args[2];
+    const selectorRaw = args[3];
+    if (!provider || !id || !selectorRaw) {
+      errorln('Usage: construct sources add <provider> <id> <selector-json>');
+      process.exit(1);
+    }
+    if (!SOURCE_PROVIDERS.includes(provider)) {
+      errorln(`Unknown provider: ${provider}. Expected: ${SOURCE_PROVIDERS.join(', ')}`);
+      process.exit(1);
+    }
+    let selector;
+    try { selector = JSON.parse(selectorRaw); } catch (err) {
+      errorln(`Invalid selector JSON: ${err.message}`);
+      process.exit(1);
+    }
+    const target = normalizeConfigTarget({ id, provider, selector });
+    const targetErrors = validateSourceTargets([target]);
+    if (targetErrors.length) {
+      for (const e of targetErrors) errorln(`  - ${e}`);
+      process.exit(1);
+    }
+    const cfgPath = findProjectConfigPath(cwd) || path.join(cwd, PROJECT_CONFIG_FILENAME);
+    const { config } = loadProjectConfig(cwd, process.env);
+    const existing = config.sources?.targets ?? [];
+    if (existing.some((t) => t.id === id)) {
+      errorln(`Target id already exists: ${id}`);
+      process.exit(1);
+    }
+    const next = {
+      ...config,
+      sources: { ...(config.sources ?? {}), targets: [...existing, target] },
+    };
+    writeProjectConfig(cfgPath, next);
+    info(`added source target ${id}`);
+    return;
+  }
+
+  if (action === 'remove') {
+    const id = args[1];
+    if (!id) {
+      errorln('Usage: construct sources remove <id>');
+      process.exit(1);
+    }
+    const cfgPath = findProjectConfigPath(cwd) || path.join(cwd, PROJECT_CONFIG_FILENAME);
+    const { config } = loadProjectConfig(cwd, process.env);
+    const existing = config.sources?.targets ?? [];
+    const nextTargets = existing.filter((t) => t.id !== id);
+    if (nextTargets.length === existing.length) {
+      errorln(`No target with id: ${id}`);
+      process.exit(1);
+    }
+    const next = { ...config, sources: { ...(config.sources ?? {}), targets: nextTargets } };
+    writeProjectConfig(cfgPath, next);
+    info(`removed source target ${id}`);
+    return;
+  }
+
+  errorln(`Unknown sources action: ${action}. Available: list, add, remove, validate`);
+  process.exit(1);
+}
+
 async function cmdIntakeMetrics() {
   try {
     const { computeIntakeMetrics, pendingAge } = await import('../lib/embed/intake-metrics.mjs');
@@ -3882,7 +4008,7 @@ async function cmdPluginEngine(args) {
   const [action = 'list', ...rest] = args;
   const isGlobal = rest.includes('--global');
   const targetPath = isGlobal
-    ? path.join(HOME, '.construct', 'plugins.json')
+    ? path.join(configDir(HOME), 'plugins.json')
     : path.join(process.cwd(), '.cx', 'plugins.json');
 
   function readPluginsJson() {
@@ -4089,7 +4215,7 @@ async function cmdEvals(args) {
     const report = await evaluateFixture(fixturePath);
 
     try {
-      const cacheDir = path.join(HOME, '.cx', 'evals');
+      const cacheDir = path.join(doctorRoot(), 'evals');
       fs.mkdirSync(cacheDir, { recursive: true });
       const ts = new Date().toISOString();
       fs.writeFileSync(
@@ -4286,7 +4412,7 @@ async function cmdDocsCheck(args) {
     println('Commands with no linked how-to in docs/README.md:');
     for (const name of result.uncovered) println(`  ✗  construct ${name}`);
     println('');
-    println(`Add cookbook recipes under docs/cookbook/ and link them from the cookbook index.`);
+    println(`Add cookbook recipes under docs/guides/cookbook/ and link them from the cookbook index.`);
     process.exitCode = 1;
   }
 }
@@ -4297,7 +4423,7 @@ async function cmdDocsSite(args = []) {
   if (check) {
     const { drift } = checkFumadocsReferenceDrift({ rootDir: ROOT_DIR });
     if (drift.length === 0) {
-      ok('docs/reference/ is up to date.');
+      ok('docs/guides/reference/ is up to date.');
       return;
     }
     println('');
@@ -4308,9 +4434,9 @@ async function cmdDocsSite(args = []) {
   }
   const { written } = buildFumadocsReference({ rootDir: ROOT_DIR });
   if (written.length === 0) {
-    ok('docs/reference/ already up to date.');
+    ok('docs/guides/reference/ already up to date.');
   } else {
-    ok(`docs/reference/ regenerated (${written.length} file${written.length === 1 ? '' : 's'}).`);
+    ok(`docs/guides/reference/ regenerated (${written.length} file${written.length === 1 ? '' : 's'}).`);
   }
 }
 
@@ -4809,7 +4935,7 @@ async function cmdProvider(args) {
       if (!id) { errorln(`Usage: construct provider plugins ${action} <id> [<package>]`); process.exit(1); }
       const isGlobal = args.includes('--global');
       const targetPath = isGlobal
-        ? path.join(HOME, '.construct', 'providers.json')
+        ? path.join(configDir(HOME), 'providers.json')
         : path.join(process.cwd(), '.cx', 'providers.json');
       let data = { providers: [] };
       try { data = JSON.parse(fs.readFileSync(targetPath, 'utf8')); } catch { /* fresh */ }
@@ -5334,7 +5460,7 @@ async function cmdTelemetryQuery(args) {
   println('  errors [--agent=<name>] [--since=24h]                error span summary');
   println('  trace <traceId>                                       full span tree');
   println('');
-  println('For Langfuse/Honeycomb/Grafana Tempo/Datadog, see docs/concepts/observability.md');
+  println('For Langfuse/Honeycomb/Grafana Tempo/Datadog, see docs/guides/concepts/observability.md');
 }
 
 async function cmdHook(args) {
@@ -5400,6 +5526,7 @@ const handlers = new Map([
   ['status', cmdStatus],
   ['install', cmdInstall],
   ['config', cmdConfig],
+  ['sources', cmdSources],
   ['intake', cmdIntake],
   ['recommendations', cmdRecommendations],
   ['integrations', cmdIntegrations],
@@ -5648,7 +5775,24 @@ const handlers = new Map([
   ['artifact', async (args) => {
     const sub = args[0];
     if (sub === 'validate') return runArtifactValidateCli(args.slice(1));
-    errorln(`Unknown artifact subcommand: ${sub || '(none)'}. Available: validate`);
+    if (sub === 'workflow') {
+      const rest = args.slice(1);
+      const request = rest.filter((arg) => !arg.startsWith('--')).join(' ');
+      const read = (name) => rest.find((arg) => arg.startsWith(`${name}=`))?.slice(name.length + 1);
+      const { runArtifactWorkflow } = await import('../lib/artifact-workflow.mjs');
+      const result = runArtifactWorkflow({
+        input: request,
+        artifactType: read('--type'),
+        filePath: read('--file'),
+        format: read('--to'),
+        outputPath: read('--output'),
+        branding: rest.includes('--plain') ? 'plain' : undefined,
+        approvalMode: rest.includes('--apply') ? 'allow-durable-write' : (read('--approval-mode') || 'proposal-only'),
+      }, { cwd: process.cwd(), rootDir: ROOT_DIR });
+      println(JSON.stringify(result, null, 2));
+      return;
+    }
+    errorln(`Unknown artifact subcommand: ${sub || '(none)'}. Available: validate, workflow`);
     process.exit(1);
   }],
   ['doc', async (args) => {
@@ -6383,7 +6527,7 @@ const handlers = new Map([
 
         println('');
         println(`Scaffolding a new profile draft. Three questions, then a preview.`);
-        println(`Background: docs/concepts/persona-research.md and docs/concepts/profile-lifecycle.md`);
+        println(`Background: docs/guides/concepts/persona-research.md and docs/guides/concepts/profile-lifecycle.md`);
         println('');
         if (!displayName) displayName = await ask('Display name?', id);
         if (seedDepartments.length === 0) {
@@ -6442,7 +6586,7 @@ const handlers = new Map([
         println('');
         println(`✓ draft created at ${pathMod.relative(process.cwd(), result.dir)}`);
         println('');
-        println(`Next steps (in order, per docs/concepts/profile-lifecycle.md):`);
+        println(`Next steps (in order, per docs/guides/concepts/profile-lifecycle.md):`);
         println(`  1. Discover  (cx-ux-researcher): fill personas/<role>.md from interviews + primary sources.`);
         println(`  2. Frame     (cx-product-manager): fill departments/<dept>.md charters and intake taxonomy.`);
         println(`  3. Architect (cx-architect): reconcile role reuse vs new; populate departments[] in profile.json.`);

package/commands/plan/decide.md

@@ -11,4 +11,4 @@ ADR format:
 - FILES AFFECTED: paths future contributors should inspect
 - FOLLOW-UP: docs, tests, migrations, or risks to track
 
-Save to `docs/adr/ADR-{NNN}-{slug}.md` and `.cx/decisions/` if those directories exist.
+Save to `docs/decisions/adr/ADR-{NNN}-{slug}.md` and `.cx/decisions/` if those directories exist.

package/commands/remember/runbook.md

@@ -11,4 +11,4 @@ Structure:
 - ROLLBACK: how to undo if something goes wrong
 - ESCALATION: who to contact and when
 
-Save to `docs/runbooks/{service}-{operation}.md` if the directory exists.
+Save to `docs/operations/runbooks/{service}-{operation}.md` if the directory exists.

package/examples/README.md

@@ -78,7 +78,7 @@ Required internal coverage:
 - Name the expected behavior in repo terms: branch confirmation, approval boundary, routing, verification, blocker surfacing, anti-pattern avoidance.
 - For bad examples, show the failure plainly and explain why it violates the surface contract.
 
-See `docs/concepts/prompt-surfaces.md` for the canonical public-vs-internal taxonomy.
+See `docs/guides/concepts/prompt-surfaces.md` for the canonical public-vs-internal taxonomy.
 
 ## Scope
 

package/examples/distribution/README.md

@@ -39,4 +39,4 @@ Edit sources, then re-run the generator. Outputs land in `.tmp/distribution-exam
 node bin/construct export examples/distribution/sources/adr.md --to=pdf --figures
 ```
 
-See [branding.md](../../docs/reference/branding.md) and [diagram-and-demo.md](../../docs/cookbook/diagram-and-demo.md).
+See [branding.md](../../docs/guides/reference/branding.md) and [diagram-and-demo.md](../../docs/guides/cookbook/diagram-and-demo.md).