@geraldmaron/construct 1.2.2 → 1.3.0

package/rules/common/beads-hygiene.md

@@ -67,3 +67,55 @@ There is no authorized bypass. Beads hygiene is a release gate. If the tooling i
 ## Automation
 
 Project-level automation is tracked in the beads queue: auto-close on merge, pre-push `bd preflight` gate, weekly drift report, memory-contradiction detection. Until that ships, hygiene is a per-session discipline.
+
+## Execution protocol (construct-m7k2 / feature/team-redesign)
+
+Every child bead under epic `construct-m7k2` uses **double validation** before close. Definitions are normative for agents on any model tier (including smaller models).
+
+### Pass A — implementer
+
+The agent that claimed the bead and wrote the code:
+
+1. Run scoped tests cited in the bead acceptance criteria (`npm test` or `node --test tests/...`).
+2. Run bead-specific grep or CLI assertions listed in the bead body.
+3. Record command output in `bd note <id>` or the close reason (exit codes, failure counts).
+
+Pass A is not done if tests were not executed in this environment.
+
+### Pass B — reviewer (different model or fresh session)
+
+A different agent, or the same agent in a new session with no assumed memory of Pass A:
+
+1. Re-run every Pass A command independently (do not trust prior transcripts).
+2. Run `npm run release:check`.
+3. Run `construct doctor` — no new team/auth/MCP warnings attributable to the change.
+4. Confirm no `CONSTRUCT_SKIP_*` / `CONSTRUCT_ALLOW_*` env vars were introduced.
+
+Pass B is not done if `release:check` was not run.
+
+### Parallel runs — verify the committed branch, never a stray worktree
+
+When beads are implemented by parallel subagents in isolated git worktrees, the verify loop must check the **implementer's committed work**, not a fresh tree branched from the base:
+
+1. **Implementers commit to a named branch before review.** No uncommitted worktree state may gate a close — uncommitted work is invisible to a fresh reviewer and is lost when the worktree is pruned.
+2. **Reviewers check out and verify that exact branch** (or the integration branch after merge). A reviewer that branches from the base commit is verifying the *wrong tree*.
+3. **Integration merges the reviewed branch**, then re-runs the close evidence on the merged result.
+4. **Close evidence is reproduced on the merged branch** — e.g. grep the new symbol on the branch, not in a worktree. A symbol that exists only in a worktree is not landed.
+
+Failure mode this prevents (observed 2026-06-25): a bead was closed with a reason naming files that were never committed — the work was stranded uncommitted in a worktree, the reviewer branched from base and "passed" the pre-existing tests, and pruning the worktree discarded the work. A close reason must name only what is reproducible on the branch.
+
+### Baseline-diff close gate
+
+When the suite is not green (pre-existing unrelated failures), "all tests pass" is unsatisfiable and invites premature closes. Use a baseline-diff instead:
+
+1. Capture the failing-test set once at the start (e.g. `.cx/artifacts/baseline-fails.json`).
+2. A bead may close only if its scoped tests pass **and** the full suite introduces **zero new failures** vs the baseline. Newly-passing tests are a bonus, not a requirement.
+3. A test that fails on genuinely out-of-scope incomplete logic is marked `node:test` `todo` with a tracking bead id — flagged, not hidden — never silently skipped.
+
+### Bead body template
+
+Child beads must include sections: Goal, Read first, Out of scope, Steps, Acceptance criteria, Pass A checklist, Pass B checklist, Do not touch. See `construct-m7k2.9` for the gate bead that introduced this contract.
+
+### Gate bead
+
+Claim `construct-m7k2.9` first on the epic branch to land this section, then proceed to `construct-m7k2-fix-tests` and downstream work per the dependency graph.

package/rules/common/neurodivergent-output.md

@@ -1,11 +1,11 @@
 ---
 description: every human-facing Construct output is formatted for neurodivergent readers — without reshaping machine-readable output.
-enforced_by: (persona prompt), tests/term-format.test.mjs, construct dashboard:sync --check
+enforced_by: (persona prompt), tests/term-format.test.mjs
 precedence_tier: style
 ---
 # Neurodivergent-Friendly Output
 
