@geraldmaron/construct 1.3.2 → 1.4.1

package/lib/visual-review.mjs

@@ -0,0 +1,70 @@
+/**
+ * lib/visual-review.mjs — Rubric registry and the visually-reviewed evidence contract.
+ *
+ * A visual review is recordable only from a real captured screenshot, a named rubric, and a
+ * reviewer verdict — never inferred from source text. recordVisualReview throws unless it is handed
+ * screenshot-captured evidence with no degradation, so the visually-reviewed rung cannot be forged
+ * without a rendered image. The verdict rides in the proof and gates the later approved rung; the
+ * review itself (model or human judgment) is supplied by the caller, not fabricated here.
+ */
+import { makeEvidence } from './artifact-completion.mjs';
+
+export const VERDICTS = Object.freeze(['pass', 'needs-changes', 'fail']);
+
+export const RUBRICS = Object.freeze({
+  'document-v1': {
+    id: 'document-v1',
+    applies: ['pdf', 'docx', 'html'],
+    criteria: ['spacing and visual rhythm', 'visual hierarchy and scan-ability', 'reading order sanity'],
+  },
+  'deck-v1': {
+    id: 'deck-v1',
+    applies: ['pptx', 'deck'],
+    criteria: ['slide density', 'font legibility at slide distance', 'no clipped or overflowing content'],
+  },
+  'diagram-v1': {
+    id: 'diagram-v1',
+    applies: ['mermaid', 'd2'],
+    criteria: ['purpose is clear', 'labels are readable', 'density is manageable', 'non-happy path shown where relevant'],
+  },
+});
+
+export function makeVisualReview({ rubricId, image, verdict, reviewer, notes = '' } = {}) {
+  if (!RUBRICS[rubricId]) {
+    throw new Error(`unknown rubric: ${rubricId} (expected one of ${Object.keys(RUBRICS).join(', ')})`);
+  }
+  if (typeof image !== 'string' || image.length === 0) {
+    throw new Error('visual review requires a rendered image path');
+  }
+  if (!VERDICTS.includes(verdict)) {
+    throw new Error(`unknown verdict: ${verdict} (expected one of ${VERDICTS.join(', ')})`);
+  }
+  if (typeof reviewer !== 'string' || reviewer.length === 0) {
+    throw new Error('visual review requires a reviewer');
+  }
+  return Object.freeze({ rubricId, image, verdict, reviewer, notes });
+}
+
+// The review must trace to a real captured screenshot; handing in anything else (a degraded
+// render, or no evidence at all) throws, so visually-reviewed is unreachable from source alone.
+
+export function recordVisualReview({ screenshotEvidence, review, actor = 'construct-review' } = {}) {
+  if (!screenshotEvidence
+    || screenshotEvidence.state !== 'screenshot-captured'
+    || screenshotEvidence.degradation) {
+    throw new Error('visual review requires non-degraded screenshot-captured evidence (no source inference)');
+  }
+  if (!review || !RUBRICS[review.rubricId] || !VERDICTS.includes(review.verdict)) {
+    throw new Error('visual review requires a valid review report');
+  }
+  return makeEvidence('visually-reviewed', {
+    actor,
+    artifact: screenshotEvidence.artifact,
+    proof: {
+      rubricId: review.rubricId,
+      image: review.image,
+      verdict: review.verdict,
+      reviewer: review.reviewer,
+    },
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geraldmaron/construct",
-  "version": "1.3.2",
+  "version": "1.4.1",
   "type": "module",
   "packageManager": "npm@11.5.1",
   "description": "Construct — agent orchestration layer for OpenCode, Claude Code, and other coding surfaces",

package/scripts/sync-specialists.mjs

@@ -448,6 +448,13 @@ const standardConstructTools = [
   "cx_trace",
   "cx_score",
 ].join(",");
+
+// The orchestrator's atomic contract is classify-then-dispatch: orchestration_policy
+// then orchestration_run. On allowlist hosts (Claude) these must be named in the
+// agent's tools list or the call is blocked, leaving the orchestrator unable to route.
+// Single source of truth so every host's orchestrator grant stays in parity.
+
+const ORCHESTRATOR_DISPATCH_TOOLS = ["orchestration_policy", "orchestration_run"];
 const managedStart = `# BEGIN ${systemName.toUpperCase()} AGENTS`;
 const managedEnd = `# END ${systemName.toUpperCase()} AGENTS`;
 const mdManagedStart = `<!-- BEGIN ${systemName.toUpperCase()} AGENTS -->`;
@@ -765,7 +772,8 @@ function orchestrationMicroPrompt(platform) {
     `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.`
+    `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.\n\n` +
+    `If a request needs a capability you lack — live web/network access, external data, code execution — do not refuse or tell the user to run it themselves. Route it via \`${runTool}\` to the specialist that holds the capability (web access lives with the researcher), or ask one clarifying question when the target is ambiguous.`
   );
 }
 
@@ -984,6 +992,13 @@ function claudeAgentMarkdown(entry, allEntries) {
     ...baseTools.split(",").map((t) => t.trim()),
     ...standardConstructTools.split(","),
   ]);
+
+  // Claude's tools list is a hard allowlist; the orchestrator can only route if its
+  // dispatch tools are named here.
+
+  if (entry.isOrchestrator) {
+    for (const tool of ORCHESTRATOR_DISPATCH_TOOLS) toolSet.add(tool);
+  }
   const tools = Array.from(toolSet).filter(Boolean).join(",");
 
   return `---
@@ -1346,6 +1361,40 @@ When using this prompt, stay within the role above and adapt to the current repo
 `;
 }
 
