@geraldmaron/construct 1.2.3 → 1.3.1

package/scripts/sync-specialists.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * sync-specialists.mjs — regenerate agent adapters for all platforms from specialists/registry.json.
+ * sync-specialists.mjs — regenerate agent adapters for all platforms from specialists/org.
  *
  * Two scopes, modelled on every host's own convention (global = personal default,
  * project = team-shared):
@@ -31,6 +31,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
+import { fileURLToPath } from "node:url";
 import { generateCompletions } from "../lib/completions.mjs";
 import {
   buildCodexMcpEntry,
@@ -43,7 +44,7 @@ import {
   tomlString,
   writeCodexConfig,
 } from "../lib/codex-config.mjs";
-import { findOpenCodeConfigPath, readOpenCodeConfig, writeOpenCodeConfig } from "../lib/opencode-config.mjs";
+import { findOpenCodeConfigPath, readOpenCodeConfig, writeOpenCodeConfig, ensureOpenRouterProviderAuth } from "../lib/opencode-config.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, readPromptBody } from "../lib/prompt-composer.js";
@@ -59,21 +60,67 @@ import { configDir } from "../lib/config/xdg.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 { resolveActiveScope } from "../lib/scopes/loader.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";
+import { loadRegistry, clearCache } from "../lib/registry/loader.mjs";
+import { loadPluginRegistry } from "../lib/plugin-registry.mjs";
 
 const home = os.homedir();
 const root = path.resolve(import.meta.dirname, "..");
+const isMain = process.argv[1] ? path.resolve(process.argv[1]) === fileURLToPath(import.meta.url) : false;
 
 const mergedEnv = loadConstructEnv({ rootDir: root, homeDir: home, env: process.env });
 for (const [key, value] of Object.entries(mergedEnv)) {
   if (!(key in process.env)) process.env[key] = value;
 }
 if (!process.env.CX_TOOLKIT_DIR) process.env.CX_TOOLKIT_DIR = root;
-const registryPath = path.join(root, "specialists", "registry.json");
-const registry = JSON.parse(fs.readFileSync(registryPath, "utf8"));
+
+function unifiedToLegacyRegistry(unified) {
+  const orchestrator = Object.values(unified.specialists || {}).find(s => s.role === 'orchestrator') || {};
+  const specialists = Object.values(unified.specialists || {}).filter(s => s.role !== 'orchestrator');
+  return {
+    version: 1,
+    system: 'construct',
+    prefix: 'cx',
+    orchestrator: {
+      name: 'construct',
+      displayName: orchestrator.displayName || orchestrator.description?.split('—')[0].trim() || 'Construct',
+      description: orchestrator.description || '',
+      promptFile: orchestrator.promptFile || 'specialists/prompts/cx-orchestrator.md',
+      modelTier: orchestrator.modelTier || 'standard',
+      skills: orchestrator.skills || [],
+      injectAgentRoster: orchestrator.injectAgentRoster ?? false,
+    },
+    specialists: specialists.map(s => ({
+      name: s.name,
+      displayName: s.displayName || s.description?.split('—')[0].trim() || s.name,
+      description: s.description || '',
+      promptFile: s.promptFile,
+      modelTier: s.modelTier || 'standard',
+      claudeTools: s.claudeTools || 'Read,Grep,Glob,LS',
+      internal: s.internal,
+      wordCapOverride: s.wordCapOverride,
+      skills: s.skills || [],
+      team: s.team,
+      role: s.role,
+      docArtifacts: s.docArtifacts || [],
+      subscriptions: s.events || [],
+      watchConditions: s.watchConditions || [],
+      fence: s.fence || {},
+    })),
+    sharedGuidance: unified.sharedGuidance || [],
+    models: unified.models || { reasoning: { primary: null }, standard: { primary: null }, fast: { primary: null } },
+    providers: unified.providers || {},
+    mcpServers: unified.mcpServers || {},
+  };
+}
+
+clearCache();
+clearCache();
+const unified = loadRegistry({ rootDir: root });
+const registry = unifiedToLegacyRegistry(unified);
 
 function validateRegistry(registry) {
   const errors = [];
@@ -378,15 +425,15 @@ const sharedGuidance = registry.sharedGuidance ?? [];
 const platformGuidance = registry.platformGuidance ?? {};
 const globalModelGuidance = registry.modelGuidance ?? {};
 
-const generatedHeader = `# Generated by ${systemName}/sync-specialists.mjs. Edit specialists/registry.json instead.`;
+const generatedHeader = `# Generated by ${systemName}/sync-specialists.mjs. Edit specialists/org instead.`;
 const generatedMarkdownNote = [
   '<!--',
-  `Generated by construct sync from specialists/registry.json.`,
+  `Generated by construct sync from specialists/org.`,
   'Do not edit this file directly — changes will be overwritten on next sync.',
   'Regenerate: construct sync',
   '-->',
   '',
-  '> Generated from `specialists/registry.json`. Edit the registry, then run `construct sync`.',
+  '> Generated from `specialists/org`. Edit the registry, then run `construct sync`.',
 ].join('\n');
 
 const standardConstructTools = [
@@ -432,6 +479,96 @@ function resolveArgs(args) {
     : a));
 }
 
+function resolveTemplateStrings(value) {
+  if (typeof value === "string") {
+    return value.replace(/__([A-Z0-9_]+)__/g, (_, name) => {
+      if (process.env[name] !== undefined && process.env[name] !== "") return process.env[name];
+      if (name === "CX_TOOLKIT_DIR") return root;
+      if (name === "MEMORY_PORT") return process.env.MEMORY_PORT || "8765";
+      if (name === "CONSTRUCT_MEMORY_BRIDGE_URL") {
+        return process.env.CONSTRUCT_MEMORY_BRIDGE_URL || "http://127.0.0.1:8765/";
+      }
+      if (name === "GITHUB_TOKEN" && process.env.GITHUB_PERSONAL_ACCESS_TOKEN) {
+        return process.env.GITHUB_PERSONAL_ACCESS_TOKEN;
+      }
+      if (/(?:TOKEN|SECRET|API_KEY|PUBLIC_KEY|PRIVATE_KEY)$/.test(name)) {
+        return `{env:${name}}`;
+      }
+      return `__${name}__`;
+    });
+  }
+  if (Array.isArray(value)) return value.map((item) => resolveTemplateStrings(item));
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, resolveTemplateStrings(item)]));
+  }
+  return value;
+}
+
+function constructMcpDefinition() {
+  return {
+    id: "construct-mcp",
+    name: "Construct MCP",
+    category: "core",
+    description: "Construct stdio MCP server for orchestration, skills, templates, and project context.",
+    command: "node",
+    args: ["__CX_TOOLKIT_DIR__/lib/mcp/server.mjs"],
+    env: {
+      CONSTRUCT_TRACE_BACKEND: "__CONSTRUCT_TRACE_BACKEND__",
+      CONSTRUCT_TELEMETRY_URL: "__CONSTRUCT_TELEMETRY_URL__",
+      CONSTRUCT_TELEMETRY_PUBLIC_KEY: "__CONSTRUCT_TELEMETRY_PUBLIC_KEY__",
+      CONSTRUCT_TELEMETRY_SECRET_KEY: "__CONSTRUCT_TELEMETRY_SECRET_KEY__",
+    },
+    requiredEnv: [],
+    setupModes: ["auto"],
+    hostSupport: {
+      claude: { mode: "managed" },
+      opencode: { mode: "managed" },
+      codex: { mode: "managed" },
+    },
+    usedBy: ["construct"],
+  };
+}
+
+function managedMcpDefs() {
+  const pluginRegistry = loadPluginRegistry({ cwd: root, homeDir: home, rootDir: root, env: process.env });
+  const defs = Object.fromEntries(
+    (pluginRegistry.mcps ?? []).map((mcp) => [mcp.id, {
+      type: mcp.type,
+      url: mcp.url,
+      command: mcp.command,
+      args: mcp.args,
+      env: mcp.env,
+      headers: mcp.headers,
+      hostSupport: mcp.hostSupport,
+      category: mcp.category,
+    }]),
+  );
+  defs["construct-mcp"] = constructMcpDefinition();
+  return { ...defs, ...(registry.mcpServers ?? {}) };
+}
+
+function scopedManagedMcpDefs({ projectScope = false } = {}) {
+  const defs = managedMcpDefs();
+  if (!projectScope) return defs;
+  return Object.fromEntries(
+    Object.entries(defs).filter(([id]) => PROJECT_DEFAULT_MCP_IDS.has(id)),
+  );
+}
+
+function mergeMissingObjectDefaults(current, defaults) {
+  if (Array.isArray(defaults)) {
+    return current === undefined ? [...defaults] : current;
+  }
+  if (!defaults || typeof defaults !== "object") {
+    return current === undefined ? defaults : current;
+  }
+  const next = current && typeof current === "object" && !Array.isArray(current) ? { ...current } : {};
+  for (const [key, value] of Object.entries(defaults)) {
+    next[key] = mergeMissingObjectDefaults(next[key], value);
+  }
+  return next;
+}
+
 function extractFallbackChain(tierDef) {
   if (typeof tierDef === "string") return [tierDef];
   if (tierDef && typeof tierDef === "object") {
@@ -554,7 +691,7 @@ function buildRoleFooter(entry) {
   return `\n\n${lines.join("\n")}`;
 }
 
-// Fence + handoff data is the source of truth in specialists/role-manifests.json
+// Fence + handoff data is the source of truth in specialists/org
 // (events, fence.allowedPaths, fence.allowedBdLabels, fence.approvalRequired,
 // handoffCandidates, outputs.docTypes). Restating that JSON inside each
 // specialist prompt would invite drift across 28 files; the renderer below
@@ -599,7 +736,7 @@ export function renderRoleFrameworkSection(entry) {
     "",
     `Construct may dispatch you in response to ${eventList} events. A bd issue with the event payload exists when dispatched: read it first via \`bd show <id>\`.`,
     "",
-    `**Fence** (source of truth: \`specialists/role-manifests.json\` → \`${personaName}\`):`,
+    `**Fence** (source of truth: \`specialists/org\` → \`${personaName}\`):`,
     `- Allowed paths: ${pathList}`,
     `- Allowed bd labels: ${labelList}`,
     `- Approval required: ${approvalList}`,
@@ -616,11 +753,21 @@ export function renderRoleFrameworkSection(entry) {
 // 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.`;
+function orchestrationToolName(platform, toolName) {
+  if (platform === "opencode") return `construct-mcp_${toolName}`;
+  return toolName;
+}
+
+function orchestrationMicroPrompt(platform) {
+  const policyTool = orchestrationToolName(platform, "orchestration_policy");
+  const runTool = orchestrationToolName(platform, "orchestration_run");
+  return (
+    `You are the primary orchestrator. Before any non-trivial answer, call \`${policyTool}\` with the user's \`request\`. Do not guess agent names or workflow types.\n\n` +
+    `Example — the user says "add rate limiting to the API". Your first action is a tool call, not prose:\n` +
+    `  call ${policyTool} { "request": "add rate limiting to the API" }\n` +
+    `If the route is focused/orchestrated specialist work, call \`${runTool}\` with the same request. If the route suggests a workflow such as \`research-synthesis\`, pass it as \`workflow_type\`. Do not narrate completed research unless \`${runTool}\` or evidence tools actually ran.`
+  );
+}
 
 // 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 —
@@ -661,7 +808,7 @@ function enforcePromptWordCap(prompt, entry) {
       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` +
+        `   - set "wordCapOverride": <N> on this entry in specialists/org 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.`,
       );
@@ -684,7 +831,7 @@ function buildPrompt(entry, allEntries, platform, { capabilityTier = 'full' } =
   if (capabilityTier && capabilityTier !== 'full' && entry.promptFile) {
     let slim = renderPersonaForTier(readPromptBody(entry.promptFile, root), capabilityTier);
     if (entry.injectAgentRoster) {
-      slim = `${ORCHESTRATION_MICRO_PROMPT}\n\n${slim}`;
+      slim = `${orchestrationMicroPrompt(platform)}\n\n${slim}`;
     }
     return enforcePromptWordCap(slim, entry);
   }
@@ -707,7 +854,7 @@ function buildPrompt(entry, allEntries, platform, { capabilityTier = 'full' } =
   // orchestration_policy / orchestration_run — never inject the static roster.
 
   if (entry.injectAgentRoster) {
-    prompt = `${ORCHESTRATION_MICRO_PROMPT}\n\n${prompt}`;
+    prompt = `${orchestrationMicroPrompt(platform)}\n\n${prompt}`;
   }
 
   prompt += buildRoleFooter(entry);
@@ -811,7 +958,7 @@ function buildEntries() {
   // so behavior is unchanged for the default; non-RND profiles emit only the
   // specialists they declare. Profiles whose role list is empty (legacy/test)
   // fall through to no filter so callers don't get a silent empty registry.
-  const activeProfile = resolveActiveProfile(process.cwd());
+  const activeProfile = resolveActiveScope(process.cwd());
   const profileRoles = Array.isArray(activeProfile?.roles) && activeProfile.roles.length > 0
     ? new Set(activeProfile.roles)
     : null;
@@ -855,13 +1002,20 @@ ${buildPrompt(entry, allEntries, "claude")}
  * Rewrite the home-mode hook command pattern
  *   node "$HOME/.config/construct/lib/hooks/<name>.mjs"
  * into the project-portable form
- *   node .construct/run.mjs hook <name>
+ *   node "${CLAUDE_PROJECT_DIR:-.}/.construct/run.mjs" hook <name>
  * so the resulting settings.json works on any clone where the project ships
  * the .construct/ launcher (committed by `npm install`'s postinstall or by
  * `construct init`). The launcher resolves Construct via node_modules → npx
  * → globally-installed CLI → cached binary → docker, in that order, so it
  * works for non-Node ecosystems too. Other commands (inline node -e
  * snippets, npx block-no-verify@…) are left untouched.
+ *
+ * The `${CLAUDE_PROJECT_DIR:-.}` anchor matters: Claude Code invokes hooks with
+ * a working directory that is not guaranteed to be the project root (observed:
+ * $HOME), and a bare relative `.construct/run.mjs` then fails with MODULE_NOT_FOUND
+ * at node:internal/modules/cjs/loader. CLAUDE_PROJECT_DIR is the project root Claude
+ * Code exports to every hook (same var lib/hooks/*.mjs already read); the `:-.`
+ * fallback preserves the prior relative behavior wherever the var is unset.
  */
 function makeHooksPortable(hooksJson) {
   // Operate on the in-memory object so we don't fight JSON string escaping.
@@ -870,7 +1024,7 @@ function makeHooksPortable(hooksJson) {
     const m = cmd.match(/^node\s+"?\$HOME\/\.config\/construct\/lib\/hooks\/([a-z0-9-]+)\.mjs"?\s*(.*)$/);
     if (!m) return cmd;
     const [, name, rest] = m;
-    return `node .construct/run.mjs hook ${name}${rest ? ' ' + rest.trim() : ''}`;
+    return `node "\${CLAUDE_PROJECT_DIR:-.}/.construct/run.mjs" hook ${name}${rest ? ' ' + rest.trim() : ''}`;
   };
 
   const walk = (node) => {
@@ -920,12 +1074,6 @@ function filterGlobalClaudeHooks(hooksJson) {
 
 function syncGlobalClaudeMcpServers(settings, registryMcp) {
   settings.mcpServers ??= {};
-  for (const id of Object.keys(settings.mcpServers)) {
-    if (id in registryMcp && !GLOBAL_CLAUDE_MCP_IDS.has(id)) {
-      delete settings.mcpServers[id];
-    }
-  }
-
   for (const [id, mcpDef] of Object.entries(registryMcp)) {
     if (!GLOBAL_CLAUDE_MCP_IDS.has(id)) continue;
     const existingEntry = settings.mcpServers[id];
@@ -979,7 +1127,7 @@ function writeProjectClaudeSettings(targetDir) {
   // Claude Code as the only selected tool without the construct config. Merge the
   // registry on top of the template seed; existing entries win so user edits stick,
   // and buildClaudeMcpEntry resolves each server's path/env.
-  const registryMcp = registry.mcpServers ?? {};
+  const registryMcp = scopedManagedMcpDefs({ projectScope: true });
   existing.mcpServers ??= {};
   for (const [id, mcpDef] of Object.entries(registryMcp)) {
     if (existing.mcpServers[id]) continue;
@@ -1057,7 +1205,7 @@ ${personaList}
           settings.hooks = JSON.parse(hookStr);
         }
       }
-      const registryMcp = registry.mcpServers ?? {};
+      const registryMcp = scopedManagedMcpDefs({ projectScope: false });
       syncGlobalClaudeMcpServers(settings, registryMcp);
       if (!DRY_RUN) fs.writeFileSync(claudeSettingsPath, JSON.stringify(settings, null, 2) + "\n");
     }
@@ -1135,7 +1283,7 @@ function syncCodex(entries, targetDir = null, wants = true) {
     : getCodexConfigPath(home);
   const existing = removeDanglingConstructMcpMarkers(removeDanglingConstructMcpTimeouts(readCodexConfig(configPath)));
   const entryNames = writeEntries.map(adapterName);
-  const registryMcp = registry.mcpServers ?? {};
+  const registryMcp = scopedManagedMcpDefs({ projectScope: Boolean(targetDir) });
   // Seed every supported MCP server (parity with Claude/OpenCode/VS Code/Cursor),
   // not just tables already present — otherwise Codex never receives `construct-mcp`
   // and the orchestration tool is unreachable there. existingMcpIds still drives
@@ -1285,7 +1433,7 @@ function getVSCodeUserMcpPaths() {
 }
 
 function syncVSCode(targetDir = null, wants = true) {
-  const registryMcp = registry.mcpServers ?? {};
+  const registryMcp = scopedManagedMcpDefs({ projectScope: Boolean(targetDir) });
   if (Object.keys(registryMcp).length === 0) return false;
 
   // Project scope writes a dedicated `.vscode/mcp.json` (VS Code's documented
@@ -1369,7 +1517,7 @@ function syncVSCode(targetDir = null, wants = true) {
 // --- Cursor adapter ---
 
 function syncCursor(targetDir = null, wants = true) {
-  const registryMcp = registry.mcpServers ?? {};
+  const registryMcp = scopedManagedMcpDefs({ projectScope: Boolean(targetDir) });
   if (Object.keys(registryMcp).length === 0) return false;
 
   const cursorDir = targetDir
@@ -1567,16 +1715,72 @@ function syncOpencode(entries, targetDir = null, wants = true) {
 
   const writeEntries = globalEntries(entries);
 
+  const hadExistingConfig = fs.existsSync(configPath);
   const { config } = targetDir
-    ? { config: fs.existsSync(configPath) ? JSON.parse(fs.readFileSync(configPath, "utf8")) : {} }
+    ? { config: hadExistingConfig ? JSON.parse(fs.readFileSync(configPath, "utf8")) : {} }
     : readOpenCodeConfig();
+  const opencodeTemplatePath = path.join(root, "platforms", "opencode", "config.template.json");
+  const opencodeTemplate = fs.existsSync(opencodeTemplatePath)
+    ? JSON.parse(fs.readFileSync(opencodeTemplatePath, "utf8"))
+    : {};
   if (!config.agent) config.agent = {};
+  if (!config.mcp) config.mcp = {};
   if (!Array.isArray(config.plugin)) config.plugin = [];
   config.plugin = config.plugin.filter((entry) => {
     if (typeof entry !== "string") return true;
     return entry !== managedPluginPath && entry !== toolkitPluginPath;
   });
 
+  if (opencodeTemplate.$schema && !config.$schema) config.$schema = opencodeTemplate.$schema;
+  if (opencodeTemplate.model && !config.model && !config.defaultModel && !hadExistingConfig) {
+    config.model = opencodeTemplate.model;
+  }
+  if (Array.isArray(opencodeTemplate.enabled_providers) && !Array.isArray(config.enabled_providers)) {
+    config.enabled_providers = [...opencodeTemplate.enabled_providers];
+  }
+  if (opencodeTemplate.provider && typeof opencodeTemplate.provider === "object") {
+    config.provider ??= {};
+    for (const [id, providerDef] of Object.entries(opencodeTemplate.provider)) {
+      config.provider[id] = mergeMissingObjectDefaults(config.provider[id], resolveTemplateStrings(providerDef));
+    }
+  }
+  if (config.provider?.ollama?.options?.headers?.Authorization === "Bearer ollama") {
+    delete config.provider.ollama.options.headers.Authorization;
+    if (Object.keys(config.provider.ollama.options.headers).length === 0) {
+      delete config.provider.ollama.options.headers;
+    }
+  }
+
+  const templateMcp = opencodeTemplate.mcp && typeof opencodeTemplate.mcp === "object"
+    ? resolveTemplateStrings(opencodeTemplate.mcp)
+    : {};
+  for (const [id, entry] of Object.entries(templateMcp)) {
+    if (!PROJECT_DEFAULT_MCP_IDS.has(id)) continue;
+    if (!config.mcp[id]) config.mcp[id] = entry;
+  }
+  if (config.mcp["construct-mcp"]) {
+    config.mcp["construct-mcp"] = templateMcp["construct-mcp"] ?? config.mcp["construct-mcp"];
+  }
+
+  const memoryBridgeEntry = buildOpenCodeMcpEntry("memory", {
+    command: "node",
+    args: ["__CX_TOOLKIT_DIR__/lib/mcp/memory-bridge.mjs"],
+    env: { CONSTRUCT_MEMORY_BRIDGE_URL: "__CONSTRUCT_MEMORY_BRIDGE_URL__" },
+  }, {
+    ...process.env,
+    CONSTRUCT_MEMORY_BRIDGE_URL:
+      config.mcp.memory?.url
+      || config.mcp.cass?.url
+      || process.env.CONSTRUCT_MEMORY_BRIDGE_URL
+      || "http://127.0.0.1:8765/",
+  }).entry;
+  const staleMemoryRemote = config.mcp.memory && (config.mcp.memory.type === "remote" || config.mcp.memory.type === "http");
+  const staleCassRemote = config.mcp.cass && (config.mcp.cass.type === "remote" || config.mcp.cass.type === "http");
+  if (staleMemoryRemote || staleCassRemote) {
+    config.mcp.memory = memoryBridgeEntry;
+    delete config.mcp.cass;
+  }
+
   // Sync providers
   const registryProviders = registry.providers ?? {};
   if (Object.keys(registryProviders).length > 0) {
@@ -1589,8 +1793,10 @@ function syncOpencode(entries, targetDir = null, wants = true) {
         ...providerDef,
         options: {
           ...providerDef.options,
+          ...existing.options,
           headers: {
             ...providerDef.options?.headers,
+            ...existing.options?.headers,
             ...(existingAuth ? { Authorization: existingAuth } : {}),
           },
         },
@@ -1602,6 +1808,8 @@ function syncOpencode(entries, targetDir = null, wants = true) {
     }
   }
 
+  ensureOpenRouterProviderAuth(config);
+
   // Derive anthropic models from registry tier definitions
   const tierModels = Object.values(registry.models ?? {}).flatMap((t) =>
     [t.primary, ...(t.fallback ?? [])].filter((m) => m?.startsWith('anthropic/'))
@@ -1627,7 +1835,7 @@ function syncOpencode(entries, targetDir = null, wants = true) {
   }
 
   // Sync MCP servers
-  const registryMcp = registry.mcpServers ?? {};
+  const registryMcp = scopedManagedMcpDefs({ projectScope: Boolean(targetDir) });
   if (Object.keys(registryMcp).length > 0) {
     if (!config.mcp) config.mcp = {};
     for (const [id, mcpDef] of Object.entries(registryMcp)) {
@@ -1656,7 +1864,7 @@ function syncOpencode(entries, targetDir = null, wants = true) {
     // 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
+    // filter (OpenCode chat.params carries no tool list), so disabling the whole server in
     // opencode.json is the only lever. The decision is INTENT-driven: trim only
     // when this config's own default model is local (or a local Ollama provider is
     // registered in it), so a cloud session on a machine that merely also has
@@ -1689,7 +1897,8 @@ function syncOpencode(entries, targetDir = null, wants = true) {
   for (const key of Object.keys(config.agent)) {
     const isManaged = prefixes.some((p) => key.startsWith(p));
     const isOrchestrator = registry.orchestrator?.name === key;
-    if ((isManaged || isOrchestrator) && !writeEntries.find((e) => adapterName(e) === key)) {
+    const isStaleOrchestratorAlias = key === 'orchestrator' && registry.orchestrator?.name === 'construct';
+    if ((isManaged || isOrchestrator || isStaleOrchestratorAlias) && !writeEntries.find((e) => adapterName(e) === key)) {
       delete config.agent[key];
     }
   }
@@ -1780,21 +1989,28 @@ function syncOpencode(entries, targetDir = null, wants = true) {
   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. 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";
+  // OpenCode's primary `model` is user-owned. Remove the legacy Construct seed
+  // when we find it so the app can fall back to its own remembered selection
+  // instead of a stale pin. New syncs never write this key back.
+  const legacyPinnedModels = new Set([
+    opencodeTemplate.model,
+    hardDefaults.standard,
+  ].filter(Boolean));
+  if (!targetDir && legacyPinnedModels.has(config.model)) {
+    delete config.model;
+  }
+
+  // OpenCode's built-in helper agents drive session naming, summaries, and
+  // compaction. Keep them on a stronger auxiliary model so those surfaces do not
+  // inherit the main chat model's selection history or a low-end coder default.
+  const auxiliaryModel = resolvedModels.reasoning || resolvedModels.standard || resolvedModels.fast;
+  if (auxiliaryModel) {
+    for (const key of ["title", "summary", "compaction"]) {
+      config.agent[key] = {
+        ...(config.agent[key] && typeof config.agent[key] === "object" ? config.agent[key] : {}),
+        model: auxiliaryModel,
+      };
+    }
   }
 
   writeOpenCodeConfig(config, configPath);
@@ -1943,6 +2159,7 @@ function syncSkills(targetDir = null) {
 
 // --- Main ---
 
+if (isMain) {
 const entries = buildEntries();
 
 if (COMPRESS_PERSONAS) {
@@ -2035,3 +2252,4 @@ try {
 } finally {
   releaseLock();
 }
+}

package/skills/ai/prompt-optimizer.md

@@ -6,7 +6,7 @@ artifactType: prompt
 ---
 # Prompt Auto-Optimization Loop
 
-Construct's prompt improvement system uses telemetry traces and quality scores as the feedback signal, Claude as the optimizer, and the agent registry (`specialists/registry.json`) as the deployment layer. This is a closed loop: production data → failure analysis → improved prompt → staging → promotion.
+Construct's prompt improvement system uses telemetry traces and quality scores as the feedback signal, Claude as the optimizer, and the modular org registry (`specialists/org/`, assembled at runtime via `loadRegistry()`) as the deployment layer. This is a closed loop: production data → failure analysis → improved prompt → staging → promotion.
 
 ## Running the optimizer
 
@@ -34,7 +34,7 @@ The optimizer requires Python 3.12+ (`pip3` must be available). It will auto-ins
 
 ## Step 1: Gather signal
 
-Retrieve the current production prompt for the target agent from `specialists/registry.json` (or the corresponding `promptFile` if using extracted prompts).
+Retrieve the current production prompt for the target agent from the specialist entry under `specialists/org/specialists/` (or the corresponding `promptFile` if using extracted prompts).
 
 Then retrieve recent traces via the telemetry backend REST API:
 
@@ -76,7 +76,7 @@ Write an improved prompt that directly addresses the diagnosed failures. Rules:
 
 ## Step 4: Push to staging
 
-Update the agent's prompt in `specialists/registry.json` (or the corresponding `promptFile`) with a staging marker comment. Tag the version by writing to `.cx/decisions/prompt-staging-{agent}-{date}.md`.
+Update the agent's prompt in `specialists/org/specialists/<agent>.json` (or the corresponding `promptFile`) with a staging marker comment. Tag the version by writing to `.cx/decisions/prompt-staging-{agent}-{date}.md`.
 
 Log the candidate prompt as a span attribute on a test run batch using `cx_trace`. Tag spans with `promptVersion: staging-{timestamp}` and score them with `cx_score` as traces complete.
 

package/skills/brand/output-vibe.md

@@ -0,0 +1,48 @@
+---
+name: brand-output-vibe
+description: Use when drafting or exporting customer-facing artifacts (PRD, deck, brief, runbook). Sets typography, prose rhythm, sketch diagrams, and export consistency.
+inputs: [artifact-draft, export-target]
+artifactType: style-guide
+---
+
+# Output vibe (construct-modern)
+
+Apply this skill before drafting or exporting any customer-facing artifact (PRD, deck, brief, runbook, video script). User instructions always win; this sets the default feel.
+
+## Typography and color
+
+- Sans: Space Grotesk (400–700). Mono: JetBrains Mono for code, IDs, and tables.
+- Monochrome ink ramp only for page furniture: near-black body (`#23272e`), muted labels (`#565c66`), hairline rules (`#e3e4e8`). Color belongs in diagrams and data, not chrome.
+- Do not stamp "Construct" on external deliverables unless the user asks.
+
+## Prose rhythm
+
+- Lead with a short declarative paragraph, then structure (headings, one compact table, selective bullets).
+- Avoid bullet walls; never more than seven bullets in a row without a prose bridge.
+- Rare em dashes; prefer commas or parentheses.
+
+## Diagrams (sketch-forward)
+
+- Prefer hand-drawn / sketch aesthetic over rigid box-and-arrow clipart.
+- In Mermaid, open with a sketch theme block:
+
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#fafafa', 'primaryBorderColor': '#565c66', 'lineColor': '#23272e', 'fontFamily': 'Space Grotesk'}}}%%
+flowchart LR
+  User --> Product
+```
+
+- For high-touch user flows, an Excalidraw embed (`*.excalidraw` beside the doc) is acceptable when Mermaid feels too mechanical.
+- Every flowchart shows at least one non-happy path (error, escalation, or rollback).
+
+## Tables and metrics
+
+- Use tables for metrics, acceptance criteria, and comparisons — not for narrative.
+- Pin baselines and targets; cite sources or mark `[unverified]`.
+
+## Export parity
+
+- PDF/HTML/PPTX inherit the same fonts and ink ramp from distribution templates.
+- No stock clip-art icons; use simple line icons or typographic labels.
+
+When invoked at the start of a workflow skill, restate which vibe choices apply to this artifact type in one sentence, then proceed.

package/skills/docs/adr-workflow.md

@@ -30,3 +30,6 @@ Use when: an architectural decision is made that affects the system structure, d
 ## Cross-referencing
 - If this ADR supersedes another: update the old ADR's status field
 - If this ADR depends on another: add a References link
+## Release gate
+
+Run `construct artifact validate <path> --type=<type>` before marking the artifact approved.

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

@@ -21,3 +21,6 @@ Use when: product evidence should create or update Jira, Linear, GitHub Issues,
 ## Rules
 
 Never write externally from weak evidence without making the risk explicit. Never create duplicate issues when an existing issue can be updated.
+## Release gate
+
+Run `construct artifact validate <path> --type=<type>` before marking the artifact approved.