@bendyline/docblocks-cli 2.1.1 → 2.2.0

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
     },
@@ -4142,7 +4274,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: "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
@@ -4422,43 +4554,32 @@ 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: 6,
         workflow: [
-          "list_roots and select an authority-scoped source",
-          "inspect_document and validate_document",
-          "convert_document to one or more immutable artifacts",
-          "preview_document and inspect previewBasis before treating images as source renders, reconstructed imports, or native extraction",
+          "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: '{[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.",
@@ -4492,6 +4613,124 @@ function registerAuthoringGuideResource(server) {
   );
 }
 function registerTemplateTools(server, context) {
+  server.registerTool(
+    "get_authoring_context",
+    {
+      description: "Get a compact agent-facing authoring contract plus the complete linked-Squisq catalog in structured content, with optional block recommendations.",
+      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_LIMITS7.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;
+          }
+          const payload = {
+            goal,
+            targetFormat: normalizedTarget,
+            defaultTemplateId: "content",
+            defaultFidelity: authoringDefaultFidelity(normalizedTarget, goal),
+            workflow: [
+              "Treat supplied facts as a closed evidence set. Use temporal or correlational wording unless causality is supplied. Label calculations, assumptions, hypotheses, recommendations, and illustrative examples. Do not infer end-to-end feasibility from one supplied phase duration.",
+              "Audit claims before conversion: causal links, rhetorical labels such as compounding, engine, healthy, strong, or constraint, superlatives, sole-cause claims, targets, capabilities, owners, dates, channels, and operational details must be supplied or explicitly framed as a hypothesis, recommendation, example, or proposal. Do not connect separate metrics, audiences, segments, or workflows unless the relationship is supplied. Prefer observed, coincided with, intended to, or proposed over drove, addresses, protects, or proves. Do not call choices a sequence or capacity allocation unless order, timing, or resource constraints were supplied.",
+              "Complete every requested element without presenting invented policy as established fact. When a requested policy, playbook, or training guide needs unsupplied roles, gates, timelines, channels, or procedures, add one explicit proposed operating model scope note placed before the first such detail so it governs all of them.",
+              "Generic option traits\u2014control, flexibility, vendor support, freed capacity, switching costs\u2014are capability claims: state one only when supplied or labeled Assumption or Judgment, even in table cells and tradeoffs.",
+              "Author complete Squisq-compatible content with heading-bound annotations; ordinary headings default to the loss-averse content template.",
+              normalizedTarget === "pptx" ? "Match every explicitly requested slide count exactly. Use exactly one level-one Markdown heading (#) per slide and no level-two through level-six headings because every heading becomes a slide by default. Target at most 80 words per slide, and use lists, tables, or bold labels for within-slide structure." : "Honor the requested word range and document genre. Prefer connected memo prose for executive decisions and native headings, tables, and checklists for operational documents.",
+              normalizedTarget === "pptx" ? "Make slide one a supported point-of-view thesis, not a generic title or unsupported flourish. For requested choices, state a concrete opportunity cost grounded in the supplied alternatives and name one clearly labeled proposed accountable role per choice. If a tradeoff requires an unsupplied capacity or outcome assumption, label it Assumption or Potential tradeoff rather than stating it as fact." : "Tie each decision implication or comparative judgment to a supplied fact or calculation, or label it Judgment. When accountability is requested but not supplied, name one clearly labeled proposed accountable role per decision or workstream.",
+              "Add decision value without inventing causes: interpret supplied comparisons to baselines, goals, targets, and rankings; use transparent calculations; label any new review cadence or measurement procedure as proposed.",
+              "Before validation and conversion, run a content preflight: count slide sections or document words, verify every requested element, and rewrite or label every unsupported claim.",
+              "Use the complete Markdown as the authoritative source. Pass it\u2014or a bundle source when assets are needed\u2014directly to convert_document, and revise by editing the complete Markdown and converting again.",
+              "Use create_document_bundle only when reusing a large Markdown-and-asset bundle across several review or conversion operations would materially reduce retransmission.",
+              "Use inspect_document or validate_document when semantic structure, content retention, accessibility, or target diagnostics need review; repair actionable findings in the authoritative Markdown.",
+              "Use preview_document when visual evidence is needed, inspect previewBasis, and repair overflow or layout problems in the authoritative Markdown.",
+              normalizedTarget === "pptx" ? "For visual polish, replace selected content blocks with compatible recommended templates; use patterns such as definitionCard for a definition, dataTable for a true table, comparisonBar for supported numeric comparisons, and list for concise steps when the returned catalog supports them. Preserve all required content and preview again." : "For visual polish, use native headings, tables, and checklists where they improve scanning; keep complete-body content when a visual template would discard detail, then preview again.",
+              "Convert to immutable artifacts, inspect conversion reports, and save only final durable outputs."
+            ],
+            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_LIMITS7.arrayEntries).map((theme) => ({
+              id: requireWireIdentifier(theme.id, "theme id"),
+              name: boundWireText(theme.name, MCP_WIRE_LIMITS7.labelCharacters, theme.id),
+              description: boundWireText(theme.description ?? "")
+            })),
+            transformStyles: transformModule.getTransformStyleSummaries().slice(0, MCP_WIRE_LIMITS7.arrayEntries).map((style) => ({
+              id: requireWireIdentifier(style.id, "transform 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);
+      }
+    }
+  );
   server.registerTool(
     "list_templates",
     {
@@ -4502,15 +4741,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 +4762,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");
@@ -4920,12 +5134,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(", ")}`
+  ];
+  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;
 }
@@ -4955,6 +5197,52 @@ function summarizeTheme(theme) {
     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_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_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 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_LIMITS7.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");
@@ -5345,32 +5633,33 @@ 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. 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) {
   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.
-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.`;
+1. Call get_authoring_context with targetFormat "mp4" for the complete linked-Squisq vocabulary and workflow.
+2. Author concise Markdown for a ${orientation ?? "landscape"} animated sequence using theme "${theme ?? "choose from the returned themes"}" and template "${template ?? "content until visual optimization"}". Bind annotations to headings.
+3. Keep the complete Markdown as the authoritative draft and pass it\u2014or a bundle source when assets are needed\u2014directly to convert_document. Use validate_document for uncertain target constraints and preview_document when representative-frame evidence is useful; repair findings in the complete Markdown.
+4. Call convert_document with the complete source, an mp4 target, and orientation "${orientation ?? "landscape"}"; monitor progress and honor cancellation. Revise by editing the complete Markdown and converting again.
+5. Use get_conversion_report for provenance and save_artifact only when a durable file is required.`;
 }
 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.
-4. Call convert_document with a ${target} target to create an immutable artifact.
-5. Call preview_document and review the bounded page images.
+1. Call get_authoring_context with targetFormat "${target}" for the complete linked-Squisq vocabulary and workflow.
+2. Treat the topic facts as a closed evidence set. Preserve them exactly, use temporal or correlational wording unless causality is supplied, and label calculations, assumptions, hypotheses, recommendations, and examples. Causal links, superlatives, sole causes, capabilities, owners, dates, channels, and operational details must be supplied or explicitly framed. When the requested genre needs unsupplied roles, gates, timelines, channels, or procedures, add one proposed operating model scope note that applies to those details.
+3. Honor the requested word range and document genre. Author structured Markdown using theme "${theme ?? "choose from the returned themes"}" and template "${template ?? "content until visual optimization"}". Bind annotations to headings. Use connected memo prose for executive decisions and native headings, tables, and checklists for operational documents; retain complete-body content when a visual template would discard detail.
+4. Before conversion, count document words, verify every requested element, and rewrite or label every unsupported claim. Keep the complete Markdown as the authoritative draft and pass it\u2014or a bundle source when assets are needed\u2014directly to convert_document. Use validate_document when syntax, accessibility, retention, or target diagnostics need review, and preview_document when page-layout evidence is useful; repair findings in the complete Markdown.
+5. Call convert_document with the complete source and a ${target} target to create an immutable artifact. Revise by editing the complete Markdown and converting again.
 6. Use get_conversion_report for provenance and save_artifact only when a durable file is required.`;
 }
 function complete(values, prefix) {
@@ -5410,7 +5699,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: "Treat provided facts as a closed evidence set: preserve them exactly; use temporal or correlational wording unless causality is supplied; label calculations, assumptions, hypotheses, recommendations, and examples. Causal links, rhetorical performance labels, superlatives, sole causes, targets, capabilities, owners, dates, channels, and operational details must be supplied or explicitly framed. Do not connect separate metrics, audiences, segments, or workflows unless the relationship is supplied. Prefer observed, coincided with, intended to, or proposed over drove, addresses, protects, or proves. Add decision value through supplied baselines, goals, targets, rankings, and transparent calculations. Do not call choices a sequence or capacity allocation unless order, timing, or resources were supplied. When a requested policy, playbook, or training guide needs unsupplied operating details, add one proposed operating model scope note, then complete every requested element. Match explicit slide/page counts and word ranges exactly; target at most 80 words per presentation section. Make slide one a supported point-of-view thesis. For requested choices, state concrete opportunity costs grounded in supplied alternatives and one proposed accountable role per choice; label unsupplied capacity, outcome, or review-cadence assumptions. Before conversion, count sections or words, verify required elements, and audit unsupported claims. Start with get_authoring_context for the compact linked-Squisq contract and structured catalog. Author complete Squisq-compatible Markdown with template annotations on headings, for example `# Heading {[content]}`; standalone `{[template]}` creates an extra heading-less block. Ordinary headings default to the loss-averse `content` template. The canonical path is complete Markdown\u2014or a bundle source when assets are needed\u2014directly into convert_document; revise by editing the complete Markdown and converting again. create_document_bundle is optional for materially large, reusable Markdown-and-asset bundles. Use inspect_document, validate_document, and preview_document when their evidence is useful rather than as required phases. Save only the final durable artifact. Never invent root ids: call list_roots and use an id exactly as returned."
+    }
+  );
   registerAgenticTools(server, {
     authority,
     artifacts,