+// VS Code reads custom agents (the renamed successor to chat modes) from
+// .github/agents/<name>.agent.md, and tool grants must use its namespaced ids:
+// <server>/* for an MCP server's tools, web/fetch for outbound web, search/read
+// for repo awareness. The Claude-format tools in .claude/agents/*.md are not
+// recognized here, so the orchestrator needs its own VS Code agent or it lists
+// in the picker with no usable tools.
+
+const COPILOT_AGENT_TOOLS = [
+  "construct-mcp/*",
+  "web/fetch",
+  "web/githubRepo",
+  "search/codebase",
+  "search/usages",
+  "search/fileSearch",
+  "read/problems",
+  "edit/editFiles",
+];
+
+function copilotAgentFile(entry, allEntries) {
+  const name = adapterName(entry);
+  return `---
+description: ${entry.description}
+name: ${name}
+tools: ${JSON.stringify(COPILOT_AGENT_TOOLS)}
+---
+
+${generatedMarkdownNote}
+
+# ${name}
+
+${buildPrompt(entry, allEntries, "copilot")}
+`;
+}
+
 function syncCopilot(entries, targetDir = null, wants = true) {
   const promptsDir = targetDir
     ? path.join(targetDir, ".github", "prompts")
@@ -1362,15 +1411,20 @@ function syncCopilot(entries, targetDir = null, wants = true) {
     sweepLegacyPrefixedFiles(promptsDir, ".prompt.md", writeEntries.map((e) => `${adapterName(e)}.prompt.md`));
   }
 
-  // VS Code / Copilot agent mode reads the project's `.claude/agents/*.md`
-  // natively (Claude-format custom agents), so Construct does NOT write a
-  // separate `.github/agents/` set — doing so duplicated every agent in the
-  // picker. A pre-existing `.github/agents/` from an earlier sync is swept.
+  // VS Code reads custom agents from `.github/agents/*.agent.md`. The Claude
+  // tool names in `.claude/agents/*.md` are not recognized there, so the front
+  // door ships as a VS Code agent with namespaced tool grants (construct-mcp/*,
+  // web/fetch, search/read) — selecting it in the dropdown then scopes those
+  // tools in. The Claude-format set stays for Claude Code.
 
-  if (targetDir) {
-    const staleAgentsDir = path.join(targetDir, ".github", "agents");
-    if (!DRY_RUN && fs.existsSync(staleAgentsDir)) fs.rmSync(staleAgentsDir, { recursive: true, force: true });
+  const agentsDir = targetDir
+    ? path.join(targetDir, ".github", "agents")
+    : path.join(home, ".github", "agents");
+  if (!DRY_RUN && wants) mkdirp(agentsDir);
+  for (const entry of writeEntries) {
+    writeFile(path.join(agentsDir, `${adapterName(entry)}.agent.md`), copilotAgentFile(entry, entries), { stamp: false });
   }
+  if (fs.existsSync(agentsDir)) removeStaleAdapters(agentsDir, ".agent.md", writeEntries);
 
   const instructionsPath = targetDir
     ? path.join(targetDir, ".github", "copilot-instructions.md")
@@ -1387,7 +1441,7 @@ function syncCopilot(entries, targetDir = null, wants = true) {
   const list = listEntries.map((e) => `- \`${adapterName(e)}\`: use \`${promptPathPrefix}/${adapterName(e)}.prompt.md\`.`).join("\n");
   const note = `## ${systemName.charAt(0).toUpperCase() + systemName.slice(1)} Agent Prompts
 
-For a real multi-specialist run, Copilot agent mode calls the \`orchestration_run\` MCP tool (start the engine with \`construct dashboard\`). The prompts below are reusable role profiles for single-pass work:
+Select \`${systemName}\` from the chat mode dropdown to enter the orchestrator: describe an outcome and it classifies the request and dispatches the right specialists through the \`construct-mcp\` tools (\`orchestration_policy\` then \`orchestration_run\`). You ask for outcomes, not specialists — it routes internally. Requires the \`construct-mcp\` server (wired in \`.vscode/mcp.json\`); if its tools are unavailable, the mode cannot route and will say so rather than guess.
 
 ${list || "(no front-door prompts to surface)"}`;
 
@@ -1432,6 +1486,45 @@ function getVSCodeUserMcpPaths() {
     .filter((file) => fs.existsSync(file));
 }
 
+// A merged mcp.json preserves existing entries so user customizations survive a
+// re-sync. A construct-owned server path is a fully-resolved, non-placeholder
+// path, so the preserve rule keeps it even when it points at a different toolkit
+// root than the current one — and VS Code then launches a server that may not
+// exist. Treat a construct toolkit path outside the current root as stale so the
+// sync refreshes it; user-owned servers carry no lib/mcp toolkit path and stay.
+
+export function mcpEntryPointsOutsideToolkit(entry, root) {
+  const args = Array.isArray(entry?.args) ? entry.args : [];
+  return args.some(
+    (arg) => typeof arg === "string"
+      && /\/lib\/mcp\/[a-z0-9-]+\.mjs$/.test(arg)
+      && !arg.startsWith(`${root}/`),
+  );
+}
+
+// VS Code scans both `.github/agents` and `.claude/agents`, so the orchestrator
+// would list twice — once with VS Code tools (.github/agents) and once with
+// Claude tool names VS Code ignores (.claude/agents). `chat.agentFilesLocations`
+// is the documented lever to pin the scan; its power over the built-in
+// `.claude/agents` compatibility scan is version-dependent, so this is a
+// best-effort hint, not a guarantee. Merge only into a strictly-parseable file
+// and never overwrite an existing choice, so a commented (JSONC) or
+// user-customized settings.json is left untouched.
+
+export function pinVscodeAgentLocations(targetDir) {
+  if (DRY_RUN) return;
+  const settingsPath = path.join(targetDir, ".vscode", "settings.json");
+  let settings = {};
+  if (fs.existsSync(settingsPath)) {
+    try { settings = JSON.parse(fs.readFileSync(settingsPath, "utf8")) || {}; }
+    catch { return; }
+  }
+  if (settings["chat.agentFilesLocations"]) return;
+  settings["chat.agentFilesLocations"] = { ".github/agents": true, ".claude/agents": false };
+  mkdirp(path.dirname(settingsPath));
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+}
+
 function syncVSCode(targetDir = null, wants = true) {
   const registryMcp = scopedManagedMcpDefs({ projectScope: Boolean(targetDir) });
   if (Object.keys(registryMcp).length === 0) return false;
@@ -1480,13 +1573,15 @@ function syncVSCode(targetDir = null, wants = true) {
       const registryWantsCommand = !mcpDef.type && Array.isArray(mcpDef.args);
       const existingIsRemote = existingEntry && (existingEntry.type === 'http' || existingEntry.type === 'remote');
       const transportMismatch = registryWantsCommand && existingIsRemote;
-      if (existingEntry && !hasPlaceholder && !transportMismatch) continue;
+      const staleToolkitPath = mcpEntryPointsOutsideToolkit(existingEntry, root);
+      if (existingEntry && !hasPlaceholder && !transportMismatch && !staleToolkitPath) continue;
       config.servers[id] = buildClaudeMcpEntry(id, mcpDef, process.env, { host: "vscode" });
     }
     if (!DRY_RUN) {
       mkdirp(path.dirname(mcpPath));
       fs.writeFileSync(mcpPath, JSON.stringify(config, null, 2) + "\n");
     }
+    pinVscodeAgentLocations(targetDir);
     return true;
   }
 
@@ -1504,7 +1599,8 @@ function syncVSCode(targetDir = null, wants = true) {
         const registryWantsCommand = !mcpDef.type && Array.isArray(mcpDef.args);
         const existingIsRemote = existingEntry && (existingEntry.type === 'http' || existingEntry.type === 'remote');
         const transportMismatch = registryWantsCommand && existingIsRemote;
-        if (existingEntry && !hasPlaceholder && !transportMismatch) continue;
+        const staleToolkitPath = mcpEntryPointsOutsideToolkit(existingEntry, root);
+        if (existingEntry && !hasPlaceholder && !transportMismatch && !staleToolkitPath) continue;
         config.servers[id] = buildClaudeMcpEntry(id, mcpDef, process.env, { host: "vscode" });
       }
       if (!DRY_RUN) fs.writeFileSync(mcpPath, JSON.stringify(config, null, 2) + "\n");

package/specialists/artifact-manifest.json

@@ -9,6 +9,10 @@
     "outputs": {
       "formats": ["pdf", "docx", "doc", "deck", "pptx", "html", "rtf", "odt", "epub", "tex", "txt", "md", "mdx"],
       "branding": "construct"
+    },
+    "qualityContract": {
+      "gateLevel": "standard",
+      "requiredStates": ["exported"]
     }
   },
   "artifacts": {
@@ -31,6 +35,13 @@
         "proseMinimum": 3,
         "requiredReviewers": ["cx-devil-advocate"],
         "optionalReviewers": ["cx-ux-researcher"]
+      },
+      "qualityContract": {
+        "gateLevel": "render-smoke",
+        "requiredStates": ["exported", "file-valid", "renderable"],
+        "perFormat": {
+          "pdf": { "requiredStates": ["file-valid", "renderable"], "a11y": "wcag-2.1-aa" }
+        }
       }
     },
     "prd-platform": {
@@ -318,6 +329,13 @@
         "proseMinimum": 2,
         "requiredReviewers": ["cx-devil-advocate"],
         "optionalReviewers": []
+      },
+      "qualityContract": {
+        "gateLevel": "render-smoke",
+        "requiredStates": ["exported", "file-valid", "renderable"],
+        "perFormat": {
+          "pdf": { "requiredStates": ["file-valid", "renderable"] }
+        }
       }
     },
     "customer-profile": {

package/specialists/artifact-manifest.schema.json

@@ -41,7 +41,8 @@
         "authorChain": { "type": "array", "items": { "type": "string" } },
         "reviewerChain": { "type": "array", "items": { "type": "string" } },
         "validation": { "$ref": "#/$defs/validation" },
-        "outputs": { "$ref": "#/$defs/outputs" }
+        "outputs": { "$ref": "#/$defs/outputs" },
+        "qualityContract": { "$ref": "#/$defs/qualityContract" }
       }
     },
     "validation": {
@@ -58,6 +59,48 @@
         "branding": { "type": "string", "enum": ["construct", "plain"] }
       }
     },
