@bendyline/docblocks-cli 2.1.1 → 2.1.2

package/dist/bin.js

@@ -869,6 +869,9 @@ async function withMaterializationLock(target, operation) {
     if (materializationTails.get(key) === tail) materializationTails.delete(key);
   }
 }
+function authorityError(message, hint) {
+  return Object.assign(new Error(message), { code: "unauthorized-path", hint });
+}
 var DEFAULT_MAX_INPUT_FILE_BYTES, MCP_FILE_AUTHORITY_LIMITS, MAX_PATH_CHARACTERS, MATERIALIZATION_WRITE_CHUNK_BYTES, HASH_READ_CHUNK_BYTES, materializationTails, McpFileAuthority;
 var init_authority = __esm({
   "src/mcp/authority.ts"() {
@@ -947,7 +950,12 @@ var init_authority = __esm({
       /** Resolve a root-relative read without ever treating the alias as new authority. */
       async authorizeRootRead(rootId, workspacePath) {
         const root = this.readRoots.find((candidate2) => candidate2.id === rootId);
-        if (!root) throw new Error("Unknown or unreadable MCP root");
+        if (!root) {
+          throw authorityError(
+            "Unknown or unreadable MCP root",
+            "Call list_roots and copy a returned read-enabled root id. If no roots are listed, use an inline markdown or bundle source, or restart the server with --allow-read."
+          );
+        }
         const candidate = path7.join(root.physical, ...parseRootRelativePath(workspacePath));
         const physical = await realpath4(candidate).catch(() => null);
         if (!physical || !isPathInside(root.physical, physical)) {
@@ -958,7 +966,12 @@ var init_authority = __esm({
       /** Resolve a root-relative write without ever treating the alias as new authority. */
       async authorizeRootWrite(rootId, workspacePath) {
         const root = this.writeRoots.find((candidate2) => candidate2.id === rootId);
-        if (!root) throw new Error("Unknown or unwritable MCP root");
+        if (!root) {
+          throw authorityError(
+            "Unknown or unwritable MCP root",
+            "Call list_roots and copy a returned write-enabled root id. If none is writable, keep the result as a session artifact or restart the server with --allow-write."
+          );
+        }
         const candidate = path7.join(root.physical, ...parseRootRelativePath(workspacePath));
         const authorized = await this.authorizeWrite(candidate);
         const physicalParent = await realpath4(path7.dirname(authorized));
@@ -1537,7 +1550,10 @@ var init_document_service = __esm({
         const { parseMarkdown: parseMarkdown2 } = await import("@bendyline/squisq/markdown");
         const { markdownToDoc: markdownToDoc2 } = await import("@bendyline/squisq/doc");
         const markdownDoc = parseMarkdown2(markdown);
-        const doc = markdownToDoc2(markdownDoc);
+        const doc = markdownToDoc2(markdownDoc, {
+          defaultTemplate: "content",
+          autoTemplates: false
+        });
         const assets = await this.assetSummaries(container, signal);
         throwIfAborted5(signal);
         return {
@@ -1776,7 +1792,8 @@ async function inspectPreparedDocument(_documents, prepared, maximumBlocks = DEF
     ...validation.diagnostics.map(
       (diagnostic) => mapDocDiagnostic(diagnostic, prepared.sourceFormat)
     ),
-    ...missingAltTextDiagnostics(prepared.markdownDoc, prepared.sourceFormat)
+    ...missingAltTextDiagnostics(prepared.markdownDoc, prepared.sourceFormat),
+    ...await authoringDiagnostics(prepared, "inspect", prepared.sourceFormat, signal)
   ];
   let wordCount = 0;
   for (let index = 0; index < analyzed.length; index += 1) {
@@ -1833,6 +1850,12 @@ async function validatePreparedDocument(_documents, prepared, targetFormat, sign
       prepared.markdownDoc,
       normalizedTargetFormat ?? prepared.sourceFormat
     ),
+    ...await authoringDiagnostics(
+      prepared,
+      "validate",
+      normalizedTargetFormat ?? prepared.sourceFormat,
+      signal
+    ),
     ...normalizedTargetFormat ? await targetPreflight(prepared, normalizedTargetFormat, signal) : []
   ];
   await yieldForCancellation(signal);
@@ -1849,6 +1872,111 @@ async function validatePreparedDocument(_documents, prepared, targetFormat, sign
     diagnostics: unique
   };
 }
+async function authoringDiagnostics(prepared, stage, format, signal) {
+  throwIfAborted5(signal);
+  const {
+    TEMPLATE_AUTHORING_METADATA,
+    flattenBlocks,
+    getBlockBodyText,
+    materializeBlockLayers,
+    resolveTemplateName,
+    resolveThemeForDoc
+  } = await import("@bendyline/squisq/doc");
+  const blocks = flattenBlocks(prepared.doc.blocks);
+  const analyzedBlocks = blocks.slice(0, MCP_WIRE_LIMITS5.arrayEntries);
+  const theme = resolveThemeForDoc(prepared.doc);
+  const diagnostics = [];
+  for (let index = 0; index < analyzedBlocks.length; index += 1) {
+    const checkpoint = cancellationCheckpoint(signal, index);
+    if (checkpoint) await checkpoint;
+    const block = analyzedBlocks[index];
+    throwIfAborted5(signal);
+    if (block.standaloneAnnotation) {
+      diagnostics.push({
+        code: "standalone-template-block",
+        severity: "warning",
+        stage,
+        format,
+        count: 1,
+        message: `Block "${block.id}" was created by a standalone template annotation and has no heading.`,
+        remediation: "Move the annotation onto the intended heading, for example `# Heading {[content]}`, unless the additional heading-less block is deliberate.",
+        retryable: false,
+        location: {
+          kind: "block",
+          blockId: toWireIdentifier(block.id, "block"),
+          nodeType: "block"
+        }
+      });
+    }
+    if (!block.template) continue;
+    const templateId = resolveTemplateName(block.template);
+    const behavior = TEMPLATE_AUTHORING_METADATA[templateId];
+    if (!behavior) continue;
+    const body = getBlockBodyText(block).trim();
+    if (!body) continue;
+    if (behavior.bodyPolicy === "ignored") {
+      diagnostics.push({
+        code: "template-body-not-rendered",
+        severity: "warning",
+        stage,
+        format,
+        count: 1,
+        message: `Template "${templateId}" does not render the body of block "${block.title ?? block.id}".`,
+        remediation: "Use the content template to preserve the complete body, or move this prose into a separate content block before visual optimization.",
+        retryable: false,
+        location: {
+          kind: "block",
+          blockId: toWireIdentifier(block.id, "block"),
+          nodeType: "block"
+        }
+      });
+      continue;
+    }
+    if (behavior.bodyPolicy !== "complete") continue;
+    const materialized = materializeBlockLayers(block, {
+      theme,
+      customTemplates: prepared.doc.customTemplates,
+      persistentLayers: false,
+      blockIndex: index,
+      totalBlocks: analyzedBlocks.length
+    });
+    const renderedText = materialized.layers.filter((layer) => layer.type === "text").map((layer) => layer.content.text).join("\n");
+    if (!normalizedText(renderedText).includes(normalizedText(body))) {
+      diagnostics.push({
+        code: "rendered-content-omitted",
+        severity: "error",
+        stage,
+        format,
+        count: 1,
+        message: `The complete body of block "${block.title ?? block.id}" is not present in its rendered text layers.`,
+        remediation: "Keep the content template and repair its inputs, then validate and preview again before conversion.",
+        retryable: false,
+        location: {
+          kind: "block",
+          blockId: toWireIdentifier(block.id, "block"),
+          nodeType: "block"
+        }
+      });
+    }
+  }
+  if (analyzedBlocks.length < blocks.length) {
+    diagnostics.push({
+      code: "authoring-analysis-truncated",
+      severity: "info",
+      stage,
+      format,
+      count: blocks.length - analyzedBlocks.length,
+      message: `Authoring diagnostics analyzed the first ${analyzedBlocks.length} blocks.`,
+      remediation: "Split the document before requesting exhaustive per-block authoring diagnostics.",
+      retryable: false,
+      location: null
+    });
+  }
+  return diagnostics;
+}
+function normalizedText(value) {
+  return value.normalize("NFKC").replace(/\s+/gu, " ").trim().toLocaleLowerCase("en-US");
+}
 async function comparePreparedDocuments(documents, left, right, signal) {
   throwIfAborted5(signal);
   await yieldForCancellation(signal);
@@ -2728,6 +2856,7 @@ async function previewPreparedDocument(artifacts, prepared, request, signal, pro
     diagnostics: boundDiagnostics(
       [
         ...prepared.diagnostics,
+        ...await authoringDiagnostics(prepared, "render", prepared.sourceFormat, signal),
         ...rendered.diagnostics ?? [],
         ...previewBasis === "reconstructed-import" ? [reconstructedPreviewDiagnostic(prepared.sourceFormat)] : []
       ],
@@ -3149,10 +3278,13 @@ async function prepareRenderedDocument(prepared, options, signal) {
     }
   };
   registry.register(captureDefinition);
+  const canonicalMarkdown = options.autoTemplates === true ? prepared.markdownDoc : (await import("@bendyline/squisq/doc")).docToMarkdown(prepared.doc, {
+    defaultTemplate: "sectionHeader"
+  });
   const result = await convert(
     {
       kind: "markdown",
-      markdown: prepared.markdownDoc,
+      markdown: canonicalMarkdown,
       container: prepared.container,
       baseName: prepared.baseName
     },
@@ -4029,13 +4161,258 @@ 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_LIMITS7,
+  MCP_WIRE_LIMITS as MCP_WIRE_LIMITS8,
   parseComparisonResult,
   parseConversionResult as parseConversionResult2,
+  parseDocumentRevisionResult as parseDocumentRevisionResult2,
   parseDocumentSource,
   parseInspectionResult,
   parseMaterializationOptions,
@@ -4047,6 +4424,7 @@ import {
   bundleDocumentSourceSchema,
   DOCBLOCKS_MCP_TOOL_OUTPUT_SCHEMAS,
   documentSourceSchema,
+  documentRevisionRequestSchema,
   formatInputSchema,
   materializationOptionsSchema
 } from "@bendyline/docblocks/mcp/zod";
@@ -4142,7 +4520,7 @@ function registerAgenticTools(server, context) {
   server.registerTool(
     "create_document_bundle",
     {
-      description: "Package Markdown and authority-scoped assets into an immutable DBK artifact with asset metadata.",
+      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.",
       inputSchema: z.object({ source: bundleDocumentSourceSchema }).strict(),
       outputSchema: DOCBLOCKS_MCP_TOOL_OUTPUT_SCHEMAS.create_document_bundle,
       annotations: ARTIFACT_CREATING
@@ -4174,6 +4552,38 @@ 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",
     {
@@ -4422,43 +4832,30 @@ function registerAuthoringGuideResource(server) {
     "docblocks://authoring-guide",
     {
       description: "Compact linked-Squisq authoring vocabulary, artifact workflow, fidelity modes, templates, themes, and transform styles.",
-      mimeType: "application/json"
+      mimeType: "application/json",
+      annotations: { audience: ["assistant"], priority: 1 }
     },
     async () => {
-      const [docModule, schemaModule, transformModule] = await Promise.all([
-        import("@bendyline/squisq/doc"),
+      const [templates, schemaModule, transformModule] = await Promise.all([
+        authoringTemplateCatalog(),
         import("@bendyline/squisq/schemas"),
         import("@bendyline/squisq/transform")
       ]);
-      const templates = docModule.getAvailableTemplates().slice(0, MCP_WIRE_LIMITS7.arrayEntries).map((id) => ({
-        id: requireWireIdentifier(id, "template id"),
-        label: boundWireText(
-          docModule.TEMPLATE_METADATA[id]?.label ?? id,
-          MCP_WIRE_LIMITS7.labelCharacters,
-          id
-        ),
-        description: boundWireText(docModule.TEMPLATE_METADATA[id]?.description ?? ""),
-        inputs: (docModule.TEMPLATE_INPUT_DESCRIPTORS[id] ?? []).slice(0, MCP_WIRE_LIMITS7.arrayEntries).map((input) => ({
-          key: requireWireIdentifier(input.key, "template input key"),
-          required: input.required ?? false,
-          values: boundWireTextArray(
-            input.values ?? [],
-            MCP_WIRE_LIMITS7.arrayEntries,
-            MCP_WIRE_LIMITS7.labelCharacters
-          ),
-          hint: boundNullableWireText(input.valueHint, MCP_WIRE_LIMITS7.labelCharacters)
-        }))
-      }));
       const guide = {
-        version: 1,
+        version: 3,
         workflow: [
-          "list_roots and select an authority-scoped source",
-          "inspect_document and validate_document",
-          "convert_document to one or more immutable artifacts",
+          "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",
           "save_artifact only when a durable file is required"
         ],
-        markdownAnnotation: '{[templateId key="value"]}',
+        markdownAnnotation: '# Heading {[templateId key="value"]}',
+        standaloneAnnotation: '{[templateId key="value"]}',
+        standaloneWarning: "A standalone annotation creates an additional heading-less block. Bind the annotation to a heading unless that extra block is deliberate.",
         fidelity: {
           semantic: "Prioritize meaning and portability.",
           "editable-native": "Produce editable native structures with target-specific diagnostics.",
@@ -4468,14 +4865,14 @@ function registerAuthoringGuideResource(server) {
         fidelityByFormat: MCP_FORMAT_FIDELITIES,
         formats: boundedFormatCapabilities(),
         templates,
-        themes: schemaModule.getThemeSummaries().slice(0, MCP_WIRE_LIMITS7.arrayEntries).map((theme) => ({
+        themes: schemaModule.getThemeSummaries().slice(0, MCP_WIRE_LIMITS8.arrayEntries).map((theme) => ({
           id: requireWireIdentifier(theme.id, "theme id"),
-          name: boundWireText(theme.name, MCP_WIRE_LIMITS7.labelCharacters, theme.id),
+          name: boundWireText(theme.name, MCP_WIRE_LIMITS8.labelCharacters, theme.id),
           description: boundWireText(theme.description ?? "")
         })),
-        transformStyles: transformModule.getTransformStyleSummaries().slice(0, MCP_WIRE_LIMITS7.arrayEntries).map((style) => ({
+        transformStyles: transformModule.getTransformStyleSummaries().slice(0, MCP_WIRE_LIMITS8.arrayEntries).map((style) => ({
           id: requireWireIdentifier(style.id, "transform style id"),
-          name: boundWireText(style.name, MCP_WIRE_LIMITS7.labelCharacters, style.id),
+          name: boundWireText(style.name, MCP_WIRE_LIMITS8.labelCharacters, style.id),
           description: boundWireText(style.description)
         }))
       };
@@ -4492,6 +4889,115 @@ function registerAuthoringGuideResource(server) {
   );
 }
 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.",
+      inputSchema: z.object({
+        targetFormat: formatInputSchema.optional(),
+        goal: z.enum(["content-first", "visual-polish"]).optional(),
+        source: documentSourceSchema.optional(),
+        maxBlocks: z.number().int().min(1).max(100).optional()
+      }).strict(),
+      outputSchema: DOCBLOCKS_MCP_TOOL_OUTPUT_SCHEMAS.get_authoring_context,
+      annotations: READ_ONLY
+    },
+    async ({ targetFormat, goal: requestedGoal, source, maxBlocks }, extra) => {
+      try {
+        return await context.runOperation(extra.signal, async (operationSignal) => {
+          const goal = requestedGoal ?? "content-first";
+          const normalizedTarget = targetFormat?.toLowerCase() ?? null;
+          const formats = boundedFormatCapabilities();
+          if (normalizedTarget) {
+            const target = formats.find((format) => format.id === normalizedTarget);
+            if (!target) throw new Error(`Unknown target format "${normalizedTarget}"`);
+            if (!target.export.supported) {
+              throw new Error(`Format "${normalizedTarget}" is not export-capable`);
+            }
+          }
+          const [templates, schemaModule, transformModule] = await Promise.all([
+            authoringTemplateCatalog(),
+            import("@bendyline/squisq/schemas"),
+            import("@bendyline/squisq/transform")
+          ]);
+          let recommendations = [];
+          let totalBlocks = null;
+          let truncated = false;
+          if (source) {
+            const documents = new DocumentService(await context.authority, context.artifacts);
+            const prepared = await documents.prepare(
+              requireDocumentSource(source),
+              operationSignal
+            );
+            const [{ flattenBlocks }, recommendModule] = await Promise.all([
+              import("@bendyline/squisq/doc"),
+              import("@bendyline/squisq/recommend")
+            ]);
+            const blocks = flattenBlocks(prepared.doc.blocks);
+            const limit = maxBlocks ?? 50;
+            recommendations = blocks.slice(0, limit).map((block) => {
+              const profile = recommendModule.profileBlockContents(block.contents ?? []);
+              const visual = recommendModule.recommendTemplatesForBlock(
+                profile,
+                templates.map((template) => template.id)
+              ).recommended;
+              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),
+                profile: {
+                  ...profile,
+                  hasAsciiDiagram: profile.hasAsciiDiagram ?? false,
+                  hasTimeline: profile.hasTimeline ?? false,
+                  hasTree: profile.hasTree ?? false
+                },
+                recommendedTemplateIds: recommendedTemplateIds.slice(0, 256).map((id) => requireWireIdentifier(id, "recommended template id"))
+              };
+            });
+            totalBlocks = blocks.length;
+            truncated = recommendations.length < blocks.length;
+          }
+          return textAndStructured({
+            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.",
+              "Convert to immutable artifacts, inspect conversion reports, and save only final durable outputs."
+            ],
+            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,
+            themes: schemaModule.getThemeSummaries().slice(0, MCP_WIRE_LIMITS8.arrayEntries).map((theme) => ({
+              id: requireWireIdentifier(theme.id, "theme id"),
+              name: boundWireText(theme.name, MCP_WIRE_LIMITS8.labelCharacters, theme.id),
+              description: boundWireText(theme.description ?? "")
+            })),
+            transformStyles: transformModule.getTransformStyleSummaries().slice(0, MCP_WIRE_LIMITS8.arrayEntries).map((style) => ({
+              id: requireWireIdentifier(style.id, "transform style id"),
+              name: boundWireText(style.name, MCP_WIRE_LIMITS8.labelCharacters, style.id),
+              description: boundWireText(style.description)
+            })),
+            recommendations,
+            totalBlocks,
+            truncated
+          });
+        });
+      } catch (caught) {
+        return errorResult(caught, "inspect", null, extra.signal);
+      }
+    }
+  );
   server.registerTool(
     "list_templates",
     {
@@ -4502,15 +5008,10 @@ function registerTemplateTools(server, context) {
     },
     async () => {
       try {
-        const { getAvailableTemplates, TEMPLATE_METADATA } = await import("@bendyline/squisq/doc");
-        const templates = getAvailableTemplates().slice(0, MCP_WIRE_LIMITS7.arrayEntries).map((id) => ({
-          id: requireWireIdentifier(id, "template id"),
-          label: boundWireText(
-            TEMPLATE_METADATA[id]?.label ?? id,
-            MCP_WIRE_LIMITS7.labelCharacters,
-            id
-          ),
-          description: boundWireText(TEMPLATE_METADATA[id]?.description ?? "")
+        const templates = (await authoringTemplateCatalog()).map(({ id, label, description }) => ({
+          id,
+          label,
+          description
         }));
         return textAndStructured({ templates });
       } catch (caught) {
@@ -4528,41 +5029,21 @@ function registerTemplateTools(server, context) {
     },
     async ({ templateId }) => {
       try {
-        const { getAvailableTemplates, TEMPLATE_INPUT_DESCRIPTORS, TEMPLATE_METADATA } = await import("@bendyline/squisq/doc");
-        if (!getAvailableTemplates().includes(templateId)) {
+        const described = (await authoringTemplateCatalog()).find(
+          (template2) => template2.id === templateId
+        );
+        if (!described) {
           return errorResult(new Error(`Unknown template "${templateId}"`), "validate");
         }
-        const inputs = (TEMPLATE_INPUT_DESCRIPTORS[templateId] ?? []).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_LIMITS7.labelCharacters,
-            "string"
-          ),
-          required: input.required ?? false,
-          values: boundWireTextArray(
-            input.values ?? [],
-            MCP_WIRE_LIMITS7.arrayEntries,
-            MCP_WIRE_LIMITS7.labelCharacters
-          ),
-          valueHint: boundNullableWireText(input.valueHint, MCP_WIRE_LIMITS7.labelCharacters)
-        }));
-        const metadata = TEMPLATE_METADATA[templateId];
         const template = {
-          id: requireWireIdentifier(templateId, "template id"),
-          label: boundWireText(
-            metadata?.label ?? templateId,
-            MCP_WIRE_LIMITS7.labelCharacters,
-            templateId
-          ),
-          description: boundWireText(metadata?.description ?? ""),
-          inputs
+          id: described.id,
+          label: described.label,
+          description: described.description,
+          inputs: described.inputs
         };
-        const required = inputs.filter((input) => input.required).map((input) => `${input.key}="\u2026"`).join(" ");
         return textAndStructured({
           template,
-          annotationExample: boundWireText(`{[${templateId}${required ? ` ${required}` : ""}]}`)
+          annotationExample: described.annotationExample
         });
       } catch (caught) {
         return errorResult(caught, "inspect");
@@ -4600,7 +5081,7 @@ function registerTemplateTools(server, context) {
             const profile = recommendModule.profileBlockContents(block.contents ?? []);
             return {
               blockId: toWireIdentifier(block.id, "block"),
-              title: boundNullableWireText(block.title, MCP_WIRE_LIMITS7.labelCharacters),
+              title: boundNullableWireText(block.title, MCP_WIRE_LIMITS8.labelCharacters),
               profile: {
                 ...profile,
                 hasAsciiDiagram: profile.hasAsciiDiagram ?? false,
@@ -4699,12 +5180,12 @@ function registerThemeTools(server, context) {
             layouts: (inferred.layouts ?? []).slice(0, 1e3).map((layout, index) => ({
               id: boundWireText(
                 layout.name,
-                MCP_WIRE_LIMITS7.labelCharacters,
+                MCP_WIRE_LIMITS8.labelCharacters,
                 `layout-${index + 1}`
               ),
               name: boundWireText(
                 layout.label,
-                MCP_WIRE_LIMITS7.labelCharacters,
+                MCP_WIRE_LIMITS8.labelCharacters,
                 `Layout ${index + 1}`
               ),
               description: boundWireText(layout.description ?? "")
@@ -4749,21 +5230,21 @@ function registerThemeTools(server, context) {
             layouts: result.layouts.slice(0, 2048).map((layout, index) => ({
               layoutPath: boundWireText(
                 layout.layoutPath,
-                MCP_WIRE_LIMITS7.pathCharacters,
+                MCP_WIRE_LIMITS8.pathCharacters,
                 `ppt/slideLayouts/slideLayout${index + 1}.xml`
               ),
               name: boundWireText(
                 layout.name,
-                MCP_WIRE_LIMITS7.labelCharacters,
+                MCP_WIRE_LIMITS8.labelCharacters,
                 `Layout ${index + 1}`
               ),
-              masterName: boundNullableWireText(layout.masterName, MCP_WIRE_LIMITS7.labelCharacters),
-              type: boundNullableWireText(layout.typeAttr, MCP_WIRE_LIMITS7.labelCharacters),
+              masterName: boundNullableWireText(layout.masterName, MCP_WIRE_LIMITS8.labelCharacters),
+              type: boundNullableWireText(layout.typeAttr, MCP_WIRE_LIMITS8.labelCharacters),
               slideCount: layout.slideCount,
               verdict: layout.verdict,
               templateId: boundNullableWireText(
                 layout.builtinTemplate ?? layout.customTemplate?.name,
-                MCP_WIRE_LIMITS7.labelCharacters
+                MCP_WIRE_LIMITS8.labelCharacters
               ),
               notes: boundWireTextArray(layout.notes ?? [], 1e3)
             }))
@@ -4863,7 +5344,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_LIMITS7.labelCharacters)),
+            layoutIds: (inferred.layouts ?? []).slice(0, 1e3).map((layout) => boundWireText(layout.name, MCP_WIRE_LIMITS8.labelCharacters)),
             warnings: boundWireWarnings(inferred.warnings)
           };
           return {
@@ -4938,34 +5419,80 @@ function summarizeTheme(theme) {
   const id = requireWireIdentifier(theme.id, "theme id");
   return {
     id,
-    name: boundWireText(theme.name, MCP_WIRE_LIMITS7.labelCharacters, id),
+    name: boundWireText(theme.name, MCP_WIRE_LIMITS8.labelCharacters, id),
     description: boundWireText(theme.description ?? ""),
     colors: {
-      primary: boundWireText(theme.colors.primary, MCP_WIRE_LIMITS7.labelCharacters, "#000000"),
-      secondary: boundWireText(theme.colors.secondary, MCP_WIRE_LIMITS7.labelCharacters, "#000000"),
+      primary: boundWireText(theme.colors.primary, MCP_WIRE_LIMITS8.labelCharacters, "#000000"),
+      secondary: boundWireText(theme.colors.secondary, MCP_WIRE_LIMITS8.labelCharacters, "#000000"),
       background: boundWireText(
         theme.colors.background,
-        MCP_WIRE_LIMITS7.labelCharacters,
+        MCP_WIRE_LIMITS8.labelCharacters,
         "#ffffff"
       ),
-      text: boundWireText(theme.colors.text, MCP_WIRE_LIMITS7.labelCharacters, "#000000"),
-      highlight: boundWireText(theme.colors.highlight, MCP_WIRE_LIMITS7.labelCharacters, "#000000")
+      text: boundWireText(theme.colors.text, MCP_WIRE_LIMITS8.labelCharacters, "#000000"),
+      highlight: boundWireText(theme.colors.highlight, MCP_WIRE_LIMITS8.labelCharacters, "#000000")
     },
     bodyFont: boundWireText(JSON.stringify(theme.typography.bodyFont) ?? ""),
     titleFont: boundWireText(JSON.stringify(theme.typography.titleFont) ?? "")
   };
 }
+async function authoringTemplateCatalog() {
+  const {
+    getAvailableTemplates,
+    TEMPLATE_AUTHORING_METADATA,
+    TEMPLATE_INPUT_DESCRIPTORS,
+    TEMPLATE_METADATA
+  } = await import("@bendyline/squisq/doc");
+  const authoring = TEMPLATE_AUTHORING_METADATA;
+  return getAvailableTemplates().slice(0, MCP_WIRE_LIMITS8.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) => ({
+      key: requireWireIdentifier(input.key, "template input key"),
+      description: boundWireText(input.description),
+      type: boundWireText(input.coerce ?? "string", MCP_WIRE_LIMITS8.labelCharacters, "string"),
+      required: input.required ?? false,
+      values: boundWireTextArray(
+        input.values ?? [],
+        MCP_WIRE_LIMITS8.arrayEntries,
+        MCP_WIRE_LIMITS8.labelCharacters
+      ),
+      valueHint: boundNullableWireText(input.valueHint, MCP_WIRE_LIMITS8.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),
+      description: boundWireText(metadata?.description ?? ""),
+      inputs,
+      ...behavior,
+      annotationExample: boundWireText(`# Heading {[${id}${required ? ` ${required}` : ""}]}`)
+    };
+  });
+}
+function authoringDefaultFidelity(targetFormat, goal) {
+  if (!targetFormat) return null;
+  if (targetFormat === "mp4" || targetFormat === "gif") return "rendered-fidelity";
+  if (goal === "visual-polish" && (targetFormat === "pptx" || targetFormat === "pdf")) {
+    return "rendered-fidelity";
+  }
+  if (targetFormat === "docx" || targetFormat === "pptx" || targetFormat === "xlsx") {
+    return "editable-native";
+  }
+  return "semantic";
+}
 function boundedFormatCapabilities() {
   return MCP_FORMAT_CAPABILITIES.slice(0, 64).map((format) => {
     const id = requireWireIdentifier(format.id, "format id");
-    if (id.length > MCP_WIRE_LIMITS7.formatCharacters || !MCP_OUTPUT_PATTERNS.format.test(id)) {
+    if (id.length > MCP_WIRE_LIMITS8.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_LIMITS7.labelCharacters, id),
+      label: boundWireText(format.label, MCP_WIRE_LIMITS8.labelCharacters, id),
       mimeType: format.mimeType,
-      extensions: boundWireTextArray(format.extensions, 64, MCP_WIRE_LIMITS7.labelCharacters),
+      extensions: boundWireTextArray(format.extensions, 64, MCP_WIRE_LIMITS8.labelCharacters),
       import: { ...format.import },
       export: { ...format.export }
     };
@@ -4981,6 +5508,7 @@ var init_agentic_tools = __esm({
     init_preview_service();
     init_error_result();
     init_progress();
+    init_revision_service();
     init_output_bounds();
     READ_ONLY = {
       readOnlyHint: true,
@@ -5000,7 +5528,7 @@ var init_agentic_tools = __esm({
       idempotentHint: false,
       openWorldHint: false
     };
-    identifierSchema = z.string().min(1).max(MCP_WIRE_LIMITS7.identifierCharacters).regex(MCP_OUTPUT_PATTERNS.identifier);
+    identifierSchema = z.string().min(1).max(MCP_WIRE_LIMITS8.identifierCharacters).regex(MCP_OUTPUT_PATTERNS.identifier);
     fidelitySchemas = {
       editable: z.enum(MCP_FORMAT_FIDELITIES.docx),
       pdf: z.enum(MCP_FORMAT_FIDELITIES.pdf),
@@ -5113,7 +5641,7 @@ var init_agentic_tools = __esm({
 
 // src/mcp/discovery-tools.ts
 import { z as z2 } from "zod";
-import { MCP_WIRE_LIMITS as MCP_WIRE_LIMITS8 } from "@bendyline/docblocks/mcp";
+import { MCP_WIRE_LIMITS as MCP_WIRE_LIMITS9 } 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(
@@ -5148,9 +5676,9 @@ function registerDiscoveryTools(server) {
       try {
         const { getThemeSummaries } = await import("@bendyline/squisq/schemas");
         const result = {
-          themes: getThemeSummaries().slice(0, MCP_WIRE_LIMITS8.arrayEntries).map((theme) => ({
+          themes: getThemeSummaries().slice(0, MCP_WIRE_LIMITS9.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_LIMITS9.labelCharacters, theme.id),
             description: boundWireText(theme.description ?? "")
           }))
         };
@@ -5175,9 +5703,9 @@ function registerDiscoveryTools(server) {
       try {
         const { getTransformStyleSummaries } = await import("@bendyline/squisq/transform");
         const result = {
-          styles: getTransformStyleSummaries().slice(0, MCP_WIRE_LIMITS8.arrayEntries).map((style) => ({
+          styles: getTransformStyleSummaries().slice(0, MCP_WIRE_LIMITS9.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_LIMITS9.labelCharacters, style.id),
             description: boundWireText(style.description)
           }))
         };
@@ -5211,16 +5739,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_LIMITS8.labelCharacters, format.id),
+    label: boundWireText(format.label, MCP_WIRE_LIMITS9.labelCharacters, format.id),
     mimeType: format.mimeType,
-    extensions: boundWireTextArray(format.extensions, 64, MCP_WIRE_LIMITS8.labelCharacters),
+    extensions: boundWireTextArray(format.extensions, 64, MCP_WIRE_LIMITS9.labelCharacters),
     import: { ...format.import },
     export: { ...format.export }
   }));
 }
 function requireWireFormat(value) {
   requireWireIdentifier(value, "format id");
-  if (value.length > MCP_WIRE_LIMITS8.formatCharacters || !MCP_OUTPUT_PATTERNS.format.test(value)) {
+  if (value.length > MCP_WIRE_LIMITS9.formatCharacters || !MCP_OUTPUT_PATTERNS.format.test(value)) {
     throw new Error("Linked Squisq returned an invalid MCP format id");
   }
   return value;
@@ -5345,19 +5873,21 @@ function registerAuthoringPrompts(server) {
 function presentationPrompt(topic, style, theme, template) {
   return `Create a presentation about: ${topic}
 
-1. Use list_formats, list_themes, list_transform_styles, and list_templates for current linked-Squisq capabilities.
-2. Author focused Markdown sections with accessible alt text. Prefer style "${style ?? "choose from list_transform_styles"}", theme "${theme ?? "choose from list_themes"}", and template "${template ?? "choose per block"}".
-3. Call validate_document with targetFormat "pptx" and repair actionable diagnostics.
-4. 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.
-5. Call preview_document and inspect the bounded slide images.
-6. Use get_conversion_report for provenance and save_artifact only when a durable file is required.`;
+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.
+8. 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. Use list_formats, list_themes, list_transform_styles, and list_templates for current linked-Squisq capabilities.
-2. Author concise Markdown for a ${orientation ?? "landscape"} animated sequence using theme "${theme ?? "choose from list_themes"}" and template "${template ?? "choose per block"}".
-3. Call validate_document with targetFormat "mp4" and repair actionable diagnostics.
+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.`;
@@ -5366,9 +5896,9 @@ function documentPrompt(topic, format, theme, template) {
   const target = format ?? "pdf";
   return `Create a professional document about: ${topic}
 
-1. Use list_formats, list_themes, list_transform_styles, and list_templates for current linked-Squisq capabilities.
-2. Author structured Markdown using theme "${theme ?? "choose from list_themes"}" and template "${template ?? "choose per block"}".
-3. Call validate_document with targetFormat "${target}" and repair actionable diagnostics.
+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.
 6. Use get_conversion_report for provenance and save_artifact only when a durable file is required.`;
@@ -5410,7 +5940,12 @@ function createMcpServer(options = {}) {
     options.shutdownDrainTimeoutMs ?? DEFAULT_SHUTDOWN_DRAIN_TIMEOUT_MS
   );
   const artifacts = new ArtifactStore(options);
-  const server = new McpServer({ name: "docblocks", version: getPackageVersion() });
+  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."
+    }
+  );
   registerAgenticTools(server, {
     authority,
     artifacts,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bendyline/docblocks-cli",
-  "version": "2.1.1",
+  "version": "2.1.2",
   "description": "Build, preview, convert, render, inspect, and automate documents",
   "license": "MIT",
   "author": "Bendyline",
@@ -46,12 +46,12 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@bendyline/docblocks": "2.1.1",
-    "@bendyline/squisq": "2.3.1",
-    "@bendyline/squisq-cli": "2.3.1",
-    "@bendyline/squisq-formats": "2.3.1",
-    "@bendyline/squisq-react": "2.3.1",
-    "@bendyline/squisq-video": "2.2.1",
+    "@bendyline/docblocks": "2.1.2",
+    "@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",
     "@modelcontextprotocol/sdk": "1.29.0",
     "commander": "13.1.0",
     "jszip": "3.10.1",