@geraldmaron/construct 1.2.0 → 1.2.2

package/lib/cost.mjs

@@ -8,6 +8,7 @@
  */
 import { readFileSync, existsSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { doctorRoot } from './config/xdg.mjs';
 
 function numberFrom(...values) {
   for (const value of values) {
@@ -82,7 +83,7 @@ export function normalizeCostEntry(entry = {}) {
 }
 
 export function readCostLog(homeDir) {
-  const logPath = join(homeDir, '.cx', 'session-cost.jsonl');
+  const logPath = join(doctorRoot(homeDir), 'session-cost.jsonl');
   if (!existsSync(logPath)) return [];
   try {
     return readFileSync(logPath, 'utf8')
@@ -97,7 +98,7 @@ export function readCostLog(homeDir) {
 }
 
 export function clearCostLog(homeDir) {
-  const logPath = join(homeDir, '.cx', 'session-cost.jsonl');
+  const logPath = join(doctorRoot(homeDir), 'session-cost.jsonl');
   if (existsSync(logPath)) writeFileSync(logPath, '');
 }
 

package/lib/decisions/registry.mjs

@@ -7,7 +7,7 @@
  * contracts as the single source of truth.
  *
  * Three decision sources are indexed:
- *   - ADRs           docs/adr/*.md            (status + supersedes parsed from body)
+ *   - ADRs           docs/decisions/adr/*.md            (status + supersedes parsed from body)
  *   - Contracts      specialists/contracts.json (executable postconditions = enforcement)
  *   - Rules          rules/**\/*.md            (enforcement link via frontmatter; bead wvbf.4)
  *
@@ -37,7 +37,7 @@ const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 const ENFORCES_LINE_RE = /^(?:\/\/|#|\*)?\s*@enforces\s+(\S+)\s*$/;
 
 // The body carries Status and Supersedes as markdown definition lines, not
-// frontmatter (see docs/adr/templates/_template.md); parse them positionally.
+// frontmatter (see docs/decisions/adr/templates/_template.md); parse them positionally.
 
 // ADR field styles vary across the lane: inline bold (`- **Status**: x`,
 // `**Status:** X`) and heading-then-value (`## Status` followed by the value on
@@ -121,7 +121,7 @@ function collectEnforcementBindings({ repoRoot }) {
 }
 
 function adrDecisions({ repoRoot, bindings }) {
-  const dir = join(repoRoot, 'docs', 'adr');
+  const dir = join(repoRoot, 'docs', 'decisions', 'adr');
   const out = [];
   if (!existsSync(dir)) return out;
   for (const name of readdirSync(dir)) {

package/lib/distill.mjs

@@ -9,8 +9,8 @@
 import { readdirSync, statSync, readFileSync, writeFileSync, existsSync, mkdirSync, openSync, readSync, closeSync } from 'fs';
 import { join, extname, relative, dirname, basename } from 'path';
 import { execSync, spawnSync } from 'child_process';
-import { homedir } from 'os';
 import { getActiveOverlays } from './headhunt.mjs';
+import { doctorRoot } from './config/xdg.mjs';
 import { withGenAiSpan, GenAiAttrs } from './telemetry/otel-tracer.mjs';
 import {
   EXTRACTABLE_DOCUMENT_EXTS,
@@ -347,7 +347,7 @@ export async function distill(dir, { format = 'summary', query = '', mode = 'aut
 
   const prompt = structured.prompt;
   if (mode === 'prompt' || !hasClaude()) {
-    const tmpFile = out || join(homedir(), '.cx', 'distill-prompt.txt');
+    const tmpFile = out || join(doctorRoot(), 'distill-prompt.txt');
     try { mkdirSync(dirname(tmpFile), { recursive: true }); } catch { /* exists */ }
     writeFileSync(tmpFile, prompt);
     process.stderr.write(`\n⚠ Prompt written to: ${tmpFile}\n`);

package/lib/docs-verify.mjs

@@ -210,7 +210,9 @@ function gitTrackedMdFiles(cwd, dir) {
 
 function checkIntakeTraceability(cwd) {
   const intakeFedDirs = [
+    path.join(cwd, 'docs', 'specs', 'prd'),
     path.join(cwd, 'docs', 'prd'),
+    path.join(cwd, 'docs', 'notes', 'research'),
     path.join(cwd, 'docs', 'research'),
     path.join(cwd, '.cx', 'knowledge', 'internal'),
   ];

package/lib/doctor/audit.mjs

@@ -6,17 +6,18 @@
  * what the L0 layer did while they weren't looking — and the basis for rolling
  * back a misfire if rules are wrong.
  *
- * Path: ~/.cx/doctor-log.jsonl (overridable via CONSTRUCT_DOCTOR_ROOT for tests).
+ * Path: <doctorRoot>/doctor-log.jsonl (overridable via CONSTRUCT_DOCTOR_ROOT for tests).
  */
 
 import { existsSync, readFileSync, appendFileSync, writeFileSync, mkdirSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 
+import { doctorRoot } from '../config/xdg.mjs';
+
 const MAX_LINES = 2000;
 
 function rootDir() {
-  return process.env.CONSTRUCT_DOCTOR_ROOT || join(homedir(), '.cx');
+  return doctorRoot();
 }
 function logPath() {
   return join(rootDir(), 'doctor-log.jsonl');

package/lib/doctor/cli.mjs

@@ -10,7 +10,6 @@
  */
 
 import { existsSync, readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 
 import { readState } from './index.mjs';

package/lib/doctor/index.mjs

@@ -7,12 +7,11 @@
  * never starves the others. Termination via SIGTERM/SIGINT triggers a clean
  * shutdown that records a final audit entry.
  *
- * State file: ~/.construct/doctor.json (pid, started, lastTick).
+ * State file: doctor.json in the XDG state dir (pid, started, lastTick).
  * Audit log:  ~/.cx/doctor-log.jsonl.
  */
 
 import { writeFileSync, existsSync, readFileSync, unlinkSync, mkdirSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 
 import { record } from './audit.mjs';
@@ -26,8 +25,9 @@ import * as consistency from './watchers/consistency.mjs';
 import * as mcpProtocol from './watchers/mcp-protocol.mjs';
 import * as cxBudget from './watchers/cx-budget.mjs';
 import * as graphStaleness from './watchers/graph-staleness.mjs';
+import { stateDir } from '../config/xdg.mjs';
 
-const STATE_PATH = join(homedir(), '.construct', 'doctor.json');
+const STATE_PATH = join(stateDir(), 'doctor.json');
 const WATCHERS = [disk, cost, processPressure, serviceHealth, bdWatch, handoffs, consistency, mcpProtocol, cxBudget, graphStaleness];
 
 let running = false;
@@ -35,7 +35,7 @@ let timers = [];
 let lastTickAt = {};
 
 function writeState(state) {
-  const dir = join(homedir(), '.construct');
+  const dir = stateDir();
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
   writeFileSync(STATE_PATH, JSON.stringify({ ...state, updatedAt: Date.now() }));
 }

package/lib/doctor/report.mjs

@@ -8,10 +8,10 @@
  */
 
 import { existsSync, readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 
 import { recent } from './audit.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
 import { getTotalDailySpend, getDailySpend, totalBudget, personaBudget, dayKey } from '../cost-ledger.mjs';
 
 function parseWindow(arg) {
@@ -67,8 +67,8 @@ export async function runReport(args = []) {
   const since = Date.now() - windowMs;
 
   const auditEntries = recent({ since, limit: 10000 });
-  const events = readJsonl(join(homedir(), '.cx', 'events.jsonl')).filter((e) => e.ts >= since);
-  const pending = readJsonl(join(homedir(), '.cx', 'role-pending.jsonl')).filter((e) => e.ts >= since);
+  const events = readJsonl(join(doctorRoot(), 'events.jsonl')).filter((e) => e.ts >= since);
+  const pending = readJsonl(join(doctorRoot(), 'role-pending.jsonl')).filter((e) => e.ts >= since);
 
   const summary = summarizeActions(auditEntries);
   const eventsByType = groupBy(events, (e) => e.type);

package/lib/doctor/source-checkout.mjs

@@ -0,0 +1,16 @@
+/**
+ * lib/doctor/source-checkout.mjs — distinguish Construct source tree vs npm install.
+ *
+ * `isConstructPackageRepo` is true for both checkouts and consumer installs.
+ * Source-only doctor checks (dashboard static export, certification role cards)
+ * should run only when this returns true.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function isConstructSourceCheckout(rootDir) {
+  const root = path.resolve(rootDir);
+  return fs.existsSync(path.join(root, 'apps', 'dashboard'))
+    || fs.existsSync(path.join(root, 'tests', 'certification', 'specialists'));
+}

package/lib/doctor/watchers/bd-watch.mjs

@@ -4,7 +4,7 @@
  * Every 5 min, polls bd for open issues labeled `next:cx-<role>` where the
  * target persona is onboarded in the role framework. Newly-seen issues are
  * enqueued as pending invocations so session-start surfaces them to
- * Construct. Seen issues are remembered in ~/.cx/bd-watch-seen.json to
+ * Construct. Seen issues are remembered in <doctorRoot>/bd-watch-seen.json to
  * prevent re-emission while the label remains.
  *
  * Closes a gap in agent-tracker: agent-tracker only catches handoffs that
@@ -16,20 +16,20 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { appendBounded } from '../../logging/rotate.mjs';
 import { resolveProjectScope } from '../../project-root.mjs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 
 import { record } from '../audit.mjs';
 import { listOnboardedPersonas, loadManifest } from '../../roles/manifest.mjs';
+import { doctorRoot } from '../../config/xdg.mjs';
 
 export const name = 'bd-watch';
 export const intervalMs = 5 * 60 * 1000;
 
-const SEEN_PATH = join(homedir(), '.cx', 'bd-watch-seen.json');
-const PENDING_PATH = join(homedir(), '.cx', 'role-pending.jsonl');
+const SEEN_PATH = join(doctorRoot(), 'bd-watch-seen.json');
+const PENDING_PATH = join(doctorRoot(), 'role-pending.jsonl');
 
 function ensureDir() {
-  const dir = join(homedir(), '.cx');
+  const dir = doctorRoot();
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
 }
 

package/lib/doctor/watchers/cost.mjs

@@ -10,10 +10,10 @@
  */
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 
 import { record } from '../audit.mjs';
+import { doctorRoot } from '../../config/xdg.mjs';
 import {
   getTotalDailySpend,
   getDailySpend,
@@ -26,15 +26,15 @@ import {
 export const name = 'cost';
 export const intervalMs = 10 * 60 * 1000;
 
-const SESSION_COST_PATH = join(homedir(), '.cx', 'session-cost.jsonl');
-const STATE_PATH = join(homedir(), '.cx', 'cost-watcher-state.json');
+const SESSION_COST_PATH = join(doctorRoot(), 'session-cost.jsonl');
+const STATE_PATH = join(doctorRoot(), 'cost-watcher-state.json');
 
 function loadState() {
   if (!existsSync(STATE_PATH)) return { lastIngestedTsMs: 0 };
   try { return JSON.parse(readFileSync(STATE_PATH, 'utf8')); } catch { return { lastIngestedTsMs: 0 }; }
 }
 function saveState(state) {
-  const dir = join(homedir(), '.cx');
+  const dir = doctorRoot();
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
   writeFileSync(STATE_PATH, JSON.stringify(state));
 }

package/lib/doctor/watchers/disk.mjs

@@ -16,6 +16,7 @@ import { join } from 'node:path';
 
 import { record } from '../audit.mjs';
 import { escalate } from '../escalate.mjs';
+import { cacheDir } from '../../config/xdg.mjs';
 
 export const name = 'disk';
 export const intervalMs = 5 * 60 * 1000;
@@ -54,7 +55,7 @@ function rotateTarget({ path: relPath, maxLines }) {
 }
 
 function pruneRuntimeLogs() {
-  const runtimeDir = join(homedir(), '.construct', '.runtime');
+  const runtimeDir = join(cacheDir(), '.runtime');
   if (!existsSync(runtimeDir)) return { pruned: 0 };
   const maxAgeMs = 7 * 24 * 60 * 60 * 1000;
   const now = Date.now();
@@ -99,11 +100,11 @@ export async function tick() {
       kind: 'action',
       watcher: name,
       action: 'prune',
-      target: '.construct/.runtime/',
+      target: '.cache/construct/.runtime/',
       summary: `pruned ${runtimePrune.pruned} stale runtime log(s) (>7 days)`,
       context: runtimePrune,
     });
-    actions.push({ type: 'prune', target: '.construct/.runtime/' });
+    actions.push({ type: 'prune', target: '.cache/construct/.runtime/' });
   }
 
   const free = freeBytesAt(homedir());

package/lib/doctor/watchers/service-health.mjs

@@ -13,12 +13,12 @@
 
 import { spawnSync, spawn } from 'node:child_process';
 import { existsSync, readFileSync, openSync, mkdirSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { record } from '../audit.mjs';
 import { escalate } from '../escalate.mjs';
+import { configDir, stateDir, cacheDir } from '../../config/xdg.mjs';
 
 export const name = 'service-health';
 export const intervalMs = 60 * 1000;
@@ -56,7 +56,7 @@ function probeTcp(host, port, timeoutMs = 1500) {
 }
 
 function probeDashboardPort() {
-  const statePath = join(homedir(), '.construct', 'dashboard.json');
+  const statePath = join(stateDir(), 'dashboard.json');
   if (!existsSync(statePath)) return true;
   try {
     const state = JSON.parse(readFileSync(statePath, 'utf8'));
@@ -68,7 +68,7 @@ function probeDashboardPort() {
 }
 
 function probeMemoryHealth() {
-  const envPath = join(homedir(), '.construct', 'config.env');
+  const envPath = join(configDir(), 'config.env');
   if (!existsSync(envPath)) return true;
   try {
     const env = readFileSync(envPath, 'utf8');
@@ -87,7 +87,7 @@ function dockerRestart(container) {
 
 function detachSpawn(command, args, logName) {
   try {
-    const runtimeDir = join(homedir(), '.construct', '.runtime');
+    const runtimeDir = join(cacheDir(), '.runtime');
     if (!existsSync(runtimeDir)) mkdirSync(runtimeDir, { recursive: true });
     const logPath = join(runtimeDir, logName);
     const fd = openSync(logPath, 'a');
@@ -106,7 +106,7 @@ function respawnViaConstructUp() {
 }
 
 function respawnCm() {
-  const envPath = join(homedir(), '.construct', 'config.env');
+  const envPath = join(configDir(), 'config.env');
   let port = '4231';
   try {
     if (existsSync(envPath)) {

package/lib/document-export.mjs

@@ -5,7 +5,7 @@
  *
  * Export **source** is Construct-authored markdown (typed artifacts). **Output**
  * spans many distributable formats. Ingest (separate pipeline) accepts PDF, Office,
- * email, AV, and plain text — see docs/reference/document-io.md.
+ * email, AV, and plain text — see docs/guides/reference/document-io.md.
  */
 
 import fs from 'node:fs';
@@ -27,6 +27,7 @@ import {
 import { exportDeckPptx, pptxgenPresent } from './deck-export-pptx.mjs';
 import { pdfUsesBundledBrandSans } from './brand-fonts.mjs';
 import { convertDocxToDoc, libreOfficeInstallHint, libreOfficePresent, resolveLibreOfficeBin } from './libreoffice-export.mjs';
+import { resolveExportBranding } from './export-branding.mjs';
 
 export const EXPORT_FORMATS = ['pdf', 'docx', 'doc', 'deck', 'pptx', 'html', 'rtf', 'odt', 'epub', 'tex', 'txt', 'md', 'mdx'];
 
@@ -153,6 +154,7 @@ function installHint(name) {
   if (name === 'mmdc') return 'Install mermaid-cli for mermaid blocks (`npm install -g @mermaid-js/mermaid-cli`).';
   if (name === 'pptxgenjs') return 'Install pptxgenjs to enable PPTX export (`npm install pptxgenjs` in the Construct package).';
   if (name === 'construct-deck.html') return 'Bundled deck template missing from templates/distribution/construct-deck.html (Construct install integrity issue).';
+  if (name === 'construct-reference.docx') return 'Bundled branded reference doc missing from templates/distribution/construct-reference.docx; construct-branded DOCX export degrades to pandoc default styling. Regenerate from a source checkout with `node scripts/build-reference-docx.mjs`.';
   if (name === 'libreoffice') return libreOfficeInstallHint();
   return `Install ${name} to enable this export format.`;
 }
@@ -160,13 +162,17 @@ function installHint(name) {
 export function detect(format, env = process.env, {
   figures = false,
   artifactType = null,
+  branding = 'construct',
   cwd = process.cwd(),
   repoRoot = REPO_ROOT,
 } = {}) {
-  const config = FORMAT_ENGINES[format];
-  if (!config) return { ok: false, format, present: false, missing: [], message: `Unsupported format: ${format}. Supported: ${EXPORT_FORMATS.join(', ')}.` };
+  const brandingPolicy = resolveExportBranding(format, branding);
+  const config = format === 'pptx' && brandingPolicy.applied === 'plain'
+    ? { engine: 'pandoc', writer: 'pptx', pdfEngine: null, extraBinaries: [] }
+    : FORMAT_ENGINES[format];
+  if (!config) return { ok: false, format, branding: brandingPolicy, present: false, missing: [], message: `Unsupported format: ${format}. Supported: ${EXPORT_FORMATS.join(', ')}.` };
   if (config.engine === 'copy') {
-    return { ok: true, format, figures: false, present: true, binaries: [], missing: [], message: `Ready: source emit (${format})` };
+    return { ok: true, format, branding: brandingPolicy, figures: false, present: true, binaries: [], missing: [], message: `Ready: source emit (${format})` };
   }
   const required = [];
   if (config.engine === 'pptxgenjs') {
@@ -174,13 +180,19 @@ export function detect(format, env = process.env, {
   } else {
     required.push(config.engine, ...(config.extraBinaries || []));
   }
-  if (format === 'pdf') {
+  if (format === 'pdf' && brandingPolicy.applied === 'construct') {
     const template = detectPdfTemplate({ artifactType, cwd, repoRoot });
     if (!template.present) required.push('construct-pdf.typ');
   }
-  if (format === 'deck' && !deckTemplatePath(repoRoot)) {
+  if (format === 'deck' && brandingPolicy.applied === 'construct' && !deckTemplatePath(repoRoot)) {
     required.push('construct-deck.html');
   }
+  if (format === 'html' && brandingPolicy.applied === 'construct' && !htmlTemplatePath(repoRoot)) required.push('construct-web.html');
+
+  // The DOCX reference doc only restyles pandoc output; pandoc emits a valid file without it and
+  // the export passes --reference-doc only when present, so unlike the PDF/HTML/deck templates a
+  // missing reference degrades gracefully rather than blocking the export.
+
   if (format === 'doc' && !libreOfficePresent(env)) {
     required.push('libreoffice');
   }
@@ -193,9 +205,10 @@ export function detect(format, env = process.env, {
     if (name.endsWith('.lua')) {
       return { name, path: fs.existsSync(diagramFilterPath()) ? diagramFilterPath() : null, version: null };
     }
-    if (name.endsWith('.html')) {
+    if (name === 'construct-deck.html') {
       return { name, path: deckTemplatePath(repoRoot), version: null };
     }
+    if (name === 'construct-web.html') return { name, path: htmlTemplatePath(repoRoot), version: null };
     if (name === 'pptxgenjs') {
       return { name, path: pptxgenPresent() ? 'bundled' : null, version: null };
     }
@@ -213,6 +226,7 @@ export function detect(format, env = process.env, {
   return {
     ok: true,
     format,
+    branding: brandingPolicy,
     figures,
     present: missing.length === 0,
     binaries: status,
@@ -290,6 +304,7 @@ export function exportMarkdown({
   outputPath,
   format,
   figures = false,
+  branding = 'construct',
   artifactType = null,
   env = process.env,
   spawnFn = spawnSync,
@@ -304,21 +319,24 @@ export function exportMarkdown({
   const resolvedType = artifactType || metadata.artifactType || null;
   const effectiveEnv = figures ? buildDistributionDiagramEnv(env) : env;
 
-  const detection = detect(format, effectiveEnv, { figures, artifactType: resolvedType, cwd, repoRoot });
+  const brandingPolicy = resolveExportBranding(format, branding);
+  const detection = detect(format, effectiveEnv, { figures, artifactType: resolvedType, branding, cwd, repoRoot });
   if (!detection.present) {
     return { ok: false, format, inputPath, missing: detection.missing, message: detection.message };
   }
 
-  const config = FORMAT_ENGINES[format];
+  const config = format === 'pptx' && brandingPolicy.applied === 'plain'
+    ? { engine: 'pandoc', writer: 'pptx', pdfEngine: null, extraBinaries: [] }
+    : FORMAT_ENGINES[format];
   const target = path.resolve(outputPath || defaultOutputPath(inputPath, format));
   fs.mkdirSync(path.dirname(target), { recursive: true });
 
   if (config.engine === 'copy') {
-    return exportSourceCopy({ inputPath, target, format });
+    return { ...exportSourceCopy({ inputPath, target, format }), branding: brandingPolicy };
   }
 
-  if (format === 'pptx') {
-    return exportDeckPptx({ inputPath, outputPath: target, metadata, repoRoot });
+  if (format === 'pptx' && brandingPolicy.applied === 'construct') {
+    return { ...exportDeckPptx({ inputPath, outputPath: target, metadata, repoRoot }), branding: brandingPolicy };
   }
 
   if (format === 'doc') {
@@ -328,6 +346,7 @@ export function exportMarkdown({
       outputPath: intermediate,
       format: 'docx',
       figures,
+      branding,
       artifactType: resolvedType,
       env: effectiveEnv,
       spawnFn,
@@ -356,12 +375,13 @@ export function exportMarkdown({
       pdfEngine: null,
       figures,
       template: null,
+      branding: brandingPolicy,
       message: loResult.message,
     };
   }
 
   const prepared = prepareExportInput(inputPath, { format, figures, metadata });
-  const templatePath = format === 'pdf'
+  const templatePath = format === 'pdf' && brandingPolicy.applied === 'construct'
     ? resolvePdfTemplatePath({ artifactType: resolvedType, cwd, repoRoot })
     : null;
 
@@ -378,25 +398,26 @@ export function exportMarkdown({
   });
 
   const args = ['-f', 'markdown', '-o', target, '--standalone'];
+  if (config.writer) args.push('-t', config.writer);
   if (config.pdfEngine) args.push(`--pdf-engine=${config.pdfEngine}`);
   if (format === 'pdf') {
     if (templatePath) args.push('--template', templatePath);
-    args.push(...pdfEngineFontOpts(repoRoot));
+    if (brandingPolicy.applied === 'construct') args.push(...pdfEngineFontOpts(repoRoot));
     args.push(...metadataArgs);
   } else if (format === 'html') {
     const htmlTpl = htmlTemplatePath(repoRoot);
-    if (htmlTpl) args.push('--template', htmlTpl);
+    if (htmlTpl && brandingPolicy.applied === 'construct') args.push('--template', htmlTpl);
     args.push('--embed-resources');
     args.push(...metadataArgs);
   } else if (format === 'deck') {
     const deckTpl = deckTemplatePath(repoRoot);
-    if (deckTpl) args.push('--template', deckTpl);
+    if (deckTpl && brandingPolicy.applied === 'construct') args.push('--template', deckTpl);
     args.push('--section-divs');
     args.push('--embed-resources');
     args.push(...metadataArgs);
   } else if (format === 'docx') {
     const ref = docxReferencePath(repoRoot);
-    if (ref) args.push('--reference-doc', ref);
+    if (ref && brandingPolicy.applied === 'construct') args.push('--reference-doc', ref);
     args.push(...metadataArgs);
   }
   if (figures && fs.existsSync(diagramFilterPath())) {
@@ -443,6 +464,7 @@ export function exportMarkdown({
     pdfEngine: config.pdfEngine,
     figures,
     template: templatePath,
+    branding: brandingPolicy,
     message: `Wrote ${path.relative(process.cwd(), target)}`,
   };
 }

package/lib/document-extract.mjs

@@ -345,8 +345,8 @@ function extractPdf(filePath) {
   if (extracted.text.length < threshold) {
     const ocrHint = process.env.CONSTRUCT_PDF_OCR_HINT || 'none';
     const hintMsg = ocrHint !== 'none'
-      ? `OCR backend hint: ${ocrHint}. See docs/intake/scanned-pdfs.md.`
-      : 'Set CONSTRUCT_PDF_OCR_HINT=tesseract|pdfocr to enable OCR. See docs/intake/scanned-pdfs.md.';
+      ? `OCR backend hint: ${ocrHint}. See docs/guides/intake/scanned-pdfs.md.`
+      : 'Set CONSTRUCT_PDF_OCR_HINT=tesseract|pdfocr to enable OCR. See docs/guides/intake/scanned-pdfs.md.';
     extracted.droppedInfo.push(makeDropInfo({
       kind: 'scanned-pdf',
       count: pages,
@@ -692,7 +692,7 @@ export function extractDocumentText(filePath, { maxChars = null } = {}) {
   // Throw a typed error so callers can route to .cx/intake/needs-asr/.
   if (AUDIO_VIDEO_EXTS.has(extension)) {
     const err = new Error(
-      `Audio/video extraction requires ASR. Set CONSTRUCT_ASR_BACKEND=whisper|assemblyai to enable. See docs/intake/audio-video.md.`,
+      `Audio/video extraction requires ASR. Set CONSTRUCT_ASR_BACKEND=whisper|assemblyai to enable. See docs/guides/intake/audio-video.md.`,
     );
     err.code = 'ASR_REQUIRED';
     err.extension = extension;

package/lib/document-ingest.mjs

@@ -137,19 +137,29 @@ function collectInputFiles(inputPath, { maxDepth = 10 } = {}) {
   return files.sort((a, b) => a.localeCompare(b));
 }
 
+// Ingest writes a markdown rendering of the source, preserving the source name
+// for provenance (report.pdf → report.pdf.md). A source already in markdown keeps
+// its name unchanged so it never gains a second extension (_template.md →
+// _template.md, not _template.md.md).
+
+function markdownOutputName(sourcePath) {
+  const base = basename(sourcePath);
+  return /\.md$/i.test(base) ? base : `${base}.md`;
+}
+
 function resolveOutputPath(sourcePath, { cwd, outputPath, outputDir, target }) {
   if (outputPath) return normalizeOutputPath(outputPath, cwd);
   if (target === 'sibling') {
-    return join(dirname(sourcePath), `${basename(sourcePath)}.md`);
+    return join(dirname(sourcePath), markdownOutputName(sourcePath));
   }
   // knowledge/<subdir> targets land in .cx/knowledge/<subdir>/
   if (target.startsWith('knowledge/')) {
     const sub = target.slice('knowledge/'.length);
     const resolvedDir = normalizeOutputPath(`${KNOWLEDGE_ROOT}/${sub}`, cwd);
-    return join(resolvedDir, `${basename(sourcePath)}.md`);
+    return join(resolvedDir, markdownOutputName(sourcePath));
   }
   const resolvedDir = normalizeOutputPath(outputDir || DEFAULT_TARGET_DIR, cwd);
-  return join(resolvedDir, `${basename(sourcePath)}.md`);
+  return join(resolvedDir, markdownOutputName(sourcePath));
 }
 
 // The high-fidelity (docling) path provisions a Python venv and downloads ML

package/lib/efficiency.mjs

@@ -6,13 +6,14 @@
  */
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { doctorRoot } from './config/xdg.mjs';
 
 const HIGH_BYTES_THRESHOLD = 750_000;
 const HIGH_REPEATED_RATIO = 0.4;
 const HIGH_LARGE_READ_COUNT = 3;
 
 export function readEfficiencyLog(homeDir) {
-  const filePath = join(homeDir, '.cx', 'session-efficiency.json');
+  const filePath = join(doctorRoot(homeDir), 'session-efficiency.json');
   if (!existsSync(filePath)) return null;
   try {
     return JSON.parse(readFileSync(filePath, 'utf8'));

package/lib/embed/approval-queue.mjs

@@ -10,7 +10,8 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import os from 'node:os';
+
+import { doctorRoot } from '../config/xdg.mjs';
 
 export class ApprovalQueue {
   #items = new Map();   // id → ApprovalItem
@@ -171,6 +172,6 @@ export class ApprovalQueue {
   }
 
   static defaultPersistPath() {
-    return path.join(os.homedir(), '.cx', 'approval-queue.jsonl');
+    return path.join(doctorRoot(), 'approval-queue.jsonl');
   }
 }

package/lib/embed/auto-sources.mjs

@@ -0,0 +1,44 @@
+/**
+ * lib/embed/auto-sources.mjs — resolve embed auto-discovery sources from project config.
+ *
+ * When embed.yaml is absent, builds provider source records from typed
+ * construct.config.json targets merged with legacy env lists. Falls back
+ * to broad provider defaults only when no targets are configured.
+ */
+
+import { loadProjectConfig } from '../config/project-config.mjs';
+import {
+  resolveEffectiveSourceTargetsFromConfig,
+  targetsToEmbedSources,
+  legacyEnvSourceTargets,
+} from '../config/source-targets.mjs';
+
+export function resolveAutoEmbedSources({ cwd = process.cwd(), env = process.env, registry }) {
+  const { config } = loadProjectConfig(cwd, env);
+  const targets = resolveEffectiveSourceTargetsFromConfig(config, env);
+
+  if (targets.length === 0) {
+    return registry.autoSources(env);
+  }
+
+  const configuredProviders = new Set(targets.map((t) => t.provider));
+  const hasLegacyForUnconfigured = (provider) =>
+    legacyEnvSourceTargets(env).some((t) => t.provider === provider);
+
+  const sources = targetsToEmbedSources(targets);
+
+  for (const name of registry.names()) {
+    if (configuredProviders.has(name)) continue;
+    if (hasLegacyForUnconfigured(name)) continue;
+    const instance = registry.get(name);
+    if (typeof instance?.defaultSources !== 'function') continue;
+  }
+
+  const seen = new Set();
+  return sources.filter((s) => {
+    const key = `${s.provider}:${(s.refs ?? []).join(',')}:${JSON.stringify(s.repos ?? s.project ?? s.team ?? s.channels ?? '')}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}