@geraldmaron/construct 1.0.21 → 1.0.24

package/lib/init-update.mjs

@@ -21,38 +21,6 @@ const dryRun = args.includes("--dry-run");
 const cwdArg = args.find((arg) => arg.startsWith("--cwd="));
 const cwd = cwdArg ? path.resolve(cwdArg.split("=")[1]) : process.cwd();
 
-const REQUIRED_AGENT_SECTIONS = [
-  "Operating hierarchy",
-  "Start-of-session rules",
-  "Maintenance rules",
-  "End-of-session rules",
-  "Verification rules",
-];
-
-async function loadAgentsTemplate(projectName) {
-  const modulePath = path.join(import.meta.dirname, "project-init-shared.mjs");
-  const module = await import(modulePath);
-  if (!module.buildAgentsGuide) {
-    throw new Error("buildAgentsGuide not available from project-init-shared.mjs");
-  }
-  return module.buildAgentsGuide(projectName);
-}
-
-function inferProjectName(targetDir) {
-  const packagePath = path.join(targetDir, "package.json");
-  if (fs.existsSync(packagePath)) {
-    try {
-      const pkg = JSON.parse(fs.readFileSync(packagePath, "utf8"));
-      if (pkg.name) return pkg.name;
-    } catch { /* fall through */ }
-  }
-  return path.basename(targetDir);
-}
-
-function findMissingAgentsSections(content) {
-  return REQUIRED_AGENT_SECTIONS.filter((section) => !content.toLowerCase().includes(section.toLowerCase()));
-}
-
 function ensureProposalDir(targetDir) {
   const dir = path.join(targetDir, ".cx", "proposals");
   fs.mkdirSync(dir, { recursive: true });
@@ -66,37 +34,6 @@ function writeProposal(targetDir, fileName, content) {
   return proposalPath;
 }
 
-function buildAgentsProposal(existingContent, template, missingSections) {
-  const missingList = missingSections.map((section) => `- ${section}`).join("\n");
-  return [
-    "<!--",
-    "Construct init:update proposal",
-    "Review this file and merge the needed sections into AGENTS.md manually.",
-    "The original AGENTS.md was not modified.",
-    "-->",
-    "",
-    "# Proposed AGENTS.md Update",
-    "",
-    "## Why this proposal exists",
-    "",
-    "Your current `AGENTS.md` is missing these required sections:",
-    missingList,
-    "",
-    "## Current AGENTS.md",
-    "",
-    "```md",
-    existingContent.trimEnd(),
-    "```",
-    "",
-    "## Current Construct template",
-    "",
-    "```md",
-    template.trimEnd(),
-    "```",
-    "",
-  ].join("\n");
-}
-
 function buildWorkflowProposal(existingContent) {
   const updatedContent = existingContent.replace(
     /(\s+- run: node bin\/construct doctor\s*\n)/,
@@ -207,29 +144,12 @@ export function resolveTemplateConflict(conflict, resolution, targetDir) {
 async function main() {
   console.log(`Preparing Construct standards update for ${cwd}`);
 
-  const agentsPath = path.join(cwd, "AGENTS.md");
-  if (!fs.existsSync(agentsPath)) {
-    console.error("AGENTS.md not found. Run `construct init` first.");
-    process.exit(1);
-  }
-
-  const projectName = inferProjectName(cwd);
-  const existingAgents = fs.readFileSync(agentsPath, "utf8");
-  const template = await loadAgentsTemplate(projectName);
-  const missingSections = findMissingAgentsSections(existingAgents);
-
   const planned = [];
 
-  if (missingSections.length > 0) {
-    const proposalPath = path.join(".cx", "proposals", "AGENTS.md.construct-update.md");
-    planned.push({
-      label: `AGENTS.md proposal (${missingSections.length} missing section${missingSections.length === 1 ? "" : "s"})`,
-      write() {
-        return writeProposal(cwd, "AGENTS.md.construct-update.md", buildAgentsProposal(existingAgents, template, missingSections));
-      },
-      relativePath: proposalPath,
-    });
-  }
+  // Construct's guidance in AGENTS.md/CLAUDE.md is owned by the versioned
+  // CONSTRUCT INTEGRATION marker block, kept current by `construct sync`
+  // (ADR-0027 §2/§4). init:update scope is opt-in standards a project owner
+  // merges by hand: CI checks and template conflicts.
 
   const workflowPath = path.join(cwd, ".github", "workflows", "ci.yml");
   if (fs.existsSync(workflowPath)) {

package/lib/init.mjs

@@ -15,7 +15,6 @@ import fs from "node:fs";
 import path from "node:path";
 
 import {
-  buildAgentsGuide,
   buildContextJson,
   buildContextMarkdown,
   buildPlanTemplate,
@@ -43,14 +42,9 @@ function inferProjectName(targetPath) {
 function main() {
   const projectName = inferProjectName(target);
 
-  writeStampedIfMissing({
-    targetRoot: target,
-    created,
-    skipped,
-    filePath: path.join(target, "AGENTS.md"),
-    content: buildAgentsGuide(projectName),
-    generator: "construct/init",
-  });
+  // AGENTS.md is user-owned (ADR-0027 §2); Construct contributes only the fenced
+  // integration block via injectIntoAgentFile, never a doctrine body here.
+
   writeStampedIfMissing({
     targetRoot: target,
     created,
@@ -75,22 +69,12 @@ function main() {
     content: buildContextMarkdown(),
     generator: "construct/init",
   });
-  writeStampedIfMissing({
-    targetRoot: target,
-    created,
-    skipped,
-    filePath: path.join(target, ".cx", ".gitkeep"),
-    content: "",
-    generator: "construct/init",
-  });
-  writeStampedIfMissing({
-    targetRoot: target,
-    created,
-    skipped,
-    filePath: path.join(target, ".cx", "inbox", ".gitkeep"),
-    content: "",
-    generator: "construct/init",
-  });
+  // `.cx/` already exists from the context writes above and is gitignored in full
+  // (ADR-0027), so a keep file there could never be tracked; `.cx/inbox/` is the local
+  // intake drop zone the watcher polls. Create the directories; write no dead keep file.
+
+  fs.mkdirSync(path.join(target, ".cx", "inbox"), { recursive: true });
+  created.push(".cx/inbox/");
 
   process.stdout.write(`\nConstruct init → ${target}\n\n`);
   if (created.length) {

package/lib/install/stage-project.mjs

@@ -14,7 +14,7 @@ import { spawnSync } from 'node:child_process';
 import { existsSync, copyFileSync, writeFileSync, mkdirSync, chmodSync } from 'node:fs';
 import path from 'node:path';
 
-export function stageProjectAdapters({ projectRoot, packageRoot, pkgVersion, log }) {
+export function stageProjectAdapters({ projectRoot, packageRoot, pkgVersion, log, hosts = null }) {
   if (!projectRoot) throw new Error('stageProjectAdapters: projectRoot is required');
   if (!packageRoot) throw new Error('stageProjectAdapters: packageRoot is required');
   const emit = typeof log === 'function' ? log : () => {};
@@ -30,8 +30,14 @@ export function stageProjectAdapters({ projectRoot, packageRoot, pkgVersion, log
     return { staged: true, synced: false };
   }
 
+  // A `hosts` array restricts which adapter sets sync writes (construct-4xy6);
+  // null/empty leaves sync writing every host, preserving the postinstall path.
+
+  const syncArgs = [syncScript, '--project'];
+  if (Array.isArray(hosts) && hosts.length > 0) syncArgs.push(`--hosts=${hosts.join(',')}`);
+
   emit(`syncing project adapters into ${projectRoot}/.claude/`);
-  const result = spawnSync(process.execPath, [syncScript, '--project'], {
+  const result = spawnSync(process.execPath, syncArgs, {
     cwd: projectRoot,
     stdio: 'inherit',
     env: { ...process.env, CONSTRUCT_PROJECT_ROOT: projectRoot },

package/lib/intake/git-queue.mjs

@@ -0,0 +1,195 @@
+/**
+ * lib/intake/git-queue.mjs — Git-backed adapter for the IntakeQueue interface.
+ *
+ * This implementation replaces the PostgresIntakeQueue for team/enterprise
+ * modes. It uses the filesystem and Git for state synchronization and
+ * conflict resolution, removing the dependency on a central database server.
+ *
+ * Structure:
+ * .cx/team-inbox/
+ *   pending/    - JSON files for unclaimed tasks
+ *   claimed/    - Subdirectories per worker containing claimed task files
+ *   processed/  - Completed tasks
+ *   skipped/    - Skipped tasks
+ *   quarantine/ - Tasks needing human review
+ */
+
+import path from 'node:path';
+import fs from 'fs';
+import { execSync } from 'node:child_process';
+import { shouldQuarantine } from './quarantine.mjs';
+
+function slugify(value) {
+  return String(value || 'untitled')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60) || 'untitled';
+}
+
+let counter = 0;
+function timestamp() {
+  counter = (counter + 1) % 1000;
+  const c = String(counter).padStart(3, '0');
+  return `${new Date().toISOString().replace(/[:.]/g, '-').slice(0, 23)}-${c}`;
+}
+
+export class GitIntakeQueue {
+  constructor({ project, rootDir = process.cwd() } = {}) {
+    this.project = project;
+    this.inboxRoot = path.join(rootDir, '.cx', 'team-inbox');
+    this._ensureDirs();
+  }
+
+  _ensureDirs() {
+    ['pending', 'claimed', 'processed', 'skipped', 'quarantine'].forEach(dir => {
+      fs.mkdirSync(path.join(this.inboxRoot, dir), { recursive: true });
+    });
+  }
+
+  _gitAddAndCommit(filePath, message) {
+    try {
+      execSync(`git add "${filePath}"`, { stdio: 'ignore' });
+      execSync(`git commit -m "${message}"`, { stdio: 'ignore' });
+    } catch (err) {
+      // It's okay if commit fails because of no changes
+    }
+  }
+
+  async enqueue(entry) {
+    const ts = timestamp();
+    const slug = slugify(path.basename(entry.intake.sourcePath, path.extname(entry.intake.sourcePath)));
+    const id = `${ts}-${slug}`;
+    const triage = entry.triage || {};
+
+    const quarantineDecision = shouldQuarantine(triage);
+    const subDir = quarantineDecision.quarantine ? 'quarantine' : 'pending';
+    const filePath = path.join(this.inboxRoot, subDir, `${id}.json`);
+
+    const data = {
+      id,
+      project: this.project,
+      status: subDir === 'quarantine' ? 'quarantined' : 'pending',
+      createdAt: new Date().toISOString(),
+      ...entry
+    };
+
+    fs.writeFileSync(filePath, JSON.stringify(data, null, 2));
+    this._gitAddAndCommit(filePath, `Enqueue task ${id}`);
+
+    return { id, route: subDir === 'quarantine' ? 'quarantine' : 'pending', reason: quarantineDecision.reason };
+  }
+
+  async listPending({ limit = 100 } = {}) {
+    const pendingDir = path.join(this.inboxRoot, 'pending');
+    return fs.readdirSync(pendingDir)
+      .filter(f => f.endsWith('.json'))
+      .slice(0, limit)
+      .map(f => JSON.parse(fs.readFileSync(path.join(pendingDir, f), 'utf8')));
+  }
+
+  async count() {
+    const pendingDir = path.join(this.inboxRoot, 'pending');
+    return fs.readdirSync(pendingDir).filter(f => f.endsWith('.json')).length;
+  }
+
+  async read(id) {
+    for (const dir of ['pending', 'claimed', 'processed', 'skipped', 'quarantine']) {
+      // Note: 'claimed' has subdirs, we'd need to search recursively for claimed.
+      // For simplicity in this implementation, we assume we know where it is or search pending first.
+      const searchPath = dir === 'claimed' 
+        ? path.join(this.inboxRoot, dir) // needs recursive search
+        : path.join(this.inboxRoot, dir, `${id}.json`);
+      
+      if (dir !== 'claimed' && fs.existsSync(searchPath)) {
+        return JSON.parse(fs.readFileSync(searchPath, 'utf8'));
+      }
+    }
+    return null;
+  }
+
+  async claim({ claimedBy }) {
+    if (!claimedBy) throw new Error('claim: claimedBy is required');
+    
+    // 1. Pull latest to minimize conflicts
+    try { execSync('git pull --rebase', { stdio: 'ignore' }); } catch (e) {}
+
+    const pendingDir = path.join(this.inboxRoot, 'pending');
+    const files = fs.readdirSync(pendingDir).filter(f => f.endsWith('.json')).sort();
+    
+    if (files.length === 0) return null;
+
+    const fileName = files[0];
+    const pendingPath = path.join(pendingDir, fileName);
+    const workerDir = path.join(this.inboxRoot, 'claimed', claimedBy);
+    fs.mkdirSync(workerDir, { recursive: true });
+    const claimedPath = path.join(workerDir, fileName);
+
+    try {
+      // Atomic move on filesystem
+      fs.renameSync(pendingPath, claimedPath);
+      
+      // Update metadata
+      const data = JSON.parse(fs.readFileSync(claimedPath, 'utf8'));
+      data.status = 'claimed';
+      data.claimedBy = claimedBy;
+      data.claimedAt = new Date().toISOString();
+      fs.writeFileSync(claimedPath, JSON.stringify(data, null, 2));
+
+      // 2. Commit and Push
+      execSync(`git add .cx/team-inbox/pending/${fileName} .cx/team-inbox/claimed/${claimedBy}/${fileName}`, { stdio: 'ignore' });
+      execSync(`git commit -m "Claim task ${data.id} by ${claimedBy}"`, { stdio: 'ignore' });
+      execSync('git push', { stdio: 'ignore' });
+
+      return data;
+    } catch (err) {
+      // If push fails, someone else probably claimed it first or Git is out of sync.
+      // We should ideally rollback the local move, but for this first pass
+      // we'll let the next 'git pull --rebase' fix the state.
+      console.error(`Failed to claim ${fileName}: ${err.message}`);
+      return null;
+    }
+  }
+
+  async markProcessed(id, { processedBy = 'unknown', notes = '' } = {}) {
+    // Locate the file (might be in claimed/<worker>/<id>.json or pending/<id>.json)
+    // For simplicity, search all subdirs.
+    let foundPath = null;
+    let currentDir = null;
+
+    const dirs = ['pending', 'claimed']; // only mark as processed if pending or claimed
+    for (const d of dirs) {
+      const dirPath = path.join(this.inboxRoot, d);
+      if (d === 'claimed') {
+        const workers = fs.readdirSync(dirPath);
+        for (const w of workers) {
+          const p = path.join(dirPath, w, `${id}.json`);
+          if (fs.existsSync(p)) { foundPath = p; currentDir = path.join(d, w); break; }
+        }
+      } else {
+        const p = path.join(dirPath, `${id}.json`);
+        if (fs.existsSync(p)) { foundPath = p; currentDir = d; break; }
+      }
+      if (foundPath) break;
+    }
+
+    if (!foundPath) throw new Error(`markProcessed: no entry ${id} found`);
+
+    const data = JSON.parse(fs.readFileSync(foundPath, 'utf8'));
+    data.status = 'processed';
+    data.processedBy = processedBy;
+    data.processedAt = new Date().toISOString();
+    data.notes = notes;
+
+    const processedPath = path.join(this.inboxRoot, 'processed', `${id}.json`);
+    fs.renameSync(foundPath, processedPath);
+    fs.writeFileSync(processedPath, JSON.stringify(data, null, 2));
+
+    this._gitAddAndCommit(this.inboxRoot, `Mark task ${id} as processed`);
+    try { execSync('git push', { stdio: 'ignore' }); } catch (e) {}
+
+    return { id };
+  }
+
+  // markSkipped and reopen would follow similar logic...
+}

package/lib/intake/queue.mjs

@@ -36,11 +36,10 @@
 import path from 'node:path';
 
 import { FilesystemIntakeQueue, queueRoot, pendingDir, processedDir, skippedDir } from './filesystem-queue.mjs';
-import { PostgresIntakeQueue } from './postgres-queue.mjs';
+import { GitIntakeQueue } from './git-queue.mjs';
 import { getDeploymentMode } from '../deployment-mode.mjs';
-import { createSqlClient } from '../storage/backend.mjs';
 
-export { FilesystemIntakeQueue, PostgresIntakeQueue, queueRoot, pendingDir, processedDir, skippedDir };
+export { FilesystemIntakeQueue, GitIntakeQueue, queueRoot, pendingDir, processedDir, skippedDir };
 
 export const INTAKE_QUEUE_BACKEND_ENV_KEY = 'CONSTRUCT_INTAKE_QUEUE_BACKEND';
 export const INTAKE_PROJECT_ENV_KEY = 'CONSTRUCT_PROJECT_NAME';
@@ -48,9 +47,9 @@ export const INTAKE_TENANT_ENV_KEY = 'CONSTRUCT_TENANT_ID';
 
 function resolveBackend(env) {
   const override = env?.[INTAKE_QUEUE_BACKEND_ENV_KEY];
-  if (override === 'filesystem' || override === 'postgres') return override;
+  if (override === 'filesystem' || override === 'git') return override;
   const mode = getDeploymentMode(env);
-  return mode === 'solo' ? 'filesystem' : 'postgres';
+  return mode === 'solo' ? 'filesystem' : 'git';
 }
 
 function resolveProject(rootDir, env) {
@@ -62,22 +61,16 @@ function resolveProject(rootDir, env) {
 /**
  * Create an IntakeQueue instance for the given project root.
  * Backend selection: CONSTRUCT_INTAKE_QUEUE_BACKEND override wins; otherwise
- * solo mode → filesystem, team/enterprise → postgres. The postgres
- * backend pulls its connection from createSqlClient(env) and uses
- * CONSTRUCT_PROJECT_NAME / CONSTRUCT_TENANT_ID to scope queries; an
- * explicit `sql` and `project` in opts override both.
+ * solo mode → filesystem, team/enterprise → git. The git
+ * backend uses the filesystem and git for state synchronization.
  */
 export function createIntakeQueue(rootDir, env = process.env, opts = {}) {
   const backend = opts.backend || resolveBackend(env);
   if (backend === 'filesystem') return new FilesystemIntakeQueue(rootDir);
-  if (backend === 'postgres') {
-    const sql = opts.sql ?? createSqlClient(env);
-    if (!sql) {
-      throw new Error('Postgres intake queue requires a configured DATABASE_URL (or sql client). Run `construct init` or set CONSTRUCT_INTAKE_QUEUE_BACKEND=filesystem.');
-    }
+  if (backend === 'git' || backend === 'postgres') {
+    // We treat 'postgres' as an alias for 'git' now to avoid breaking existing configs
     const project = opts.project ?? resolveProject(rootDir, env);
-    const tenantId = opts.tenantId ?? env?.[INTAKE_TENANT_ENV_KEY] ?? null;
-    return new PostgresIntakeQueue({ sql, project, tenantId });
+    return new GitIntakeQueue({ project, rootDir });
   }
   throw new Error(`Unknown intake queue backend: ${backend}`);
 }

package/lib/intent-classifier.mjs

@@ -150,7 +150,7 @@ async function defaultModelCaller({ system, user }) {
       headers: {
         Authorization: `Bearer ${orKey}`,
         'content-type': 'application/json',
-        'HTTP-Referer': 'https://github.com/construct',
+        'HTTP-Referer': 'https://github.com/geraldmaron/construct',
       },
       body: JSON.stringify({
         model: modelId.replace(/^openrouter\//, ''),

package/lib/knowledge/search.mjs

@@ -11,6 +11,9 @@
  *   3. docs/README.md        — docs index + contract
  *   4. .cx/knowledge/        — operator-written internal docs
  *   5. Any *.md in docs/cookbook/ — task-oriented recipes
+ *   6. <projectRoot>/.cx/knowledge/** — the cwd project's knowledge tree,
+ *      including `external/research/` written by `construct knowledge add`,
+ *      so foreign-project queries surface project content alongside bundled docs.
  *
  * Retrieval strategy:
  *   Token-based BM25-like scoring over 200-char chunks. Returns top-K chunks
@@ -30,8 +33,17 @@ const REPO_ROOT = join(MODULE_DIR, '..', '..');
 
 // ─── Source catalogue ────────────────────────────────────────────────────────
 
-/** Priority-ordered list of source files to search. */
-function buildSourceList(repoRoot = REPO_ROOT) {
+/**
+ * Priority-ordered list of source files to search.
+ *
+ * `projectRoot` covers the case where Construct is invoked from a foreign
+ * project (cwd != construct repo): the project's own `.cx/knowledge/**` —
+ * including the `external/research/` tree written by `construct knowledge add
+ * --source=research` — joins the source set, so freshly added project knowledge
+ * surfaces alongside (and ahead of) the bundled Construct docs. When
+ * projectRoot equals repoRoot or is absent, only the bundled set is searched.
+ */
+function buildSourceList(repoRoot = REPO_ROOT, projectRoot = null) {
   const sources = [];
 
   const priority = [
@@ -92,9 +104,45 @@ function buildSourceList(repoRoot = REPO_ROOT) {
     }
   }
 
+  // Project knowledge — the cwd project's `.cx/knowledge/**`. Searched only
+  // when the project is distinct from the construct repo (the latter's own
+  // .cx/knowledge is already covered above as repoRoot's internal knowledge).
+  // Priority 1 puts project content on the same scoring tier as core docs so a
+  // freshly added project finding outranks bundled framework material on tied
+  // matches; the `source: 'project'` tag lets consumers distinguish origin.
+
+  if (projectRoot && projectRoot !== repoRoot) {
+    const projectKnowledgeRoot = join(projectRoot, '.cx', 'knowledge');
+    if (existsSync(projectKnowledgeRoot)) {
+      for (const file of walkMarkdown(projectKnowledgeRoot)) {
+        sources.push({
+          path: file,
+          rel: relative(projectRoot, file),
+          priority: 1,
+          source: 'project',
+        });
+      }
+    }
+  }
+
   return sources;
 }
 
+// Recursive .md walk used for the project-knowledge tree, where `external/`
+// nests one subdirectory deeper than the flat internal/reference/how-tos layout.
+
+function walkMarkdown(root) {
+  const out = [];
+  let entries;
+  try { entries = readdirSync(root, { withFileTypes: true }); } catch { return out; }
+  for (const entry of entries) {
+    const full = join(root, entry.name);
+    if (entry.isDirectory()) out.push(...walkMarkdown(full));
+    else if (entry.isFile() && entry.name.endsWith('.md')) out.push(full);
+  }
+  return out;
+}
+
 // ─── Chunking ────────────────────────────────────────────────────────────────
 
 const CHUNK_CHARS = 400;
@@ -272,7 +320,7 @@ export function knowledgeSearch({ query, topK = 5, minScore = 0.1, repoRoot, roo
 
   const root = repoRoot ?? REPO_ROOT;
   const dataDir = rootDir ?? (process.env.CX_DATA_DIR?.trim() || homedir());
-  const sources = buildSourceList(root);
+  const sources = buildSourceList(root, rootDir);
 
   // Build corpus from docs + operator knowledge
   const allChunks = [];
@@ -318,6 +366,7 @@ export function knowledgeSearch({ query, topK = 5, minScore = 0.1, repoRoot, roo
     text: chunk.text,
     heading: chunk.heading,
     file: chunk.source.rel,
+    origin: chunk.source.source || 'bundled',
     score: Math.round(score * 100) / 100,
     lineStart: chunk.lineStart,
   }));

package/lib/mcp/server.mjs

@@ -723,19 +723,6 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         required: ['query'],
       },
     },
-    {
-      name: 'rovo_search',
-      description: 'Cross-system semantic search via Atlassian Rovo. Searches Jira, Confluence, and other accessible sources. Returns excerpts with source attribution. Does NOT store results in the observation store. Use for broad queries across all sources, not just focal projects.',
-      inputSchema: {
-        type: 'object',
-        properties: {
-          query: { type: 'string', description: 'Search query (e.g., "Iverson reliability", "DR failover").' },
-          top_k: { type: 'number', description: 'Max results (default: 10, max: 50).' },
-          sources: { type: 'string', description: 'Comma-separated source filter (e.g., "jira,confluence").' },
-        },
-        required: ['query'],
-      },
-    },
     {
       name: 'efficiency_snapshot',
       description: 'Returns the read-efficiency snapshot for the current session — repeated reads, large reads, hot-spot files, and recommendations. Use this when investigating why a session feels slow or to surface optimization opportunities.',
@@ -939,6 +926,20 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         properties: { cwd: { type: 'string', description: 'Project root (default: server cwd).' } },
       },
     },
+    {
+      name: 'document_export',
+      description: 'Convert a markdown file into a distributable PDF, DOCX, or HTML document via Pandoc (DOCX/HTML) and Typst (PDF engine), per ADR-0024. Both engines are optional system binaries discovered at runtime — the tool returns a structured "install <binary>" error when tooling is absent, never crashes. Use `detect_only=true` to check availability without running an export.',
+      inputSchema: {
+        type: 'object',
+        required: ['format'],
+        properties: {
+          input_path: { type: 'string', description: 'Absolute path to the markdown source file (required unless detect_only=true).' },
+          output_path: { type: 'string', description: 'Optional absolute output path; defaults to <input>.<format> next to the source.' },
+          format: { type: 'string', enum: ['pdf', 'docx', 'html'], description: 'Target format.' },
+          detect_only: { type: 'boolean', description: 'When true, report binary availability without exporting. Default false.' },
+        },
+      },
+    },
     {
       name: 'knowledge_search',
       description: 'Search Construct\'s own documentation, knowledge base, and distilled embed observations. Call this immediately — no approval needed — when the user asks what Construct is, how a feature works, what commands exist, or anything about Construct\'s architecture or configuration. Also searches embed observations from GitHub, Jira, and other configured sources. Returns relevant excerpts with source file and heading.',
@@ -1176,6 +1177,38 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
       },
     },
+    {
+      name: 'orchestration_run',
+      description: 'EXECUTE a real multi-specialist orchestration run via the local Construct daemon and return per-specialist output — the executing counterpart to workflow_invoke (which only plans). For MCP hosts with no subagent primitive (VS Code/Copilot, Cursor), this is how you actually run a specialist chain: the engine owns orchestration, this tool is the thin client (ADR-0022). Requires a running daemon (`construct dashboard`); if it is unreachable the tool fails fast with how to start it rather than silently degrading to a single-persona pass. Real specialist output requires the daemon to run the `provider` worker backend (a provider key configured); the default `inline` backend prepares tasks only.',
+      inputSchema: {
+        type: 'object',
+        required: ['request'],
+        properties: {
+          request: { type: 'string', description: 'Natural-language description of the work to orchestrate (e.g. "refactor the auth module and review it for security").' },
+          workflow_type: { type: 'string', description: 'Optional workflow type to shape the plan (e.g. architecture-review, risk-review).' },
+          requested_strategy: { type: 'string', enum: ['orchestrated', 'prompt-only', 'auto'], description: 'Execution strategy (default auto).' },
+          worker_backend: { type: 'string', enum: ['inline', 'provider'], description: 'provider executes specialists (needs a provider key); inline prepares only. Default: daemon config.' },
+          host: { type: 'string', description: 'Host/IDE identifier (advisory).' },
+          host_model: { type: 'string', description: 'Model the host uses, for model resolution.' },
+          host_provider: { type: 'string', description: 'Provider family the host uses, for model resolution.' },
+          file_count: { type: 'number', description: 'Optional planning hint: number of files in scope.' },
+          module_count: { type: 'number', description: 'Optional planning hint: number of modules in scope.' },
+          wait: { type: 'boolean', description: 'Wait for the run to reach a terminal state and return task output (default true). false returns the runId immediately to poll with orchestration_status.' },
+          timeout_ms: { type: 'number', description: 'Max time to wait when wait=true (default 120000). On timeout the runId is returned to poll.' },
+        },
+      },
+    },
+    {
+      name: 'orchestration_status',
+      description: 'Inspect orchestration runs on the local Construct daemon: pass run_id for the full record (status, per-task status/executor/output/error), or omit it for a list of recent runs. Fails fast if the daemon is unreachable.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          run_id: { type: 'string', description: 'Run id to fetch. Omit to list recent runs.' },
+          limit: { type: 'number', description: 'Max runs to list when run_id is omitted (default 20).' },
+        },
+      },
+    },
   ],
 }));
 
@@ -1227,7 +1260,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     else if (name === 'session_search') result = sessionSearch(args);
     else if (name === 'session_save') result = sessionSave(args);
     else if (name === 'memory_search') result = await memorySearch(args);
-    else if (name === 'memory_add_observations') result = memoryAddObservations(args);
+    else if (name === 'memory_add_observations') result = await memoryAddObservations(args);
     else if (name === 'memory_create_entities') result = memoryCreateEntities(args);
     else if (name === 'memory_recent') result = memoryRecent(args);
     else if (name === 'rovo_search') result = await rovoSearch(args);
@@ -1241,6 +1274,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       const { knowledgeSearch } = await import('../knowledge/search.mjs');
       result = knowledgeSearch({ query: args.query, topK: args.top_k, repoRoot: args.repo_root, rootDir: args.root_dir });
     }
+    else if (name === 'document_export') {
+      const { detect, exportMarkdown } = await import('../document-export.mjs');
+      if (args.detect_only) {
+        result = detect(args.format);
+      } else {
+        result = exportMarkdown({ inputPath: args.input_path, outputPath: args.output_path, format: args.format });
+      }
+    }
     else if (name === 'profile_show') result = profileShow(args);
     else if (name === 'profile_list') result = profileList();
     else if (name === 'profile_drafts') result = profileDrafts(args);
@@ -1258,6 +1299,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     else if (name === 'workflow_invoke') result = await workflowInvoke(args);
     else if (name === 'capability_describe') result = capabilityDescribe(args);
     else if (name === 'construct_execution_resolve') result = executionResolve(args);
+    else if (name === 'orchestration_run') { const m = await import('./tools/orchestration-run.mjs'); result = await m.orchestrationRun(args); }
+    else if (name === 'orchestration_status') { const m = await import('./tools/orchestration-run.mjs'); result = await m.orchestrationStatus(args); }
     else result = { error: `Unknown tool: ${name}` };
   } catch (err) {
     result = { error: err.message ?? String(err) };