@geraldmaron/construct 1.2.2 → 1.3.0

package/lib/parity.mjs

@@ -3,7 +3,7 @@
  *
  * After `construct sync` writes adapters to multiple surfaces (Claude Code,
  * OpenCode, Codex, Copilot, VS Code, Cursor), the module diffs each surface's actual state against the
- * canonical `specialists/registry.json`. Backs `construct doctor` for surfacing
+ * canonical `specialists/org`. Backs `construct doctor` for surfacing
  * silent divergence — for instance, an agent added to the registry that
  * never made it to OpenCode because of a sync regression.
  *
@@ -62,9 +62,10 @@ function readJsoncFile(file) {
   return parseJsonc(fs.readFileSync(file, 'utf8'));
 }
 
+import { loadRegistry as loadAssembledRegistry } from './registry/loader.mjs';
+
 function loadRegistry(rootDir = ROOT_DIR) {
-  const file = path.join(rootDir, 'specialists', 'registry.json');
-  return JSON.parse(fs.readFileSync(file, 'utf8'));
+  return loadAssembledRegistry({ rootDir });
 }
 
 function adapterName(entry, prefix) {
@@ -74,18 +75,30 @@ function adapterName(entry, prefix) {
 function entriesForSurface(registry, surface, { scope = 'global' } = {}) {
   const prefix = registry.prefix || 'cx';
 
+  // Support both legacy format (registry.orchestrator) and unified format
+  // (orchestrator lives in registry.specialists with role:'orchestrator').
+  // Unified format stores name:'orchestrator' but the adapter name is 'construct'
+  // (hardcoded in unifiedToLegacyRegistry) — normalize it here so parity matches.
+  const rawOrchestrator = registry.orchestrator
+    || Object.values(registry.specialists || {}).find((s) => s.role === 'orchestrator');
+  const orchestratorEntry = rawOrchestrator && rawOrchestrator.name !== 'construct'
+    ? { ...rawOrchestrator, name: 'construct' }
+    : rawOrchestrator;
+
   // User-scope expects only the `construct` front-door agent. Specialists
-  // live with each Construct-managed project (apps/dashboard, apps/docs,
+  // live with each Construct-managed project (apps/docs,
   // and every other repo that runs `construct init`) — see the two-tier
   // sync contract in scripts/sync-specialists.mjs.
 
   const entries = scope === 'project'
     ? [
-        ...(registry.orchestrator ? [{ ...registry.orchestrator, isPersona: true }] : []),
-        ...(registry.specialists || []).map((s) => ({ ...s, isPersona: false })),
+        ...(orchestratorEntry ? [{ ...orchestratorEntry, isPersona: true }] : []),
+        ...Object.values(registry.specialists || {})
+          .filter((s) => s.role !== 'orchestrator')
+          .map((s) => ({ ...s, isPersona: false })),
       ]
-    : registry.orchestrator
-      ? [{ ...registry.orchestrator, isPersona: true }]
+    : orchestratorEntry
+      ? [{ ...orchestratorEntry, isPersona: true }]
       : [];
 
   return entries
@@ -171,6 +184,19 @@ function checkClaude(registry, { homeDir = os.homedir() } = {}) {
 
 const OPENCODE_BUILTIN_AGENTS = new Set(['title', 'summary', 'compaction']);
 
+function normalizeOpenCodeManagedAgents(actual, expected) {
+  const managed = actual.filter((id) => !OPENCODE_BUILTIN_AGENTS.has(id));
+  const expectsConstruct = expected.length === 1 && expected[0] === 'construct';
+  if (!expectsConstruct) return managed;
+  if (managed.includes('construct')) {
+    return managed.filter((id) => id !== 'orchestrator');
+  }
+  if (managed.length === 1 && managed[0] === 'orchestrator') {
+    return ['construct'];
+  }
+  return managed;
+}
+
 function checkOpenCode(registry, { homeDir = os.homedir() } = {}) {
   const file = path.join(homeDir, '.config', 'opencode', 'opencode.json');
   if (!fs.existsSync(file)) return { surface: 'opencode', kind: 'agents', status: 'absent', file };
@@ -181,8 +207,8 @@ function checkOpenCode(registry, { homeDir = os.homedir() } = {}) {
     return { surface: 'opencode', kind: 'agents', status: 'unreadable', file, error: err.message };
   }
   const expected = entriesForSurface(registry, 'opencode');
-  const actual = Object.keys(config.agent || config.agents || {})
-    .filter((id) => !OPENCODE_BUILTIN_AGENTS.has(id));
+  const rawActual = Object.keys(config.agent || config.agents || {});
+  const actual = normalizeOpenCodeManagedAgents(rawActual, expected);
   const { missing, extra } = diffSets(expected, actual);
 
   // OpenCode's own system agents (title/summary/compaction) are filtered from
@@ -379,7 +405,7 @@ export function checkProjectParity({ rootDir = ROOT_DIR, projectDir = rootDir }
 // an upgrade," not real drift.
 function legacyUserScopeRoster(registry) {
   const prefix = registry.prefix || 'cx';
-  const specialists = (registry.specialists || []).map((s) => `${prefix}-${s.name}`);
+  const specialists = Object.values(registry.specialists || {}).map((s) => `${prefix}-${s.name}`);
   // The front-door agent is project-scoped too now, so a leftover `construct.md`
   // in user-scope `.claude/agents` is a soft upgrade state, not real drift.
   const frontDoor = registry.orchestrator?.name ? [registry.orchestrator.name] : [];

package/lib/policy/engine.mjs

@@ -1,37 +1,88 @@
 /**
  * lib/policy/engine.mjs — role-based policy decisions for tool / action access.
  *
- * Reads role permissions from `specialists/role-manifests.json` and decides
+ * Reads role permissions from the unified registry and decides
  * whether a given (role, project, tool, action, risk) tuple is allowed,
  * needs approval, or is denied outright. Powers the MCP broker for team
  * and enterprise deployments; solo mode leaves the broker off so this
  * engine returns allow-without-approval everywhere.
  *
  * Decision precedence:
- *   1. Explicit deny in the role's fence → denied + typed reason.
- *   2. Action falls in the role's approvalRequired list → allowed but
+ *   1. Team-level decisions gate specialist decisions — forbidden by team blocks the action.
+ *   2. Explicit deny in the role's fence → denied + typed reason.
+ *   3. Action falls in the role's approvalRequired list → allowed but
  *      approvalRequired = true (UI must collect human consent).
- *   3. risk === 'high' and role is not in HIGH_RISK_AUTONOMOUS → approval required.
- *   4. Otherwise → allowed.
+ *   4. risk === 'high' and role is not in HIGH_RISK_AUTONOMOUS → approval required.
+ *   5. Otherwise → allowed.
  */
 
 import { readFileSync, existsSync } from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
-const DEFAULT_MANIFEST_PATH = path.join(MODULE_DIR, '..', '..', 'specialists', 'role-manifests.json');
+import { loadRegistry } from '../registry/loader.mjs';
 
 const HIGH_RISK_AUTONOMOUS = new Set(['security', 'sre', 'release-manager']);
 
 let cachedManifests = null;
 
-export function loadRoleManifests(manifestPath = DEFAULT_MANIFEST_PATH) {
-  if (cachedManifests && cachedManifests.path === manifestPath) return cachedManifests.data;
-  if (!existsSync(manifestPath)) {
-    cachedManifests = { path: manifestPath, data: { personas: {} } };
+/**
+ * Find the team that owns a specialist/role.
+ * Returns the team id if found, null otherwise.
+ */
+function findTeamForRole(roleId, registry) {
+  if (!registry || !registry.teams) return null;
+  for (const [teamId, team] of Object.entries(registry.teams)) {
+    if (Array.isArray(team.roles) && team.roles.includes(roleId)) {
+      return teamId;
+    }
+  }
+  return null;
+}
+
+/**
+ * Check if a role can make a decision at the team level.
+ * Returns { allowed: boolean, reason: string }.
+ */
+function canRoleDecide(roleId, decisionId, registry) {
+  const teamId = findTeamForRole(roleId, registry);
+  if (!teamId) return { allowed: true, reason: 'no-team-restriction' };
+
+  const team = registry.teams[teamId];
+  if (!team) return { allowed: true, reason: 'team-not-found' };
+
+  // Check forbidden decisions first — explicit blocks override everything
+  if (Array.isArray(team.forbiddenDecisions) && team.forbiddenDecisions.includes(decisionId)) {
+    return { allowed: false, reason: 'forbidden-by-team' };
+  }
+
+  // Check allowed decisions — team must explicitly grant it
+  if (Array.isArray(team.decisionRights) && team.decisionRights.includes(decisionId)) {
+    return { allowed: true, reason: 'authorized-by-team' };
+  }
+
+  // Default: if team doesn't forbid, allow (permissive default)
+  return { allowed: true, reason: 'not-restricted-by-team' };
+}
+
+export function loadRoleManifests(manifestPath) {
+  // Unified registry is canonical. Explicit manifestPath overrides exist only for tests.
+  if (!manifestPath || !existsSync(manifestPath)) {
+    const manifestPathKey = manifestPath || '__unified_registry__';
+    if (cachedManifests && cachedManifests.path === manifestPathKey) return cachedManifests.data;
+    const registry = loadRegistry();
+    const personas = {};
+    for (const [specId, spec] of Object.entries(registry.specialists || {})) {
+      const personaId = specId.replace(/^cx-/, '');
+      const teamId = findTeamForRole(personaId, registry);
+      personas[personaId] = {
+        events: spec.events || [],
+        fence: spec.fence || {},
+        outputs: { docTypes: spec.docArtifacts || [] },
+        teamId: teamId || null,
+      };
+    }
+    cachedManifests = { path: manifestPathKey, data: { personas, registry } };
     return cachedManifests.data;
   }
+  if (cachedManifests && cachedManifests.path === manifestPath) return cachedManifests.data;
   const raw = readFileSync(manifestPath, 'utf8');
   const data = JSON.parse(raw);
   cachedManifests = { path: manifestPath, data };
@@ -72,12 +123,13 @@ function needsApprovalFromManifest(action, manifest) {
  * @param {string} [input.project]
  * @param {string} input.tool
  * @param {string} input.action
+ * @param {string} [input.decision] — optional decision id for team-level gate
  * @param {string} [input.risk]
  * @param {object} [opts]
  * @returns {{allowed: boolean, reason: string, approvalRequired: boolean, source: string}}
  */
 export function policyDecision(input = {}, opts = {}) {
-  const { role, tool, action, risk = 'low' } = input;
+  const { role, tool, action, decision, risk = 'low' } = input;
   if (!role) return { allowed: false, reason: 'role is required', approvalRequired: false, source: 'engine' };
   if (!tool) return { allowed: false, reason: 'tool is required', approvalRequired: false, source: 'engine' };
   if (!action) return { allowed: false, reason: 'action is required', approvalRequired: false, source: 'engine' };
@@ -94,6 +146,19 @@ export function policyDecision(input = {}, opts = {}) {
     };
   }
 
+  // Team decision gate: if a decision id is supplied, check team-level authorization first
+  if (decision && manifests.registry) {
+    const teamDecision = canRoleDecide(role, decision, manifests.registry);
+    if (!teamDecision.allowed) {
+      return {
+        allowed: false,
+        reason: `decision "${decision}" forbidden for team of role "${role}": ${teamDecision.reason}`,
+        approvalRequired: false,
+        source: 'team.forbiddenDecisions',
+      };
+    }
+  }
+
   if (isExplicitlyDenied(action, manifest)) {
     return {
       allowed: false,

package/lib/prompt-composer.js

@@ -38,6 +38,8 @@ import { readRoleFile } from './role-preload.mjs';
 import { estimateTokens, estimatePromptTokens, estimateTokensSync } from './token-engine.js';
 import { cxDir } from './paths.mjs';
 import { getStrategyDigestSync } from './strategy-store.mjs';
+import { loadRegistry } from './registry/loader.mjs';
+import { bindingForSpecialist, resolveRoleOverlayId } from './roles/flavor-bindings.mjs';
 
 const MAX_OBSERVATIONS = 3;
 
@@ -46,6 +48,7 @@ const PRIORITY = {
   'core': 1,
   'task-packet': 1,
   'role-flavor': 2,
+  'team-context': 2,
   'model-profile': 2,
   'context-digest': 3,
   'strategy': 3,
@@ -55,23 +58,13 @@ const PRIORITY = {
 
 // workspaceType → roleFlavors auto-selection when caller doesn't override
 const WORKSPACE_FLAVOR_MAP = {
-  platform: { productManager: 'platform', architect: 'platform', engineer: 'platform' },
+  platform: { productManager: 'platform', architect: 'platform', platformEngineer: 'core' },
   enterprise: { productManager: 'enterprise', architect: 'enterprise' },
   'ai-product': { productManager: 'ai-product', architect: 'ai-systems' },
   growth: { productManager: 'growth' },
   product: {},
 };
 
-const AGENT_FLAVOR_MAP = {
-  engineer: { classifierKey: 'engineer', rolePrefix: 'engineer' },
-  architect: { classifierKey: 'architect', rolePrefix: 'architect' },
-  'product-manager': { classifierKey: 'productManager', rolePrefix: 'product-manager' },
-  qa: { classifierKey: 'qa', rolePrefix: 'qa' },
-  security: { classifierKey: 'security', rolePrefix: 'security' },
-  'data-analyst': { classifierKey: 'dataAnalyst', rolePrefix: 'data-analyst' },
-  'data-engineer': { classifierKey: 'dataEngineer', rolePrefix: 'data-engineer' },
-};
-
 // Merge workspaceType-derived overlays with explicit roleFlavors. Explicit always wins.
 function resolveRoleFlavors(roleFlavors, workspaceType, shortName) {
   const workspaceDefaults = workspaceType ? (WORKSPACE_FLAVOR_MAP[workspaceType] ?? {}) : {};
@@ -181,6 +174,14 @@ export function resolvePromptContract(entryOrName, {
     };
   }
 
+  if (directEntry?.promptFile) {
+    const body = stripSectionMarkers(readPromptBody(directEntry.promptFile, rootDir));
+    return {
+      prompt: body || fallback,
+      metadata: resolvePromptMetadata(directEntry.name, { rootDir, registry }),
+    };
+  }
+
   const agentName = directEntry?.name || entryOrName;
   if (!agentName) return { prompt: fallback, metadata: {} };
 
@@ -191,6 +192,27 @@ export function resolvePromptContract(entryOrName, {
   };
 }
 
+function buildTeamBlock(entry, registry, { tokenLimit = 200, modelId = 'default' } = {}) {
+  if (!entry?.team || !registry?.teams) return null;
+  const squad = registry.teams[entry.team];
+  if (!squad) return null;
+  const groupId = squad.groupId || entry.groupId;
+  const group = groupId ? registry.teams[groupId] : null;
+  const collaborators = (squad.collaborators || []).filter(Boolean);
+  const lines = [
+    '## Team context',
+    '',
+    `Squad: **${squad.name || squad.id}** (\`${squad.id}\`)`,
+  ];
+  if (group) lines.push(`Group: **${group.name || groupId}** (\`${groupId}\`)`);
+  if (squad.charter) lines.push('', compactTokens(squad.charter, tokenLimit, { modelId }));
+  if (collaborators.length) {
+    lines.push('', `Collaborators: ${collaborators.map((c) => `\`${c}\``).join(', ')}`);
+  }
+  lines.push('', 'Invoke sibling squad specialists when work crosses squad boundaries. Call `suggest_skills` when the task domain is ambiguous.');
+  return lines.join('\n');
+}
+
 export function composePrompt(agentName, {
   rootDir = process.cwd(),
   registry,
@@ -219,8 +241,20 @@ export function composePrompt(agentName, {
 
   fragments.push({ type: 'core', priority: PRIORITY['core'], label: entry.name, content: stripSectionMarkers(readPromptBody(entry.promptFile, rootDir)), tokenBudget: null });
 
+  const resolvedRegistry = registry || loadRegistry({ rootDir });
+  const teamBlock = buildTeamBlock(entry, resolvedRegistry, { modelId });
+  if (teamBlock) {
+    fragments.push({
+      type: 'team-context',
+      priority: PRIORITY['team-context'],
+      label: entry.team,
+      content: teamBlock,
+      tokenBudget: 200,
+    });
+  }
+
   const shortName = String(agentName).replace(/^cx-/, '');
-  const flavorMapping = AGENT_FLAVOR_MAP[shortName];
+  const flavorMapping = bindingForSpecialist(shortName);
 
   // When workspaceType is provided and roleFlavors doesn't already specify this agent's flavor,
   // auto-select the matching overlay so agents get domain guidance without requiring explicit caller config.
@@ -229,7 +263,8 @@ export function composePrompt(agentName, {
   if (flavorMapping && effectiveRoleFlavors) {
     const flavor = effectiveRoleFlavors[flavorMapping.classifierKey];
     if (flavor) {
-      const overlayBody = readRoleFile(rootDir, `${flavorMapping.rolePrefix}.${flavor}`, {
+      const roleId = resolveRoleOverlayId(flavorMapping, flavor);
+      const overlayBody = readRoleFile(rootDir, roleId, {
         source: 'prompt-composer',
         callerContext: agentName,
       });
@@ -240,8 +275,8 @@ export function composePrompt(agentName, {
         fragments.push({
           type: 'role-flavor',
           priority: PRIORITY['role-flavor'],
-          label: `${flavorMapping.rolePrefix}.${flavor}`,
-          content: `### ${flavor} domain guidance\n\n${overlayContent}`,
+          label: roleId,
+          content: `### ${flavor === 'core' ? shortName : flavor} domain guidance\n\n${overlayContent}`,
           tokenBudget: selectedProfile.roleFlavorTokens,
         });
       }
@@ -484,6 +519,7 @@ export function summarizePromptComposition(agentName, options = {}) {
       routeIntent: route.intent,
       routeTrack: route.track,
       routeWorkCategory: route.workCategory,
+      routeSuggestedWorkflowType: route.suggestedWorkflowType || null,
       routeSpecialists: route.specialists,
       routeDispatchPlan: route.dispatchPlan,
       ...(route.roleFlavors ? { routeRoleFlavors: route.roleFlavors } : {}),

package/lib/prompt-metadata.mjs

@@ -6,6 +6,7 @@
  * the telemetry backend instead of embedding full production prompt text in every trace.
  */
 import crypto from 'node:crypto';
+import { loadRegistry } from './registry/loader.mjs';
 import fs from 'node:fs';
 import path from 'node:path';
 
@@ -26,7 +27,7 @@ function findEntry(registry, agentName) {
   const normalized = normalizeName(agentName);
   const entries = [
     registry.orchestrator,
-    ...(registry.specialists ?? []),
+    ...Object.values(registry.specialists ?? {}),
   ].filter(Boolean);
   return entries.find((entry) => {
     const entryName = normalizeName(entry.name);
@@ -36,7 +37,7 @@ function findEntry(registry, agentName) {
 
 export function resolvePromptEntry(agentName, { rootDir = process.cwd(), registry } = {}) {
   if (!agentName) return null;
-  const loadedRegistry = registry ?? readJson(path.join(rootDir, 'specialists', 'registry.json'));
+  const loadedRegistry = registry ?? loadRegistry({ rootDir });
   if (!loadedRegistry) return null;
   return findEntry(loadedRegistry, agentName);
 }

package/lib/providers/connection-probe.mjs

@@ -0,0 +1,58 @@
+/**
+ * lib/providers/connection-probe.mjs — lightweight provider auth probes for doctor and tests.
+ *
+ * Issues a minimal HTTP request per API-key provider to distinguish valid keys from
+ * auth failures. Uses injectable fetch so functional tests stay hermetic.
+ */
+
+import { resolveFirstSecret } from './secret-resolver.mjs';
+
+const OPENROUTER_MODELS = 'https://openrouter.ai/api/v1/models';
+const ANTHROPIC_MODELS = 'https://api.anthropic.com/v1/models';
+const OPENAI_MODELS = 'https://api.openai.com/v1/models';
+
+function classifyStatus(status) {
+  if (status === 401 || status === 403) return 'auth_error';
+  if (status >= 200 && status < 300) return 'ok';
+  if (status === 429) return 'rate_limited';
+  return 'probe_failed';
+}
+
+async function probeGet(url, headers, fetchImpl) {
+  const res = await fetchImpl(url, { method: 'GET', headers });
+  return { ok: classifyStatus(res.status) === 'ok', status: res.status, code: classifyStatus(res.status) };
+}
+
+export async function probeProviderConnection(providerId, { env = process.env, cwd = process.cwd(), allowAmbient = true, fetch: fetchImpl = globalThis.fetch } = {}) {
+  if (!fetchImpl) {
+    return { ok: false, code: 'fetch_unavailable', status: null, provider: providerId };
+  }
+
+  const secretOpts = { env, cwd, allowAmbient };
+
+  if (providerId === 'openrouter') {
+    const apiKey = resolveFirstSecret(['OPENROUTER_API_KEY', 'OPEN_ROUTER_API_KEY'], secretOpts);
+    if (!apiKey) return { ok: false, code: 'missing_key', status: null, provider: providerId };
+    return { provider: providerId, ...(await probeGet(OPENROUTER_MODELS, { Authorization: `Bearer ${apiKey}` }, fetchImpl)) };
+  }
+
+  if (providerId === 'anthropic') {
+    const apiKey = resolveFirstSecret(['ANTHROPIC_API_KEY'], secretOpts);
+    if (!apiKey) return { ok: false, code: 'missing_key', status: null, provider: providerId };
+    return {
+      provider: providerId,
+      ...(await probeGet(ANTHROPIC_MODELS, {
+        'x-api-key': apiKey,
+        'anthropic-version': '2023-06-01',
+      }, fetchImpl)),
+    };
+  }
+
+  if (providerId === 'openai') {
+    const apiKey = resolveFirstSecret(['OPENAI_API_KEY'], secretOpts);
+    if (!apiKey) return { ok: false, code: 'missing_key', status: null, provider: providerId };
+    return { provider: providerId, ...(await probeGet(OPENAI_MODELS, { Authorization: `Bearer ${apiKey}` }, fetchImpl)) };
+  }
+
+  return { ok: false, code: 'unsupported_provider', status: null, provider: providerId };
+}

package/lib/providers/copilot-auth.mjs

@@ -283,7 +283,7 @@ export function __resetCopilotCache() {
   sessionCache = null;
 }
 
-// Exchange probe used at chat launch — a configured Copilot pin is not enough if
+// Exchange probe used at host launch — a configured Copilot pin is not enough if
 // the session token cannot be minted (stale oauth, whitespace-corrupt store).
 
 export async function preflightCopilotSession({ fetchImpl = fetch } = {}) {

package/lib/providers/credential-bootstrap.mjs

@@ -2,7 +2,7 @@
  * lib/providers/credential-bootstrap.mjs — lazy credential linking for Construct.
  *
  * Before any LLM surface runs, missing API keys can be satisfied from existing
- * stores or a one-time 1Password link into ~/.construct/config.env. Runs at
+ * stores or a one-time 1Password link into the XDG config.env. Runs at
  * the construct CLI entrypoint in presence-check mode; op item list runs only
  * when autoLink:true (scripts/setup-credentials.mjs).
  */

package/lib/providers/op-run.mjs

@@ -2,12 +2,11 @@
  * lib/providers/op-run.mjs — optionally launch a child under 1Password `op run`.
  *
  * When CONSTRUCT_OP_ENV_FILE points to an `op run` env-file (KEY=op://… lines)
- * and the `op` CLI is installed, long-lived Construct services — the dashboard
- * daemon that runs chat turns — are spawned through
+ * and the `op` CLI is installed, long-lived Construct services are spawned through
  * `op run --no-masking --env-file <file> -- <cmd>`, so op:// references resolve
  * once at startup into the process env. This mirrors the per-invocation model
- * other LLM CLIs use (e.g. `op run -- opencode`) and means a bare `construct chat`
- * gets resolved provider keys without a shell wrapper.
+ * other LLM CLIs use (e.g. `op run -- opencode`) and gives child processes
+ * resolved provider keys without a shell wrapper.
  *
  * Strictly opt-in: with the var unset, the file missing, or `op` absent, the
  * command is returned unchanged and 1Password is never invoked. No other setup

package/lib/providers/secret-resolver.mjs

@@ -109,6 +109,35 @@ function readShellRcVar(varName, home) {
   return null;
 }
 
+function expandHomePath(file, home) {
+  if (file === '~') return home;
+  if (file.startsWith('~/')) return `${home}${file.slice(1)}`;
+  return file;
+}
+
+function readOpEnvCatalogPath({ env, home }) {
+  const pointerSources = [
+    env?.CONSTRUCT_OP_ENV_FILE,
+    readDotenvVar(path.join(configDir(home), 'config.env'), 'CONSTRUCT_OP_ENV_FILE'),
+    readDotenvVar(path.join(home, '.construct', 'config.env'), 'CONSTRUCT_OP_ENV_FILE'),
+  ].filter((value) => typeof value === 'string' && value.length > 0);
+  for (const raw of pointerSources) {
+    const file = expandHomePath(unquote(raw), home);
+    try {
+      if (fs.existsSync(file)) return file;
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+function readFromOpEnvCatalog(varName, { env, home }) {
+  const catalogPath = readOpEnvCatalogPath({ env, home });
+  if (!catalogPath) return null;
+  return readDotenvVar(catalogPath, varName);
+}
+
 function rawCandidate(varName, { env, cwd, home }) {
   const direct = env?.[varName];
   if (typeof direct === 'string' && direct.length > 0) return direct;
@@ -119,6 +148,8 @@ function rawCandidate(varName, { env, cwd, home }) {
   }
   const alt = discoverAlternateRawForVar(varName, { home });
   if (alt) return alt;
+  const fromOpCatalog = readFromOpEnvCatalog(varName, { env, home });
+  if (fromOpCatalog) return fromOpCatalog;
   return readShellRcVar(varName, home);
 }
 

package/lib/publish-tooling.mjs

@@ -1,9 +1,9 @@
 /**
  * lib/publish-tooling.mjs — detect optional binaries for the publish pipeline.
  *
- * Composes export (Pandoc/Typst), diagram (D2/mmdc), terminal demo (VHS), and
- * dashboard demo (Playwright workspace) probes for `construct tools detect`,
- * `construct publish --strict`, and doctor one-shot checks.
+ * Composes export (Pandoc/Typst), diagram (D2/mmdc), and terminal demo (VHS)
+ * probes for `construct tools detect`, `construct publish --strict`, and doctor
+ * one-shot checks.
  */
 
 import fs from 'node:fs';
@@ -13,7 +13,6 @@ import { fileURLToPath } from 'node:url';
 import { detect as detectExport } from './document-export.mjs';
 import { locateRenderer } from './diagram.mjs';
 import { locateRecorder } from './demo.mjs';
-import { detectDashboardDemo } from './dashboard-demo.mjs';
 import { detectIngestPipeline } from './ingest-tooling.mjs';
 
 const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -56,7 +55,6 @@ export function detectPublishPipeline({
   format = 'pdf',
   includeFigures = true,
   includeTerminalDemo = false,
-  includeDashboardDemo = false,
   includeIngest = true,
   cwd = process.cwd(),
   repoRoot = REPO_ROOT,
@@ -89,12 +87,6 @@ export function detectPublishPipeline({
     if (!recorder) missing.push('vhs');
   }
 
-  if (includeDashboardDemo) {
-    const dashboard = detectDashboardDemo({ cwd, repoRoot: REPO_ROOT });
-    steps.dashboardDemo = dashboard;
-    if (!dashboard.present) missing.push(...dashboard.missing);
-  }
-
   const uniqueMissing = [...new Set(missing)];
   return {
     ok: true,