thinkpool-pair 0.7.311 → 0.7.313

package/README.md

@@ -81,8 +81,11 @@ their own sandbox cannot bind localhost or launch Chrome:
 - `preview_start` serves a built directory inside that lane's workspace
   (`dist` by default; it must contain `index.html`).
 - `preview_capture` returns exact desktop (1440×900) and mobile (390×844)
-  screenshots to the agent. A complete pair is queued as a room card after the
-  agent's final response; a single-viewport capture remains tool evidence only.
+  screenshots to the agent as verification evidence. It creates no transcript
+  artifact by default. Pass `card: true` only for an intentional user-facing
+  mockup/Design deliverable; a settled complete pair is then queued after the
+  agent's final response. Loading, empty, and public-auth fallback shells are
+  rejected before a card can be created.
 - `preview_inspect` returns rendered DOM text, document size, and optional
   selector geometry at either viewport.
 - `preview_stop` releases the preview port.

package/bridge.mjs

@@ -55,6 +55,8 @@ import { readCodexDefaultModel, readCodexModels, codexConfigForMode, codexThread
 import { codexAccountUsageLine, codexCreditsReportLine, codexLimitReportLine } from './codex-commands.mjs'
 import { withMcpSessionFactory } from './codex-mcp-http.mjs'
 import { startStructuredSession } from './runtime-session.mjs'
+import { claudeOneShot } from './claude-session.mjs'
+import { fallbackTerminalName, suggestTerminalName } from './terminal-name.mjs'
 import { defaultStructuredMode, normalizeStructuredEffort, shouldDeferStructuredRuntime, structuredModeForSlice, structuredModeLocked, structuredModesForLane, structuredRuntimeForCommand, structuredRuntimeMetadata, structuredRuntimeSupportsMode } from './runtime-registry.mjs'
 import { commandCatalogForRuntime, commandHelpLine, reconcileCommandCatalog } from './command-catalog.mjs'
 import { probeHermesRuntime } from './hermes-probe.mjs'
@@ -1160,6 +1162,9 @@ const replayPump = createLatestReplayPump({
 // Persisted on the host so a rename is cross-device + survives a bridge restart;
 // every announce carries them so a late-joining or second device sees them too.
 const termNames = loadNames(room)
+const manualNameTouched = new Set()
+const autoNameAttempts = new Set()
+const autoNames = new Map()
 // The SDK's supported-model LIST (value/displayName/description), captured from
 // any session's `models` event. Announced room-level so EVERY device gets it on
 // connect — not just the one that saw the one-shot event (the picker fell back to
@@ -1254,6 +1259,91 @@ const announce = () => {
     ],
   }) }
 
+const uniqueTerminalName = (id, candidate) => {
+  const used = new Set(Object.entries(termNames)
+    .filter(([otherId]) => otherId !== id)
+    .map(([, label]) => String(label).toLowerCase()))
+  if (!used.has(candidate.toLowerCase())) return candidate
+  for (let n = 2; n < 100; n++) {
+    const suffix = ` ${n}`
+    const next = `${candidate.slice(0, 48 - suffix.length).trim()}${suffix}`
+    if (!used.has(next.toLowerCase())) return next
+  }
+  return candidate
+}
+
+// Best-effort row convergence: the bridge map updates the room immediately and
+// survives this host's restarts; the row carries the generated name to another host.
+const persistAutoTerminalName = async (id, label, previous, retry = true) => {
+  if (!codeAuthToken || !id || !label) return
+  try {
+    // Compare-and-set: an in-flight generated write must never overwrite a
+    // manual rename that won just before this request reached Postgres.
+    const expected = previous
+      ? `&name=eq.${encodeURIComponent(previous)}`
+      : `&or=${encodeURIComponent('(name.is.null,name.eq.Terminal)')}`
+    const response = await fetch(`${SUPABASE_URL}/rest/v1/code_terminals?id=eq.${encodeURIComponent(id)}${expected}&select=id`, {
+      method: 'PATCH',
+      headers: {
+        apikey: SUPABASE_ANON,
+        Authorization: `Bearer ${codeAuthToken}`,
+        'Content-Type': 'application/json',
+        Prefer: 'return=representation',
+      },
+      body: JSON.stringify({ name: label }),
+    })
+    const rows = response.ok ? await response.json().catch(() => []) : []
+    // Bridge-created lanes can receive work before the browser inserts their row.
+    if (retry && (!response.ok || !Array.isArray(rows) || rows.length === 0)) {
+      const timer = setTimeout(() => { void persistAutoTerminalName(id, label, previous, false) }, 1500)
+      timer.unref?.()
+    }
+  } catch {
+    if (retry) {
+      const timer = setTimeout(() => { void persistAutoTerminalName(id, label, previous, false) }, 1500)
+      timer.unref?.()
+    }
+  }
+}
+
+const applyAutoTerminalName = (id, candidate) => {
+  if (!candidate || manualNameTouched.has(id)) return false
+  const currentAuto = autoNames.get(id)
+  if (termNames[id] && termNames[id] !== currentAuto) return false
+  const previous = termNames[id] || null
+  const label = uniqueTerminalName(id, candidate)
+  if (termNames[id] === label) return true
+  termNames[id] = label
+  autoNames.set(id, label)
+  saveNames(room, termNames)
+  void persistAutoTerminalName(id, label, previous)
+  announce()
+  return true
+}
+
+// First real task only. A zero-token title appears immediately. Built-in Claude
+// may refine it through the existing raw Haiku path; other runtimes stay local so
+// a Codex/Hermes/custom-provider prompt is never leaked across providers.
+const autoNameTerminal = (id, text) => {
+  const entry = sessions.get(id)
+  if (!entry || termNames[id] || manualNameTouched.has(id) || autoNameAttempts.has(id)) return
+  if (entry.log?.some((event) => event?.kind === 'you')) return
+  const fallback = fallbackTerminalName(text)
+  if (!fallback) return
+  autoNameAttempts.add(id)
+  applyAutoTerminalName(id, fallback)
+  const canUseHaiku = entry.runtime === 'claude'
+    && (!entry.provider || entry.provider === 'anthropic')
+    && hostMemoryAdmission('name this terminal').ok
+  if (!canUseHaiku) return
+  const context = `Repository: ${repoLabel}. Existing terminal names: ${Object.values(termNames).filter(Boolean).slice(-8).join(', ') || 'none'}.`
+  void suggestTerminalName({
+    text,
+    context,
+    generate: (prompt) => claudeOneShot({ prompt, cwd: entry.cwd || process.cwd(), env: process.env, timeoutMs: 8000 }),
+  }).then((candidate) => applyAutoTerminalName(id, candidate))
+}
+
 // (cross-person grantee yield removed 2026-07-06 — owner-only serving now; the owner's
 //  bridge never stands down. See docs/specs/2026-07-06-remove-cross-person-serve.md.)
 