+    "gateLevel": {
+      "type": "string",
+      "enum": ["fast", "standard", "render-smoke", "full-certification", "human-reviewed"]
+    },
+    "completionState": {
+      "type": "string",
+      "enum": [
+        "planned",
+        "authored",
+        "structurally-valid",
+        "source-linted",
+        "exported",
+        "file-valid",
+        "renderable",
+        "screenshot-captured",
+        "visually-reviewed",
+        "accessibility-reviewed",
+        "approved",
+        "completed"
+      ]
+    },
+    "qualityContract": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "gateLevel": { "$ref": "#/$defs/gateLevel" },
+        "requiredStates": { "type": "array", "items": { "$ref": "#/$defs/completionState" } },
+        "perFormat": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "gateLevel": { "$ref": "#/$defs/gateLevel" },
+              "requiredStates": { "type": "array", "items": { "$ref": "#/$defs/completionState" } },
+              "a11y": { "type": "string" },
+              "fontFloorPt": { "type": "number" }
+            }
+          }
+        }
+      }
+    },
     "artifactEntry": {
       "type": "object",
       "required": ["template", "primaryOwners", "toneDefault", "releaseGate"],
@@ -76,7 +119,8 @@
         "authorChain": { "type": "array", "items": { "type": "string" } },
         "reviewerChain": { "type": "array", "items": { "type": "string" } },
         "validation": { "$ref": "#/$defs/validation" },
-        "outputs": { "$ref": "#/$defs/outputs" }
+        "outputs": { "$ref": "#/$defs/outputs" },
+        "qualityContract": { "$ref": "#/$defs/qualityContract" }
       }
     }
   }

