@bendyline/docblocks-cli 2.1.2 → 2.2.1

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;
@@ -4161,258 +4225,13 @@ var init_progress = __esm({
   }
 });
 
-// src/mcp/revision-service.ts
-import { createHash as createHash7 } from "crypto";
-import {
-  DOCBLOCKS_MCP_WIRE_VERSION as DOCBLOCKS_MCP_WIRE_VERSION5,
-  MCP_WIRE_LIMITS as MCP_WIRE_LIMITS7,
-  parseDocumentRevisionResult
-} from "@bendyline/docblocks/mcp";
-async function reviseDocumentArtifact(artifacts, documents, request, signal) {
-  throwIfAborted5(signal);
-  const parentArtifact = await artifacts.get(request.artifactUri, signal);
-  if (parentArtifact.sha256 !== request.expectedSha256) {
-    throw revisionError(
-      "conflict",
-      `Revision precondition failed: expected ${request.expectedSha256}, but the parent artifact is ${parentArtifact.sha256}.`,
-      `Use expectedSha256 "${parentArtifact.sha256}" only if this is still the intended parent artifact.`
-    );
-  }
-  if (parentArtifact.format !== "dbk") {
-    throw revisionError(
-      "invalid-revision-source",
-      `Artifact-native block revision requires a DBK parent, not ${parentArtifact.format}.`,
-      "Stage Markdown and assets with create_document_bundle, or convert the source to DBK first."
-    );
-  }
-  if (new Set(request.edits.map((edit) => edit.blockId)).size !== request.edits.length) {
-    throw revisionError(
-      "duplicate-block-edit",
-      "Each block id may be revised at most once per request.",
-      "Combine changes to the same block into one replacement fragment."
-    );
-  }
-  const totalReplacementCharacters = request.edits.reduce(
-    (sum, edit) => sum + edit.markdown.length,
-    0
-  );
-  if (totalReplacementCharacters > MCP_WIRE_LIMITS7.documentCharacters) {
-    throw revisionError(
-      "revision-too-large",
-      "Combined replacement Markdown exceeds the MCP document character limit.",
-      "Use fewer or smaller block replacements."
-    );
-  }
-  const prepared = await documents.prepare({ kind: "artifact", uri: parentArtifact.uri }, signal);
-  const { flattenBlocks } = await import("@bendyline/squisq/doc");
-  const blocks = flattenBlocks(prepared.doc.blocks);
-  const ranges = await computeBlockSourceRanges(blocks, prepared.markdown.length, signal);
-  const blockRecords = indexEditableBlocks(blocks, ranges);
-  const replacements = [];
-  for (let index = 0; index < request.edits.length; index += 1) {
-    throwIfAborted5(signal);
-    const edit = request.edits[index];
-    const record = blockRecords.get(edit.blockId);
-    if (!record) {
-      throw revisionError(
-        "block-not-found",
-        `Block "${edit.blockId}" is not an editable heading block in the parent artifact.`,
-        "Call inspect_document on the exact parent artifact and use a returned block id with a non-null sourceRange."
-      );
-    }
-    const replacementMarkdown = await canonicalReplacement(
-      edit.markdown,
-      record.block,
-      edit.blockId
-    );
-    const before = prepared.markdown.slice(record.start, record.end);
-    if (replacementMarkdown === before) {
-      throw revisionError(
-        "no-op-block-edit",
-        `Replacement for block "${edit.blockId}" does not change its heading or body.`,
-        "Omit no-op block edits from the revision request."
-      );
-    }
-    replacements.push({
-      blockId: edit.blockId,
-      start: record.start,
-      end: record.end,
-      markdown: replacementMarkdown,
-      applied: {
-        kind: "replace_block",
-        blockId: edit.blockId,
-        beforeSha256: sha256(Buffer.from(before, "utf8")),
-        afterSha256: sha256(Buffer.from(replacementMarkdown, "utf8"))
-      }
-    });
-    if ((index + 1) % 16 === 0) await yieldForCancellation2(signal);
-  }
-  const revisedMarkdown = applyReplacements(prepared.markdown, replacements);
-  if (revisedMarkdown.length > MCP_WIRE_LIMITS7.documentCharacters) {
-    throw revisionError(
-      "revision-too-large",
-      "The revised Markdown exceeds the MCP document character limit.",
-      "Use smaller block replacements or split the document before revising it."
-    );
-  }
-  if (revisedMarkdown === prepared.markdown) {
-    throw revisionError(
-      "no-op-revision",
-      "The requested block replacements do not change the document.",
-      "Submit only replacements that change heading or body Markdown."
-    );
-  }
-  const [{ parseMarkdown: parseMarkdown2 }, { markdownToDoc: markdownToDoc2, flattenBlocks: flattenRevisedBlocks }] = await Promise.all([import("@bendyline/squisq/markdown"), import("@bendyline/squisq/doc")]);
-  const markdownDoc = parseMarkdown2(revisedMarkdown);
-  const doc = markdownToDoc2(markdownDoc, { defaultTemplate: "content", autoTemplates: false });
-  const revisedIds = new Set(
-    flattenRevisedBlocks(doc.blocks).map((block) => toWireIdentifier(block.id, "block"))
-  );
-  for (const replacement of replacements) {
-    if (!revisedIds.has(replacement.blockId)) {
-      throw revisionError(
-        "unstable-block-id",
-        `Replacement for block "${replacement.blockId}" did not preserve its stable id.`,
-        "Keep the replacement heading id unchanged and retry from the parent artifact."
-      );
-    }
-  }
-  throwIfAborted5(signal);
-  await prepared.container.writeDocument(revisedMarkdown);
-  const revisionSourceSha256 = createHash7("sha256").update("docblocks-artifact-revision-v1\0", "utf8").update(parentArtifact.sha256, "utf8").update("\0", "utf8").update(revisedMarkdown, "utf8").digest("hex");
-  const [conversion] = await convertPreparedDocument(
-    artifacts,
-    {
-      ...prepared,
-      markdown: revisedMarkdown,
-      markdownDoc,
-      doc,
-      sourceSha256: revisionSourceSha256
-    },
-    { targets: [{ format: "dbk", fidelity: "semantic" }] },
-    signal
-  );
-  if (!conversion) throw new Error("Document revision produced no DBK artifact");
-  const result = {
-    version: DOCBLOCKS_MCP_WIRE_VERSION5,
-    kind: "revision",
-    parentArtifact,
-    artifact: conversion.artifact,
-    edits: replacements.map((replacement) => replacement.applied),
-    diagnostics: conversion.diagnostics
-  };
-  const parsed = parseDocumentRevisionResult(result);
-  if (!parsed) throw new Error("Document revision produced an invalid MCP result");
-  return parsed;
-}
-function indexEditableBlocks(blocks, ranges) {
-  const indexed = /* @__PURE__ */ new Map();
-  const ambiguous = /* @__PURE__ */ new Set();
-  for (let index = 0; index < blocks.length; index += 1) {
-    const block = blocks[index];
-    const range = ranges[index];
-    if (!block || !range || !block.sourceHeading) continue;
-    const wireId = toWireIdentifier(block.id, "block");
-    if (indexed.has(wireId)) {
-      indexed.delete(wireId);
-      ambiguous.add(wireId);
-    } else if (!ambiguous.has(wireId)) {
-      indexed.set(wireId, { block, start: range.start, end: range.end });
-    }
-  }
-  return indexed;
-}
-async function canonicalReplacement(markdown, target, wireBlockId) {
-  const { parseMarkdown: parseMarkdown2, stringifyMarkdown } = await import("@bendyline/squisq/markdown");
-  const fragment = parseMarkdown2(markdown);
-  if (fragment.frontmatter && Object.keys(fragment.frontmatter).length > 0) {
-    throw revisionError(
-      "invalid-block-replacement",
-      `Replacement for block "${wireBlockId}" cannot contain frontmatter.`,
-      "Provide one heading and its direct body only."
-    );
-  }
-  const headings = fragment.children.filter(
-    (node) => node.type === "heading"
-  );
-  const heading = headings[0];
-  if (!heading || fragment.children[0] !== heading || headings.length !== 1) {
-    throw revisionError(
-      "invalid-block-replacement",
-      `Replacement for block "${wireBlockId}" must begin with exactly one heading and cannot contain nested headings.`,
-      "Use a complete fragment such as `# Heading {[content]}\n\nReplacement body`."
-    );
-  }
-  const sourceHeading = target.sourceHeading;
-  if (!sourceHeading) throw new Error("Editable replacement target has no source heading");
-  if (heading.depth !== sourceHeading.depth) {
-    throw revisionError(
-      "invalid-block-replacement",
-      `Replacement for block "${wireBlockId}" must keep heading depth ${sourceHeading.depth}.`,
-      `Begin the replacement with ${"#".repeat(sourceHeading.depth)} followed by the heading text.`
-    );
-  }
-  if (heading.attributes?.id && heading.attributes.id !== target.id) {
-    throw revisionError(
-      "block-id-change-not-allowed",
-      `Replacement for block "${wireBlockId}" cannot change its id to "${heading.attributes.id}".`,
-      `Omit the explicit id or keep {#${target.id}}.`
-    );
-  }
-  const sourceAttributes = sourceHeading.attributes;
-  const replacementAttributes = heading.attributes;
-  const attributes = {
-    ...sourceAttributes,
-    ...replacementAttributes,
-    id: target.id,
-    ...replacementAttributes?.classes === void 0 && sourceAttributes?.classes ? { classes: sourceAttributes.classes } : {},
-    ...replacementAttributes?.params === void 0 && sourceAttributes?.params ? { params: sourceAttributes.params } : {},
-    ...replacementAttributes?.blockMeta === void 0 && sourceAttributes?.blockMeta ? { blockMeta: sourceAttributes.blockMeta } : {},
-    ...replacementAttributes?.metadata === void 0 && sourceAttributes?.metadata ? { metadata: sourceAttributes.metadata } : {}
-  };
-  const pinnedHeading = {
-    ...heading,
-    attributes,
-    templateAnnotation: heading.templateAnnotation ?? sourceHeading.templateAnnotation
-  };
-  return stringifyMarkdown({
-    type: "document",
-    children: [pinnedHeading, ...fragment.children.slice(1)]
-  });
-}
-function applyReplacements(source, replacements) {
-  let revised = source;
-  const descending = [...replacements].sort((left, right) => right.start - left.start);
-  for (const replacement of descending) {
-    revised = revised.slice(0, replacement.start) + replacement.markdown + revised.slice(replacement.end);
-  }
-  return revised;
-}
-function revisionError(code, message, hint) {
-  return Object.assign(new Error(message), { code, hint, retryable: false });
-}
-async function yieldForCancellation2(signal) {
-  await new Promise((resolve4) => setImmediate(resolve4));
-  throwIfAborted5(signal);
-}
-var init_revision_service = __esm({
-  "src/mcp/revision-service.ts"() {
-    "use strict";
-    init_conversion_service();
-    init_document_service();
-    init_intelligence();
-    init_output_bounds();
-  }
-});
-
 // src/mcp/agentic-tools.ts
 import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import {
-  MCP_WIRE_LIMITS as MCP_WIRE_LIMITS8,
+  MCP_WIRE_LIMITS as MCP_WIRE_LIMITS7,
   parseComparisonResult,
   parseConversionResult as parseConversionResult2,
-  parseDocumentRevisionResult as parseDocumentRevisionResult2,
   parseDocumentSource,
   parseInspectionResult,
   parseMaterializationOptions,
@@ -4424,7 +4243,6 @@ import {
   bundleDocumentSourceSchema,
   DOCBLOCKS_MCP_TOOL_OUTPUT_SCHEMAS,
   documentSourceSchema,
-  documentRevisionRequestSchema,
   formatInputSchema,
   materializationOptionsSchema
 } from "@bendyline/docblocks/mcp/zod";
@@ -4520,7 +4338,7 @@ function registerAgenticTools(server, context) {
   server.registerTool(
     "create_document_bundle",
     {
-      description: "Stage authored Markdown and authority-scoped assets as an immutable DBK artifact. Use the returned artifact URI directly with validate_document, preview_document, and convert_document; no local Markdown file or invented root id is required.",
+      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.",
       inputSchema: z.object({ source: bundleDocumentSourceSchema }).strict(),
       outputSchema: DOCBLOCKS_MCP_TOOL_OUTPUT_SCHEMAS.create_document_bundle,
       annotations: ARTIFACT_CREATING
@@ -4552,38 +4370,6 @@ function registerAgenticTools(server, context) {
       }
     }
   );
-  server.registerTool(
-    "revise_document",
-    {
-      description: "Replace selected heading blocks in an immutable DBK artifact without resending the full document. Requires the parent artifact SHA-256, preserves block ids and child blocks, and returns a new DBK artifact without mutating the parent.",
-      inputSchema: documentRevisionRequestSchema,
-      outputSchema: DOCBLOCKS_MCP_TOOL_OUTPUT_SCHEMAS.revise_document,
-      annotations: ARTIFACT_CREATING
-    },
-    async (request, extra) => {
-      try {
-        return await context.runOperation(extra.signal, async (operationSignal) => {
-          const documents = new DocumentService(await context.authority, context.artifacts);
-          const result = await reviseDocumentArtifact(
-            context.artifacts,
-            documents,
-            request,
-            operationSignal
-          );
-          requireWire(parseDocumentRevisionResult2(result), "document revision");
-          return {
-            content: [
-              { type: "text", text: JSON.stringify(result) },
-              artifactLink(result.artifact)
-            ],
-            structuredContent: asStructuredContent(successResult(result))
-          };
-        });
-      } catch (caught) {
-        return errorResult(caught, "transform", "dbk", extra.signal);
-      }
-    }
-  );
   server.registerTool(
     "save_artifact",
     {
@@ -4842,15 +4628,17 @@ function registerAuthoringGuideResource(server) {
         import("@bendyline/squisq/transform")
       ]);
       const guide = {
-        version: 3,
+        version: 6,
         workflow: [
-          "author complete Markdown with annotations bound to headings; ordinary headings default to content",
-          "keep Markdown inline or stage Markdown plus assets with create_document_bundle",
-          "inspect_document and validate_document before visual optimization",
-          "for a staged DBK, use revise_document with inspected block ids and the exact parent SHA-256 for targeted repairs",
-          "preview_document and inspect previewBasis before treating images as source renders, reconstructed imports, or native extraction",
-          "replace selected content blocks with compatible visual templates and preview again",
-          "convert_document to one or more immutable artifacts",
+          "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",
+          "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"
         ],
         markdownAnnotation: '# Heading {[templateId key="value"]}',
@@ -4865,14 +4653,14 @@ function registerAuthoringGuideResource(server) {
         fidelityByFormat: MCP_FORMAT_FIDELITIES,
         formats: boundedFormatCapabilities(),
         templates,
-        themes: schemaModule.getThemeSummaries().slice(0, MCP_WIRE_LIMITS8.arrayEntries).map((theme) => ({
+        themes: schemaModule.getThemeSummaries().slice(0, MCP_WIRE_LIMITS7.arrayEntries).map((theme) => ({
           id: requireWireIdentifier(theme.id, "theme id"),
-          name: boundWireText(theme.name, MCP_WIRE_LIMITS8.labelCharacters, theme.id),
+          name: boundWireText(theme.name, MCP_WIRE_LIMITS7.labelCharacters, theme.id),
           description: boundWireText(theme.description ?? "")
         })),
-        transformStyles: transformModule.getTransformStyleSummaries().slice(0, MCP_WIRE_LIMITS8.arrayEntries).map((style) => ({
+        transformStyles: transformModule.getTransformStyleSummaries().slice(0, MCP_WIRE_LIMITS7.arrayEntries).map((style) => ({
           id: requireWireIdentifier(style.id, "transform style id"),
-          name: boundWireText(style.name, MCP_WIRE_LIMITS8.labelCharacters, style.id),
+          name: boundWireText(style.name, MCP_WIRE_LIMITS7.labelCharacters, style.id),
           description: boundWireText(style.description)
         }))
       };
@@ -4892,7 +4680,7 @@ function registerTemplateTools(server, context) {
   server.registerTool(
     "get_authoring_context",
     {
-      description: "Get the complete linked-Squisq authoring vocabulary, canonical heading syntax, content-retention behavior, workflow, and optional block recommendations in one call.",
+      description: "Get a compact agent-facing authoring contract plus the complete linked-Squisq catalog in structured content, with optional block recommendations.",
       inputSchema: z.object({
         targetFormat: formatInputSchema.optional(),
         goal: z.enum(["content-first", "visual-polish"]).optional(),
@@ -4915,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 templates = annotationHandling === "ignored" ? fullTemplates.filter((template) => template.safeForContentFirst) : fullTemplates;
           let recommendations = [];
           let totalBlocks = null;
           let truncated = false;
@@ -4944,7 +4734,7 @@ function registerTemplateTools(server, context) {
               const recommendedTemplateIds = goal === "content-first" ? ["content", ...visual.filter((id) => id !== "content")] : visual;
               return {
                 blockId: toWireIdentifier(block.id, "block"),
-                title: boundNullableWireText(block.title, MCP_WIRE_LIMITS8.labelCharacters),
+                title: boundNullableWireText(block.title, MCP_WIRE_LIMITS7.labelCharacters),
                 profile: {
                   ...profile,
                   hasAsciiDiagram: profile.hasAsciiDiagram ?? false,
@@ -4957,18 +4747,26 @@ function registerTemplateTools(server, context) {
             totalBlocks = blocks.length;
             truncated = recommendations.length < blocks.length;
           }
-          return textAndStructured({
+          const payload = {
             goal,
             targetFormat: normalizedTarget,
             defaultTemplateId: "content",
             defaultFidelity: authoringDefaultFidelity(normalizedTarget, goal),
             workflow: [
-              "Author complete content with heading-bound annotations; ordinary headings default to content.",
-              "Keep Markdown inline or stage Markdown plus assets with create_document_bundle.",
-              "Validate the source and repair content-retention, accessibility, and target diagnostics.",
-              "For a staged DBK, use revise_document with inspected block ids and the exact parent SHA-256 for targeted repairs.",
-              "Preview the bounded visual items and repair overflow before changing layouts.",
-              "For visual polish, replace selected content blocks with compatible recommended templates and preview again.",
+              "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. 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 resources 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. Prefix each unsupplied operational rule with Proposed: on its slide or section.",
+              "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.",
+              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. For requested choices, state a concrete opportunity cost from supplied alternatives and one proposed accountable role per choice. Label any unsupplied capacity or outcome assumption Assumption or Potential tradeoff." : "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, and targets; use transparent calculations; label new review cadences or measurement procedures 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; revise by editing it and converting again.",
+              "When a draft will feed two or more validate, preview, or convert calls, stage it once with create_document_bundle and pass the returned artifact URI as each source; after edits, stage the revised draft again.",
+              "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." : 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; 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."
             ],
             syntax: {
@@ -4978,20 +4776,21 @@ function registerTemplateTools(server, context) {
             },
             formats,
             templates,
-            themes: schemaModule.getThemeSummaries().slice(0, MCP_WIRE_LIMITS8.arrayEntries).map((theme) => ({
+            themes: schemaModule.getThemeSummaries().slice(0, MCP_WIRE_LIMITS7.arrayEntries).map((theme) => ({
               id: requireWireIdentifier(theme.id, "theme id"),
-              name: boundWireText(theme.name, MCP_WIRE_LIMITS8.labelCharacters, theme.id),
+              name: boundWireText(theme.name, MCP_WIRE_LIMITS7.labelCharacters, theme.id),
               description: boundWireText(theme.description ?? "")
             })),
-            transformStyles: transformModule.getTransformStyleSummaries().slice(0, MCP_WIRE_LIMITS8.arrayEntries).map((style) => ({
+            transformStyles: transformModule.getTransformStyleSummaries().slice(0, MCP_WIRE_LIMITS7.arrayEntries).map((style) => ({
               id: requireWireIdentifier(style.id, "transform style id"),
-              name: boundWireText(style.name, MCP_WIRE_LIMITS8.labelCharacters, style.id),
+              name: boundWireText(style.name, MCP_WIRE_LIMITS7.labelCharacters, style.id),
               description: boundWireText(style.description)
             })),
             recommendations,
             totalBlocks,
             truncated
-          });
+          };
+          return textAndStructured(payload, compactAuthoringContextText(payload));
         });
       } catch (caught) {
         return errorResult(caught, "inspect", null, extra.signal);
@@ -5081,7 +4880,7 @@ function registerTemplateTools(server, context) {
             const profile = recommendModule.profileBlockContents(block.contents ?? []);
             return {
               blockId: toWireIdentifier(block.id, "block"),
-              title: boundNullableWireText(block.title, MCP_WIRE_LIMITS8.labelCharacters),
+              title: boundNullableWireText(block.title, MCP_WIRE_LIMITS7.labelCharacters),
               profile: {
                 ...profile,
                 hasAsciiDiagram: profile.hasAsciiDiagram ?? false,
@@ -5180,12 +4979,12 @@ function registerThemeTools(server, context) {
             layouts: (inferred.layouts ?? []).slice(0, 1e3).map((layout, index) => ({
               id: boundWireText(
                 layout.name,
-                MCP_WIRE_LIMITS8.labelCharacters,
+                MCP_WIRE_LIMITS7.labelCharacters,
                 `layout-${index + 1}`
               ),
               name: boundWireText(
                 layout.label,
-                MCP_WIRE_LIMITS8.labelCharacters,
+                MCP_WIRE_LIMITS7.labelCharacters,
                 `Layout ${index + 1}`
               ),
               description: boundWireText(layout.description ?? "")
@@ -5230,21 +5029,21 @@ function registerThemeTools(server, context) {
             layouts: result.layouts.slice(0, 2048).map((layout, index) => ({
               layoutPath: boundWireText(
                 layout.layoutPath,
-                MCP_WIRE_LIMITS8.pathCharacters,
+                MCP_WIRE_LIMITS7.pathCharacters,
                 `ppt/slideLayouts/slideLayout${index + 1}.xml`
               ),
               name: boundWireText(
                 layout.name,
-                MCP_WIRE_LIMITS8.labelCharacters,
+                MCP_WIRE_LIMITS7.labelCharacters,
                 `Layout ${index + 1}`
               ),
-              masterName: boundNullableWireText(layout.masterName, MCP_WIRE_LIMITS8.labelCharacters),
-              type: boundNullableWireText(layout.typeAttr, MCP_WIRE_LIMITS8.labelCharacters),
+              masterName: boundNullableWireText(layout.masterName, MCP_WIRE_LIMITS7.labelCharacters),
+              type: boundNullableWireText(layout.typeAttr, MCP_WIRE_LIMITS7.labelCharacters),
               slideCount: layout.slideCount,
               verdict: layout.verdict,
               templateId: boundNullableWireText(
                 layout.builtinTemplate ?? layout.customTemplate?.name,
-                MCP_WIRE_LIMITS8.labelCharacters
+                MCP_WIRE_LIMITS7.labelCharacters
               ),
               notes: boundWireTextArray(layout.notes ?? [], 1e3)
             }))
@@ -5344,7 +5143,7 @@ function registerThemeTools(server, context) {
           const payload = {
             result,
             theme: summarizeTheme(inferred.theme),
-            layoutIds: (inferred.layouts ?? []).slice(0, 1e3).map((layout) => boundWireText(layout.name, MCP_WIRE_LIMITS8.labelCharacters)),
+            layoutIds: (inferred.layouts ?? []).slice(0, 1e3).map((layout) => boundWireText(layout.name, MCP_WIRE_LIMITS7.labelCharacters)),
             warnings: boundWireWarnings(inferred.warnings)
           };
           return {
@@ -5401,12 +5200,40 @@ function artifactLink(artifact) {
 async function sendProgress(extra, progress, total, message) {
   await reportMcpProgress(extra, progress, total, message);
 }
-function textAndStructured(payload) {
+function textAndStructured(payload, text = JSON.stringify(payload, null, 2)) {
   return {
-    content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+    content: [{ type: "text", text }],
     structuredContent: asStructuredContent(successResult(payload))
   };
 }
+function compactAuthoringContextText(context) {
+  const target = context.targetFormat ?? "unspecified target";
+  const lines = [
+    `DocBlocks authoring contract: ${target}, ${context.goal}.`,
+    `Default template: ${context.defaultTemplateId}. Default fidelity: ${context.defaultFidelity ?? "select for target"}.`,
+    "",
+    "Required workflow:",
+    ...context.workflow.map((step, index) => `${index + 1}. ${step}`),
+    "",
+    `Heading annotation: ${context.syntax.headingAnnotation}`,
+    `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(", ")} \u2014 transforms re-compose blocks and can change section count; avoid on exact-count briefs.`
+  ];
+  if (context.recommendations.length > 0) {
+    lines.push(
+      `Recommended blocks: ${context.recommendations.map(
+        ({ blockId, recommendedTemplateIds }) => `${blockId} -> ${recommendedTemplateIds.join("/")}`
+      ).join("; ")}`
+    );
+  }
+  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."
+  );
+  return lines.join("\n");
+}
 function asStructuredContent(payload) {
   return payload;
 }
@@ -5419,18 +5246,18 @@ function summarizeTheme(theme) {
   const id = requireWireIdentifier(theme.id, "theme id");
   return {
     id,
-    name: boundWireText(theme.name, MCP_WIRE_LIMITS8.labelCharacters, id),
+    name: boundWireText(theme.name, MCP_WIRE_LIMITS7.labelCharacters, id),
     description: boundWireText(theme.description ?? ""),
     colors: {
-      primary: boundWireText(theme.colors.primary, MCP_WIRE_LIMITS8.labelCharacters, "#000000"),
-      secondary: boundWireText(theme.colors.secondary, MCP_WIRE_LIMITS8.labelCharacters, "#000000"),
+      primary: boundWireText(theme.colors.primary, MCP_WIRE_LIMITS7.labelCharacters, "#000000"),
+      secondary: boundWireText(theme.colors.secondary, MCP_WIRE_LIMITS7.labelCharacters, "#000000"),
       background: boundWireText(
         theme.colors.background,
-        MCP_WIRE_LIMITS8.labelCharacters,
+        MCP_WIRE_LIMITS7.labelCharacters,
         "#ffffff"
       ),
-      text: boundWireText(theme.colors.text, MCP_WIRE_LIMITS8.labelCharacters, "#000000"),
-      highlight: boundWireText(theme.colors.highlight, MCP_WIRE_LIMITS8.labelCharacters, "#000000")
+      text: boundWireText(theme.colors.text, MCP_WIRE_LIMITS7.labelCharacters, "#000000"),
+      highlight: boundWireText(theme.colors.highlight, MCP_WIRE_LIMITS7.labelCharacters, "#000000")
     },
     bodyFont: boundWireText(JSON.stringify(theme.typography.bodyFont) ?? ""),
     titleFont: boundWireText(JSON.stringify(theme.typography.titleFont) ?? "")
@@ -5444,26 +5271,26 @@ async function authoringTemplateCatalog() {
     TEMPLATE_METADATA
   } = await import("@bendyline/squisq/doc");
   const authoring = TEMPLATE_AUTHORING_METADATA;
-  return getAvailableTemplates().slice(0, MCP_WIRE_LIMITS8.arrayEntries).map((id) => {
+  return getAvailableTemplates().slice(0, MCP_WIRE_LIMITS7.arrayEntries).map((id) => {
     const metadata = TEMPLATE_METADATA[id];
     const behavior = authoring[id];
     if (!behavior) throw new Error(`Template "${id}" has no authoring metadata`);
-    const inputs = (TEMPLATE_INPUT_DESCRIPTORS[id] ?? []).slice(0, MCP_WIRE_LIMITS8.arrayEntries).map((input) => ({
+    const inputs = (TEMPLATE_INPUT_DESCRIPTORS[id] ?? []).slice(0, MCP_WIRE_LIMITS7.arrayEntries).map((input) => ({
       key: requireWireIdentifier(input.key, "template input key"),
       description: boundWireText(input.description),
-      type: boundWireText(input.coerce ?? "string", MCP_WIRE_LIMITS8.labelCharacters, "string"),
+      type: boundWireText(input.coerce ?? "string", MCP_WIRE_LIMITS7.labelCharacters, "string"),
       required: input.required ?? false,
       values: boundWireTextArray(
         input.values ?? [],
-        MCP_WIRE_LIMITS8.arrayEntries,
-        MCP_WIRE_LIMITS8.labelCharacters
+        MCP_WIRE_LIMITS7.arrayEntries,
+        MCP_WIRE_LIMITS7.labelCharacters
       ),
-      valueHint: boundNullableWireText(input.valueHint, MCP_WIRE_LIMITS8.labelCharacters)
+      valueHint: boundNullableWireText(input.valueHint, MCP_WIRE_LIMITS7.labelCharacters)
     }));
     const required = inputs.filter((input) => input.required).map((input) => `${input.key}="\u2026"`).join(" ");
     return {
       id: requireWireIdentifier(id, "template id"),
-      label: boundWireText(metadata?.label ?? id, MCP_WIRE_LIMITS8.labelCharacters, id),
+      label: boundWireText(metadata?.label ?? id, MCP_WIRE_LIMITS7.labelCharacters, id),
       description: boundWireText(metadata?.description ?? ""),
       inputs,
       ...behavior,
@@ -5471,6 +5298,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";
@@ -5485,14 +5321,14 @@ function authoringDefaultFidelity(targetFormat, goal) {
 function boundedFormatCapabilities() {
   return MCP_FORMAT_CAPABILITIES.slice(0, 64).map((format) => {
     const id = requireWireIdentifier(format.id, "format id");
-    if (id.length > MCP_WIRE_LIMITS8.formatCharacters || !MCP_OUTPUT_PATTERNS.format.test(id)) {
+    if (id.length > MCP_WIRE_LIMITS7.formatCharacters || !MCP_OUTPUT_PATTERNS.format.test(id)) {
       throw new Error("Linked Squisq returned an invalid MCP format id");
     }
     return {
       id,
-      label: boundWireText(format.label, MCP_WIRE_LIMITS8.labelCharacters, id),
+      label: boundWireText(format.label, MCP_WIRE_LIMITS7.labelCharacters, id),
       mimeType: format.mimeType,
-      extensions: boundWireTextArray(format.extensions, 64, MCP_WIRE_LIMITS8.labelCharacters),
+      extensions: boundWireTextArray(format.extensions, 64, MCP_WIRE_LIMITS7.labelCharacters),
       import: { ...format.import },
       export: { ...format.export }
     };
@@ -5508,7 +5344,6 @@ var init_agentic_tools = __esm({
     init_preview_service();
     init_error_result();
     init_progress();
-    init_revision_service();
     init_output_bounds();
     READ_ONLY = {
       readOnlyHint: true,
@@ -5528,7 +5363,7 @@ var init_agentic_tools = __esm({
       idempotentHint: false,
       openWorldHint: false
     };
-    identifierSchema = z.string().min(1).max(MCP_WIRE_LIMITS8.identifierCharacters).regex(MCP_OUTPUT_PATTERNS.identifier);
+    identifierSchema = z.string().min(1).max(MCP_WIRE_LIMITS7.identifierCharacters).regex(MCP_OUTPUT_PATTERNS.identifier);
     fidelitySchemas = {
       editable: z.enum(MCP_FORMAT_FIDELITIES.docx),
       pdf: z.enum(MCP_FORMAT_FIDELITIES.pdf),
@@ -5641,7 +5476,7 @@ var init_agentic_tools = __esm({
 
 // src/mcp/discovery-tools.ts
 import { z as z2 } from "zod";
-import { MCP_WIRE_LIMITS as MCP_WIRE_LIMITS9 } from "@bendyline/docblocks/mcp";
+import { MCP_WIRE_LIMITS as MCP_WIRE_LIMITS8 } from "@bendyline/docblocks/mcp";
 import { DOCBLOCKS_MCP_TOOL_OUTPUT_SCHEMAS as DOCBLOCKS_MCP_TOOL_OUTPUT_SCHEMAS2 } from "@bendyline/docblocks/mcp/zod";
 function registerDiscoveryTools(server) {
   server.registerTool(
@@ -5676,9 +5511,9 @@ function registerDiscoveryTools(server) {
       try {
         const { getThemeSummaries } = await import("@bendyline/squisq/schemas");
         const result = {
-          themes: getThemeSummaries().slice(0, MCP_WIRE_LIMITS9.arrayEntries).map((theme) => ({
+          themes: getThemeSummaries().slice(0, MCP_WIRE_LIMITS8.arrayEntries).map((theme) => ({
             id: requireWireIdentifier(theme.id, "theme id"),
-            name: boundWireText(theme.name, MCP_WIRE_LIMITS9.labelCharacters, theme.id),
+            name: boundWireText(theme.name, MCP_WIRE_LIMITS8.labelCharacters, theme.id),
             description: boundWireText(theme.description ?? "")
           }))
         };
@@ -5703,9 +5538,9 @@ function registerDiscoveryTools(server) {
       try {
         const { getTransformStyleSummaries } = await import("@bendyline/squisq/transform");
         const result = {
-          styles: getTransformStyleSummaries().slice(0, MCP_WIRE_LIMITS9.arrayEntries).map((style) => ({
+          styles: getTransformStyleSummaries().slice(0, MCP_WIRE_LIMITS8.arrayEntries).map((style) => ({
             id: requireWireIdentifier(style.id, "transform style id"),
-            name: boundWireText(style.name, MCP_WIRE_LIMITS9.labelCharacters, style.id),
+            name: boundWireText(style.name, MCP_WIRE_LIMITS8.labelCharacters, style.id),
             description: boundWireText(style.description)
           }))
         };
@@ -5739,16 +5574,16 @@ function registerDiscoveryTools(server) {
 function serializableCapabilities() {
   return MCP_FORMAT_CAPABILITIES.slice(0, 64).map((format) => ({
     id: requireWireFormat(format.id),
-    label: boundWireText(format.label, MCP_WIRE_LIMITS9.labelCharacters, format.id),
+    label: boundWireText(format.label, MCP_WIRE_LIMITS8.labelCharacters, format.id),
     mimeType: format.mimeType,
-    extensions: boundWireTextArray(format.extensions, 64, MCP_WIRE_LIMITS9.labelCharacters),
+    extensions: boundWireTextArray(format.extensions, 64, MCP_WIRE_LIMITS8.labelCharacters),
     import: { ...format.import },
     export: { ...format.export }
   }));
 }
 function requireWireFormat(value) {
   requireWireIdentifier(value, "format id");
-  if (value.length > MCP_WIRE_LIMITS9.formatCharacters || !MCP_OUTPUT_PATTERNS.format.test(value)) {
+  if (value.length > MCP_WIRE_LIMITS8.formatCharacters || !MCP_OUTPUT_PATTERNS.format.test(value)) {
     throw new Error("Linked Squisq returned an invalid MCP format id");
   }
   return value;
@@ -5874,12 +5709,12 @@ 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. 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"}".
-3. Keep the draft inline or stage Markdown plus assets with create_document_bundle. Do not write a temporary local Markdown file or invent a root id.
-4. Call validate_document with targetFormat "pptx" and repair actionable diagnostics before optimizing layouts.
-5. Call preview_document and inspect every bounded slide image, especially overflow and body-retention diagnostics.
-6. If a staged DBK needs targeted repairs, call inspect_document for block IDs and revise_document with the artifact's exact SHA-256 instead of resending the full Markdown. Only after content coverage is acceptable, replace selected \`content\` blocks with more visual recommended templates and preview again.
-7. Call convert_document with a pptx target. Choose editable-native for editable Office structures, rendered-fidelity for exact Squisq visuals, or hybrid for rendered visuals plus semantic retention.
+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.`;
 }
 function videoPrompt(topic, orientation, theme, template) {
@@ -5887,20 +5722,19 @@ function videoPrompt(topic, orientation, theme, template) {
 
 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. If the draft is staged, use inspect_document plus revise_document for targeted repairs instead of resending the full Markdown. Call validate_document with targetFormat "mp4" and repair actionable diagnostics.
-4. Call preview_document to review representative frames.
-5. Call convert_document with an mp4 target and orientation "${orientation ?? "landscape"}"; monitor progress and honor cancellation.
-6. Use get_conversion_report for provenance and save_artifact only when a durable file is required.`;
+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.`;
 }
 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. Author structured Markdown using theme "${theme ?? "choose from the returned themes"}" and template "${template ?? "content until visual optimization"}". Bind annotations to headings.
-3. If the draft is staged, use inspect_document plus revise_document for targeted repairs instead of resending the full Markdown. Call validate_document with targetFormat "${target}" and repair actionable diagnostics.
-4. Call convert_document with a ${target} target to create an immutable artifact.
-5. Call preview_document and review the bounded page images.
+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.`;
 }
 function complete(values, prefix) {
@@ -5943,7 +5777,7 @@ function createMcpServer(options = {}) {
   const server = new McpServer(
     { name: "docblocks", version: getPackageVersion() },
     {
-      instructions: "Start with get_authoring_context for one-call format, theme, transform, template, syntax, and workflow guidance. Author template annotations on headings, for example `# Heading {[content]}`; standalone `{[template]}` creates an extra heading-less block. DocBlocks MCP defaults ordinary headings to the loss-averse `content` template. Keep authored work in an inline source or stage Markdown plus assets with create_document_bundle. For targeted repairs to a staged DBK, inspect its block ids and call revise_document with the artifact's exact SHA-256 instead of resending the full Markdown. Then validate, preview, convert, and only save the final artifact when durable output is required. Never invent root ids: call list_roots and use an id exactly as returned."
+      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. When one draft will feed two or more validate, preview, or convert calls, stage it once with create_document_bundle and pass the returned artifact URI as each source instead of re-sending the Markdown. 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."
     }
   );
   registerAgenticTools(server, {