@@ -1345,6 +1435,7 @@ async function receiveCrossRoomPost({ fromRoom, fromHost, fromTerminalName, text
   te.roomHop = 1; te.hop = (te.hop || 0) + 1; te.peekCount = 0; te.postCount = 0; te.pairPeekCount = 0; te.crossRoomPostCount = 0
   const msg = `[From: room ${fromLabel} — relayed via the ThinkPool cross-room Ensemble, approved by a person in this room]\n${body}`
   const evt = { kind: 'you', text: msg, by: `room ${fromRoom}`, crosspost: true, relaySourceName: String(fromTerminalName || '').trim().slice(0, 80) || undefined }
+  autoNameTerminal(targetId, body)
   stampEvent(evt); pushLog(te, evt); bcast('code-event', { term: targetId, evt })
   try { if (te.session.sendTurn(msg) === false) return { error: `Could not deliver to room ${room} — the lane refused the turn (check its visible host-memory/runtime error).` } } catch { return { error: `Could not deliver to room ${room} — the lane may have just closed.` } }
   return { ok: true, ref: String(targetId).slice(0, 8) }
@@ -1684,10 +1775,13 @@ function receiveManifest(box, file, term, trustedDesignSource = false) {
   if (!item) return
   const lane = sessions.get(term)
   const active = !!lane && (lane._busyAnn === true || lane.session?.turnActive === true)
-  const accepted = mockupDeliveries.enqueue(term, item, { active })
+  const deliveryKey = item.m.sourceKind === 'preview'
+    ? `preview:${item.m.captureKey || item.m.route || item.m.slug}:${item.m.title || ''}`
+    : `authored:${item.m.slug}`
+  const accepted = mockupDeliveries.enqueue(term, item, { active, key: deliveryKey })
   if (accepted.queued) {
     writeMockupReceipt(box, item.slug, true, 'queued')
-    process.stderr.write(`\n  ◆ mockup "${item.m.title || item.m.slug}" ready — queued after the final response.\n`)
+    process.stderr.write(`\n  ◆ mockup "${item.m.title || item.m.slug}" ready — ${accepted.replaced ? 'replaced an earlier queued render' : 'queued after the final response'}.\n`)
   } else {
     accepted.delivery.catch(() => {})
   }
@@ -2577,6 +2671,7 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
           // Echo the injected prompt into the TARGET lane so both people see what
           // arrived (rides the existing code-event 'you' path — no new topic).
           const evt = { kind: 'you', text: msg, by: `terminal ${fromRef} (agent)`, crosspost: true, relaySourceName: termNames[id] || undefined }
+          autoNameTerminal(target.id, args.text)
           stampEvent(evt)
           pushLog(te, evt)
           bcast('code-event', { term: target.id, evt })
@@ -2630,6 +2725,7 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
           announce()
           const msg = `[Task from main terminal ${fromRef}'s agent — opened as an independent MAIN CASCADE CONDUCTOR terminal, not an Ensemble child]\n${String(args.task).trim()}`
           const evt = { kind: 'you', text: msg, by: `main terminal ${fromRef} (agent)`, crosspost: true, relaySourceName: termNames[id] || undefined }
+          autoNameTerminal(newId, args.task)
           stampEvent(evt); pushLog(conductor, evt); bcast('code-event', { term: newId, evt })
           try { if (conductor.session.sendTurn(msg) === false) return okText(`Opened main conductor ${newRef}, but host pressure prevented its runtime from starting. Existing lanes remain connected; free memory and retry the task.`) }
           catch { return okText(`Opened main conductor ${newRef}${args?.name ? ` ("${args.name}")` : ''}, but it may still be starting — the initial task could not be delivered.`) }
@@ -2749,6 +2845,7 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
               : ''
             const msg = `[Task from terminal ${fromRef}'s agent — relayed via ThinkPool Ensemble; you are its WORKER SUB-TERMINAL, never a main terminal or Cascade conductor]\n${args.task}${reviewTarget}`
             const evt = { kind: 'you', text: msg, by: `terminal ${fromRef} (agent)`, crosspost: true, relaySourceName: termNames[id] || undefined }
+            autoNameTerminal(newId, args.task)
             stampEvent(evt); pushLog(ne, evt); bcast('code-event', { term: newId, evt })
             try { if (ne.session.sendTurn(msg) === false) return okText(`Opened lane ${newRef}${args?.name ? ` ("${args.name}")` : ''}, but host pressure prevented its runtime from accepting the task. Existing lanes remain connected; free memory and retry.`) } catch { return okText(`Opened lane ${newRef}${args?.name ? ` ("${args.name}")` : ''}, but it may still be starting — could not hand off the task. Try post_to_terminal shortly.`) }
             return okText(`Opened agent lane ${newRef}${args?.name ? ` ("${args.name}")` : ''} and handed it the task. It runs in its own lane — check back with read_terminal, then close_terminal when done.`)
@@ -4241,6 +4338,7 @@ channel
     // Sample the runtime before dispatch so a missed prior falling edge cannot
     // make this genuinely new turn inherit the previous turn's revision.
     syncStructuredTurn(s)
+    autoNameTerminal(payload.term, payload.body != null ? String(payload.body) : text)
     const accepted = s.session.sendTurn(sendText, Object.keys(turnOptions).length ? turnOptions : undefined)
     if (accepted === false) syncStructuredTurn(s)
     else beginStructuredTurn(s)
@@ -4410,6 +4508,8 @@ channel
   // LATER (or a second machine) — those only ever see the announce.
   .on('broadcast', { event: 'term-rename' }, ({ payload }) => {
     if (!payload?.id) return
+    manualNameTouched.add(payload.id)
+    autoNames.delete(payload.id)
     if (payload.name) termNames[payload.id] = String(payload.name).slice(0, 80)
     else delete termNames[payload.id]
     saveNames(room, termNames)

package/claude-session.mjs

@@ -27,10 +27,42 @@ import { stallDecision, stallEvent, isCompactTurn } from './turn-stall.mjs'
 
 // The caret-pulled SDK's real version (^0.3.x auto-upgrades on restart). Resolved
 // once at import by walking up from the package entry to its own package.json.
+const req = createRequire(import.meta.url)
+
+// Shared raw one-shot for tiny bridge-owned inference jobs. No settings, skills,
+// MCP servers, or repo instructions are loaded; callers provide the model + prompt.
+export async function claudeOneShot({ prompt, model = 'claude-haiku-4-5', cwd, env, timeoutMs = 8000 } = {}) {
+  const abortController = new AbortController()
+  const timer = setTimeout(() => { try { abortController.abort() } catch { /* noop */ } }, timeoutMs)
+  try {
+    const result = query({
+      prompt,
+      options: {
+        model,
+        ...(cwd ? { cwd } : {}),
+        env,
+        maxTurns: 1,
+        permissionMode: 'bypassPermissions',
+        settingSources: [],
+        strictMcpConfig: true,
+        mcpServers: {},
+        abortController,
+      },
+    })
+    let out = ''
+    for await (const message of result) {
+      if (message.type === 'assistant') {
+        for (const block of (message.message?.content || [])) if (block.type === 'text') out += block.text
+      }
+      if (message.type === 'result') break
+    }
+    return out.trim()
+  } finally { clearTimeout(timer) }
+}
+
 // Named in the [SDK-REGRESSION] guard below so a silent gate-change is attributable.
 const SDK_VERSION = (() => {
   try {
-    const req = createRequire(import.meta.url)
     let d = dirname(req.resolve('@anthropic-ai/claude-agent-sdk'))
     for (let i = 0; i < 8; i++) {
       try { const p = JSON.parse(readFileSync(join(d, 'package.json'), 'utf8')); if (p.name === '@anthropic-ai/claude-agent-sdk') return p.version } catch { /* keep walking */ }
@@ -788,35 +820,17 @@ export function startClaudeSession({ cwd, model, effort: initialEffort = 'high',
     if (!suggest) return
     const seed = (lastAssistantText || '').trim().slice(-1500)
     if (!seed || closed) return
-    const ac2 = new AbortController()
-    const t = setTimeout(() => { try { ac2.abort() } catch { /* noop */ } }, 8000)
     try {
-      const hq = query({
+      let out = await claudeOneShot({
         prompt: `You are predicting the user's NEXT chat message in a live coding session, to prefill their composer. Given the assistant's latest reply below, output the single most likely next user message — short and natural (often just "proceed", "go with option A", "yes do that", or a brief follow-up). One line, <=12 words, imperative, no preamble, no quotes, no markdown.\n\nAssistant's latest reply:\n"""\n${seed}\n"""\n\nNext user message:`,
-        options: {
-          model: 'claude-haiku-4-5',
-          ...(cwd ? { cwd } : {}),
-          env: opts.env,
-          maxTurns: 1,
-          permissionMode: 'bypassPermissions',
-          settingSources: [],          // no CLAUDE.md / commands / agents — raw call
-          strictMcpConfig: true,
-          mcpServers: {},              // no MCP servers — fast cold start
-          abortController: ac2,
-        },
+        model: 'claude-haiku-4-5', cwd, env: opts.env, timeoutMs: 8000,
       })
-      let out = ''
-      for await (const mm of hq) {
-        if (mm.type === 'assistant') for (const b of (mm.message?.content || [])) if (b.type === 'text') out += b.text
-        if (mm.type === 'result') break
-      }
       out = out.trim().split('\n')[0].replace(/^["'`]+|["'`]+$/g, '').trim().slice(0, 140)
       if (out && !sawSuggestion && !closed && !/^(sure|of course|certainly|let me know|i can help|happy to)\b/i.test(out)) {
         emit({ kind: 'suggestion', text: out, source: 'haiku' })
         process.stderr.write(`  ◆ [suggestion] haiku fallback: ${JSON.stringify(out)}\n`)
       }
     } catch { /* fallback failed (rate limit / abort / model error) — silent */ }
-    finally { clearTimeout(t) }
   }
 
   const admitColdStart = () => {

package/cross-terminal.mjs

@@ -266,7 +266,7 @@ export const nativeClaudeProviderAccessFailed = (events) => {
   let text = ''
   try { text = typeof events === 'string' ? events : JSON.stringify(events || '') }
   catch { text = String(events || '') }
-  return /organization has disabled (?:claude )?subscription access|(?:claude )?subscription access (?:has been |is )?disabled|invalid anthropic (?:api )?key|invalid x-api-key|not logged in to claude|(?:run|use) \/login[^\n]{0,80}claude|no valid anthropic (?:api )?key/i.test(text)
+  return /organization has disabled (?:claude(?: subscription access)?|subscription access)|(?:claude )?subscription access (?:has been |is )?disabled|invalid anthropic (?:api )?key|invalid x-api-key|not logged in to claude|(?:run|use) \/login[^\n]{0,80}claude|no valid anthropic (?:api )?key/i.test(text)
 }
 
 const HERMES_CLAUDE_REVIEW_PREFERENCE = Object.freeze([

package/mockup-delivery.mjs

@@ -6,6 +6,7 @@
 // terminal boundary has been emitted, then deliver them in render order.
 export function completeMockupManifest(manifest, { isReadyFile } = {}) {
   if (typeof isReadyFile !== 'function') throw new TypeError('completeMockupManifest requires isReadyFile')
+  if (manifest?.sourceKind === 'preview' && (manifest.deliveryIntent !== 'card' || manifest.readinessValidated !== true)) return false
   const files = [manifest?.desktop, manifest?.mobile, manifest?.snapshot || manifest?.source || manifest?.html]
   return files.every((file) => !!file && isReadyFile(file))
 }
@@ -23,12 +24,18 @@ export class MockupDeliveryQueue {
     this.pending = new Map()
   }
 
-  enqueue(owner, item, { active = false } = {}) {
+  enqueue(owner, item, { active = false, key = null } = {}) {
     if (!owner || !active) return { queued: false, delivery: Promise.resolve().then(() => this.deliver(item)) }
     const queue = this.pending.get(owner) || []
-    queue.push(item)
+    const existing = key == null ? -1 : queue.findIndex((entry) => entry.key === key)
+    if (existing >= 0) {
+      queue[existing] = { item, key }
+      this.pending.set(owner, queue)
+      return { queued: true, replaced: true, delivery: null }
+    }
+    queue.push({ item, key })
     this.pending.set(owner, queue)
-    return { queued: true, delivery: null }
+    return { queued: true, replaced: false, delivery: null }
   }
 
   count(owner) {
@@ -38,7 +45,7 @@ export class MockupDeliveryQueue {
   async flush(owner) {
     const queue = this.pending.get(owner) || []
     this.pending.delete(owner)
-    for (const item of queue) await this.deliver(item)
+    for (const entry of queue) await this.deliver(entry.item)
     return queue.length
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.7.311",
+  "version": "0.7.313",
   "description": "Share a local coding-agent CLI (Claude Code, Codex, Gemini, Aider, …) into a ThinkPool Code room, live.",
   "type": "module",
   "bin": {
@@ -18,6 +18,7 @@
     "byok-detect.mjs",
     "context-windows.mjs",
     "claude-session.mjs",
+    "terminal-name.mjs",
     "claude-command-catalog.mjs",
     "codex-session.mjs",
     "question-response.mjs",

package/terminal-name.mjs

@@ -0,0 +1,54 @@
+import { nativeClaudeProviderAccessFailed } from './cross-terminal.mjs'
+
+const SKIP = new Set([
+  'a', 'an', 'and', 'are', 'at', 'be', 'can', 'could', 'for', 'from', 'how', 'i',
+  'in', 'is', 'it', 'just', 'like', 'maybe', 'me', 'my', 'of', 'on', 'or', 'our',
+  'please', 'something', 'that', 'the', 'this', 'to', 'we', 'with', 'would', 'you',
+])
+
+const GENERIC = /^(?:new )?(?:agent |coding )?(?:terminal|task|lane|session|work)$/i
+
+export function cleanTerminalName(value) {
+  let name = String(value || '')
+    .trim()
+    .split(/\r?\n/, 1)[0]
+    .replace(/^\s*(?:[-*#>]+|title\s*:?)\s*/i, '')
+    .replace(/^["'`]+|["'`]+$/g, '')
+    .replace(/[^\p{L}\p{N}+#&.' -]+/gu, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+  if (!name || GENERIC.test(name) || nativeClaudeProviderAccessFailed(name)) return null
+  if (/^(?:error|failed|sorry|unable|i (?:cannot|can't)|rate limit|request failed)\b/i.test(name)) return null
+  if (name.length > 48) name = name.slice(0, 48).replace(/\s+\S*$/, '').trim()
+  return name || null
+}
+
+export function fallbackTerminalName(text) {
+  const body = String(text || '')
+    .replace(/^\s*\[[^\]\n]{1,240}\]\s*/g, '')
+    .replace(/^\s*(?:hey|hi|okay|ok|so)\b[,:!]?\s*/i, '')
+    .replace(/^\s*(?:can|could|would|will)\s+you\s+/i, '')
+    .replace(/^\s*(?:how about|i (?:do not|don't) know|i guess)\s+/i, '')
+    .replace(/[`*_>#()[\]{}]/g, ' ')
+    .slice(0, 600)
+  const words = body.match(/[\p{L}\p{N}][\p{L}\p{N}+#.'-]*/gu) || []
+  const useful = words.filter((word) => !SKIP.has(word.toLowerCase()) && !/^https?$/i.test(word))
+  if (!useful.length) return null
+  const title = useful.slice(0, 5).map((word) => {
+    if (/^[A-Z\d+#.-]{2,}$/.test(word) || /\d/.test(word)) return word
+    return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()
+  }).join(' ')
+  return cleanTerminalName(title)
+}
+
+export async function suggestTerminalName({ text, context = '', generate } = {}) {
+  const fallback = fallbackTerminalName(text)
+  if (!fallback || typeof generate !== 'function') return fallback
+  const prompt = [
+    'Name one terminal lane from its first task. Output only a distinctive 2-5 word title, title case, at most 40 characters. Describe the concrete work, not the person or model. Never output “Terminal”, “Task”, “Session”, or a numbered label.',
+    context ? `Room context: ${String(context).slice(0, 500)}` : '',
+    `First task:\n${String(text || '').slice(0, 1600)}`,
+  ].filter(Boolean).join('\n\n')
+  try { return cleanTerminalName(await generate(prompt)) || fallback }
+  catch { return fallback }
+}

package/thinkpool-capabilities.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "bundleVersion": 11,
+  "bundleVersion": 12,
   "contracts": [
     {
       "id": "room-coordination",
@@ -88,13 +88,13 @@
     },
     {
       "id": "visual-proof",
-      "version": 3,
+      "version": 4,
       "routes": [
         {
           "id": "visual-proof",
           "tools": ["preview_start", "preview_capture", "preview_inspect", "preview_stop"],
           "trigger": "\\b(ui|ux|visual|design|frontend|html|css|page|route|mockup|screenshot|responsive|desktop|mobile|preview)\\b",
-          "prompt": "For built visual work, run the build, use preview_start, preview_capture at desktop and mobile, preview_inspect when rendered state matters, and preview_stop when finished. preview_capture uses a fresh isolated browser, so authenticated app routes require an authenticated visual harness; if a room route resolves to the signed-out invitation, the capture is rejected and no mockup card is created. A room card requires complete desktop and mobile evidence and is delivered after the final agent response; partial captures remain tool evidence only. Surface PNG evidence only when no interactive source-backed Design card is displayed."
+          "prompt": "For built visual work, run the build, use preview_start, preview_capture at desktop and mobile, preview_inspect when rendered state matters, and preview_stop when finished. preview_capture uses a fresh isolated browser and is inline verification evidence by default; it must not create a transcript card. Set card=true only when the person asked for a mockup/Design artifact or the visual itself is an intentional deliverable that should remain editable in the transcript. A card requires settled meaningful content at both desktop and mobile, rejects loading/public-auth fallback shells, and is delivered after the final agent response. Authenticated app routes require an authenticated visual harness. Surface PNG evidence only when no interactive source-backed Design card is displayed."
         }
       ],
       "impact": [
@@ -168,9 +168,9 @@
     },
     {
       "id": "design-workspace",
-      "version": 5,
+      "version": 6,
       "interactionPrompt": "DESIGN EDITING MODEL: every complete bridge preview_capture card and every trusted source-backed mockup card offers Edit in Design. The bridge freezes a safe rendered-DOM snapshot for application previews; Design edits are then applied by the producing lane to the real application source and verified by a fresh correlated desktop+mobile capture. For authored HTML, the producing lane edits the canonical authored HTML source directly. Edit in Design—not ordinary Preview or unrelated artifact delivery—arms a persistent room-level Design workspace, opens the artifact directly in editable mode, and adds Design · Page name beneath the producing terminal in its Ensemble row for both partners; it creates no terminal, agent runtime, or worker slot. The virtual lane can be closed from that Ensemble row without deleting the artifact. Once armed, the Design lane reopens the active artifact at its latest verified revision without another agent turn, history search, HTML/path request, or re-selection. Design is the default canvas there and Preview is only a temporary interaction mode. Direct text, supported movement, and selected-image changes auto-stage as optimistic drafts in the bounded changes queue; queued edits can be reopened, revised, or removed before Apply. Apply changes sends the ordered batch once to the producing lane, and a successful correlated desktop+mobile render advances the verified revision for the room. Never call a staged draft saved or live. When a person asks for many mockups or options that can share a surface, prefer one source-backed multi-option board or gallery in one file and one card so they can compare together; create separate files/cards only when the person explicitly requests independently editable artifacts or the options cannot be represented faithfully together.",
-      "turnReminder": "DESIGN ROUTE: preview_capture and authored HTML must produce editable Thinkpool Design cards with verified desktop and mobile renders. Cards are delivered after the final agent response so they remain the newest transcript item. Edit in Design explicitly arms the persistent Design workspace and adds its virtual Design · Page beneath the producing terminal in the Ensemble row; Preview alone does not arm it. For large direction sets, consolidate compatible options into one source-backed comparison board/gallery and one card; use separate files/cards only when independent editing is explicitly requested or technically necessary. Do not duplicate the card renders as inline PNGs. Use inline PNG evidence only when no interactive Design artifact is available.",
+      "turnReminder": "DESIGN ROUTE: intentional application-preview deliverables use preview_capture with card=true; correlated Design recaptures are recognized automatically. Authored HTML uses the source-backed render helper. Both must produce editable Thinkpool Design cards with verified desktop and mobile renders. Ordinary verification captures stay inline evidence and must not create cards. Cards are delivered after the final agent response so they remain the newest transcript item. Edit in Design explicitly arms the persistent Design workspace and adds its virtual Design · Page beneath the producing terminal in the Ensemble row; Preview alone does not arm it. For large direction sets, consolidate compatible options into one source-backed comparison board/gallery and one card; use separate files/cards only when independent editing is explicitly requested or technically necessary. Do not duplicate the card renders as inline PNGs. Use inline PNG evidence only when no interactive Design artifact is available.",
       "impact": [
         {"path": "src/pages/code/design/"},
         {"path": "src/pages/code/structured.jsx", "diffPattern": "Edit in Design|openMockup|tp-mockup-view|sourceKnown"},

package/thinkpool-room-prompt.mjs

@@ -41,7 +41,7 @@ export const THINKPOOL_REMOTE_DELIVERY_RULES = Object.freeze([
   'LINKS & ARTIFACTS: a local filesystem path, file:// URL, localhost/127.0.0.1 address, or host-only preview is useless to a remote room. Every link you surface must be reachable by the people in the room.',
   'Whenever you produce HTML or shareable markup — a demo, mockup, preview, report, or page — publish it to a browser-renderable GitHub-shareable URL, normally GitHub Pages (or an equivalent URL that actually renders; raw.githubusercontent.com serves HTML as plain text). Give the room that shareable URL in addition to the Thinkpool Design card, never instead of it and never only as a local path. If you cannot publish it, say so instead of falling back to a host-only path.',
   'SHOW VISUAL WORK: whenever you build, change, or fix anything visual, show the result in the room. A source-backed Thinkpool Design card/popup is already the interactive visible result, so do not additionally surface duplicate PNGs. When no interactive Design artifact is available, capture and surface desktop/mobile PNG evidence inline.',
-  'BRIDGE PREVIEWS: for a built web UI, use preview_start (default root: dist), then preview_capture for exact desktop 1440x900 and mobile 390x844 PNGs, and preview_inspect when DOM text or selector geometry helps. Run the project build first and stop the preview server with preview_stop when done.',
+  'BRIDGE PREVIEWS: for a built web UI, use preview_start (default root: dist), then preview_capture for exact desktop 1440x900 and mobile 390x844 PNGs, and preview_inspect when DOM text or selector geometry helps. Run the project build first and stop the preview server with preview_stop when done. Captures are verification evidence by default; set card=true only for an intentional user-facing mockup or Design deliverable, never merely because a turn changed visual code.',
   THINKPOOL_DESIGN_DELIVERY_RULE,
   'VERIFY BEFORE CLAIMING: run or serve what you changed, observe it, and show the evidence in the room — the PNG, passing test output, or real response. If something could not be verified, say exactly what remains unverified.',
 ])

package/viewport.mjs

@@ -70,6 +70,30 @@ export function isSignedOutRoomPreview(route, snapshot) {
   return /\bid\s*=\s*["']invitation-room-title["']/i.test(String(snapshot || ''))
 }
 
+export function previewArtifactIssue(route, capture) {
+  const parsed = new URL(normalizeRoute(route), 'http://127.0.0.1')
+  const routeIdentity = (url) => {
+    if (typeof url !== 'string' || !url.trim()) return null
+    try {
+      const value = new URL(url, 'http://127.0.0.1')
+      const pathname = value.pathname === '/' ? '/' : value.pathname.replace(/\/+$/, '')
+      return `${pathname}${value.search}`
+    } catch { return null }
+  }
+  const expectedRoute = routeIdentity(parsed.href)
+  const protectedRoute = parsed.pathname === '/code' || parsed.pathname.startsWith('/code/') || parsed.searchParams.has('r')
+  for (const state of [capture?.beforeState, capture?.afterState]) {
+    if (!state) return 'The captured page did not report settled rendered state.'
+    const actualRoute = routeIdentity(state.url)
+    if (actualRoute && actualRoute !== expectedRoute) return `Preview navigated from ${expectedRoute} to ${actualRoute}.`
+    if (state.signedOutInvite) return 'Preview resolved to the signed-out room invitation instead of the authenticated Code room.'
+    if (state.visibleBoot) return 'Preview was still showing the application loading shell.'
+    if (protectedRoute && state.prerenderGeo) return 'Preview resolved to the public marketing shell instead of the authenticated Code surface.'
+    if (!state.hasBody || (state.textLength < 2 && state.meaningfulVisualCount < 1)) return 'Preview rendered an empty page.'
+  }
+  return null
+}
+
 export function findBrowserExecutable({ env = process.env, platform = process.platform, exists = fs.existsSync } = {}) {
   const candidates = [
     env.TP_BROWSER_PATH,
@@ -261,8 +285,106 @@ export class CdpBrowser {
     }
   }
 
-  async capture({ url, viewport, fullPage = true, waitMs = 300 }) {
+  async renderedState(pipe, sessionId) {
+    const expression = `(() => {
+      const visible = (node) => {
+        if (!node) return false;
+        const style = getComputedStyle(node);
+        const rect = node.getBoundingClientRect();
+        return style.display !== 'none' && style.visibility !== 'hidden' && Number(style.opacity || 1) > 0 && rect.width > 0 && rect.height > 0;
+      };
+      const boot = document.querySelector('#boot');
+      const meaningful = [...document.querySelectorAll('main,article,section,img,video,canvas,svg,[role="dialog"],[role="main"],[role="img"]')]
+        .filter((node) => !node.closest('#boot') && visible(node));
+      return {
+        title: document.title || '', url: location.href,
+        hasBody: !!document.body,
+        textLength: (document.body?.innerText || '').trim().length,
+        meaningfulVisualCount: meaningful.length,
+        visibleBoot: visible(boot),
+        signedOutInvite: !!document.querySelector('#invitation-room-title'),
+        prerenderGeo: !!document.querySelector('[data-prerender="geo"]'),
+      };
+    })()`
+    const result = await pipe.send('Runtime.evaluate', { expression, returnByValue: true }, sessionId)
+    if (result.exceptionDetails) throw new Error('Could not inspect the rendered preview state.')
+    return result.result?.value || null
+  }
+
+  async freezeCurrentPage(pipe, sessionId) {
+    // Freeze the rendered DOM, not the build entry document. A Vite/React entry
+    // depends on root-relative chunks and often boots to an empty shell in a
+    // sandboxed srcDoc; the settled DOM plus same-origin CSS/assets is portable.
+    const expression = `(async () => {
+      const clone = document.documentElement.cloneNode(true);
+      clone.querySelectorAll('script,link[rel="modulepreload"],link[rel="preload"]').forEach((node) => node.remove());
+      clone.querySelectorAll('*').forEach((node) => {
+        for (const attr of [...node.attributes]) if (/^on/i.test(attr.name)) node.removeAttribute(attr.name);
+        if (node instanceof HTMLInputElement) node.removeAttribute('value');
+        if (node instanceof HTMLTextAreaElement) node.textContent = '';
+      });
+      const css = [];
+      for (const sheet of [...document.styleSheets]) {
+        try { css.push([...sheet.cssRules].map((rule) => rule.cssText).join('\\n')); } catch {}
+      }
+      clone.querySelectorAll('style,link[rel="stylesheet"]').forEach((node) => node.remove());
+      const head = clone.querySelector('head') || clone.insertBefore(document.createElement('head'), clone.firstChild);
+      const style = document.createElement('style');
+      style.setAttribute('data-thinkpool-snapshot', '');
+      style.textContent = css.join('\\n');
+      head.appendChild(style);
+
+      const assetUrls = new Set();
+      const remember = (raw) => {
+        if (!raw || /^(data:|blob:|#)/i.test(raw)) return;
+        try {
+          const absolute = new URL(raw, location.href);
+          if (absolute.origin === location.origin) assetUrls.add(absolute.href);
+        } catch {}
+      };
+      clone.querySelectorAll('[src],[poster]').forEach((node) => {
+        remember(node.getAttribute('src'));
+        remember(node.getAttribute('poster'));
+      });
+      for (const match of style.textContent.matchAll(/url\\(\\s*(['"]?)([^'"\\)]+)\\1\\s*\\)/gi)) remember(match[2]);
+
+      const replacements = new Map();
+      let inlinedBytes = 0;
+      for (const absolute of assetUrls) {
+        try {
+          const response = await fetch(absolute);
+          const buffer = await response.arrayBuffer();
+          if (!response.ok || buffer.byteLength > 512000 || inlinedBytes + buffer.byteLength > 1000000) continue;
+          const bytes = new Uint8Array(buffer);
+          let binary = '';
+          for (let offset = 0; offset < bytes.length; offset += 0x8000) binary += String.fromCharCode(...bytes.subarray(offset, offset + 0x8000));
+          replacements.set(absolute, 'data:' + (response.headers.get('content-type') || 'application/octet-stream') + ';base64,' + btoa(binary));
+          inlinedBytes += buffer.byteLength;
+        } catch {}
+      }
+      const replaceAsset = (raw) => {
+        try { return replacements.get(new URL(raw, location.href).href) || raw; } catch { return raw; }
+      };
+      clone.querySelectorAll('[src],[poster]').forEach((node) => {
+        for (const name of ['src', 'poster']) if (node.hasAttribute(name)) node.setAttribute(name, replaceAsset(node.getAttribute(name)));
+        node.removeAttribute('srcset');
+      });
+      style.textContent = style.textContent.replace(/url\\(\\s*(['"]?)([^'"\\)]+)\\1\\s*\\)/gi, (_all, quote, raw) => 'url("' + replaceAsset(raw) + '")');
+      return '<!doctype html>\\n' + clone.outerHTML;
+    })()`
+    const result = await pipe.send('Runtime.evaluate', { expression, awaitPromise: true, returnByValue: true }, sessionId)
+    if (result.exceptionDetails || typeof result.result?.value !== 'string') {
+      const detail = result.exceptionDetails?.exception?.description || result.exceptionDetails?.text || result.result?.description
+      throw new Error(`Could not freeze the rendered preview for Design${detail ? `: ${detail}` : '.'}`)
+    }
+    const html = result.result.value
+    if (!html.trim() || Buffer.byteLength(html) > MAX_PORTABLE_SNAPSHOT_BYTES) throw new Error('The rendered preview is too large to make editable.')
+    return html
+  }
+
+  async capture({ url, viewport, fullPage = true, waitMs = 300, includeSnapshot = false }) {
     return this.withPage({ url, viewport, waitMs }, async ({ pipe, sessionId }) => {
+      const beforeState = await this.renderedState(pipe, sessionId)
       const metrics = await pipe.send('Page.getLayoutMetrics', {}, sessionId)
       const contentHeight = Math.ceil(metrics.cssContentSize?.height || viewport.height)
       const height = fullPage ? Math.min(MAX_CAPTURE_HEIGHT, Math.max(viewport.height, contentHeight)) : viewport.height
@@ -270,81 +392,14 @@ export class CdpBrowser {
         format: 'png', fromSurface: true, captureBeyondViewport: true,
         clip: { x: 0, y: 0, width: viewport.width, height, scale: 1 },
       }, sessionId)
-      return { png: Buffer.from(result.data, 'base64'), width: viewport.width, height, contentHeight, capped: contentHeight > MAX_CAPTURE_HEIGHT }
+      const afterState = await this.renderedState(pipe, sessionId)
+      const snapshot = includeSnapshot ? await this.freezeCurrentPage(pipe, sessionId) : null
+      return { png: Buffer.from(result.data, 'base64'), width: viewport.width, height, contentHeight, capped: contentHeight > MAX_CAPTURE_HEIGHT, beforeState, afterState, snapshot }
     })
   }
 
   async snapshot({ url, viewport = DEFAULT_VIEWPORTS.desktop, waitMs = 300 }) {
-    return this.withPage({ url, viewport, waitMs }, async ({ pipe, sessionId }) => {
-      // Freeze the rendered DOM, not the build entry document. A Vite/React entry
-      // depends on root-relative chunks and often boots to an empty shell in a
-      // sandboxed srcDoc; the settled DOM plus same-origin CSS/assets is portable.
-      const expression = `(async () => {
-        const clone = document.documentElement.cloneNode(true);
-        clone.querySelectorAll('script,link[rel="modulepreload"],link[rel="preload"]').forEach((node) => node.remove());
-        clone.querySelectorAll('*').forEach((node) => {
-          for (const attr of [...node.attributes]) if (/^on/i.test(attr.name)) node.removeAttribute(attr.name);
-          if (node instanceof HTMLInputElement) node.removeAttribute('value');
-          if (node instanceof HTMLTextAreaElement) node.textContent = '';
-        });
-        const css = [];
-        for (const sheet of [...document.styleSheets]) {
-          try { css.push([...sheet.cssRules].map((rule) => rule.cssText).join('\\n')); } catch {}
-        }
-        clone.querySelectorAll('style,link[rel="stylesheet"]').forEach((node) => node.remove());
-        const head = clone.querySelector('head') || clone.insertBefore(document.createElement('head'), clone.firstChild);
-        const style = document.createElement('style');
-        style.setAttribute('data-thinkpool-snapshot', '');
-        style.textContent = css.join('\\n');
-        head.appendChild(style);
-
-        const assetUrls = new Set();
-        const remember = (raw) => {
-          if (!raw || /^(data:|blob:|#)/i.test(raw)) return;
-          try {
-            const absolute = new URL(raw, location.href);
-            if (absolute.origin === location.origin) assetUrls.add(absolute.href);
-          } catch {}
-        };
-        clone.querySelectorAll('[src],[poster]').forEach((node) => {
-          remember(node.getAttribute('src'));
-          remember(node.getAttribute('poster'));
-        });
-        for (const match of style.textContent.matchAll(/url\\(\\s*(['"]?)([^'"\\)]+)\\1\\s*\\)/gi)) remember(match[2]);
-
-        const replacements = new Map();
-        let inlinedBytes = 0;
-        for (const absolute of assetUrls) {
-          try {
-            const response = await fetch(absolute);
-            const buffer = await response.arrayBuffer();
-            if (!response.ok || buffer.byteLength > 512000 || inlinedBytes + buffer.byteLength > 1000000) continue;
-            const bytes = new Uint8Array(buffer);
-            let binary = '';
-            for (let offset = 0; offset < bytes.length; offset += 0x8000) binary += String.fromCharCode(...bytes.subarray(offset, offset + 0x8000));
-            replacements.set(absolute, 'data:' + (response.headers.get('content-type') || 'application/octet-stream') + ';base64,' + btoa(binary));
-            inlinedBytes += buffer.byteLength;
-          } catch {}
-        }
-        const replaceAsset = (raw) => {
-          try { return replacements.get(new URL(raw, location.href).href) || raw; } catch { return raw; }
-        };
-        clone.querySelectorAll('[src],[poster]').forEach((node) => {
-          for (const name of ['src', 'poster']) if (node.hasAttribute(name)) node.setAttribute(name, replaceAsset(node.getAttribute(name)));
-          node.removeAttribute('srcset');
-        });
-        style.textContent = style.textContent.replace(/url\\(\\s*(['"]?)([^'"\\)]+)\\1\\s*\\)/gi, (_all, quote, raw) => 'url("' + replaceAsset(raw) + '")');
-        return '<!doctype html>\\n' + clone.outerHTML;
-      })()`
-      const result = await pipe.send('Runtime.evaluate', { expression, awaitPromise: true, returnByValue: true }, sessionId)
-      if (result.exceptionDetails || typeof result.result?.value !== 'string') {
-        const detail = result.exceptionDetails?.exception?.description || result.exceptionDetails?.text || result.result?.description
-        throw new Error(`Could not freeze the rendered preview for Design${detail ? `: ${detail}` : '.'}`)
-      }
-      const html = result.result.value
-      if (!html.trim() || Buffer.byteLength(html) > MAX_PORTABLE_SNAPSHOT_BYTES) throw new Error('The rendered preview is too large to make editable.')
-      return html
-    })
+    return this.withPage({ url, viewport, waitMs }, ({ pipe, sessionId }) => this.freezeCurrentPage(pipe, sessionId))
   }
 
   async inspect({ url, viewport = DEFAULT_VIEWPORTS.mobile, selector, waitMs = 300 }) {
@@ -424,33 +479,12 @@ export class ViewportManager {
     return new URL(normalizeRoute(route), preview.url).href
   }
 
-  async capture({ route = '/', viewports = 'both', title = 'Viewport capture', fullPage = true, waitMs = 300 } = {}) {
+  async capture({ route = '/', viewports = 'both', title = 'Viewport capture', fullPage = true, waitMs = 300, card = false } = {}) {
     const normalizedRoute = normalizeRoute(route)
     const url = this.pageUrl(normalizedRoute)
     const names = viewports === 'both' ? ['desktop', 'mobile'] : [viewports]
     if (names.some((name) => !DEFAULT_VIEWPORTS[name])) throw new Error('viewports must be "both", "desktop", or "mobile".')
-    await fsp.mkdir(this.outbox, { recursive: true })
     const slug = `${safeSlug(title)}-${Date.now().toString(36)}`
-    // A preview browser is deliberately isolated and cannot inherit the room
-    // member's Supabase session. Catch the production failure mode where an
-    // agent requests /?r=ROOM expecting Code, but actually renders the public
-    // invitation landing and publishes it under an unrelated feature title.
-    // Validate before writing screenshots or a manifest so no misleading card
-    // can enter the room.
-    const snapshotViewport = names.includes('desktop') ? DEFAULT_VIEWPORTS.desktop : DEFAULT_VIEWPORTS[names[0]]
-    const snapshot = await this.browser.snapshot({ url, viewport: snapshotViewport, waitMs })
-    if (isSignedOutRoomPreview(normalizedRoute, snapshot)) {
-      throw new Error('Preview resolved to the signed-out room invitation instead of the authenticated Code room. preview_capture uses a fresh isolated browser and cannot inherit a person\'s login. Use an authenticated visual harness or signed-in browser evidence; no mockup card was created.')
-    }
-    const captures = {}
-    for (const name of names) {
-      const result = await this.browser.capture({ url, viewport: DEFAULT_VIEWPORTS[name], fullPage, waitMs })
-      const file = path.join(this.outbox, `${slug}--${name}.png`)
-      await fsp.writeFile(file, result.png)
-      captures[name] = { ...result, file }
-    }
-    const snapshotPath = path.join(this.outbox, `${slug}--source.html`)
-    await fsp.writeFile(snapshotPath, snapshot)
     const workspace = await fsp.realpath(this.workspaceRoot)
     const previewRoot = path.relative(workspace, this.root) || '.'
     const captureKey = JSON.stringify([previewRoot, normalizedRoute])
@@ -458,16 +492,45 @@ export class ViewportManager {
     const correlation = active?.captureKey === captureKey
       ? { designRequestId: active.requestId, parentRevision: active.parentRevision }
       : {}
-    // A room card is a finished artifact, not a partial verification frame. A
-    // one-viewport request still returns useful MCP image evidence, but only the
-    // exact desktop+mobile pair gets a manifest and enters the turn-final queue.
-    const cardReady = !!(captures.desktop && captures.mobile)
+    // A correlated Design revision is already an explicit room deliverable;
+    // ordinary verification still needs the caller to opt in with card=true.
+    const cardRequested = card === true || !!correlation.designRequestId
+    const captures = {}
+    for (const name of names) {
+      captures[name] = await this.browser.capture({
+        url, viewport: DEFAULT_VIEWPORTS[name], fullPage, waitMs,
+        includeSnapshot: cardRequested && name === (names.includes('desktop') ? 'desktop' : names[0]),
+      })
+    }
+    // The screenshot and readiness state must come from the SAME page. The old
+    // preflight loaded one page and then opened fresh pages for each PNG;
+    // production proved the preflight could see marketing content while the
+    // screenshot caught only the boot spinner.
+    const cardReady = cardRequested && !!(captures.desktop && captures.mobile)
+    if (cardReady) {
+      for (const [name, capture] of Object.entries(captures)) {
+        const issue = previewArtifactIssue(normalizedRoute, capture)
+        if (issue) throw new Error(`${name} deliverable rejected: ${issue} No mockup card was created.`)
+      }
+    }
+    const snapshot = captures.desktop?.snapshot || captures.mobile?.snapshot || null
+    if (cardReady && (typeof snapshot !== 'string' || !snapshot.trim())) {
+      throw new Error('The deliverable could not freeze its rendered source. No mockup card was created.')
+    }
+    await fsp.mkdir(this.outbox, { recursive: true })
+    for (const [name, capture] of Object.entries(captures)) {
+      capture.file = path.join(this.outbox, `${slug}--${name}.png`)
+      await fsp.writeFile(capture.file, capture.png)
+    }
+    const snapshotPath = cardReady ? path.join(this.outbox, `${slug}--source.html`) : null
+    if (snapshotPath) await fsp.writeFile(snapshotPath, snapshot)
     let manifestPath = null
     if (cardReady) {
       const manifest = {
         slug, title: String(title || 'Viewport capture').slice(0, 120),
         desktop: captures.desktop.file, mobile: captures.mobile.file, ts: Date.now(),
-        sourceKind: 'preview', snapshot: snapshotPath, previewRoot, route: normalizedRoute, captureKey,
+        sourceKind: 'preview', deliveryIntent: 'card', readinessValidated: true,
+        snapshot: snapshotPath, previewRoot, route: normalizedRoute, captureKey,
         ...correlation,
       }
       manifestPath = path.join(this.outbox, `${slug}.json`)
@@ -509,23 +572,24 @@ export function createViewportTools({ tool, z, manager }) {
     ),
     tool(
       'preview_capture',
-      'Capture this lane preview in a fresh isolated browser at exact desktop (1440×900) and mobile (390×844) CSS viewports. Defaults to both and full-page. Authenticated app routes require an authenticated visual harness; a room route that resolves to the signed-out invitation is rejected. Captures always return PNG evidence; only a complete desktop+mobile capture surfaces a mockup card, after the agent final response.',
+      'Capture this lane preview in a fresh isolated browser at exact desktop (1440×900) and mobile (390×844) CSS viewports. Defaults to both and full-page. Captures are inline verification evidence by default. Set card=true only for a user-requested mockup or visual deliverable that should remain editable in the transcript; complete desktop+mobile settled content is then required and the card arrives after the final response. Authenticated app routes require an authenticated visual harness.',
       {
         path: z.string().max(500).optional().describe('route within the preview, e.g. / or /settings; never a full URL'),
         viewports: z.enum(['both', 'desktop', 'mobile']).optional(),
         title: z.string().max(120).optional(),
         fullPage: z.boolean().optional(),
+        card: z.boolean().optional().describe('default false; true only for an intentional user-facing mockup/Design deliverable'),
         waitMs: z.number().int().min(0).max(MAX_SETTLE_MS).optional().describe('settle time after load, max 5000ms'),
       },
       async (args) => {
         try {
           const result = await manager.capture({
             route: args?.path || '/', viewports: args?.viewports || 'both', title: args?.title || 'Viewport capture',
-            fullPage: args?.fullPage !== false, waitMs: args?.waitMs ?? 300,
+            fullPage: args?.fullPage !== false, waitMs: args?.waitMs ?? 300, card: args?.card === true,
           })
           const delivery = result.cardReady
             ? 'The complete room preview card is queued after your final response.'
-            : 'This is partial viewport evidence only; no room card was created.'
+            : 'This is verification evidence only; no room card was created.'
           const content = [{ type: 'text', text: `Captured ${Object.keys(result.captures).join(' + ')} for ${args?.path || '/'}. ${delivery}` }]
           for (const [name, capture] of Object.entries(result.captures)) {
             content.push({ type: 'text', text: `${name}: ${capture.width}×${capture.height}${capture.capped ? ' (height capped)' : ''}` })