package/templates/distribution/construct-brand.typ

@@ -280,8 +280,7 @@
     #v(0.28em)
     #set text(font: construct-font-sans, size: fs-micro, fill: ink-faint)
     #align(center)[
-      #text(weight: wt-bold, fill: ink, tracking: 0.04em)[Construct]
-      #text[ #sym.dot.c #footer-label]
+      #text(weight: wt-bold, fill: ink, tracking: 0.04em)[#footer-label]
       #if classification != "" [ #sym.dot.c #upper(classification)]
     ]
   ]

package/templates/distribution/construct-deck.html

@@ -1,15 +1,14 @@
 <!--
-  templates/distribution/construct-deck.html — Construct branded 16:9 slide deck
-  HTML for `construct export --to=deck`. Pandoc emits section divs (--section-divs)
-  from markdown slides separated by ---; Space Grotesk via Google Fonts; monochrome ink
-  tokens mirror construct-brand.typ. Metadata variables fill the title slide.
+  Standalone 16:9 slide-deck HTML export template. Pandoc emits section divs
+  (--section-divs) from markdown slides separated by ---; Space Grotesk via Google
+  Fonts; monochrome ink tokens. Metadata variables fill the title slide.
 -->
 <!DOCTYPE html>
 <html lang="en">
 <head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
