@geraldmaron/construct 1.1.0 → 1.2.0

package/scripts/sync-specialists.mjs

@@ -13,8 +13,8 @@
  *       global so hooks fire in every Claude Code session.
  *
  *   Project scope (`<project>/.claude/`, `<project>/.codex/`, `<project>/.github/`, …)
- *     - `construct` + all 28 `cx-*` specialists, slash commands, skills, MCP
- *       wiring. Files version with the repo and travel with teammates via git.
+ *     - `construct` front door only (Single Front Door), slash commands, skills, MCP
+ *       wiring. Specialists dispatch internally via orchestration MCP tools.
  *
  * Flags:
  *   --dry-run             Print a diff of what would change without writing anything.
@@ -44,9 +44,11 @@ import {
   writeCodexConfig,
 } from "../lib/codex-config.mjs";
 import { findOpenCodeConfigPath, readOpenCodeConfig, writeOpenCodeConfig } from "../lib/opencode-config.mjs";
-import { HEAVY_EXTERNAL_MCP_IDS, LOCAL_SURFACE_MODES, decideTrim } from "../lib/mcp/tool-budget.mjs";
+import { HEAVY_EXTERNAL_MCP_IDS, LOCAL_SURFACE_MODES, decideTrim, isLocalModel } from "../lib/mcp/tool-budget.mjs";
 import { emitCursorRules } from "../lib/rules-delivery.mjs";
-import { resolvePromptContract } from "../lib/prompt-composer.js";
+import { resolvePromptContract, readPromptBody } from "../lib/prompt-composer.js";
+import { renderPersonaForTier } from "../lib/persona-sections.mjs";
+import { getModelVerdict } from "../lib/ollama/capability-store.mjs";
 import {
   buildClaudeMcpEntry,
   buildOpenCodeMcpEntry,
@@ -54,9 +56,10 @@ import {
 } from "../lib/mcp-platform-config.mjs";
 import { loadConstructEnv } from "../lib/env-config.mjs";
 import { inlineRoleAntiPatterns, PROMPT_WORD_CAP } from "../lib/role-preload.mjs";
+import { inlineValidationContract } from "../lib/prompt-validation-contract.mjs";
 import { loadManifest } from "../lib/roles/manifest.mjs";
 import { resolveActiveProfile } from "../lib/profiles/loader.mjs";
-import { resolveTiersForPrimary } from "../lib/model-router.mjs";
+import { resolveTiersForPrimary, resolveCapabilityTier, selectLocalEditorModel } from "../lib/model-router.mjs";
 import { stampFrontmatter } from "../lib/doc-stamp.mjs";
 import { buildSkillFrontmatter, stripLeadingFrontmatter } from "../lib/sync/skill-frontmatter.mjs";
 
@@ -152,6 +155,16 @@ if (validationErrors.length > 0) {
   }
 }
 
+{
+  const { validatePromptFiles } = await import("../lib/specialists/prompt-schema.mjs");
+  const promptResult = validatePromptFiles({ rootDir: root, registry });
+  if (promptResult.errors.length > 0) {
+    console.error("Specialist prompt validation failed:");
+    for (const err of promptResult.errors) console.error(`  - ${err}`);
+    process.exit(1);
+  }
+}
+
 // --- Dry-run + lockfile + two-phase write infrastructure ---
 
 const DRY_RUN = process.argv.includes("--dry-run");
@@ -516,10 +529,6 @@ function loadPersonaPrompt(persona) {
   return prompt;
 }
 
