@geraldmaron/construct 1.2.0 → 1.2.2

package/examples/distribution/sources/adr.md

@@ -51,7 +51,7 @@ tokens -> dash
 
 ## Decision
 
-Adopt `lib/brand-tokens.mjs` as the single source of truth for visual brand primitives. Document naming, voice, tone, and profile rebrand in `docs/reference/branding.md`. Enforce retired-font drift with `scripts/audit/03d-brand.mjs` in the audit ratchet.
+Adopt `lib/brand-tokens.mjs` as the single source of truth for visual brand primitives. Document naming, voice, tone, and profile rebrand in `docs/guides/reference/branding.md`. Enforce retired-font drift with `scripts/audit/03d-brand.mjs` in the audit ratchet.
 
 ## Rationale
 
@@ -79,6 +79,6 @@ Two-way door for documentation and audit scope; one-way for shipped PDFs already
 
 ## References
 
-- `docs/reference/branding.md`
+- `docs/guides/reference/branding.md`
 - `lib/brand-tokens.mjs`
 - https://fonts.google.com/specimen/Space+Grotesk (accessed 2026-06-22)

package/examples/distribution/sources/deck-one-pager.md

@@ -60,6 +60,6 @@ One token set across all distributable formats:
 
 - Export: `construct export … --to=pptx`
 - Regenerate: `npm run examples:deck`
-- Matrix: [Document I/O reference](/reference/document-io)
+- Matrix: [Document I/O reference](/guides/reference/document-io)
 
 Review outputs in `.tmp/distribution-examples/`.

package/examples/distribution/sources/prd-platform.md

@@ -157,5 +157,5 @@ https://langchain-ai.github.io/langgraph/ (accessed 2026-06-19).
 
 - Construct artifact manifest: `specialists/artifact-manifest.json`
 - PRD workflow skill: `skills/docs/prd-workflow.md`
-- Publish cookbook: `docs/cookbook/diagram-and-demo.md`
+- Publish cookbook: `docs/guides/cookbook/diagram-and-demo.md`
 - Golden D2 sources: `tests/fixtures/publish/diagrams/`

package/examples/distribution/sources/research-brief.md

@@ -32,7 +32,7 @@ Searched arXiv and vendor docs (2024–2026), reviewed three internal ADRs on in
 |---|---|---|---|---|---|---|---|
 | Multi-agent survey | secondary | B | 3 | 2023-08-01 | https://arxiv.org/abs/2308.08155 | yes | Patterns for specialist routing |
 | LangGraph overview | primary | A | 4 | 2025-01-15 | https://langchain-ai.github.io/langgraph/ | yes | Stateful agent graphs |
-| Construct architecture | primary | A | 5 | 2026-06-01 | docs/concepts/architecture.mdx | yes | Internal contract |
+| Construct architecture | primary | A | 5 | 2026-06-01 | docs/guides/concepts/architecture.mdx | yes | Internal contract |
 
 ## Findings
 
@@ -77,4 +77,4 @@ Ship distribution examples (`npm run examples:distribution`) so evaluators can c
 ## References
 
 - https://arxiv.org/abs/2308.08155 (accessed 2026-06-22)
-- `docs/cookbook/diagram-and-demo.md`
+- `docs/guides/cookbook/diagram-and-demo.md`

package/examples/distribution/sources/rfc-platform.md

@@ -78,5 +78,5 @@ sequenceDiagram
 
 ## References
 
-- `docs/reference/branding.md`
+- `docs/guides/reference/branding.md`
 - `scripts/generate-deck-examples.mjs` (prior art)

package/examples/distribution/sources/runbook.md

@@ -99,5 +99,5 @@ Preserve `construct tools detect --json` output and the failing pandoc/typst std
 
 ## References
 
-- `docs/reference/document-io.md`
-- `docs/cookbook/diagram-and-demo.md`
+- `docs/guides/reference/document-io.md`
+- `docs/guides/cookbook/diagram-and-demo.md`

package/examples/distribution/sources/strategy.md