-<title>$if(title)$$title$$else$Construct deck$endif$</title>
+<title>$if(title)$$title$$else$Slides$endif$</title>
 <link rel="preconnect" href="https://fonts.googleapis.com">
 <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
 <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600&family=Space+Grotesk:wght@400;500;600;700&display=swap" rel="stylesheet">
@@ -24,57 +23,58 @@
   }
   * { box-sizing:border-box; }
   html { scroll-behavior:smooth; -webkit-text-size-adjust:100%; }
-  body { margin:0; background:#e8e9ec; color:var(--ink-body); font-family:var(--sans); font-size:22px; line-height:1.45; -webkit-font-smoothing:antialiased; }
+  body { margin:0; background:#e8e9ec; color:var(--ink-body); font-family:var(--sans); font-size:17px; line-height:1.5; -webkit-font-smoothing:antialiased; }
   .deck { display:flex; flex-direction:column; align-items:center; gap:32px; padding:40px 24px 80px; }
-  section.slide {
+  .deck > section {
     width:min(100%, var(--slide-w));
     aspect-ratio:16/9;
     background:var(--paper);
     border:1px solid var(--hairline);
     border-radius:8px;
     box-shadow:0 18px 48px rgba(10,12,16,.08);
-    padding:56px 64px 48px;
+    padding:48px 56px 40px;
     overflow:hidden;
     display:flex;
     flex-direction:column;
     position:relative;
   }
-  section.slide::after {
+  .deck > section::after {
     content:"";
     position:absolute;
     left:0; right:0; bottom:0;
     height:4px;
     background:linear-gradient(90deg, var(--ink) 46px, var(--hairline) 46px);
   }
-  section.slide.title-slide { justify-content:center; }
-  section.slide.title-slide h1 { font-size:52px; line-height:1.06; letter-spacing:-.024em; margin:0 0 16px; color:var(--ink); font-weight:600; }
-  section.slide.title-slide .subtitle { font-size:26px; color:var(--muted); margin:0 0 28px; letter-spacing:-.005em; }
-  section.slide.title-slide .meta { font-size:15px; color:var(--muted); letter-spacing:.04em; text-transform:uppercase; font-weight:600; }
-  section.slide.title-slide .meta .sep { color:var(--faint); font-weight:400; }
-  section.slide h1 { font-size:40px; line-height:1.08; letter-spacing:-.02em; margin:0 0 20px; color:var(--ink); font-weight:600; }
-  section.slide h1::after { content:""; display:block; width:36px; height:3px; background:var(--ink); margin-top:14px; }
-  section.slide h2 { font-size:28px; font-weight:600; color:var(--ink-strong); margin:28px 0 12px; letter-spacing:-.01em; }
-  section.slide h3 { font-size:22px; font-weight:600; color:var(--ink-strong); margin:20px 0 8px; }
-  section.slide p { margin:0 0 14px; max-width:52em; }
-  section.slide ul, section.slide ol { margin:0 0 16px; padding-left:1.2em; }
-  section.slide li { margin:0 0 10px; }
-  section.slide li::marker { color:var(--ink); }
-  section.slide strong { color:var(--ink); font-weight:600; }
-  section.slide code { font-family:var(--mono); font-size:.84em; background:var(--surface-alt); padding:1px 6px; border-radius:4px; }
-  section.slide pre { background:var(--surface); border:1px solid var(--hairline); border-radius:8px; padding:16px 18px; overflow:auto; font-size:17px; }
-  section.slide pre code { background:none; padding:0; }
-  section.slide blockquote { margin:16px 0; padding:14px 18px; background:var(--surface-alt); border-left:3px solid var(--ink); border-radius:0 4px 4px 0; }
-  section.slide table { width:100%; border-collapse:collapse; font-size:18px; margin:12px 0; }
-  section.slide th, section.slide td { text-align:left; padding:8px 12px; border-bottom:1px solid var(--hairline); }
-  section.slide thead th { font-weight:700; color:var(--ink); border-bottom:2px solid var(--ink); }
-  section.slide figure { margin:16px 0; text-align:center; }
-  section.slide figure img { max-width:58%; max-height:42vh; width:auto; height:auto; object-fit:contain; border:1px solid var(--hairline); border-radius:6px; padding:8px; }
+  .deck > section.title-slide { justify-content:center; }
+  .deck > section.title-slide h1 { font-size:38px; line-height:1.1; letter-spacing:-.022em; margin:0 0 14px; color:var(--ink); font-weight:600; }
+  .deck > section.title-slide .subtitle { font-size:19px; color:var(--muted); margin:0 0 24px; letter-spacing:-.005em; }
+  .deck > section.title-slide .meta { font-size:13px; color:var(--muted); letter-spacing:.04em; text-transform:uppercase; font-weight:600; }
+  .deck > section.title-slide .meta .sep { color:var(--faint); font-weight:400; }
+  .deck > section h1 { font-size:28px; line-height:1.12; letter-spacing:-.018em; margin:0 0 16px; color:var(--ink); font-weight:600; }
+  .deck > section h1::after { content:""; display:block; width:30px; height:2px; background:var(--ink); margin-top:12px; }
+  .deck > section h2 { font-size:20px; font-weight:600; color:var(--ink-strong); margin:22px 0 10px; letter-spacing:-.01em; }
+  .deck > section h3 { font-size:16px; font-weight:600; color:var(--ink-strong); margin:16px 0 6px; }
+  .deck > section p { margin:0 0 12px; max-width:54em; }
+  .deck > section ul, .deck > section ol { margin:0 0 12px; padding-left:1.2em; }
+  .deck > section li { margin:0 0 7px; }
+  .deck > section li::marker { color:var(--ink); }
+  .deck > section strong { color:var(--ink); font-weight:600; }
+  .deck > section code { font-family:var(--mono); font-size:.84em; background:var(--surface-alt); padding:1px 6px; border-radius:4px; }
+  .deck > section pre { background:var(--surface); border:1px solid var(--hairline); border-radius:8px; padding:14px 16px; overflow:auto; font-size:13.5px; }
+  .deck > section pre code { background:none; padding:0; }
+  .deck > section blockquote { margin:16px 0; padding:14px 18px; background:var(--surface-alt); border-left:3px solid var(--ink); border-radius:0 4px 4px 0; }
+  .deck > section table { width:100%; border-collapse:collapse; font-size:15px; margin:10px 0; }
+  .deck > section th, .deck > section td { text-align:left; padding:8px 12px; border-bottom:1px solid var(--hairline); }
+  .deck > section thead th { font-weight:700; color:var(--ink); border-bottom:2px solid var(--ink); }
+  .deck > section figure { margin:12px 0; text-align:center; flex:1 1 auto; min-height:0; display:flex; flex-direction:column; align-items:center; justify-content:center; }
+  .deck > section figure img { max-width:80%; max-height:100%; width:auto; height:auto; object-fit:contain; border:1px solid var(--hairline); border-radius:6px; padding:8px; }
+  .deck > section > img { display:block; margin:12px auto; flex:1 1 auto; min-height:0; max-width:84%; max-height:100%; width:auto; height:auto; object-fit:contain; border:1px solid var(--hairline); border-radius:6px; padding:8px; }
   .slide-foot { margin-top:auto; padding-top:16px; font-size:13px; color:var(--faint); display:flex; justify-content:space-between; align-items:center; }
   .slide-foot b { color:var(--ink); font-weight:600; }
   @media print {
     body { background:var(--paper); }
     .deck { gap:0; padding:0; }
-    section.slide { box-shadow:none; border:none; border-radius:0; page-break-after:always; width:100%; height:100vh; }
+    .deck > section { box-shadow:none; border:none; border-radius:0; page-break-after:always; width:100%; height:100vh; }
   }
 </style>
 </head>
@@ -86,7 +86,7 @@ $if(artifactType)$<div class="meta">$artifactType$$if(docId)$ <span class="sep">
 <h1>$title$</h1>
 $if(subtitle)$<p class="subtitle">$subtitle$</p>$endif$
 $if(owner)$<p class="meta">$owner$$if(date)$ <span class="sep">&middot;</span> $date$$endif$$if(status)$ <span class="sep">&middot;</span> $status$$endif$</p>$endif$
-<div class="slide-foot"><span><b>Construct</b>$if(classification)$ &middot; $classification$$endif$</span></div>
+<div class="slide-foot"><span>$if(classification)$<b>$classification$</b>$endif$$if(date)$$if(classification)$ &middot; $endif$$date$$endif$</span></div>
 </section>
 $endif$
 $body$

package/templates/distribution/construct-pdf.typ

@@ -16,7 +16,7 @@
     version: "$if(version)$$version$$endif$",
   ),
   footer: construct-running-footer(
-    "Construct brief",
+    "Brief",
     classification: "$if(classification)$$classification$$endif$",
   ),
 )

package/templates/distribution/construct-web.html

@@ -1,18 +1,16 @@
 <!--
-  templates/distribution/construct-web.html — Construct branded standalone HTML
-  template for `construct export --to=html`. Monochrome design mirroring the PDF
-  brand (construct-brand.typ): Space Grotesk webfont, masthead from frontmatter metadata,
-  bold-header hairline tables, callout blockquotes, framed figures. Pandoc fills
-  $title$/$subtitle$/$status$/$owner$/$date$/$artifactType$/$version$/$docId$/
-  $classification$ and $body$; export runs with --embed-resources so diagrams and
-  fonts inline into a single portable file.
+  Standalone branded HTML export template. Monochrome design: Space Grotesk
+  webfont, masthead from frontmatter metadata, bold-header hairline tables, callout
+  blockquotes, framed figures. Pandoc fills the title, subtitle, status, owner,
+  date, artifactType, version, docId, classification, and document body; export
+  runs with --embed-resources so diagrams and fonts inline into one portable file.
 -->
 <!DOCTYPE html>
 <html lang="en">
 <head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
-<title>$if(title)$$title$$else$Construct document$endif$</title>
+<title>$if(title)$$title$$else$Document$endif$</title>
 <link rel="preconnect" href="https://fonts.googleapis.com">
 <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
 <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600&family=Space+Grotesk:wght@400;500;600;700&display=swap" rel="stylesheet">
@@ -79,14 +77,14 @@
 $if(title)$
 <header class="masthead">
 $if(artifactType)$  <div class="chips">$artifactType$$if(docId)$ <span class="sep">&middot;</span> $docId$$endif$$if(version)$ <span class="sep">&middot;</span> v$version$$endif$$if(classification)$ <span class="sep">&middot;</span> $classification$$endif$</div>
-$endif$  <div class="title">$title$</div>
+$endif$  <h1 class="title">$title$</h1>
 $if(subtitle)$  <p class="subtitle">$subtitle$</p>
 $endif$  <div class="byline">$if(status)$<span class="pill">$status$</span>$endif$$if(owner)$<span>$owner$</span>$endif$$if(date)$<span class="sep">&middot;</span><span>$date$</span>$endif$</div>
 </header>
 <div class="rule"></div>
 $endif$
 $body$
-<div class="doc-foot"><b>Construct</b>$if(classification)$ &middot; $classification$$endif$</div>
+<div class="doc-foot">$if(classification)$<b>$classification$</b>$endif$$if(date)$$if(classification)$ &middot; $endif$$date$$endif$</div>
 </main>
 </body>
 </html>