-export function buildAgentRoster(allEntries) {
-  return allEntries.map((e) => `- ${adapterName(e)}: ${e.when_to_use || e.description}`).join("\n");
-}
-
 function buildModelGuidanceBlock(entry) {
   const merged = { ...globalModelGuidance, ...(entry.modelGuidance ?? {}) };
   const families = Object.keys(merged);
@@ -602,7 +611,83 @@ export function renderRoleFrameworkSection(entry) {
   return `\n\n${lines.join("\n")}`;
 }
 
-function buildPrompt(entry, allEntries, platform) {
+// The native-subagent orchestration micro-prompt. A worked tool-call example lifts
+// small local models' tool-use reliability sharply (bead construct-c16l). Shared by the
+// full path and the capability-tiered local path so both stay in sync.
+
+const ORCHESTRATION_MICRO_PROMPT =
+  `You are the primary orchestrator. To discover available specialist agents, you MUST call the \`orchestration_policy\` MCP tool. Do not guess agent names.\n\n` +
+  `Example — the user says "add rate limiting to the API". Your first action is a tool call, not prose:\n` +
+  `  call orchestration_policy { "task": "add rate limiting to the API" }\n` +
+  `Then dispatch the specialists it returns. Always call the tool before answering.`;
+
+// Directive for the local editor agent (construct-local). It executes bounded work on
+// the cheap local model and hands planning/reasoning back to the construct architect —
+// the aider architect/editor split. Kept short: a small model must actually obey it.
+
+const LOCAL_EDITOR_DIRECTIVE =
+  `You are a focused execution agent running on a local model, dispatched by construct to do one bounded job. Do well-scoped edits for the current task and verify them; make the smallest correct change, never a broad rewrite.\n` +
+  `You do NOT plan, classify, orchestrate, or spawn other agents. For anything needing multi-file design, architecture or security judgment, dependency or contract changes, or research, STOP and return control to construct — report what needs deeper work and why, rather than attempting it yourself.`;
+
+// Warn-and-emit capability advisory. Sizing already consumes the probe verdict
+// (COLLAPSED → floor tier via resolveCapabilityTier); this only nudges the user toward a
+// measured verdict and never suppresses emission. Notice-only, so it auto-suppresses in
+// CI / test / non-TTY per the repo's wrong-context rule — no skip env var.
+
+const localAdvisorySeen = new Set();
+function adviseLocalModelCapability(model) {
+  if (!model || !isLocalModel(model)) return;
+  if (process.env.CI === "true" || process.env.NODE_ENV === "test" || !process.stderr.isTTY) return;
+  if (localAdvisorySeen.has(model)) return;
+  localAdvisorySeen.add(model);
+  const verdict = getModelVerdict(model)?.verdict ?? null;
+  if (verdict === "COLLAPSED") {
+    console.warn(`[sync] ${model} probed COLLAPSED — emitting at the floor tier with escalation to construct. Re-probe after a Modelfile change: construct doctor --probe-local`);
+  } else if (!verdict) {
+    console.warn(`[sync] ${model} is local with no coherence verdict — tier inferred from parameter count. For a measured tier: construct doctor --probe-local`);
+  }
+}
+
+function enforcePromptWordCap(prompt, entry) {
+  const wordCount = prompt.split(/\s+/).filter(Boolean).length;
+  const effectiveCap = Number(entry.wordCapOverride) > 0 ? entry.wordCapOverride : PROMPT_WORD_CAP;
+  if (wordCount > effectiveCap) {
+    const msg = `[sync] ${entry.name}: prompt is ${wordCount} words (cap ${effectiveCap})`;
+    if (process.env.CONSTRUCT_SYNC_FORCE === '1' || process.argv.includes('--force')) {
+      console.warn(`${msg} — proceeding due to --force / CONSTRUCT_SYNC_FORCE=1.`);
+    } else {
+      console.error(`${msg}`);
+      console.error(
+        `[sync] Hard cap exceeded. Options:\n` +
+        `   - trim the prompt body or move detail to a skill (preferred)\n` +
+        `   - set "wordCapOverride": <N> on this entry in specialists/registry.json with a written reason\n` +
+        `   - re-run with --force or CONSTRUCT_SYNC_FORCE=1 as a temporary escape hatch\n` +
+        `Prompt budget is a hard contract because every over-cap agent degrades every session that dispatches it.`,
+      );
+      process.exit(1);
+    }
+  }
+  return prompt;
+}
+
+function buildPrompt(entry, allEntries, platform, { capabilityTier = 'full' } = {}) {
+  const capabilities = { hasNativeSubagents: HOST_KEYS.includes(platform) ? hostHasNativeSubagents(platform) : false };
+
+  // Capability-tiered local path. A small local model follows a long multi-instruction
+  // persona poorly (instruction-following degrades before the window fills), so emit
+  // only the persona sections at/below its tier plus the orchestration micro-prompt, and
+  // skip the role footer, role-framework, operating-guidance, and model-family blocks —
+  // those add instruction load the model cannot track. Cloud models resolve to 'full'
+  // and take the unchanged path below, so cloud configs are never slimmed.
+
+  if (capabilityTier && capabilityTier !== 'full' && entry.promptFile) {
+    let slim = renderPersonaForTier(readPromptBody(entry.promptFile, root), capabilityTier);
+    if (entry.injectAgentRoster) {
+      slim = `${ORCHESTRATION_MICRO_PROMPT}\n\n${slim}`;
+    }
+    return enforcePromptWordCap(slim, entry);
+  }
+
   let prompt = resolvePromptContract(entry, {
     rootDir: root,
     registry,
@@ -610,29 +695,18 @@ function buildPrompt(entry, allEntries, platform) {
   }).prompt;
 
   prompt = inlineRoleAntiPatterns(prompt, root, entry.name, console.warn, { preload: entry.preloadRoleGuidance === true });
+  prompt = inlineValidationContract(prompt, root, entry.name);
 
-  const capabilities = { hasNativeSubagents: HOST_KEYS.includes(platform) ? hostHasNativeSubagents(platform) : false };
-
-  // Platform-Native Orchestration Alignment (ADR-0002). Hosts with native subagent
-  // routing (OpenCode, VS Code, Cursor) do not get the static specialist roster
-  // injected — on a small-context local model the roster alone is ~3-4k tokens and,
-  // combined with MCP tool schemas, overruns the model's real context window and
-  // collapses output. Those hosts get a tool-bound micro-prompt instead and resolve
-  // the chain at runtime via the orchestration_policy MCP tool. Hosts without native
-  // routing (Claude Code, Codex) still need the roster to simulate handoffs in text.
+  // Platform-Native Orchestration Alignment (ADR-0002). All hosts receive the
+  // tool-bound micro-prompt when injectAgentRoster is set; the static 29-line
+  // roster was removed (construct-ymp5). Specialists resolve at runtime via
+  // orchestration_policy, which returns a lazy specialistCatalog.
 
-  if (entry.injectAgentRoster && allEntries && !capabilities.hasNativeSubagents) {
-    const roster = buildAgentRoster(allEntries);
-    prompt = `Available specialist agents:\n${roster}\n\n${prompt}`;
-  } else if (entry.injectAgentRoster && capabilities.hasNativeSubagents) {
-    // A worked tool-call example lifts small local models' tool-use reliability
-    // sharply (bead construct-c16l). Keep it to one compact turn so it stays within
-    // the prompt word cap; native-subagent hosts are exactly where local models run.
+  // Single Front Door: all hosts resolve specialists at runtime via
+  // orchestration_policy / orchestration_run — never inject the static roster.
 
-    prompt = `You are the primary orchestrator. To discover available specialist agents, you MUST call the \`orchestration_policy\` MCP tool. Do not guess agent names.\n\n` +
-      `Example — the user says "add rate limiting to the API". Your first action is a tool call, not prose:\n` +
-      `  call orchestration_policy { "task": "add rate limiting to the API" }\n` +
-      `Then dispatch the specialists it returns. Always call the tool before answering.\n\n${prompt}`;
+  if (entry.injectAgentRoster) {
+    prompt = `${ORCHESTRATION_MICRO_PROMPT}\n\n${prompt}`;
   }
 
   prompt += buildRoleFooter(entry);
@@ -648,26 +722,7 @@ function buildPrompt(entry, allEntries, platform) {
 
   prompt += buildModelGuidanceBlock(entry);
 
-  const wordCount = prompt.split(/\s+/).filter(Boolean).length;
-  const effectiveCap = Number(entry.wordCapOverride) > 0 ? entry.wordCapOverride : PROMPT_WORD_CAP;
-  if (wordCount > effectiveCap) {
-    const msg = `[sync] ${entry.name}: prompt is ${wordCount} words (cap ${effectiveCap})`;
-    if (process.env.CONSTRUCT_SYNC_FORCE === '1' || process.argv.includes('--force')) {
-      console.warn(`${msg} — proceeding due to --force / CONSTRUCT_SYNC_FORCE=1.`);
-    } else {
-      console.error(`${msg}`);
-      console.error(
-        `[sync] Hard cap exceeded. Options:\n` +
-        `   - trim the prompt body or move detail to a skill (preferred)\n` +
-        `   - set "wordCapOverride": <N> on this entry in specialists/registry.json with a written reason\n` +
-        `   - re-run with --force or CONSTRUCT_SYNC_FORCE=1 as a temporary escape hatch\n` +
-        `Prompt budget is a hard contract because every over-cap agent degrades every session that dispatches it.`,
-      );
-      process.exit(1);
-    }
-  }
-
-  return prompt;
+  return enforcePromptWordCap(prompt, entry);
 }
 
 function escapeRegExp(value) { return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); }
@@ -1382,12 +1437,10 @@ function syncCursor(targetDir = null, wants = true) {
 
   if (targetDir) {
     const rulesPath = path.join(targetDir, ".cursor", "rules", "construct.mdc");
-    if (!fs.existsSync(rulesPath)) {
-      const body = `---\ndescription: Construct front-door — invoke \`construct\` for orchestration\nalwaysApply: false\n---\n\nThis project uses Construct (\`@geraldmaron/construct\`) as the single agent\nentry point. Route work through the \`construct\` persona; specialists are\ninternal and dispatched by Construct itself.\n\nSee \`.claude/agents/\` for the registered agents in this project.\n`;
-      if (!DRY_RUN) {
-        mkdirp(path.dirname(rulesPath));
-        fs.writeFileSync(rulesPath, body);
-      }
+    const body = `---\ndescription: Construct front-door — invoke \`construct\` for orchestration\nalwaysApply: false\n---\n\n<!-- Generated by construct sync — do not edit; re-run \`construct sync\` -->\n\nThis project uses Construct (\`@geraldmaron/construct\`) as the single agent\nentry point. Route work through the \`construct\` persona; specialists are\ninternal and dispatched via MCP \`orchestration_run\` (start \`construct dashboard\`).\n\nSkills load via MCP \`get_skill\`; see \`.claude/skills/\` for synced playbooks.\n`;
+    if (!DRY_RUN) {
+      mkdirp(path.dirname(rulesPath));
+      fs.writeFileSync(rulesPath, body);
     }
 
     // Glob-scoped language rules land as managed per-rule .mdc files only when
@@ -1596,7 +1649,8 @@ function syncOpencode(entries, targetDir = null, wants = true) {
       }
     }
 
-    // Heavy external MCP servers serialize ~12k tokens of schema into EVERY
+    // Heavy external MCP servers serialize a measured ~37k tokens of tool schema
+    // into EVERY agent's request — github ~30k alone (fixtures 2026-06-22) —
     // agent's request — including the built-in Build/Plan agents the per-agent
     // permission prune cannot reach. OpenCode 1.15.4 has no per-session tool
     // filter (chat.params carries no tool list), so disabling the whole server in
@@ -1638,6 +1692,20 @@ function syncOpencode(entries, targetDir = null, wants = true) {
   }
 
   // Write agents — no model/modelFallback set; agents inherit the global model.
+  //
+  // Capability tier for the orchestrator prompt. Keyed ONLY to an EXPLICIT local default
+  // model — that is a clear intent signal we can size against at sync time. With no
+  // explicit default (the orchestrator runs whatever model the user picks at runtime) or
+  // a cloud default, resolveCapabilityTier returns 'full', so cloud configs and unknown
+  // selections are never slimmed. Per-model slimming of a known pinned model lands on the
+  // construct-local editor agent.
+
+  const orchestratorDefaultModel = config.model || config.defaultModel || "";
+  adviseLocalModelCapability(orchestratorDefaultModel);
+  const orchestratorTier = resolveCapabilityTier({
+    model: orchestratorDefaultModel,
+    verdict: orchestratorDefaultModel ? (getModelVerdict(orchestratorDefaultModel)?.verdict ?? null) : null,
+  });
 
   for (const entry of writeEntries) {
     const name = adapterName(entry);
@@ -1647,7 +1715,9 @@ function syncOpencode(entries, targetDir = null, wants = true) {
         ? `${entry.role} — ${entry.description}`
         : entry.description,
       mode: entry.isOrchestrator ? "all" : "subagent",
-      prompt: buildPrompt(entry, entries, "opencode"),
+      prompt: buildPrompt(entry, entries, "opencode", {
+        capabilityTier: entry.isOrchestrator ? orchestratorTier : "full",
+      }),
       permission: {
         ...perms,
         task: opencodeTaskPermissions(entry),
@@ -1655,18 +1725,75 @@ function syncOpencode(entries, targetDir = null, wants = true) {
     };
   }
 
+  // Hybrid split (aider architect/editor). When the fast tier is a LOCAL model, emit a
+  // narrow `construct-local` editor: it does bounded edits on a cheap local model and hands
+  // planning/reasoning back to `construct` (the architect, which stays on the user's chosen
+  // model — we never pin it). The editor's model is NOT the generic fast-tier default
+  // (which for an Ollama family resolves to a non-code generalist); it is the best-installed
+  // CODE model from this config's DECLARED local inventory (OpenCode only uses declared
+  // models), excluding probe-COLLAPSED ones, with the fast tier as a last resort. Its prompt
+  // is sized to the chosen model's capability tier. Deterministic name, so manage it
+  // explicitly: emit when fast is local, delete otherwise, so switching to cloud cleans up.
+
+  const orchestratorEntry = writeEntries.find((e) => e.isOrchestrator) || registry.orchestrator;
+  const orchestratorName = orchestratorEntry ? adapterName(orchestratorEntry) : "construct";
+  const localEditorName = `${orchestratorName}-local`;
+  if (orchestratorEntry?.promptFile && isLocalModel(resolvedModels.fast)) {
+    const declaredLocal = Object.entries(config.provider || {})
+      .flatMap(([pid, pv]) => Object.keys(pv?.models || {}).map((mk) => `${pid}/${mk}`))
+      .filter((id) => isLocalModel(id) && getModelVerdict(id)?.verdict !== "COLLAPSED");
+    const editorModel = selectLocalEditorModel(declaredLocal) || resolvedModels.fast;
+    adviseLocalModelCapability(editorModel);
+    const editorVerdict = getModelVerdict(editorModel)?.verdict ?? null;
+    const editorTier = resolveCapabilityTier({ model: editorModel, verdict: editorVerdict });
+    const editorBody = renderPersonaForTier(readPromptBody(orchestratorEntry.promptFile, root), editorTier);
+    config.agent[localEditorName] = {
+      description: "Local execution agent — bounded edits on the local model; escalates planning and reasoning to construct.",
+      mode: "subagent",
+      model: editorModel,
+      prompt: `${LOCAL_EDITOR_DIRECTIVE}\n\n${editorBody}`,
+      permission: {
+        edit: "allow",
+        bash: { "*": "allow", "rm -rf *": "deny", "git push *": "ask", "git push --force*": "ask", "git reset --hard *": "ask" },
+        "mcp__construct-mcp__orchestration_policy": "deny",
+        "mcp__construct-mcp__agent_contract": "deny",
+        "mcp__construct-mcp__broker_check": "deny",
+        "mcp__github__*": "deny",
+        "mcp__context7__*": "deny",
+        "mcp__sequential-thinking__*": "deny",
+        "mcp__memory__*": "deny",
+        // OpenCode 1.15.4 disables the `task` tool entirely for any restrictive task map
+        // (verified in a sterile run). For an editor that is exactly right: it spawns no
+        // subagents and escalates by RETURNING to the construct agent that dispatched it,
+        // not by dispatching. Deny-all states that intent directly.
+        task: { "*": "deny" },
+      },
+    };
+  } else {
+    delete config.agent[localEditorName];
+  }
+
   // Pass current Construct model tiers to OpenCode config for native routing.
   config.construct = config.construct || {};
   config.construct.models = { ...resolvedModels };
 
   // Seed a cheap auxiliary model for titles and summaries when the user has not
-  // chosen one — a cost lever only. The primary `model` stays the user's choice
-  // and is never written. Global scope only; project configs inherit it.
+  // chosen one — a cost lever only. Global scope only; project configs inherit it.
 
   if (!targetDir && config.small_model === undefined) {
     config.small_model = resolvedModels.fast || "anthropic/claude-haiku-4-5-20251001";
   }
 
+  // Seed a text-capable primary model when the user has not pinned one, so chat
+  // and routing never fall through to a host provider-default that happens to be
+  // an image/non-text model. Seeds only when absent; an explicit user choice is
+  // never overwritten. resolvedModels.standard is family-/registry-aware and
+  // free-biased. Global scope only; project configs inherit it.
+
+  if (!targetDir && (config.model === undefined || config.model === null || config.model === "")) {
+    config.model = resolvedModels.standard || resolvedModels.reasoning || resolvedModels.fast || "openrouter/qwen/qwen3-coder:free";
+  }
+
   writeOpenCodeConfig(config, configPath);
 
   const sourcePluginsDir = path.join(root, "platforms", "opencode", "plugins");

package/skills/devops/data-engineering.md

@@ -17,7 +17,7 @@ artifactType: data-pipeline
 
 ### ELT over ETL
 
-Modern data platforms (BigQuery, Snowflake, Redshift) are powerful enough to transform inside the warehouse. Prefer **ELT** (Extract → Load raw → Transform in warehouse):
+Modern data platforms (BigQuery, Snowflake, Redshift) are capable enough to transform inside the warehouse. Prefer **ELT** (Extract → Load raw → Transform in warehouse):
 
 ```
 Source → Airbyte/Fivetran → Raw tables → dbt models → Mart/API

package/skills/docs/adr-workflow.md

@@ -3,6 +3,7 @@ name: docs-adr-workflow
 description: "Use when: an architectural decision is made that affects the system structure, data model, API contracts, or technology choices."
 inputs: [decision-context]
 artifactType: adr
+verificationBar: "Every load-bearing claim cites a verifiable source; label inference confidence; satisfy template structure requirements."
 ---
 # ADR Workflow
 

package/skills/docs/backlog-proposal-workflow.md

@@ -3,6 +3,7 @@ name: docs-backlog-proposal-workflow
 description: "Use when: product evidence should create or update Jira, Linear, GitHub Issues, or another tracker."
 inputs: [evidence-brief, prd, signal]
 artifactType: backlog-proposal
+verificationBar: "Every load-bearing claim cites a verifiable source; label inference confidence; satisfy template structure requirements."
 ---
 # Backlog Proposal Workflow
 

package/skills/docs/codebase-research-workflow.md

@@ -0,0 +1,40 @@
+---
+name: docs-codebase-research-workflow
+description: "Use when: cx-explorer maps the repo — entry points, dependencies, hot paths, or unfamiliar subsystems."
+inputs: [repository-path]
+artifactType: research-brief
+toneDefault: pedagogical
+toneAllowed: [pedagogical, direct]
+verificationBar: "Every claim cites file:line or command output; no assumed architecture."
+---
+# Codebase Research Workflow
+
+Use when: cx-explorer investigates **this repository** — structure, dependencies, behavior. Not for external vendor research or user interviews.
+
+Call `get_skill("roles/researcher.explorer")` and `get_skill("exploration/repo-map")` before deep dives.
+
+## Steps
+
+1. **Clarify the map question**: what subsystem, entry point, or data flow must be understood?
+2. **Read before concluding**: grep, glob, read implicated files. No claims from memory.
+3. **Produce artifacts**:
+   - `.cx/codebase-map.md` for broad orientation (repo-map skill)
+   - `.cx/research/{slug}.md` for focused investigations using `get_template("research-brief")`
+4. **Source classes** (codebase-primary):
+
+   | Source | Class |
+   |---|---|
+   | Source file at commit | primary |
+   | Test asserting behavior | primary |
+   | Config / schema in repo | primary |
+   | Comment or doc in repo | secondary |
+   | External blog about the repo | tertiary — locate code, do not cite alone |
+
+5. **Cite as** `[source: path#Lnn]` or `[source: commit-sha]`.
+6. **Tone**: default `pedagogical` — teach the next reader the shape of the system.
+
+## Verification bar
+
+- Every architectural claim traceable to file:line.
+- Unknown paths marked `[unverified]` until read.
+- cx-explorer must **not** answer product prioritization or user preference questions.

package/skills/docs/customer-profile-workflow.md

@@ -3,6 +3,7 @@ name: docs-customer-profile-workflow
 description: "Use when: customer evidence should update durable product memory."
 inputs: [signal, customer-profile]
 artifactType: customer-profile
+verificationBar: "Every load-bearing claim cites a verifiable source; label inference confidence; satisfy template structure requirements."
 ---
 # Customer Profile Workflow
 

package/skills/docs/document-ingest-workflow.md

@@ -3,6 +3,7 @@ name: docs-document-ingest-workflow
 description: "Use when: the user points at a PDF, Word doc, spreadsheet, slide deck, export, or mixed document folder and wants a markdown version that Construct can search efficiently later."
 inputs: [document]
 artifactType: ingested-markdown
+verificationBar: "Every load-bearing claim cites a verifiable source; label inference confidence; satisfy template structure requirements."
 ---
 # Document Ingest Workflow
 

package/skills/docs/evidence-ingest-workflow.md

@@ -3,6 +3,7 @@ name: docs-evidence-ingest-workflow
 description: "Use when: the user pastes customer notes, Slack threads, support tickets, sales notes, research snippets, RFCs, analytics summaries, or competitor signals."
 inputs: [signal, document]
 artifactType: evidence-brief
+verificationBar: "Every load-bearing claim cites a verifiable source; label inference confidence; satisfy template structure requirements."
 ---
 # Evidence Ingest Workflow
 

package/skills/docs/init-docs.md

@@ -46,7 +46,7 @@ docs/
 
 ## Interactive UX (TTY)
 
-When run interactively, `construct init-docs` renders a keyboard-driven **full-screen checkbox picker**: all available lanes listed with the default set pre-checked and context-suggested lanes highlighted in the UI. No typing required.
+When run interactively, `construct init --docs-preset=*` renders a keyboard-driven **full-screen checkbox picker**: all available lanes listed with the default set pre-checked and context-suggested lanes highlighted in the UI. No typing required.
 
 - **↑ / ↓**: move cursor (details shown in a dedicated panel)
 - **Space**: toggle lane on/off
@@ -54,7 +54,7 @@ When run interactively, `construct init-docs` renders a keyboard-driven **full-s
 - **Enter**: confirm and scaffold
 - Follow-up choices use the same menu pattern instead of free-text answers
 
-If the user selects the `intake` lane, `construct init-docs` should also create `.cx/inbox/`. Both `.cx/inbox/` and `docs/intake/` act as drop zones for ingestable files, while `docs/intake/` also serves as the durable paper trail lane.
+If the user selects the `intake` lane, `construct init` should also create `.cx/inbox/`. Both `.cx/inbox/` and `docs/intake/` act as drop zones for ingestable files, while `docs/intake/` also serves as the durable paper trail lane.
 
 When run non-interactively (`--yes` or piped stdin), the lean default set is used unless `--docs=` is supplied. `--docs=lean|product|full` or `--docs=adrs,prds,rfcs` both work.
 

package/skills/docs/init-project.md

@@ -10,9 +10,14 @@ Use when: starting work on a new project or joining an existing one without doc
 
 ## Command
 ```bash
-construct init-docs [path]   # defaults to current directory
+construct init --docs-preset=lean [path]   # defaults to current directory; presets: lean | product | full
+# or lane-specific init:
+construct init [path] [--docs-preset=lean|product|full]   # unified bootstrap (preferred)
+construct init --docs-preset=lean [path]                  # docs-only lean preset
 ```
 
+`npm run docs:init` is deprecated — use `construct init --docs-preset=*` instead.
+
 ## What it creates
 ```
 .cx/                    ← agent session memory and decisions
@@ -32,10 +37,10 @@ docs/                   ← human-readable project documentation
 1. Treat `.cx/context.md`, `.cx/context.json`, `.cx/workflow.json`, `docs/README.md`, and `docs/architecture.md` as required project state.
 2. Read them at the start of every meaningful session.
 3. Update them whenever work changes active reality: decisions, workflow phase, architecture assumptions, or documentation contract.
-4. Run `construct serve` to see the project in the dashboard.
+4. Run `construct dashboard` to see the project in the dashboard.
 
 ## For cx-docs-keeper
-At session start, check the core docs set. If missing, suggest running `construct init-docs`.
+At session start, check the core docs set. If missing, suggest running `construct init --docs-preset=lean` (or `construct init --docs-preset=full` for the full lane set).
 At session end, update the affected core docs so the next LLM session inherits current project reality.
 
 ## For all LLMs working in the repo

package/skills/docs/prd-workflow.md

@@ -3,6 +3,7 @@ name: docs-prd-workflow
 description: "Use when: the user asks to create a PRD, platform spec, business case, RFC, or requirements document."
 inputs: [research-question, evidence-brief]
 artifactType: prd
+verificationBar: "Every load-bearing claim cites a verifiable source; label inference confidence; satisfy template structure requirements."
 ---
 # PRD Workflow
 
@@ -10,6 +11,8 @@ Use when: the user asks to create a PRD, platform spec, business case, RFC, or r
 
 Choose the document type before drafting:
 
+Resolve tone from `specialists/tone-profiles.json` and optional `.cx/brand-voice.json` override for the selected template.
+
 | Template | Use when |
 |---|---|
 | `prd` | Customer-facing product capabilities, user workflows, end-user requirements |
@@ -36,7 +39,10 @@ Style constraint: do not produce a wall of bullets. Use paragraphs for reasoning
    | `meta-prd` | `docs/meta-prd/{YYYY-MM-DD}-{slug}.md` |
    | `rfc` | `docs/rfc/{YYYY-MM-DD}-{slug}.md` |
    | `rfc-platform` | `docs/rfc/{YYYY-MM-DD}-{slug}.md` |
-5. **cx-docs-keeper** updates `.cx/context.md` with a link to the PRD
+5. **cx-devil-advocate** runs the FMEA challenge pass (`roles/reviewer.devil-advocate`) on the draft; highest-RPN failure modes need a mitigation or explicit accept-with-rationale before ship. Their specialist id must appear in `.cx/agent-log.jsonl` (manifest `releaseGate.requiredReviewers` for PRD-family types).
+6. **cx-docs-keeper** updates `.cx/context.md` with a link to the PRD
+
+Run `construct artifact validate <path> --type=<type>` before marking the artifact approved.
 
 ## File naming
 - `docs/{template-type}/{YYYY-MM-DD}-{slug}.md`
@@ -54,3 +60,20 @@ Style constraint: do not produce a wall of bullets. Use paragraphs for reasoning
 ## After approval → beads
 
 Once the PRD is approved, run `/plan feature {feature-slug}` to produce a structured implementation plan and import it as workflow task packets (beads) into `.cx/workflow.json`. Link the resulting `.cx/plans/` file back in the PRD as the implementation reference.
+
+## Distribution (publish pipeline)
+
+**`construct workflow invoke` returns a plan only** — it does not draft the PRD. Run the listed specialists (cx-product-manager, cx-researcher, cx-ux-researcher as needed) to author the artifact from the template. **Do not hand-write a stub and publish.**
+
+Before distribution:
+
+```bash
+node bin/construct artifact validate docs/prd-platform/<slug>.md --type=prd-platform
+node bin/construct publish docs/prd-platform/<slug>.md --strict --figures
+```
+
+`construct publish` runs the artifact release gate by default. Thin or unscaffolded docs **exit 2** with remediation hints. Do not use `--no-gate` or `--no-strict` in demos or ship paths.
+
+**Presentation is part of done.** Published PDFs use type-specific Typst templates (`construct-prd.typ`, `construct-research.typ`, `construct-decision.typ`) with violet editorial branding and Inter body typography. Lead with an `::: executive-summary` narrative paragraph — not a bullet wall. Diagrams on the publish path use D2 `--sketch` and Mermaid `handDrawn` styling with Construct violet accent.
+
+`--strict` means **toolchain and release gate** both pass. Invoke alone is not "done."

package/skills/docs/prfaq-workflow.md

@@ -3,6 +3,7 @@ name: docs-prfaq-workflow
 description: "Use when: the user asks for a PRFAQ, working-backwards doc, launch narrative, or FAQ grounded in product evidence."
 inputs: [prd, evidence-brief]
 artifactType: prfaq
+verificationBar: "Every load-bearing claim cites a verifiable source; label inference confidence; satisfy template structure requirements."
 ---
 # PRFAQ Workflow
 

package/skills/docs/product-intelligence-workflow.md

@@ -3,6 +3,7 @@ name: docs-product-intelligence-workflow
 description: "Use when: the request involves customer evidence, PM synthesis, product requirements, PRDs, PRFAQs, customer profiles, product signals, or backlog proposals."
 inputs: [signal, evidence-brief]
 artifactType: prd
+verificationBar: "Every load-bearing claim cites a verifiable source; label inference confidence; satisfy template structure requirements."
 ---
 # Product Intelligence Workflow
 

package/skills/docs/product-signal-workflow.md

@@ -3,6 +3,7 @@ name: docs-product-signal-workflow
 description: "Use when: the user asks what customers are asking for, what themes are emerging, whether evidence is strong enough, or what should become a PRD."
 inputs: [signal, evidence-brief]
 artifactType: signal-brief
+verificationBar: "Every load-bearing claim cites a verifiable source; label inference confidence; satisfy template structure requirements."
 ---
 # Product Signal Workflow