@@ -26,7 +26,7 @@ Host-native agents optimize for single-session chat. Enterprise platform teams n
 ## Goals
 
 1. **Prove value in five minutes** — `npm run examples:distribution` produces a browsable gallery with figures.
-2. **One brand contract** — `docs/reference/branding.md` + `03d-brand` audit ratchet.
+2. **One brand contract** — `docs/guides/reference/branding.md` + `03d-brand` audit ratchet.
 3. **Profile-aware language** — intake queue labels follow active profile rebrand in CLI, session prelude, and dashboard API.
 
 ## Non-goals

package/lib/agent-instructions/inject.mjs

@@ -71,7 +71,7 @@ export function buildConstructIntegrationBody({ hasBeadsBlock = false, variant =
     '- **Durable state** lives in `.cx/` (context, knowledge, intake, traces) and Beads.',
     '  If services are down, resume from `plan.md`, `.cx/context.md`, the latest',
     '  `.cx/handoffs/` file, Beads, and git.',
-    '- **Signals**: drop a file into `.cx/inbox/`; `construct intake` classifies and routes it.',
+    '- **Signals**: drop a file into `inbox/`; `construct intake` classifies and routes it.',
     '- **Specialists** (architect, reviewer, security, …) are dispatched by Construct — you',
     '  do not call them directly.',
     tracker,

package/lib/artifact-manifest.mjs

@@ -14,6 +14,12 @@ import { fileURLToPath } from 'node:url';
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const EMPTY_MANIFEST = { version: 1, artifacts: {} };
 
+// Kept here, next to the manifest resolver, so every public workflow surface
+// uses one answer for what can carry Construct styling. Source formats remain
+// deliberately plain unless a caller explicitly asks otherwise.
+export const BRAND_CAPABLE_FORMATS = Object.freeze(['pdf', 'docx', 'doc', 'deck', 'pptx', 'html', 'rtf', 'odt', 'epub', 'tex']);
+export const PLAIN_OUTPUT_FORMATS = Object.freeze(['txt', 'md', 'mdx']);
+
 let cached = null;
 let cachedRoot = null;
 
@@ -60,6 +66,140 @@ export function artifactTypes(opts = {}) {
   return Object.keys(manifest.artifacts ?? {});
 }
 
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function mergeObjects(...values) {
+  const out = {};
+  for (const value of values) {
+    if (!isObject(value)) continue;
+    for (const [key, next] of Object.entries(value)) {
+      out[key] = isObject(next) && isObject(out[key]) ? mergeObjects(out[key], next) : structuredClone(next);
+    }
+  }
+  return out;
+}
+
+function unique(items) {
+  return [...new Set(items.filter(Boolean))];
+}
+
+/**
+ * Resolve a user-facing type or registered alias. The result intentionally
+ * distinguishes an unknown request from a fallback: callers must ask for
+ * classification/registration instead of silently turning it into a PRD.
+ */
+export function resolveArtifactType(type, opts = {}) {
+  const requestedType = String(type ?? '').trim().toLowerCase();
+  const manifest = loadArtifactManifest(opts);
+  if (!requestedType) {
+    return {
+      status: 'unrecognized',
+      requestedType: null,
+      type: null,
+      guidance: 'Specify a registered document class or register one in specialists/artifact-manifest.json.',
+    };
+  }
+  for (const [registeredType, entry] of Object.entries(manifest.artifacts ?? {})) {
+    const aliases = [registeredType, ...(entry.aliases ?? [])].map((value) => String(value).toLowerCase());
+    if (aliases.includes(requestedType)) {
+      return { status: 'registered', requestedType, type: registeredType, entry };
+    }
+  }
+  return {
+    status: 'unrecognized',
+    requestedType,
+    type: null,
+    guidance: `Document class '${requestedType}' is not registered. Classify the request or add it to specialists/artifact-manifest.json.`,
+  };
+}
+
+/**
+ * Resolve the canonical workflow contract for a registered document class.
+ * Precedence is deliberately explicit: invocation > project config > manifest
+ * defaults. Existing entries remain compatible: primaryOwners and releaseGate
+ * are the fallback author and reviewer/validation declarations.
+ */
+export function resolveArtifactWorkflowContract(type, {
+  rootDir,
+  cwd = process.cwd(),
+  projectConfig = null,
+  overrides = null,
+} = {}) {
+  const resolved = resolveArtifactType(type, { rootDir, cwd });
+  if (resolved.status !== 'registered') return resolved;
+
+  const manifest = loadArtifactManifest({ rootDir, cwd });
+  const entry = resolved.entry;
+  const config = projectConfig?.artifactWorkflow ?? {};
+  const manifestDefaults = manifest.workflowDefaults ?? {};
+  const projectType = config.types?.[resolved.type] ?? {};
+  const appliedOverrides = [];
+  if (isObject(config.defaults) && Object.keys(config.defaults).length) appliedOverrides.push('project.defaults');
+  if (isObject(projectType) && Object.keys(projectType).length) appliedOverrides.push(`project.types.${resolved.type}`);
+  if (isObject(overrides) && Object.keys(overrides).length) appliedOverrides.push('invocation');
+
+  const configured = mergeObjects(manifestDefaults, entry, config.defaults, projectType, overrides);
+  const releaseGate = configured.releaseGate ?? {};
+  const authorChain = unique(configured.authorChain ?? configured.primaryOwners ?? []);
+  const reviewerChain = unique(configured.reviewerChain ?? [
+    ...(releaseGate.requiredReviewers ?? []),
+    ...(releaseGate.optionalReviewers ?? []),
+  ]);
+  const outputs = mergeObjects({
+    formats: [...BRAND_CAPABLE_FORMATS, ...PLAIN_OUTPUT_FORMATS],
+    branding: 'construct',
+  }, configured.outputs);
+  const validation = mergeObjects({ releaseGate: true }, configured.validation);
+
+  return {
+    status: 'registered',
+    requestedType: resolved.requestedType,
+    type: resolved.type,
+    documentClass: configured.documentClass ?? resolved.type,
+    template: configured.template ?? null,
+    workflowSkill: configured.workflowSkill ?? null,
+    authorChain,
+    reviewerChain,
+    requiredReviewers: unique(releaseGate.requiredReviewers ?? []),
+    optionalReviewers: unique(releaseGate.optionalReviewers ?? []),
+    researchProfile: configured.researchProfile ?? null,
+    validation,
+    releaseGate,
+    outputs,
+    appliedOverrides,
+  };
+}
+
+/** A dependency-free validator used by startup checks and tests. */
+export function validateArtifactManifest(manifest) {
+  const errors = [];
+  if (!isObject(manifest)) return { valid: false, errors: ['root: must be an object'] };
+  if (!Number.isInteger(manifest.version) || manifest.version < 1) errors.push('version: must be an integer >= 1');
+  if (!isObject(manifest.artifacts)) errors.push('artifacts: must be an object');
+  for (const [type, entry] of Object.entries(manifest.artifacts ?? {})) {
+    const prefix = `artifacts.${type}`;
+    if (!isObject(entry)) { errors.push(`${prefix}: must be an object`); continue; }
+    if (typeof entry.template !== 'string' || !entry.template) errors.push(`${prefix}.template: required string missing`);
+    if (!Array.isArray(entry.primaryOwners) || entry.primaryOwners.some((owner) => typeof owner !== 'string')) {
+      errors.push(`${prefix}.primaryOwners: required string array missing`);
+    }
+    for (const field of ['authorChain', 'reviewerChain', 'aliases']) {
+      if (entry[field] !== undefined && (!Array.isArray(entry[field]) || entry[field].some((value) => typeof value !== 'string'))) {
+        errors.push(`${prefix}.${field}: must be an array of strings`);
+      }
+    }
+    if (entry.outputs?.formats !== undefined && (!Array.isArray(entry.outputs.formats) || entry.outputs.formats.length === 0)) {
+      errors.push(`${prefix}.outputs.formats: must be a non-empty array`);
+    }
+    if (entry.outputs?.branding !== undefined && !['construct', 'plain'].includes(entry.outputs.branding)) {
+      errors.push(`${prefix}.outputs.branding: must be construct or plain`);
+    }
+  }
+  return errors.length ? { valid: false, errors } : { valid: true, errors: [] };
+}
+
 export function structureRequirementsFromManifest(opts = {}) {
   const manifest = loadArtifactManifest(opts);
   const out = {};
@@ -97,16 +237,22 @@ export function resolveToneForArtifact(type, { cwd = process.cwd(), rootDir } =
 }
 
 export function templateMetadata(type, { cwd = process.cwd(), rootDir } = {}) {
-  const entry = getArtifactEntry(type, { rootDir, cwd });
-  if (!entry) return null;
+  const workflow = resolveArtifactWorkflowContract(type, { rootDir, cwd });
+  if (workflow.status !== 'registered') return null;
+  const entry = getArtifactEntry(workflow.type, { rootDir, cwd });
   return {
-    type,
-    tone: resolveToneForArtifact(type, { cwd, rootDir }),
+    type: workflow.type,
+    documentClass: workflow.documentClass,
+    tone: resolveToneForArtifact(workflow.type, { cwd, rootDir }),
     toneAllowed: entry.toneAllowed ?? [],
     structureRequirements: entry.structureRequirements ?? [],
     visualRequirements: entry.visualRequirements ?? [],
     primaryOwners: entry.primaryOwners ?? [],
     workflowSkill: entry.workflowSkill ?? null,
     releaseGate: entry.releaseGate ?? null,
+    authorChain: workflow.authorChain,
+    reviewerChain: workflow.reviewerChain,
+    validation: workflow.validation,
+    outputs: workflow.outputs,
   };
 }

package/lib/artifact-type-from-path.mjs

@@ -41,12 +41,16 @@ function inferRfcSubtype(rel, base) {
   return 'rfc';
 }
 
+// Match both this repo's bucketed layout (docs/specs/prd, docs/decisions/adr, …)
+// and the init-lane layout that `construct init` scaffolds downstream (docs/prd,
+// docs/adr, …), so artifact-type inference works in either project shape.
+
 const PREFIX_RULES = [
-  [/^docs\/prd\//, inferPrdSubtype],
-  [/^docs\/adr\//, () => 'adr'],
-  [/^docs\/rfc\//, inferRfcSubtype],
-  [/^docs\/research\//, () => 'research-brief'],
-  [/^docs\/runbooks?\//, () => 'runbook'],
+  [/^docs\/(?:specs\/)?prd\//, inferPrdSubtype],
+  [/^docs\/(?:decisions\/)?adr\//, () => 'adr'],
+  [/^docs\/(?:decisions\/)?rfc\//, inferRfcSubtype],
+  [/^docs\/(?:notes\/)?research\//, () => 'research-brief'],
+  [/^docs\/(?:operations\/)?runbooks?\//, () => 'runbook'],
   [/^\.cx\/research\//, () => 'research-brief'],
 ];
 

package/lib/artifact-workflow.mjs

@@ -0,0 +1,252 @@
+/**
+ * lib/artifact-workflow.mjs — intent-to-artifact workflow planning.
+ *
+ * Planning describes specialist work and manifest ordering without reporting a
+ * planned role as executed.
+ */
+
+import { existsSync } from 'node:fs';
+import { loadProjectConfig } from './config/project-config.mjs';
+import {
+  BRAND_CAPABLE_FORMATS,
+  artifactTypes,
+  resolveArtifactType,
+  resolveArtifactWorkflowContract,
+} from './artifact-manifest.mjs';
+import { inferArtifactTypeFromPath } from './artifact-type-from-path.mjs';
+import { validateArtifactRelease } from './artifact-release-gate.mjs';
+import { exportMarkdown } from './document-export.mjs';
+
+function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function findRequestedTypes(input, { rootDir, cwd }) {
+  const text = String(input ?? '').toLowerCase();
+  const matches = [];
+  for (const type of artifactTypes({ rootDir, cwd }).sort((a, b) => b.length - a.length)) {
+    const entry = resolveArtifactType(type, { rootDir, cwd }).entry;
+    for (const candidate of [type, ...(entry?.aliases ?? [])]) {
+      if (new RegExp(`(?:^|[^a-z0-9])${escapeRegex(candidate.toLowerCase())}(?:$|[^a-z0-9])`, 'i').test(text)) {
+        matches.push(type);
+        break;
+      }
+    }
+  }
+  return [...new Set(matches)];
+}
+
+function inferFormat(input, requestedFormat) {
+  if (requestedFormat) return String(requestedFormat).toLowerCase();
+  const text = String(input ?? '').toLowerCase();
+  for (const format of ['pptx', 'docx', 'pdf', 'deck', 'html', 'doc', 'rtf', 'odt', 'epub', 'tex', 'txt', 'mdx', 'md']) {
+    if (new RegExp(`\\b${format}\\b`, 'i').test(text)) return format;
+  }
+  return null;
+}
+
+function inferBranding(input, requestedBranding) {
+  if (requestedBranding) return requestedBranding;
+  return /\b(?:unbranded|plain|without (?:the )?construct brand)\b/i.test(String(input ?? '')) ? 'plain' : 'construct';
+}
+
+function buildSteps({ contract, input, targetFormat, branding }) {
+  const text = String(input ?? '').toLowerCase();
+  const needsResearch = Boolean(contract.researchProfile) && /\b(?:research|source|evidence|validate claims)\b/.test(text);
+  const needsReview = /\b(?:review|critique|audit|feedback)\b/.test(text) || contract.requiredReviewers.length > 0;
+  const rewrite = /\b(?:rewrite|revise|edit|polish|improve)\b/.test(text);
+  const steps = [];
+  if (needsResearch) steps.push({ id: 'research', action: 'research', roles: [], required: false, reason: `research profile: ${contract.researchProfile}` });
+  if (needsReview) steps.push({ id: 'review', action: 'review', roles: contract.reviewerChain, required: contract.requiredReviewers.length > 0, reason: 'review occurs before any rewrite' });
+  steps.push({
+    id: rewrite ? 'rewrite' : 'author',
+    action: rewrite ? 'rewrite' : 'author',
+    roles: contract.authorChain,
+    required: true,
+    reason: rewrite ? 'requested revision after review' : 'manifest author chain',
+  });
+  if (contract.validation.releaseGate !== false) {
+    steps.push({ id: 'validate', action: 'validate', roles: [], required: true, reason: 'manifest validation policy' });
+  }
+  if (targetFormat && BRAND_CAPABLE_FORMATS.includes(targetFormat) && branding === 'construct') {
+    steps.push({ id: 'brand', action: 'brand', roles: [], required: true, reason: 'default Construct branding for brand-capable format' });
+  }
+  if (targetFormat) steps.push({ id: 'export', action: 'export', roles: [], required: true, format: targetFormat, reason: 'requested distribution format' });
+  return steps;
+}
+
+/**
+ * Build an artifact plan from an ordinary request. A missing or ambiguous
+ * class is a clarification result, never an implicit PRD route.
+ */
+export function planArtifactWorkflow(request = {}, { cwd = process.cwd(), rootDir } = {}) {
+  const input = request.input ?? request.request ?? '';
+  const sourcePath = request.sourcePath ?? request.filePath ?? '';
+  const project = request.projectConfig ?? loadProjectConfig(cwd).config;
+  const requested = request.artifactType ?? request.documentClass ?? null;
+  const pathType = sourcePath && existsSync(sourcePath) ? inferArtifactTypeFromPath(sourcePath, { rootDir: cwd }) : null;
+  const inferredTypes = requested ? [] : findRequestedTypes(input, { rootDir, cwd });
+  const candidates = requested ? [requested] : [...new Set([pathType, ...inferredTypes].filter(Boolean))];
+
+  if (candidates.length !== 1) {
+    return {
+      kind: 'artifact-workflow',
+      status: 'needs-classification',
+      plannedSteps: [],
+      executedSteps: [],
+      skippedSteps: [],
+      producedFiles: [],
+      validation: null,
+      appliedOverrides: [],
+      clarification: candidates.length > 1
+        ? `Request names multiple document classes (${candidates.join(', ')}). Specify one registered class.`
+        : 'Specify a registered document class, use a typed source path, or register the requested class in specialists/artifact-manifest.json.',
+    };
+  }
+
+  const resolution = resolveArtifactType(candidates[0], { rootDir, cwd });
+  if (resolution.status !== 'registered') {
+    return {
+      kind: 'artifact-workflow',
+      status: 'needs-classification',
+      plannedSteps: [],
+      executedSteps: [],
+      skippedSteps: [],
+      producedFiles: [],
+      validation: null,
+      appliedOverrides: [],
+      clarification: resolution.guidance,
+    };
+  }
+
+  const targetFormat = inferFormat(input, request.format ?? request.targetFormat);
+  const requestedBranding = inferBranding(input, request.branding);
+  const contract = resolveArtifactWorkflowContract(resolution.type, {
+    rootDir,
+    cwd,
+    projectConfig: project,
+    overrides: request.overrides,
+  });
+  const branding = request.branding ?? (requestedBranding === 'plain' ? 'plain' : (contract.outputs.branding ?? 'construct'));
+  const steps = buildSteps({ contract, input, targetFormat, branding });
+  const unavailableFormat = targetFormat && !contract.outputs.formats.includes(targetFormat);
+
+  return {
+    kind: 'artifact-workflow',
+    status: unavailableFormat ? 'needs-classification' : 'planned',
+    documentClass: contract.documentClass,
+    artifactType: contract.type,
+    sourcePath: sourcePath || null,
+    target: {
+      format: targetFormat,
+      audience: /\bcustomer(?:-facing)?\b/i.test(input) ? 'customer' : 'internal',
+      branding,
+      brandCapable: Boolean(targetFormat && BRAND_CAPABLE_FORMATS.includes(targetFormat)),
+    },
+    contract,
+    plannedSteps: steps,
+    executedSteps: [],
+    skippedSteps: [],
+    producedFiles: [],
+    validation: null,
+    appliedOverrides: contract.appliedOverrides,
+    clarification: unavailableFormat ? `${targetFormat} is not an output capability for ${contract.type}.` : null,
+  };
+}
+
+/**
+ * Produce a provenance-preserving workflow run report. Specialist authoring
+ * and review are never fabricated: Construct can plan them, but only reports
+ * them as executed when a host returns execution evidence (not available in
+ * the deterministic entry point). Validation/export are local operations and
+ * run only with the explicit durable-write approval mode.
+ */
+export function runArtifactWorkflow(request = {}, { cwd = process.cwd(), rootDir } = {}) {
+  const plan = planArtifactWorkflow(request, { cwd, rootDir });
+  const approvalMode = request.approvalMode ?? 'proposal-only';
+  const report = {
+    reportVersion: 1,
+    kind: 'artifact-workflow-run',
+    status: plan.status === 'planned' ? 'planned' : plan.status,
+    approval: {
+      mode: approvalMode,
+      durableWriteAllowed: approvalMode === 'allow-durable-write',
+    },
+    plan,
+    plannedSteps: plan.plannedSteps,
+    executedSteps: [],
+    skippedSteps: [],
+    producedFiles: [],
+    validation: null,
+    appliedOverrides: plan.appliedOverrides,
+  };
+  if (plan.status !== 'planned') return report;
+
+  const pendingReason = approvalMode === 'allow-durable-write'
+    ? 'specialist execution is host-owned; this local command has no specialist execution evidence'
+    : `approval mode '${approvalMode}' permits planning only`;
+  for (const step of plan.plannedSteps) {
+    if (['review', 'rewrite', 'author', 'research'].includes(step.action)) {
+      report.skippedSteps.push({ id: step.id, reason: pendingReason });
+    }
+  }
+  if (approvalMode !== 'allow-durable-write') {
+    for (const step of plan.plannedSteps) {
+      if (!['review', 'rewrite', 'author', 'research'].includes(step.action)) {
+        report.skippedSteps.push({ id: step.id, reason: pendingReason });
+      }
+    }
+    return report;
+  }
+
+  const sourcePath = plan.sourcePath;
+  for (const step of plan.plannedSteps) {
+    if (step.action === 'validate') {
+      if (!sourcePath) {
+        report.skippedSteps.push({ id: step.id, reason: 'validation needs sourcePath or filePath' });
+      } else {
+        const result = validateArtifactRelease({ filePath: sourcePath, type: plan.artifactType, cwd, rootDir });
+        report.validation = result;
+        report.executedSteps.push({ id: step.id, result: result.ok ? 'passed' : 'failed' });
+        if (!result.ok) {
+          report.status = 'validation-failed';
+          return report;
+        }
+      }
+    }
+    if (step.action === 'brand') {
+      // Branding is applied by the export operation. Keeping this pending until
+      // output exists avoids claiming a template was applied when no export ran.
+      report.skippedSteps.push({ id: step.id, reason: 'branding is evidenced by the export result' });
+    }
+    if (step.action === 'export') {
+      if (!sourcePath) {
+        report.skippedSteps.push({ id: step.id, reason: 'export needs sourcePath or filePath' });
+      } else {
+        const result = exportMarkdown({
+          inputPath: sourcePath,
+          outputPath: request.outputPath,
+          format: step.format,
+          artifactType: plan.artifactType,
+          branding: plan.target.branding,
+          cwd,
+          rootDir,
+        });
+        if (!result.ok) {
+          report.status = 'export-failed';
+          report.skippedSteps.push({ id: step.id, reason: result.message });
+          return report;
+        }
+        report.executedSteps.push({ id: step.id, result: 'produced', format: step.format });
+        report.producedFiles.push({ path: result.outputPath, format: step.format, branding: result.branding });
+        const brandStep = report.skippedSteps.findIndex((entry) => entry.id === 'brand');
+        if (brandStep >= 0 && result.branding?.applied === 'construct') {
+          report.skippedSteps.splice(brandStep, 1);
+          report.executedSteps.push({ id: 'brand', result: 'applied', mechanism: result.branding.mechanism });
+        }
+      }
+    }
+  }
+  report.status = report.executedSteps.length ? 'completed-local-steps' : 'planned';
+  return report;
+}

package/lib/audit-specialists.mjs

@@ -3,7 +3,7 @@
  *
  * Merges live registry, contracts, skills, prompts, and audit-enrichments into
  * one machine-readable matrix. Powers `construct audit specialists` and the
- * human-readable docs/concepts/specialist-skill-audit.md companion.
+ * human-readable docs/guides/concepts/specialist-skill-audit.md companion.
  */
 
 import fs from 'node:fs';

package/lib/audit-trail.mjs

@@ -16,17 +16,17 @@
  * Corrupted links cannot be re-derived, so a `chain_reset` boundary line seals
  * the damaged prefix as immutable legacy and re-bases the live chain;
  * verifyChain validates only from the last boundary forward. See
- * docs/concepts/observability.md.
+ * docs/guides/concepts/observability.md.
  */
 import { readFileSync, existsSync, statSync, mkdirSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { join, dirname } from 'node:path';
-import { homedir } from 'node:os';
 
 import { appendBounded, readLastLineAcrossSegments } from './logging/rotate.mjs';
 import { withFileLockSync } from './storage/file-lock.mjs';
+import { doctorRoot } from './config/xdg.mjs';
 
-const AUDIT_FILE = join(homedir(), '.cx', 'audit-trail.jsonl');
+const AUDIT_FILE = join(doctorRoot(), 'audit-trail.jsonl');
 
 function sha256(input) {
   return createHash('sha256').update(input).digest('hex');