@bendyline/docblocks-cli 2.2.0 → 2.2.2

package/dist/bin.js

@@ -1872,6 +1872,66 @@ async function validatePreparedDocument(_documents, prepared, targetFormat, sign
     diagnostics: unique
   };
 }
+function annotationSyntaxDiagnostics(markdown, stage, format) {
+  const diagnostics = [];
+  const lines = markdown.split(/\r?\n/);
+  let inFence = false;
+  for (let lineIndex = 0; lineIndex < lines.length; lineIndex += 1) {
+    if (diagnostics.length >= MCP_WIRE_LIMITS5.arrayEntries) break;
+    const rawLine = lines[lineIndex];
+    if (/^\s*(?:```|~~~)/u.test(rawLine)) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+    const line = rawLine.replace(/`[^`]*`/gu, "``");
+    let search = 0;
+    while (search < line.length) {
+      const open6 = line.indexOf("{[", search);
+      if (open6 === -1) break;
+      const close = line.indexOf("]}", open6 + 2);
+      if (close === -1) {
+        diagnostics.push(
+          malformedAnnotationDiagnostic(
+            stage,
+            format,
+            lineIndex + 1,
+            open6 + 1,
+            'An annotation opened with "{[" has no matching "]}" on the same line.'
+          )
+        );
+        break;
+      }
+      const inner = line.slice(open6 + 2, close).replace(/"[^"]*"/gu, '""');
+      if (/[{}[\]]/u.test(inner)) {
+        diagnostics.push(
+          malformedAnnotationDiagnostic(
+            stage,
+            format,
+            lineIndex + 1,
+            open6 + 1,
+            "An annotation contains a stray brace or bracket outside quoted values."
+          )
+        );
+      }
+      search = close + 2;
+    }
+  }
+  return diagnostics;
+}
+function malformedAnnotationDiagnostic(stage, format, line, column, message) {
+  return {
+    code: "malformed-template-annotation",
+    severity: "warning",
+    stage,
+    format,
+    count: 1,
+    message,
+    remediation: 'Repair the annotation so it reads exactly `{[templateId key="value"]}` with no extra braces or brackets, then validate again.',
+    retryable: false,
+    location: { kind: "source", line, column }
+  };
+}
 async function authoringDiagnostics(prepared, stage, format, signal) {
   throwIfAborted5(signal);
   const {
@@ -1885,7 +1945,11 @@ async function authoringDiagnostics(prepared, stage, format, signal) {
   const blocks = flattenBlocks(prepared.doc.blocks);
   const analyzedBlocks = blocks.slice(0, MCP_WIRE_LIMITS5.arrayEntries);
   const theme = resolveThemeForDoc(prepared.doc);
-  const diagnostics = [];
+  const diagnostics = annotationSyntaxDiagnostics(
+    prepared.markdown,
+    stage,
+    format
+  );
   for (let index = 0; index < analyzedBlocks.length; index += 1) {
     const checkpoint = cancellationCheckpoint(signal, index);
     if (checkpoint) await checkpoint;
@@ -4189,7 +4253,7 @@ function registerAgenticTools(server, context) {
   server.registerTool(
     "list_roots",
     {
-      description: "List opaque root aliases granted when this DocBlocks MCP server started. Root aliases improve path usability but never expand authority.",
+      description: "Call first when durable local output is requested. Lists opaque startup-granted roots; if none is write-enabled, save_artifact cannot publish a file and the MCP server must be restarted with --allow-write.",
       inputSchema: z.object({}).strict(),
       outputSchema: DOCBLOCKS_MCP_TOOL_OUTPUT_SCHEMAS.list_roots,
       annotations: READ_ONLY
@@ -4197,7 +4261,7 @@ function registerAgenticTools(server, context) {
     async () => {
       try {
         const roots = (await context.authority).listRoots();
-        return textAndStructured({ roots });
+        return textAndStructured({ roots }, rootDiscoveryText(roots));
       } catch (caught) {
         return errorResult(caught, "resolve");
       }
@@ -4274,7 +4338,7 @@ function registerAgenticTools(server, context) {
   server.registerTool(
     "create_document_bundle",
     {
-      description: "Optionally stage Markdown plus authority-scoped assets as a reusable immutable DBK artifact when the same bundle will feed several operations. For normal authoring, pass complete Markdown or a bundle source directly to convert_document.",
+      description: "Stage Markdown plus authority-scoped assets as a reusable immutable DBK artifact when the same complete draft will be passed to two or more validate, inspect, preview, or convert calls. Pass its artifact URI instead of repeating the Markdown.",
       inputSchema: z.object({ source: bundleDocumentSourceSchema }).strict(),
       outputSchema: DOCBLOCKS_MCP_TOOL_OUTPUT_SCHEMAS.create_document_bundle,
       annotations: ARTIFACT_CREATING
@@ -4348,7 +4412,7 @@ function registerAgenticTools(server, context) {
   server.registerTool(
     "inspect_document",
     {
-      description: "Inspect any linked-registry document as bounded semantic structure, block provenance, assets, metadata, theme, and diagnostics.",
+      description: "Inspect bounded semantic structure, block provenance, assets, metadata, theme, and diagnostics. Use for those details; do not pair it with validate_document for a routine export preflight.",
       inputSchema: z.object({
         source: documentSourceSchema,
         maxBlocks: z.number().int().min(1).max(2e3).optional(),
@@ -4380,7 +4444,7 @@ function registerAgenticTools(server, context) {
   server.registerTool(
     "validate_document",
     {
-      description: "Validate document structure, templates, annotations, assets, accessibility, and optional target-format fidelity before export.",
+      description: "Primary pre-export review for structure, template content retention, annotations, assets, accessibility, and target fidelity. Diagnostics include repairs; normally do not also call inspect_document.",
       inputSchema: z.object({
         source: documentSourceSchema,
         targetFormat: formatInputSchema.nullable().optional()
@@ -4553,7 +4617,7 @@ function registerAuthoringGuideResource(server) {
     "authoring-guide",
     "docblocks://authoring-guide",
     {
-      description: "Compact linked-Squisq authoring vocabulary, artifact workflow, fidelity modes, templates, themes, and transform styles.",
+      description: "Complete linked-Squisq authoring catalog with exact template inputs, fidelity modes, themes, and transform styles. Read only when the focused authoring context is insufficient.",
       mimeType: "application/json",
       annotations: { audience: ["assistant"], priority: 1 }
     },
@@ -4564,15 +4628,15 @@ function registerAuthoringGuideResource(server) {
         import("@bendyline/squisq/transform")
       ]);
       const guide = {
-        version: 6,
+        version: 7,
         workflow: [
           "treat supplied facts as a closed evidence set; label calculations, assumptions, hypotheses, recommendations, and examples; do not present causal links, rhetorical performance labels, superlatives, sole causes, targets, capabilities, owners, dates, channels, or operational details as established facts unless supplied",
           "when the requested genre needs unsupplied roles, gates, timelines, channels, or procedures, add one explicit proposed operating model scope note that applies to those details, then complete the requested element",
           "author complete Squisq-compatible Markdown with annotations bound to headings; ordinary headings default to the loss-averse content template",
           "for PPTX, use exactly one level-one Markdown heading per slide and no level-two through level-six headings because every heading becomes a slide by default",
           "by default, pass the complete Markdown\u2014or a bundle source when assets are needed\u2014directly to convert_document; revise by editing the complete Markdown and converting again",
-          "use create_document_bundle only when a reusable staged DBK materially avoids repeating a large Markdown-and-asset bundle across several operations",
-          "use inspect_document, validate_document, and preview_document when their semantic, diagnostic, or visual evidence is useful; they are review tools rather than required phases",
+          "use create_document_bundle when the same complete draft will be passed to two or more validate, inspect, preview, or convert calls, then pass its artifact URI instead of repeating Markdown",
+          "use validate_document as the routine export preflight; use inspect_document only for semantic structure, provenance, assets, metadata, or theme details; use preview_document only when visual evidence is useful",
           "for visual polish, replace selected content blocks with compatible visual templates while preserving required content",
           "convert_document creates one or more immutable artifacts from the authoritative complete source",
           "save_artifact only when a durable file is required"
@@ -4616,7 +4680,7 @@ function registerTemplateTools(server, context) {
   server.registerTool(
     "get_authoring_context",
     {
-      description: "Get a compact agent-facing authoring contract plus the complete linked-Squisq catalog in structured content, with optional block recommendations.",
+      description: "Get a focused authoring contract, target capability, safe default template, themes, transforms, and optional source-based recommendations. Exact full template inputs remain on demand through describe_template or docblocks://authoring-guide.",
       inputSchema: z.object({
         targetFormat: formatInputSchema.optional(),
         goal: z.enum(["content-first", "visual-polish"]).optional(),
@@ -4639,11 +4703,13 @@ function registerTemplateTools(server, context) {
               throw new Error(`Format "${normalizedTarget}" is not export-capable`);
             }
           }
-          const [templates, schemaModule, transformModule] = await Promise.all([
+          const [fullTemplates, schemaModule, transformModule] = await Promise.all([
             authoringTemplateCatalog(),
             import("@bendyline/squisq/schemas"),
             import("@bendyline/squisq/transform")
           ]);
+          const annotationHandling = normalizedTarget ? await targetTemplateAnnotationHandling(normalizedTarget) : null;
+          const candidateTemplates = annotationHandling === "ignored" ? fullTemplates.filter((template) => template.safeForContentFirst) : fullTemplates;
           let recommendations = [];
           let totalBlocks = null;
           let truncated = false;
@@ -4663,7 +4729,7 @@ function registerTemplateTools(server, context) {
               const profile = recommendModule.profileBlockContents(block.contents ?? []);
               const visual = recommendModule.recommendTemplatesForBlock(
                 profile,
-                templates.map((template) => template.id)
+                candidateTemplates.map((template) => template.id)
               ).recommended;
               const recommendedTemplateIds = goal === "content-first" ? ["content", ...visual.filter((id) => id !== "content")] : visual;
               return {
@@ -4687,29 +4753,23 @@ function registerTemplateTools(server, context) {
             defaultTemplateId: "content",
             defaultFidelity: authoringDefaultFidelity(normalizedTarget, goal),
             workflow: [
-              "Treat supplied facts as a closed evidence set. Use temporal or correlational wording unless causality is supplied. Label calculations, assumptions, hypotheses, recommendations, and illustrative examples. Do not infer end-to-end feasibility from one supplied phase duration.",
-              "Audit claims before conversion: causal links, rhetorical labels such as compounding, engine, healthy, strong, or constraint, superlatives, sole-cause claims, targets, capabilities, owners, dates, channels, and operational details must be supplied or explicitly framed as a hypothesis, recommendation, example, or proposal. Do not connect separate metrics, audiences, segments, or workflows unless the relationship is supplied. Prefer observed, coincided with, intended to, or proposed over drove, addresses, protects, or proves. Do not call choices a sequence or capacity allocation unless order, timing, or resource constraints were supplied.",
-              "Complete every requested element without presenting invented policy as established fact. When a requested policy, playbook, or training guide needs unsupplied roles, gates, timelines, channels, or procedures, add one explicit proposed operating model scope note placed before the first such detail so it governs all of them.",
-              "Generic option traits\u2014control, flexibility, vendor support, freed capacity, switching costs\u2014are capability claims: state one only when supplied or labeled Assumption or Judgment, even in table cells and tradeoffs.",
-              "Author complete Squisq-compatible content with heading-bound annotations; ordinary headings default to the loss-averse content template.",
+              "For durable local output, call list_roots before drafting. If no returned root is write-enabled, stop and explain that the MCP server must restart with --allow-write; do not fall back to a shell or CLI converter. A transient artifact is acceptable only when the user did not require a file.",
+              "Treat supplied facts as a closed evidence set. Preserve them exactly; label calculations, assumptions, hypotheses, recommendations, causal claims, capabilities, owners, dates, and unsupplied operating details. When a requested policy or playbook needs invented procedures, introduce one proposed operating model scope note before those details.",
               normalizedTarget === "pptx" ? "Match every explicitly requested slide count exactly. Use exactly one level-one Markdown heading (#) per slide and no level-two through level-six headings because every heading becomes a slide by default. Target at most 80 words per slide, and use lists, tables, or bold labels for within-slide structure." : "Honor the requested word range and document genre. Prefer connected memo prose for executive decisions and native headings, tables, and checklists for operational documents.",
-              normalizedTarget === "pptx" ? "Make slide one a supported point-of-view thesis, not a generic title or unsupported flourish. For requested choices, state a concrete opportunity cost grounded in the supplied alternatives and name one clearly labeled proposed accountable role per choice. If a tradeoff requires an unsupplied capacity or outcome assumption, label it Assumption or Potential tradeoff rather than stating it as fact." : "Tie each decision implication or comparative judgment to a supplied fact or calculation, or label it Judgment. When accountability is requested but not supplied, name one clearly labeled proposed accountable role per decision or workstream.",
-              "Add decision value without inventing causes: interpret supplied comparisons to baselines, goals, targets, and rankings; use transparent calculations; label any new review cadence or measurement procedure as proposed.",
-              "Before validation and conversion, run a content preflight: count slide sections or document words, verify every requested element, and rewrite or label every unsupported claim.",
-              "Use the complete Markdown as the authoritative source. Pass it\u2014or a bundle source when assets are needed\u2014directly to convert_document, and revise by editing the complete Markdown and converting again.",
-              "Use create_document_bundle only when reusing a large Markdown-and-asset bundle across several review or conversion operations would materially reduce retransmission.",
-              "Use inspect_document or validate_document when semantic structure, content retention, accessibility, or target diagnostics need review; repair actionable findings in the authoritative Markdown.",
-              "Use preview_document when visual evidence is needed, inspect previewBasis, and repair overflow or layout problems in the authoritative Markdown.",
-              normalizedTarget === "pptx" ? "For visual polish, replace selected content blocks with compatible recommended templates; use patterns such as definitionCard for a definition, dataTable for a true table, comparisonBar for supported numeric comparisons, and list for concise steps when the returned catalog supports them. Preserve all required content and preview again." : "For visual polish, use native headings, tables, and checklists where they improve scanning; keep complete-body content when a visual template would discard detail, then preview again.",
-              "Convert to immutable artifacts, inspect conversion reports, and save only final durable outputs."
+              "Author the complete Squisq-compatible Markdown with annotations bound to headings. Ordinary headings default to the loss-averse content template; keep that default until the complete content is sound.",
+              "Before conversion, count slide sections or document words, verify every requested element, and rewrite or label unsupported claims. For decisions, ground tradeoffs in supplied alternatives and label unsupplied accountability, capacity, outcomes, and review cadences as proposed or assumed.",
+              "Use validate_document as the routine export preflight and follow its repair diagnostics. Call inspect_document only when semantic structure, provenance, assets, metadata, or theme details are needed.",
+              "When the same complete draft will feed two or more validate, inspect, preview, or convert calls, stage it once with create_document_bundle and reuse its artifact URI; after edits, stage the revised draft again.",
+              normalizedTarget === "pptx" ? "For visual polish, call recommend_templates on the complete draft, then describe_template only for selected candidates before replacing content blocks. Preserve required content and use preview_document only when visual evidence is needed." : annotationHandling === "ignored" ? "This target flattens template annotations to semantic content, so visual templates have no effect on the exported file: rely on native headings, tables, and checklists for structure and scanning." : "For visual polish, use native headings, tables, and checklists where they improve scanning; describe a selected visual template before use and keep complete-body content when it would discard detail.",
+              "Pass the authoritative Markdown or bundle source directly to convert_document. It returns immutable artifacts; call save_artifact only for final durable outputs and never switch to a shell or CLI converter."
             ],
             syntax: {
               headingAnnotation: "# Heading {[content]}",
               standaloneAnnotation: "{[content]}",
               standaloneWarning: "A standalone annotation creates an additional heading-less block. Bind it to a heading unless that extra block is deliberate."
             },
-            formats,
-            templates,
+            formats: normalizedTarget ? formats.filter((format) => format.id === normalizedTarget) : formats,
+            templates: focusedAuthoringTemplates(candidateTemplates, recommendations),
             themes: schemaModule.getThemeSummaries().slice(0, MCP_WIRE_LIMITS7.arrayEntries).map((theme) => ({
               id: requireWireIdentifier(theme.id, "theme id"),
               name: boundWireText(theme.name, MCP_WIRE_LIMITS7.labelCharacters, theme.id),
@@ -4724,7 +4784,19 @@ function registerTemplateTools(server, context) {
             totalBlocks,
             truncated
           };
-          return textAndStructured(payload, compactAuthoringContextText(payload));
+          return {
+            content: [
+              { type: "text", text: compactAuthoringContextText(payload) },
+              {
+                type: "resource_link",
+                uri: "docblocks://authoring-guide",
+                name: "authoring-guide",
+                description: "Complete linked-Squisq authoring catalog; read only if needed.",
+                mimeType: "application/json"
+              }
+            ],
+            structuredContent: asStructuredContent(successResult(payload))
+          };
         });
       } catch (caught) {
         return errorResult(caught, "inspect", null, extra.signal);
@@ -5140,6 +5212,25 @@ function textAndStructured(payload, text = JSON.stringify(payload, null, 2)) {
     structuredContent: asStructuredContent(successResult(payload))
   };
 }
+function rootDiscoveryText(roots) {
+  if (roots.length === 0) {
+    return "No DocBlocks MCP roots are configured. Durable file output is unavailable: restart the server with --allow-write <directory>. Do not fall back to a shell or CLI converter; keep a transient artifact only when the user did not require a file.";
+  }
+  const catalog = JSON.stringify({ roots }, null, 2);
+  if (roots.some((root) => root.write)) return catalog;
+  return `${catalog}
+
+No returned root is write-enabled. Durable file output is unavailable: restart the server with --allow-write <directory>. Do not fall back to a shell or CLI converter.`;
+}
+function focusedAuthoringTemplates(candidates, recommendations) {
+  const selectedIds = /* @__PURE__ */ new Set(["content"]);
+  for (const recommendation of recommendations) {
+    for (const templateId of recommendation.recommendedTemplateIds) {
+      selectedIds.add(templateId);
+    }
+  }
+  return candidates.filter((template) => selectedIds.has(template.id));
+}
 function compactAuthoringContextText(context) {
   const target = context.targetFormat ?? "unspecified target";
   const lines = [
@@ -5153,7 +5244,7 @@ function compactAuthoringContextText(context) {
     `Warning: ${context.syntax.standaloneWarning}`,
     `Templates (${context.templates.length}): ${context.templates.map(({ id }) => id).join(", ")}`,
     `Themes (${context.themes.length}): ${context.themes.map(({ id }) => id).join(", ")}`,
-    `Transform styles (${context.transformStyles.length}): ${context.transformStyles.map(({ id }) => id).join(", ")}`
+    `Transform styles (${context.transformStyles.length}): ${context.transformStyles.map(({ id }) => id).join(", ")} \u2014 transforms re-compose blocks and can change section count; avoid on exact-count briefs.`
   ];
   if (context.recommendations.length > 0) {
     lines.push(
@@ -5164,7 +5255,7 @@ function compactAuthoringContextText(context) {
   }
   lines.push(
     "",
-    "The complete exact format, template-input, theme, transform, and recommendation catalog is in structuredContent. Use describe_template for focused follow-up when structured content is unavailable."
+    "This response is intentionally focused. Use recommend_templates on a complete draft, describe_template for exact selected inputs, or read docblocks://authoring-guide only when the full catalog is required."
   );
   return lines.join("\n");
 }
@@ -5232,6 +5323,15 @@ async function authoringTemplateCatalog() {
     };
   });
 }
+async function targetTemplateAnnotationHandling(targetFormat) {
+  const { createCliRegistry: createCliRegistry2 } = await import("@bendyline/squisq-cli/api");
+  const definition = createCliRegistry2().get(targetFormat);
+  if (definition && typeof definition === "object" && "templateAnnotationHandling" in definition) {
+    const value = definition.templateAnnotationHandling;
+    if (value === "rendered" || value === "preserved" || value === "ignored") return value;
+  }
+  return null;
+}
 function authoringDefaultFidelity(targetFormat, goal) {
   if (!targetFormat) return null;
   if (targetFormat === "mp4" || targetFormat === "gif") return "rendered-fidelity";
@@ -5633,34 +5733,37 @@ function registerAuthoringPrompts(server) {
 function presentationPrompt(topic, style, theme, template) {
   return `Create a presentation about: ${topic}
 
-1. Call get_authoring_context with targetFormat "pptx" and goal "content-first" for the complete linked-Squisq vocabulary and workflow in one response.
-2. Treat the topic facts as a closed evidence set. Preserve them exactly, use temporal or correlational wording unless causality is supplied, and label calculations, assumptions, hypotheses, recommendations, and examples. Causal links, rhetorical performance labels, superlatives, sole causes, capabilities, owners, dates, channels, and operational details must be supplied or explicitly framed. Do not connect separate metrics, audiences, segments, or workflows unless the relationship is supplied. Prefer observed, coincided with, intended to, or proposed over drove, addresses, protects, or proves. Add decision value through supplied baselines, goals, targets, rankings, and transparent calculations. Do not call choices a sequence or capacity allocation unless order, timing, or resources were supplied. When the requested content needs unsupplied operating details, add one proposed operating model scope note that applies to them.
-3. Match every explicitly requested slide count exactly. Use exactly one level-one Markdown heading (\`#\`) per slide and no level-two through level-six headings because every heading becomes a slide by default; use lists, tables, or bold labels within a slide. Target at most 80 words per slide. Make slide one a supported point-of-view thesis, not a generic title or unsupported flourish. For requested choices, state concrete opportunity costs grounded in supplied alternatives and one clearly labeled proposed accountable role per choice. Label any unsupplied capacity or outcome assumption as \`Assumption:\` or \`Potential tradeoff:\`. Author complete Markdown sections with accessible alt text. Put annotations on headings, for example \`# Heading {[content]}\`; a standalone \`{[template]}\` creates an extra block. Prefer style "${style ?? "choose from the returned transform styles"}", theme "${theme ?? "choose from the returned themes"}", and template "${template ?? "content until visual optimization"}".
-4. Keep the complete Markdown as the authoritative draft. Pass it\u2014or a bundle source when assets are needed\u2014directly to convert_document. Use create_document_bundle only when the same materially large Markdown-and-asset bundle will feed several operations. Do not write a temporary local Markdown file or invent a root id.
-5. Before conversion, count slide sections, verify every requested element, and rewrite or label every unsupported claim. Label any new review cadence or measurement procedure as proposed. Use validate_document when syntax, accessibility, retention, or target diagnostics need review; use preview_document when visual evidence such as overflow needs review. Repair findings in the complete Markdown.
-6. Only after content coverage is acceptable, replace selected \`content\` blocks with compatible visual templates such as \`definitionCard\`, \`dataTable\`, \`comparisonBar\`, or \`list\` when their semantic inputs fit. Preserve required content.
-7. Call convert_document with the complete source and a pptx target. Choose editable-native for editable Office structures, rendered-fidelity for exact Squisq visuals, or hybrid for rendered visuals plus semantic retention. Revise by editing the complete Markdown and converting again.
-8. Use get_conversion_report for provenance and save_artifact only when a durable file is required.`;
+1. For durable output, call list_roots before drafting. If no returned root is write-enabled, stop and explain that the MCP server must restart with --allow-write; do not use a shell or CLI converter.
+2. Call get_authoring_context with targetFormat "pptx" and goal "content-first" for the focused linked-Squisq workflow and safe default. Read the full authoring-guide resource only if focused follow-up tools are insufficient.
+3. Treat the topic facts as a closed evidence set. Preserve them exactly, use temporal or correlational wording unless causality is supplied, and label calculations, assumptions, hypotheses, recommendations, and examples. Causal links, rhetorical performance labels, superlatives, sole causes, capabilities, owners, dates, channels, and operational details must be supplied or explicitly framed. Do not connect separate metrics, audiences, segments, or workflows unless the relationship is supplied. Prefer observed, coincided with, intended to, or proposed over drove, addresses, protects, or proves. Add decision value through supplied baselines, goals, targets, rankings, and transparent calculations. Do not call choices a sequence or capacity allocation unless order, timing, or resources were supplied. When the requested content needs unsupplied operating details, add one proposed operating model scope note that applies to them.
+4. Match every explicitly requested slide count exactly. Use exactly one level-one Markdown heading (\`#\`) per slide and no level-two through level-six headings because every heading becomes a slide by default; use lists, tables, or bold labels within a slide. Target at most 80 words per slide. Make slide one a supported point-of-view thesis, not a generic title or unsupported flourish. For requested choices, state concrete opportunity costs grounded in supplied alternatives and one clearly labeled proposed accountable role per choice. Label any unsupplied capacity or outcome assumption as \`Assumption:\` or \`Potential tradeoff:\`. Author complete Markdown sections with accessible alt text. Put annotations on headings, for example \`# Heading {[content]}\`; a standalone \`{[template]}\` creates an extra block. Prefer style "${style ?? "choose from the returned transform styles"}", theme "${theme ?? "choose from the returned themes"}", and template "${template ?? "content until visual optimization"}".
+5. Keep the complete Markdown as the authoritative draft. If it will feed two or more validate, inspect, preview, or convert calls, stage it once with create_document_bundle and reuse the artifact URI. Otherwise pass it\u2014or a bundle source when assets are needed\u2014directly to convert_document. Do not write a temporary local Markdown file or invent a root id.
+6. Before conversion, count slide sections, verify every requested element, and rewrite or label every unsupported claim. Use validate_document as the routine export preflight; use inspect_document only for semantic or metadata detail and preview_document only for visual evidence such as overflow. Repair findings in the complete Markdown.
+7. Only after content coverage is acceptable, call recommend_templates, describe only selected candidates, and replace compatible \`content\` blocks when their semantic inputs fit. Preserve required content.
+8. Call convert_document with the complete source and a pptx target. Choose editable-native for editable Office structures, rendered-fidelity for exact Squisq visuals, or hybrid for rendered visuals plus semantic retention. Revise by editing the complete Markdown and converting again.
+9. Use get_conversion_report for provenance and save_artifact only when a durable file is required.`;
 }
 function videoPrompt(topic, orientation, theme, template) {
   return `Create a video about: ${topic}
 
-1. Call get_authoring_context with targetFormat "mp4" for the complete linked-Squisq vocabulary and workflow.
-2. Author concise Markdown for a ${orientation ?? "landscape"} animated sequence using theme "${theme ?? "choose from the returned themes"}" and template "${template ?? "content until visual optimization"}". Bind annotations to headings.
-3. Keep the complete Markdown as the authoritative draft and pass it\u2014or a bundle source when assets are needed\u2014directly to convert_document. Use validate_document for uncertain target constraints and preview_document when representative-frame evidence is useful; repair findings in the complete Markdown.
-4. Call convert_document with the complete source, an mp4 target, and orientation "${orientation ?? "landscape"}"; monitor progress and honor cancellation. Revise by editing the complete Markdown and converting again.
-5. Use get_conversion_report for provenance and save_artifact only when a durable file is required.`;
+1. For durable output, call list_roots before drafting and stop if no root is write-enabled; do not use a shell or CLI converter.
+2. Call get_authoring_context with targetFormat "mp4" for the focused linked-Squisq workflow.
+3. Author concise Markdown for a ${orientation ?? "landscape"} animated sequence using theme "${theme ?? "choose from the returned themes"}" and template "${template ?? "content until visual optimization"}". Bind annotations to headings.
+4. Keep the complete Markdown as the authoritative draft and pass it\u2014or a bundle source when assets are needed\u2014directly to convert_document. Use validate_document for uncertain target constraints and preview_document when representative-frame evidence is useful; repair findings in the complete Markdown.
+5. Call convert_document with the complete source, an mp4 target, and orientation "${orientation ?? "landscape"}"; monitor progress and honor cancellation. Revise by editing the complete Markdown and converting again.
+6. Use get_conversion_report for provenance and save_artifact only when a durable file is required.`;
 }
 function documentPrompt(topic, format, theme, template) {
   const target = format ?? "pdf";
   return `Create a professional document about: ${topic}
 
-1. Call get_authoring_context with targetFormat "${target}" for the complete linked-Squisq vocabulary and workflow.
-2. Treat the topic facts as a closed evidence set. Preserve them exactly, use temporal or correlational wording unless causality is supplied, and label calculations, assumptions, hypotheses, recommendations, and examples. Causal links, superlatives, sole causes, capabilities, owners, dates, channels, and operational details must be supplied or explicitly framed. When the requested genre needs unsupplied roles, gates, timelines, channels, or procedures, add one proposed operating model scope note that applies to those details.
-3. Honor the requested word range and document genre. Author structured Markdown using theme "${theme ?? "choose from the returned themes"}" and template "${template ?? "content until visual optimization"}". Bind annotations to headings. Use connected memo prose for executive decisions and native headings, tables, and checklists for operational documents; retain complete-body content when a visual template would discard detail.
-4. Before conversion, count document words, verify every requested element, and rewrite or label every unsupported claim. Keep the complete Markdown as the authoritative draft and pass it\u2014or a bundle source when assets are needed\u2014directly to convert_document. Use validate_document when syntax, accessibility, retention, or target diagnostics need review, and preview_document when page-layout evidence is useful; repair findings in the complete Markdown.
-5. Call convert_document with the complete source and a ${target} target to create an immutable artifact. Revise by editing the complete Markdown and converting again.
-6. Use get_conversion_report for provenance and save_artifact only when a durable file is required.`;
+1. For durable output, call list_roots before drafting and stop if no root is write-enabled; do not use a shell or CLI converter.
+2. Call get_authoring_context with targetFormat "${target}" for the focused linked-Squisq workflow.
+3. Treat the topic facts as a closed evidence set. Preserve them exactly, use temporal or correlational wording unless causality is supplied, and label calculations, assumptions, hypotheses, recommendations, and examples. Causal links, superlatives, sole causes, capabilities, owners, dates, channels, and operational details must be supplied or explicitly framed. When the requested genre needs unsupplied roles, gates, timelines, channels, or procedures, add one proposed operating model scope note that applies to those details.
+4. Honor the requested word range and document genre. Author structured Markdown using theme "${theme ?? "choose from the returned themes"}" and template "${template ?? "content until visual optimization"}". Bind annotations to headings. Use connected memo prose for executive decisions and native headings, tables, and checklists for operational documents; retain complete-body content when a visual template would discard detail.
+5. Before conversion, count document words, verify every requested element, and rewrite or label every unsupported claim. If the complete draft will feed two or more review or conversion calls, stage it with create_document_bundle and reuse the artifact URI. Use validate_document as the routine export preflight and preview_document only when page-layout evidence is useful; repair findings in the complete Markdown.
+6. Call convert_document with the complete source and a ${target} target to create an immutable artifact. Revise by editing the complete Markdown and converting again.
+7. Use get_conversion_report for provenance and save_artifact only when a durable file is required.`;
 }
 function complete(values, prefix) {
   const value = prefix ?? "";
@@ -5702,7 +5805,16 @@ function createMcpServer(options = {}) {
   const server = new McpServer(
     { name: "docblocks", version: getPackageVersion() },
     {
-      instructions: "Treat provided facts as a closed evidence set: preserve them exactly; use temporal or correlational wording unless causality is supplied; label calculations, assumptions, hypotheses, recommendations, and examples. Causal links, rhetorical performance labels, superlatives, sole causes, targets, capabilities, owners, dates, channels, and operational details must be supplied or explicitly framed. Do not connect separate metrics, audiences, segments, or workflows unless the relationship is supplied. Prefer observed, coincided with, intended to, or proposed over drove, addresses, protects, or proves. Add decision value through supplied baselines, goals, targets, rankings, and transparent calculations. Do not call choices a sequence or capacity allocation unless order, timing, or resources were supplied. When a requested policy, playbook, or training guide needs unsupplied operating details, add one proposed operating model scope note, then complete every requested element. Match explicit slide/page counts and word ranges exactly; target at most 80 words per presentation section. Make slide one a supported point-of-view thesis. For requested choices, state concrete opportunity costs grounded in supplied alternatives and one proposed accountable role per choice; label unsupplied capacity, outcome, or review-cadence assumptions. Before conversion, count sections or words, verify required elements, and audit unsupported claims. Start with get_authoring_context for the compact linked-Squisq contract and structured catalog. Author complete Squisq-compatible Markdown with template annotations on headings, for example `# Heading {[content]}`; standalone `{[template]}` creates an extra heading-less block. Ordinary headings default to the loss-averse `content` template. The canonical path is complete Markdown\u2014or a bundle source when assets are needed\u2014directly into convert_document; revise by editing the complete Markdown and converting again. create_document_bundle is optional for materially large, reusable Markdown-and-asset bundles. Use inspect_document, validate_document, and preview_document when their evidence is useful rather than as required phases. Save only the final durable artifact. Never invent root ids: call list_roots and use an id exactly as returned."
+      instructions: [
+        "For durable local output, call list_roots before drafting and use a returned write-enabled root id exactly as given. If none is writable, stop and explain that the server must restart with --allow-write; do not fall back to a shell or CLI converter.",
+        "Call get_authoring_context once for the focused linked-Squisq contract. Read the full authoring-guide resource or call describe_template only when exact additional catalog detail is needed; do not also enumerate catalogs by default.",
+        "Treat supplied facts as a closed evidence set: preserve them exactly, use temporal or correlational wording unless causality is supplied, and label calculations, assumptions, hypotheses, recommendations, capabilities, owners, dates, and unsupplied operating details. For a policy or playbook, introduce one proposed operating model scope note before invented procedures.",
+        "Honor explicit slide/page counts and word ranges. For PPTX use one level-one heading per slide, no lower-level headings, and at most 80 words per slide. Ground decision tradeoffs in supplied alternatives and label unsupplied accountability, capacity, outcomes, or review cadences as proposed or assumed.",
+        "Author complete Squisq-compatible Markdown with annotations on headings, for example `# Heading {[content]}`. Ordinary headings default to the loss-averse content template; standalone annotations create an extra heading-less block.",
+        "Use validate_document as the routine export preflight and repair its diagnostics. Use inspect_document only for semantic structure, provenance, assets, metadata, or theme details, and preview_document only when visual evidence is useful.",
+        "When the same complete draft will feed two or more validate, inspect, preview, or convert calls, stage it once with create_document_bundle and reuse its artifact URI instead of resending Markdown.",
+        "Pass the complete Markdown or bundle source directly into convert_document. Save only the final durable artifact with save_artifact; never invent root ids or switch conversion to a shell or CLI."
+      ].join(" ")
     }
   );
   registerAgenticTools(server, {

package/dist/eval/cli.js

@@ -704,7 +704,8 @@ function missingArtifact(caught) {
 }
 
 // src/eval/codex-host.ts
-import { readFile as readFile3, writeFile as writeFile2 } from "fs/promises";
+import { mkdtemp, readFile as readFile3, rm, writeFile as writeFile2 } from "fs/promises";
+import { tmpdir } from "os";
 import path3 from "path";
 import { z } from "zod";
 
@@ -908,17 +909,30 @@ async function runGeneration(options, testCase, caseDirectory) {
   const prompt = generationPrompt(testCase, options.profile);
   await writeFile2(path3.join(caseDirectory, "generation-prompt.txt"), prompt);
   const resolved = await resolveCodexCommand(options.codexCommand);
+  const agentCwd = await mkdtemp(path3.join(tmpdir(), "docblocks-eval-agent-"));
   const args = [
     ...resolved.prefixArgs,
-    ...buildCodexGenerationArgs(options, testCase, caseDirectory, outputSchemaPath, finalPath)
+    ...buildCodexGenerationArgs(
+      options,
+      testCase,
+      caseDirectory,
+      agentCwd,
+      outputSchemaPath,
+      finalPath
+    )
   ];
-  const capture = await runCapturedProcess({
-    command: resolved.command,
-    args,
-    cwd: options.repoRoot,
-    stdin: prompt,
-    timeoutMs: 15 * 60 * 1e3
-  });
+  let capture;
+  try {
+    capture = await runCapturedProcess({
+      command: resolved.command,
+      args,
+      cwd: agentCwd,
+      stdin: prompt,
+      timeoutMs: 15 * 60 * 1e3
+    });
+  } finally {
+    await rm(agentCwd, { recursive: true, force: true }).catch(() => void 0);
+  }
   await Promise.all([
     writeFile2(path3.join(caseDirectory, "generation-trace.jsonl"), capture.stdout),
     writeFile2(path3.join(caseDirectory, "generation-stderr.log"), capture.stderr)
@@ -951,6 +965,7 @@ async function runLlmJudge(options, testCase, markdown, caseDirectory) {
   const prompt = judgePrompt(testCase, markdown);
   await writeFile2(path3.join(caseDirectory, "judge-prompt.txt"), prompt);
   const resolved = await resolveCodexCommand(options.codexCommand);
+  const judgeCwd = await mkdtemp(path3.join(tmpdir(), "docblocks-eval-judge-"));
   const args = [
     ...resolved.prefixArgs,
     "exec",
@@ -964,7 +979,7 @@ async function runLlmJudge(options, testCase, markdown, caseDirectory) {
     "--color",
     "never",
     "--cd",
-    caseDirectory,
+    judgeCwd,
     "--output-schema",
     outputSchemaPath,
     "--output-last-message",
@@ -972,13 +987,18 @@ async function runLlmJudge(options, testCase, markdown, caseDirectory) {
     ...options.model ? ["--model", options.model] : [],
     "-"
   ];
-  const capture = await runCapturedProcess({
-    command: resolved.command,
-    args,
-    cwd: options.repoRoot,
-    stdin: prompt,
-    timeoutMs: 10 * 60 * 1e3
-  });
+  let capture;
+  try {
+    capture = await runCapturedProcess({
+      command: resolved.command,
+      args,
+      cwd: judgeCwd,
+      stdin: prompt,
+      timeoutMs: 10 * 60 * 1e3
+    });
+  } finally {
+    await rm(judgeCwd, { recursive: true, force: true }).catch(() => void 0);
+  }
   await Promise.all([
     writeFile2(path3.join(caseDirectory, "judge-trace.jsonl"), capture.stdout),
     writeFile2(path3.join(caseDirectory, "judge-stderr.log"), capture.stderr)
@@ -990,7 +1010,7 @@ async function runLlmJudge(options, testCase, markdown, caseDirectory) {
     usage: extractTokenUsage(capture.stdout)
   };
 }
-function buildCodexGenerationArgs(options, testCase, caseDirectory, outputSchemaPath, finalPath) {
+function buildCodexGenerationArgs(options, testCase, caseDirectory, agentCwd, outputSchemaPath, finalPath) {
   const mcpArgs = [
     options.cliEntry,
     "mcp",
@@ -1013,7 +1033,7 @@ function buildCodexGenerationArgs(options, testCase, caseDirectory, outputSchema
     "--color",
     "never",
     "--cd",
-    caseDirectory,
+    agentCwd,
     "-c",
     `mcp_servers.docblocks.command=${tomlString(process.execPath)}`,
     "-c",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bendyline/docblocks-cli",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "description": "Build, preview, convert, render, inspect, and automate documents",
   "license": "MIT",
   "author": "Bendyline",
@@ -39,24 +39,25 @@
     "node": ">=22.14.0"
   },
   "files": [
-    "dist"
+    "dist",
+    "THIRD_PARTY_NOTICES.txt"
   ],
   "scripts": {
     "build": "tsup",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@bendyline/docblocks": "2.2.0",
-    "@bendyline/squisq": "2.3.2",
-    "@bendyline/squisq-cli": "2.3.2",
-    "@bendyline/squisq-formats": "2.3.2",
-    "@bendyline/squisq-react": "2.3.2",
-    "@bendyline/squisq-video": "2.2.2",
+    "@bendyline/docblocks": "2.2.2",
+    "@bendyline/squisq": "2.4.1",
+    "@bendyline/squisq-cli": "2.4.1",
+    "@bendyline/squisq-formats": "2.3.5",
+    "@bendyline/squisq-react": "2.4.1",
+    "@bendyline/squisq-video": "2.2.5",
     "@modelcontextprotocol/sdk": "1.29.0",
     "commander": "13.1.0",
     "jszip": "3.10.1",
-    "playwright-core": "1.58.2",
     "pdf-lib": "1.17.1",
+    "playwright-core": "1.61.1",
     "zod": "3.25.76"
   }
 }