-Construct's output is read under load — in a terminal, mid-task, often by people who process text differently. Dense walls of prose, buried conclusions, inconsistent structure, and meaning carried only by color cost every reader attention, and cost neurodivergent readers more. This rule applies to **every human-facing output** Construct produces: terminal output, agent prose to the user, reports, error messages, and the dashboard.
+Construct's output is read under load — in a terminal, mid-task, often by people who process text differently. Dense walls of prose, buried conclusions, inconsistent structure, and meaning carried only by color cost every reader attention, and cost neurodivergent readers more. This rule applies to **every human-facing output** Construct produces: terminal output, agent prose to the user, reports, and error messages.
 
 It is a `style` rule by design. The precedence resolver (`rules/common/precedence.md`) guarantees a style rule never overrides a higher tier — so when accessible formatting would conflict with correct machine output, correctness wins automatically. Section 0 states that boundary explicitly.
 
@@ -13,8 +13,8 @@ It is a `style` rule by design. The precedence resolver (`rules/common/precedenc
 
 Two layers, treated differently:
 
-- **Presentation layer (human-facing)** — section titles, prose, help text, report narratives, guidance notes, error wording, dashboard markup and CSS. This is what the rest of this rule shapes.
-- **Data layer (machine-readable)** — never reshape it for readability. Off-limits: any `--json` / `--plain` output; `specialists/registry.json`, `contracts.json`, `role-manifests.json`; the parsed tokens hooks emit (for example the session-start `## Working branch: **<name>**` line, the efficiency status enum `degraded` / `configured` / `healthy`, commit hashes, counts); auxiliary state JSON; any text one component parses out of another.
+- **Presentation layer (human-facing)** — section titles, prose, help text, report narratives, guidance notes, error wording. This is what the rest of this rule shapes.
+- **Data layer (machine-readable)** — never reshape it for readability. Off-limits: any `--json` / `--plain` output; `specialists/org`, `contracts.json`, `role-manifests.json`; the parsed tokens hooks emit (for example the session-start `## Working branch: **<name>**` line, the efficiency status enum `degraded` / `configured` / `healthy`, commit hashes, counts); auxiliary state JSON; any text one component parses out of another.
 
 When a format choice would change a value, key, ordering, or token that something downstream parses, do not make it. Accessibility is presentation; it never edits the contract.
 
@@ -47,19 +47,16 @@ End human-facing output with the current state and the next action in plain word
 - Meaning carried by color must also be carried by text, shape, or label. A red number is also labelled `error`; a green check is also the word `passed`.
 - Honor `NO_COLOR`, non-TTY, and `TERM=dumb`: degrade to plain text, never to nothing.
 - Respect terminal width — wrap rather than overflow.
-- On the dashboard, honor `prefers-reduced-motion` and `prefers-color-scheme`; motion is never required to understand state, and animation can be fully disabled.
 
 ## Applies to
 
 - **Terminal / CLI** — help text, status, reports, hook display. Routed through the shared formatter (`lib/term-format.mjs`); color and width handled there, never per-call.
 - **Agent prose** — every response Construct and its specialists return to the user.
-- **Dashboard** — `apps/dashboard/` source (semantic landmarks, labels, focus, contrast, reduced-motion), rebuilt into `lib/server/static/`.
 
 ## Enforcement
 
 - Persona prompt: `personas/construct.md` carries the output-style directive; specialists inherit the standard through the front-door agent.
 - `tests/term-format.test.mjs` asserts the terminal formatter honors `NO_COLOR` / non-TTY and that machine-readable `--json` output is unchanged by presentation changes.
-- `construct dashboard:sync --check` keeps the built dashboard in step with the accessible source.
 
 ## Bypass
 

package/rules/common/research.md

@@ -58,6 +58,8 @@ Start with the narrowest authoritative source that can answer the question:
 4. **Tertiary sources last**
    - blogs, forums, Q&A, analyst summaries, AI-generated summaries
 
+When the research is specifically about a library/framework/API/cloud-docs surface, a docs MCP such as Context7 is an acceptable way to reach the official documentation. It is a retrieval path, not the evidence standard. If that MCP is unavailable or incomplete, fall back to direct web search and fetch against the official docs, changelog, and release notes. Do not block research on the presence of a single docs integration.
+
 ## 4. Required metadata for every source
 
 Record:

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;
@@ -920,12 +1067,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 +1120,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 +1198,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 +1276,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 +1426,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 +1510,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 +1708,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 +1786,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 +1801,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 +1828,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 +1857,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 +1890,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 +1982,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 +2152,7 @@ function syncSkills(targetDir = null) {
 
 // --- Main ---
 
+if (isMain) {
 const entries = buildEntries();
 
 if (COMPRESS_PERSONAS) {
@@ -2035,3 +2245,4 @@ try {
 } finally {
   releaseLock();
 }
+}