@bendyline/docblocks-cli 2.2.1 → 2.3.0

package/dist/bin.js

@@ -1831,47 +1831,6 @@ async function inspectPreparedDocument(_documents, prepared, maximumBlocks = DEF
     diagnostics: boundDiagnostics(diagnostics, "inspect")
   };
 }
-async function validatePreparedDocument(_documents, prepared, targetFormat, signal) {
-  throwIfAborted5(signal);
-  const normalizedTargetFormat = normalizeTargetFormat(targetFormat);
-  const { validateMarkdownSource } = await import("@bendyline/squisq/doc");
-  await yieldForCancellation(signal);
-  const assets = prepared.assets;
-  const validation = validateMarkdownSource(prepared.markdown, {
-    assets: new Set(assets.map((asset) => asset.path))
-  });
-  throwIfAborted5(signal);
-  const diagnostics = [
-    ...prepared.diagnostics,
-    ...validation.diagnostics.map(
-      (diagnostic) => mapDocDiagnostic(diagnostic, prepared.sourceFormat)
-    ),
-    ...missingAltTextDiagnostics(
-      prepared.markdownDoc,
-      normalizedTargetFormat ?? prepared.sourceFormat
-    ),
-    ...await authoringDiagnostics(
-      prepared,
-      "validate",
-      normalizedTargetFormat ?? prepared.sourceFormat,
-      signal
-    ),
-    ...normalizedTargetFormat ? await targetPreflight(prepared, normalizedTargetFormat, signal) : []
-  ];
-  await yieldForCancellation(signal);
-  const unique = boundDiagnostics(diagnostics, "validate");
-  throwIfAborted5(signal);
-  const summary = summarizeDiagnostics(unique);
-  return {
-    version: DOCBLOCKS_MCP_WIRE_VERSION,
-    kind: "validation",
-    sourceFormat: prepared.sourceFormat,
-    targetFormat: normalizedTargetFormat,
-    valid: summary.errorCount === 0,
-    summary,
-    diagnostics: unique
-  };
-}
 function annotationSyntaxDiagnostics(markdown, stage, format) {
   const diagnostics = [];
   const lines = markdown.split(/\r?\n/);
@@ -1927,7 +1886,7 @@ function malformedAnnotationDiagnostic(stage, format, line, column, message) {
     format,
     count: 1,
     message,
-    remediation: 'Repair the annotation so it reads exactly `{[templateId key="value"]}` with no extra braces or brackets, then validate again.',
+    remediation: 'Repair the annotation so it reads exactly `{[templateId key="value"]}` with no extra braces or brackets.',
     retryable: false,
     location: { kind: "source", line, column }
   };
@@ -2013,7 +1972,7 @@ async function authoringDiagnostics(prepared, stage, format, signal) {
         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.",
+        remediation: "Keep the content template or repair its inputs; request a preview only when visual evidence is useful.",
         retryable: false,
         location: {
           kind: "block",
@@ -2400,7 +2359,7 @@ function mapDocDiagnostic(diagnostic, format) {
   return {
     code: diagnostic.code,
     severity: diagnostic.severity,
-    stage: "validate",
+    stage: "inspect",
     format,
     count: 1,
     message: diagnostic.message,
@@ -2429,7 +2388,7 @@ function missingAltTextDiagnostics(markdownDoc, format) {
     {
       code: "missing-alt-text",
       severity: "warning",
-      stage: "validate",
+      stage: "inspect",
       format,
       count: missingCount,
       message: missingCount === 1 ? "One image has no alternative text." : `${missingCount} images have no alternative text.`,
@@ -2439,130 +2398,6 @@ function missingAltTextDiagnostics(markdownDoc, format) {
     }
   ];
 }
-async function targetPreflight(prepared, targetFormat, signal) {
-  throwIfAborted5(signal);
-  const normalized = targetFormat.toLowerCase();
-  const { createCliRegistry: createCliRegistry2 } = await import("@bendyline/squisq-cli/api");
-  throwIfAborted5(signal);
-  const target = createCliRegistry2().get(normalized);
-  if (!target?.exportDoc) {
-    return [
-      {
-        code: target ? "unsupported-output" : "unknown-format",
-        severity: "error",
-        stage: "validate",
-        format: normalized,
-        count: 1,
-        message: target ? `${target.label} cannot be used as a conversion target.` : `Unknown target format "${normalized}".`,
-        remediation: "Choose an export-capable format from list_formats.",
-        retryable: false,
-        location: null
-      }
-    ];
-  }
-  const diagnostics = [];
-  const details = summarizeMarkdownNodes(prepared.markdownDoc);
-  const { flattenBlocks } = await import("@bendyline/squisq/doc");
-  const flatBlocks = flattenBlocks(prepared.doc.blocks);
-  await yieldForCancellation(signal);
-  if (["pptx", "pdf", "mp4", "gif"].includes(normalized)) {
-    let denseBlockCount = 0;
-    let firstDenseBlock = null;
-    let analyzedIndex = 0;
-    for (const entry of await analyzeDocumentBlocks(prepared.doc.blocks)) {
-      const checkpoint = cancellationCheckpoint(signal, analyzedIndex);
-      if (checkpoint) await checkpoint;
-      analyzedIndex += 1;
-      if (entry.bodyWordCount <= 120 && entry.plainText.length <= 900) continue;
-      denseBlockCount += 1;
-      firstDenseBlock ?? (firstDenseBlock = entry.block);
-    }
-    if (denseBlockCount > 0) {
-      diagnostics.push({
-        code: "content-density-high",
-        severity: "warning",
-        stage: "validate",
-        format: normalized,
-        count: denseBlockCount,
-        message: denseBlockCount === 1 ? `Block "${firstDenseBlock?.title ?? firstDenseBlock?.id ?? "unknown"}" may be too dense for a single rendered item.` : `${denseBlockCount} blocks may be too dense for a single rendered item.`,
-        remediation: "Split the block, shorten prose, or confirm the result with preview_document overflow diagnostics.",
-        retryable: false,
-        location: denseBlockCount === 1 && firstDenseBlock ? {
-          kind: "block",
-          blockId: toWireIdentifier(firstDenseBlock.id, "block"),
-          nodeType: "block"
-        } : null
-      });
-    }
-    const denseTables = details.tables.filter(
-      (table) => table.columnCount > 8 || table.rowCount > 30
-    );
-    if (denseTables.length > 0) {
-      const firstDenseTable = denseTables[0];
-      diagnostics.push({
-        code: "table-density-high",
-        severity: "warning",
-        stage: "validate",
-        format: normalized,
-        count: denseTables.length,
-        message: denseTables.length === 1 && firstDenseTable ? `Table ${firstDenseTable.index + 1} has ${firstDenseTable.rowCount} rows and ${firstDenseTable.columnCount} columns and may overflow.` : `${denseTables.length} tables may overflow the rendered output.`,
-        remediation: "Split the table or use a spreadsheet target; verify visual clipping with preview_document.",
-        retryable: false,
-        location: null
-      });
-    }
-  }
-  if (normalized === "pptx" && flatBlocks.some((block) => block.template)) {
-    diagnostics.push(
-      warningDiagnostic(
-        "Editable-native PPTX export preserves semantic content and theme but does not reproduce arbitrary Squisq template geometry.",
-        "validate",
-        normalized
-      )
-    );
-  }
-  if (normalized === "pdf" && await hasImages(prepared.markdownDoc, signal)) {
-    diagnostics.push(
-      warningDiagnostic(
-        "Native PDF export currently represents Markdown images as labeled placeholders.",
-        "validate",
-        normalized
-      )
-    );
-  }
-  if ((normalized === "csv" || normalized === "xlsx") && details.tableCount === 0) {
-    diagnostics.push(
-      warningDiagnostic(
-        `${normalized.toUpperCase()} export is table-oriented; this document contains no Markdown tables.`,
-        "validate",
-        normalized
-      )
-    );
-  }
-  if (normalized === "gif" && (prepared.doc.audio?.segments?.length ?? 0) > 0) {
-    diagnostics.push(
-      warningDiagnostic(
-        "Animated GIF does not support audio; audio will be omitted.",
-        "validate",
-        normalized
-      )
-    );
-  }
-  return diagnostics;
-}
-async function hasImages(markdownDoc, signal) {
-  throwIfAborted5(signal);
-  let found = false;
-  const visit = (node) => {
-    if (found || !node || typeof node !== "object") return;
-    const candidate = node;
-    if (candidate.type === "image" || candidate.type === "imageReference") found = true;
-    if (Array.isArray(candidate.children)) candidate.children.forEach(visit);
-  };
-  visit(markdownDoc);
-  await yieldForCancellation(signal);
-  return found;
-}
 function boundDiagnostics(diagnostics, stage) {
   const aggregated = aggregateDiagnostics(diagnostics);
   if (aggregated.length <= MAX_DIAGNOSTICS) return aggregated;
@@ -2643,29 +2478,6 @@ function sameLocation(left, right) {
 function safeDiagnosticCountSum(left, right) {
   return Math.min(Number.MAX_SAFE_INTEGER, left + right);
 }
-function summarizeDiagnostics(diagnostics) {
-  let errorCount = 0;
-  let warningCount2 = 0;
-  let infoCount = 0;
-  for (const diagnostic of diagnostics) {
-    if (diagnostic.severity === "error") {
-      errorCount = safeDiagnosticCountSum(errorCount, diagnostic.count);
-    } else if (diagnostic.severity === "warning") {
-      warningCount2 = safeDiagnosticCountSum(warningCount2, diagnostic.count);
-    } else {
-      infoCount = safeDiagnosticCountSum(infoCount, diagnostic.count);
-    }
-  }
-  return { errorCount, warningCount: warningCount2, infoCount };
-}
-function normalizeTargetFormat(targetFormat) {
-  if (targetFormat === null) return null;
-  const normalized = targetFormat.toLowerCase();
-  if (!FORMAT_PATTERN.test(normalized)) {
-    throw new Error(`Invalid target format "${targetFormat.slice(0, 64)}"`);
-  }
-  return normalized;
-}
 function words(text) {
   return text.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [];
 }
@@ -4235,8 +4047,7 @@ import {
   parseDocumentSource,
   parseInspectionResult,
   parseMaterializationOptions,
-  parsePreviewResult,
-  parseValidationResult
+  parsePreviewResult
 } from "@bendyline/docblocks/mcp";
 import {
   artifactUriSchema,
@@ -4253,7 +4064,7 @@ function registerAgenticTools(server, context) {
   server.registerTool(
     "list_roots",
     {
-      description: "List opaque root aliases granted when this DocBlocks MCP server started. Root aliases improve path usability but never expand authority.",
+      description: "Call first when durable local output is requested. Lists opaque startup-granted roots; if none is write-enabled, save_artifact cannot publish a file and the MCP server must be restarted with --allow-write.",
       inputSchema: z.object({}).strict(),
       outputSchema: DOCBLOCKS_MCP_TOOL_OUTPUT_SCHEMAS.list_roots,
       annotations: READ_ONLY
@@ -4261,7 +4072,7 @@ function registerAgenticTools(server, context) {
     async () => {
       try {
         const roots = (await context.authority).listRoots();
-        return textAndStructured({ roots });
+        return textAndStructured({ roots }, rootDiscoveryText(roots));
       } catch (caught) {
         return errorResult(caught, "resolve");
       }
@@ -4288,13 +4099,15 @@ function registerAgenticTools(server, context) {
   server.registerTool(
     "convert_document",
     {
-      description: "Convert any linked-registry input into one or more immutable artifacts. Use save_artifact only when a durable filesystem file is required.",
+      description: "Convert plain text, Markdown, bundles, or linked-registry inputs directly into one or more immutable artifacts. Plain Markdown needs no preflight or annotations; valid Squisq annotations are optional layout hints. Use save_artifact only for durable filesystem output.",
       inputSchema: z.object({
         source: documentSourceSchema,
         targets: z.array(conversionTargetSchema).min(1).max(12),
         themeId: identifierSchema.optional(),
         transformId: identifierSchema.optional(),
-        autoTemplates: z.boolean().optional(),
+        autoTemplates: z.boolean().optional().describe(
+          "Enable content-aware automatic template selection. Defaults to true; explicit annotations still take precedence."
+        ),
         title: z.string().max(4e3).optional()
       }).strict(),
       outputSchema: DOCBLOCKS_MCP_TOOL_OUTPUT_SCHEMAS.convert_document,
@@ -4314,7 +4127,7 @@ function registerAgenticTools(server, context) {
               targets: targets.map(toConversionTarget),
               themeId,
               transformId,
-              autoTemplates,
+              autoTemplates: autoTemplates ?? true,
               title
             },
             operationSignal,
@@ -4338,7 +4151,7 @@ function registerAgenticTools(server, context) {
   server.registerTool(
     "create_document_bundle",
     {
-      description: "Optionally stage Markdown plus authority-scoped assets as a reusable immutable DBK artifact when the same bundle will feed several operations. For normal authoring, pass complete Markdown or a bundle source directly to convert_document.",
+      description: "Stage Markdown plus authority-scoped assets as a reusable immutable DBK artifact when assets must travel with the document or the same draft will be passed to two or more inspect, preview, or convert calls. Pass its artifact URI instead of repeating the Markdown.",
       inputSchema: z.object({ source: bundleDocumentSourceSchema }).strict(),
       outputSchema: DOCBLOCKS_MCP_TOOL_OUTPUT_SCHEMAS.create_document_bundle,
       annotations: ARTIFACT_CREATING
@@ -4412,7 +4225,7 @@ function registerAgenticTools(server, context) {
   server.registerTool(
     "inspect_document",
     {
-      description: "Inspect any linked-registry document as bounded semantic structure, block provenance, assets, metadata, theme, and diagnostics.",
+      description: "Inspect bounded semantic structure, block provenance, assets, metadata, theme, and diagnostics when the user asks for document analysis. Inspection is never required before conversion.",
       inputSchema: z.object({
         source: documentSourceSchema,
         maxBlocks: z.number().int().min(1).max(2e3).optional(),
@@ -4441,37 +4254,6 @@ function registerAgenticTools(server, context) {
       }
     }
   );
-  server.registerTool(
-    "validate_document",
-    {
-      description: "Validate document structure, templates, annotations, assets, accessibility, and optional target-format fidelity before export.",
-      inputSchema: z.object({
-        source: documentSourceSchema,
-        targetFormat: formatInputSchema.nullable().optional()
-      }).strict(),
-      outputSchema: DOCBLOCKS_MCP_TOOL_OUTPUT_SCHEMAS.validate_document,
-      annotations: READ_ONLY
-    },
-    async ({ source, targetFormat }, extra) => {
-      try {
-        return await context.runOperation(extra.signal, async (operationSignal) => {
-          const documents = new DocumentService(await context.authority, context.artifacts);
-          const prepared = await documents.prepare(requireDocumentSource(source), operationSignal);
-          const normalizedTargetFormat = targetFormat?.toLowerCase() ?? null;
-          const result = await validatePreparedDocument(
-            documents,
-            prepared,
-            normalizedTargetFormat,
-            operationSignal
-          );
-          requireWire(parseValidationResult(result), "validation");
-          return textAndStructured(result);
-        });
-      } catch (caught) {
-        return errorResult(caught, "validate", null, extra.signal);
-      }
-    }
-  );
   server.registerTool(
     "compare_documents",
     {
@@ -4617,7 +4399,7 @@ function registerAuthoringGuideResource(server) {
     "authoring-guide",
     "docblocks://authoring-guide",
     {
-      description: "Compact linked-Squisq authoring vocabulary, artifact workflow, fidelity modes, templates, themes, and transform styles.",
+      description: "Complete linked-Squisq authoring catalog with exact template inputs, fidelity modes, themes, and transform styles. Read only when the focused authoring context is insufficient.",
       mimeType: "application/json",
       annotations: { audience: ["assistant"], priority: 1 }
     },
@@ -4628,18 +4410,14 @@ function registerAuthoringGuideResource(server) {
         import("@bendyline/squisq/transform")
       ]);
       const guide = {
-        version: 6,
+        version: 8,
         workflow: [
-          "treat supplied facts as a closed evidence set; label calculations, assumptions, hypotheses, recommendations, and examples; do not present causal links, rhetorical performance labels, superlatives, sole causes, targets, capabilities, owners, dates, channels, or operational details as established facts unless supplied",
-          "when the requested genre needs unsupplied roles, gates, timelines, channels, or procedures, add one explicit proposed operating model scope note that applies to those details, then complete the requested element",
-          "author complete Squisq-compatible Markdown with annotations bound to headings; ordinary headings default to the loss-averse content template",
-          "for PPTX, use exactly one level-one Markdown heading per slide and no level-two through level-six headings because every heading becomes a slide by default",
-          "by default, pass the complete Markdown\u2014or a bundle source when assets are needed\u2014directly to convert_document; revise by editing the complete Markdown and converting again",
-          "use create_document_bundle only when a reusable staged DBK materially avoids repeating a large Markdown-and-asset bundle across several operations",
-          "use inspect_document, validate_document, and preview_document when their semantic, diagnostic, or visual evidence is useful; they are review tools rather than required phases",
-          "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"
+          "plain text and ordinary Markdown can be passed directly to convert_document without a preflight or template annotations",
+          "for deliberate PPTX slide boundaries, use one level-one Markdown heading per slide; unstructured text is still accepted",
+          "convert_document chooses compatible templates automatically; Squisq annotations on headings are optional layout hints that take precedence",
+          "use a bundle source when assets must travel with the document, or create_document_bundle when one draft will be reused by two or more inspect, preview, or convert calls",
+          "use inspect_document or preview_document only when the user asks for document analysis or visual evidence",
+          "convert_document creates immutable artifacts; save_artifact only when a durable file is required"
         ],
         markdownAnnotation: '# Heading {[templateId key="value"]}',
         standaloneAnnotation: '{[templateId key="value"]}',
@@ -4680,7 +4458,7 @@ function registerTemplateTools(server, context) {
   server.registerTool(
     "get_authoring_context",
     {
-      description: "Get a compact agent-facing authoring contract plus the complete linked-Squisq catalog in structured content, with optional block recommendations.",
+      description: "Optionally discover target capabilities, safe defaults, themes, transforms, and exact starter annotation examples. Plain Markdown can be converted without calling this tool.",
       inputSchema: z.object({
         targetFormat: formatInputSchema.optional(),
         goal: z.enum(["content-first", "visual-polish"]).optional(),
@@ -4709,7 +4487,7 @@ function registerTemplateTools(server, context) {
             import("@bendyline/squisq/transform")
           ]);
           const annotationHandling = normalizedTarget ? await targetTemplateAnnotationHandling(normalizedTarget) : null;
-          const templates = annotationHandling === "ignored" ? fullTemplates.filter((template) => template.safeForContentFirst) : fullTemplates;
+          const candidateTemplates = annotationHandling === "ignored" ? fullTemplates.filter((template) => template.safeForContentFirst) : fullTemplates;
           let recommendations = [];
           let totalBlocks = null;
           let truncated = false;
@@ -4729,7 +4507,7 @@ function registerTemplateTools(server, context) {
               const profile = recommendModule.profileBlockContents(block.contents ?? []);
               const visual = recommendModule.recommendTemplatesForBlock(
                 profile,
-                templates.map((template) => template.id)
+                candidateTemplates.map((template) => template.id)
               ).recommended;
               const recommendedTemplateIds = goal === "content-first" ? ["content", ...visual.filter((id) => id !== "content")] : visual;
               return {
@@ -4751,31 +4529,26 @@ function registerTemplateTools(server, context) {
             goal,
             targetFormat: normalizedTarget,
             defaultTemplateId: "content",
-            defaultFidelity: authoringDefaultFidelity(normalizedTarget, goal),
+            defaultFidelity: authoringDefaultFidelity(normalizedTarget),
             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. Do not connect separate metrics, audiences, segments, or workflows unless the relationship is supplied. Prefer observed, coincided with, intended to, or proposed over drove, addresses, protects, or proves. Do not call choices a sequence or capacity allocation unless order, timing, or resources were supplied.",
-              "Complete every requested element without presenting invented policy as established fact. When a requested policy, playbook, or training guide needs unsupplied roles, gates, timelines, channels, or procedures, add one explicit proposed operating model scope note placed before the first such detail so it governs all of them. Prefix each unsupplied operational rule with Proposed: on its slide or section.",
-              "Generic option traits\u2014control, flexibility, vendor support, freed capacity, switching costs\u2014are capability claims: state one only when supplied or labeled Assumption or Judgment, even in table cells and tradeoffs.",
-              "Author complete Squisq-compatible content with heading-bound annotations; ordinary headings default to the loss-averse content template.",
-              normalizedTarget === "pptx" ? "Match every explicitly requested slide count exactly. Use exactly one level-one Markdown heading (#) per slide and no level-two through level-six headings because every heading becomes a slide by default. Target at most 80 words per slide, and use lists, tables, or bold labels for within-slide structure." : "Honor the requested word range and document genre. Prefer connected memo prose for executive decisions and native headings, tables, and checklists for operational documents.",
-              normalizedTarget === "pptx" ? "Make slide one a supported point-of-view thesis, not a generic title. For requested choices, state a concrete opportunity cost from supplied alternatives and one proposed accountable role per choice. Label any unsupplied capacity or outcome assumption Assumption or Potential tradeoff." : "Tie each decision implication or comparative judgment to a supplied fact or calculation, or label it Judgment. When accountability is requested but not supplied, name one clearly labeled proposed accountable role per decision or workstream.",
-              "Add decision value without inventing causes: interpret supplied comparisons to baselines, goals, and targets; use transparent calculations; label new review cadences or measurement procedures as proposed.",
-              "Before validation and conversion, run a content preflight: count slide sections or document words, verify every requested element, and rewrite or label every unsupported claim.",
-              "Use the complete Markdown as the authoritative source. Pass it\u2014or a bundle source when assets are needed\u2014directly to convert_document; revise by editing it and converting again.",
-              "When a draft will feed two or more validate, preview, or convert calls, stage it once with create_document_bundle and pass the returned artifact URI as each source; after edits, stage the revised draft again.",
-              "Use inspect_document or validate_document when semantic structure, content retention, accessibility, or target diagnostics need review; repair actionable findings in the authoritative Markdown.",
-              "Use preview_document when visual evidence is needed, inspect previewBasis, and repair overflow or layout problems in the authoritative Markdown.",
-              normalizedTarget === "pptx" ? "For visual polish, replace selected content blocks with compatible recommended templates; use patterns such as definitionCard for a definition, dataTable for a true table, comparisonBar for supported numeric comparisons, and list for concise steps when the returned catalog supports them. Preserve all required content and preview again." : annotationHandling === "ignored" ? "This target flattens template annotations to semantic content, so visual templates have no effect on the exported file: rely on native headings, tables, and checklists for structure and scanning." : "For visual polish, use native headings, tables, and checklists where they improve scanning; keep complete-body content when a visual template would discard detail, then preview again.",
-              "Convert to immutable artifacts, inspect conversion reports, and save only final durable outputs."
+              "For durable local output, call list_roots before drafting. If no returned root is write-enabled, stop and explain that the MCP server must restart with --allow-write; do not fall back to a shell or CLI converter. A transient artifact is acceptable only when the user did not require a file.",
+              normalizedTarget === "pptx" ? "Plain text and ordinary Markdown convert directly. Use one level-one Markdown heading (#) for each deliberate slide boundary; unstructured text is still accepted." : "Plain text and ordinary Markdown convert directly without a preflight.",
+              "convert_document chooses compatible templates automatically. Annotations on headings are optional layout hints that take precedence; use the returned exact starter examples when useful.",
+              annotationHandling === "ignored" ? "This target flattens template annotations to semantic content, so annotations are unnecessary for the exported file." : "Explicit valid annotations override automatic layout choices; invalid or unnecessary annotations should be omitted rather than repaired through a separate workflow.",
+              "Pass Markdown directly to convert_document. Use a bundle source for assets, or create_document_bundle only when one draft will be reused by two or more inspect, preview, or convert calls.",
+              "Use inspect_document or preview_document only when the user asks for document analysis or visual evidence. Save only final durable artifacts with save_artifact."
             ],
             syntax: {
               headingAnnotation: "# Heading {[content]}",
               standaloneAnnotation: "{[content]}",
               standaloneWarning: "A standalone annotation creates an additional heading-less block. Bind it to a heading unless that extra block is deliberate."
             },
-            formats,
-            templates,
+            formats: normalizedTarget ? formats.filter((format) => format.id === normalizedTarget) : formats,
+            templates: focusedAuthoringTemplates(
+              candidateTemplates,
+              recommendations,
+              normalizedTarget
+            ),
             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),
@@ -4790,7 +4563,19 @@ function registerTemplateTools(server, context) {
             totalBlocks,
             truncated
           };
-          return textAndStructured(payload, compactAuthoringContextText(payload));
+          return {
+            content: [
+              { type: "text", text: compactAuthoringContextText(payload) },
+              {
+                type: "resource_link",
+                uri: "docblocks://authoring-guide",
+                name: "authoring-guide",
+                description: "Complete linked-Squisq authoring catalog; read only if needed.",
+                mimeType: "application/json"
+              }
+            ],
+            structuredContent: asStructuredContent(successResult(payload))
+          };
         });
       } catch (caught) {
         return errorResult(caught, "inspect", null, extra.signal);
@@ -4832,7 +4617,7 @@ function registerTemplateTools(server, context) {
           (template2) => template2.id === templateId
         );
         if (!described) {
-          return errorResult(new Error(`Unknown template "${templateId}"`), "validate");
+          return errorResult(new Error(`Unknown template "${templateId}"`), "inspect");
         }
         const template = {
           id: described.id,
@@ -4929,7 +4714,7 @@ function registerThemeTools(server, context) {
           const documentTheme = prepared?.doc.customThemes?.find((theme2) => theme2.id === themeId);
           const builtIn = Object.prototype.hasOwnProperty.call(schemaModule.THEMES, themeId);
           if (!documentTheme && !builtIn) {
-            return errorResult(new Error(`Unknown theme "${themeId}"`), "validate");
+            return errorResult(new Error(`Unknown theme "${themeId}"`), "inspect");
           }
           const theme = docModule.resolveThemeForDoc(prepared?.doc, themeId);
           return textAndStructured({
@@ -5206,20 +4991,45 @@ function textAndStructured(payload, text = JSON.stringify(payload, null, 2)) {
     structuredContent: asStructuredContent(successResult(payload))
   };
 }
+function rootDiscoveryText(roots) {
+  if (roots.length === 0) {
+    return "No DocBlocks MCP roots are configured. Durable file output is unavailable: restart the server with --allow-write <directory>. Do not fall back to a shell or CLI converter; keep a transient artifact only when the user did not require a file.";
+  }
+  const catalog = JSON.stringify({ roots }, null, 2);
+  if (roots.some((root) => root.write)) return catalog;
+  return `${catalog}
+
+No returned root is write-enabled. Durable file output is unavailable: restart the server with --allow-write <directory>. Do not fall back to a shell or CLI converter.`;
+}
+function focusedAuthoringTemplates(candidates, recommendations, targetFormat) {
+  const selectedIds = /* @__PURE__ */ new Set(["content"]);
+  if (targetFormat === "pptx") {
+    for (const templateId of ["title", "sectionHeader", "statHighlight", "quote"]) {
+      selectedIds.add(templateId);
+    }
+  }
+  for (const recommendation of recommendations) {
+    for (const templateId of recommendation.recommendedTemplateIds) {
+      selectedIds.add(templateId);
+    }
+  }
+  return candidates.filter((template) => selectedIds.has(template.id));
+}
 function compactAuthoringContextText(context) {
   const target = context.targetFormat ?? "unspecified target";
   const lines = [
     `DocBlocks authoring contract: ${target}, ${context.goal}.`,
     `Default template: ${context.defaultTemplateId}. Default fidelity: ${context.defaultFidelity ?? "select for target"}.`,
     "",
-    "Required workflow:",
+    "Optional guidance:",
     ...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(", ")}`,
+    ...context.templates.filter(({ id }) => id !== "content").map(({ annotationExample }) => `Optional example: ${annotationExample}`),
     `Themes (${context.themes.length}): ${context.themes.map(({ id }) => id).join(", ")}`,
-    `Transform styles (${context.transformStyles.length}): ${context.transformStyles.map(({ id }) => id).join(", ")} \u2014 transforms re-compose blocks and can change section count; avoid on exact-count briefs.`
+    `Transform styles (${context.transformStyles.length}): ${context.transformStyles.map(({ id }) => id).join(", ")}.`
   ];
   if (context.recommendations.length > 0) {
     lines.push(
@@ -5230,7 +5040,7 @@ function compactAuthoringContextText(context) {
   }
   lines.push(
     "",
-    "The complete exact format, template-input, theme, transform, and recommendation catalog is in structuredContent. Use describe_template for focused follow-up when structured content is unavailable."
+    "This response is intentionally focused. Use recommend_templates on a complete draft, describe_template for exact selected inputs, or read docblocks://authoring-guide only when the full catalog is required."
   );
   return lines.join("\n");
 }
@@ -5307,12 +5117,9 @@ async function targetTemplateAnnotationHandling(targetFormat) {
   }
   return null;
 }
-function authoringDefaultFidelity(targetFormat, goal) {
+function authoringDefaultFidelity(targetFormat) {
   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";
   }
@@ -5638,7 +5445,7 @@ function registerAuthoringPrompts(server) {
   const presentation = server.registerPrompt(
     "create-presentation",
     {
-      description: "Create, validate, preview, and export an artifact-first presentation.",
+      description: "Convert model-authored Markdown into an artifact-first presentation.",
       argsSchema: presentationArgs.shape
     },
     async (args) => ({
@@ -5663,7 +5470,7 @@ function registerAuthoringPrompts(server) {
   const video = server.registerPrompt(
     "create-video",
     {
-      description: "Create, validate, preview, and export an artifact-first MP4 video.",
+      description: "Convert model-authored Markdown into an artifact-first MP4 video.",
       argsSchema: videoArgs.shape
     },
     async (args) => ({
@@ -5688,7 +5495,7 @@ function registerAuthoringPrompts(server) {
   const document2 = server.registerPrompt(
     "create-document",
     {
-      description: "Create, validate, preview, and export an artifact-first document.",
+      description: "Convert model-authored Markdown into an artifact-first document.",
       argsSchema: documentArgs.shape
     },
     async (args) => ({
@@ -5706,36 +5513,39 @@ function registerAuthoringPrompts(server) {
   document2.argsSchema = documentArgs;
 }
 function presentationPrompt(topic, style, theme, template) {
+  const templateHint = template ? ` Use the requested \`${template}\` annotation where appropriate.` : "";
+  const themeHint = theme ? ` with themeId \`${theme}\`` : "";
+  const styleHint = style ? ` and transformId \`${style}\`` : "";
   return `Create a presentation about: ${topic}
 
-1. Call get_authoring_context with targetFormat "pptx" and goal "content-first" for the complete linked-Squisq vocabulary and workflow in one response.
-2. Treat the topic facts as a closed evidence set. Preserve them exactly, use temporal or correlational wording unless causality is supplied, and label calculations, assumptions, hypotheses, recommendations, and examples. Causal links, rhetorical performance labels, superlatives, sole causes, capabilities, owners, dates, channels, and operational details must be supplied or explicitly framed. Do not connect separate metrics, audiences, segments, or workflows unless the relationship is supplied. Prefer observed, coincided with, intended to, or proposed over drove, addresses, protects, or proves. Add decision value through supplied baselines, goals, targets, rankings, and transparent calculations. Do not call choices a sequence or capacity allocation unless order, timing, or resources were supplied. When the requested content needs unsupplied operating details, add one proposed operating model scope note that applies to them.
-3. Match every explicitly requested slide count exactly. Use exactly one level-one Markdown heading (\`#\`) per slide and no level-two through level-six headings because every heading becomes a slide by default; use lists, tables, or bold labels within a slide. Target at most 80 words per slide. Make slide one a supported point-of-view thesis, not a generic title or unsupported flourish. For requested choices, state concrete opportunity costs grounded in supplied alternatives and one clearly labeled proposed accountable role per choice. Label any unsupplied capacity or outcome assumption as \`Assumption:\` or \`Potential tradeoff:\`. Author complete Markdown sections with accessible alt text. Put annotations on headings, for example \`# Heading {[content]}\`; a standalone \`{[template]}\` creates an extra block. Prefer style "${style ?? "choose from the returned transform styles"}", theme "${theme ?? "choose from the returned themes"}", and template "${template ?? "content until visual optimization"}".
-4. Keep the complete Markdown as the authoritative draft. Pass it\u2014or a bundle source when assets are needed\u2014directly to convert_document. Use create_document_bundle only when the same materially large Markdown-and-asset bundle will feed several operations. Do not write a temporary local Markdown file or invent a root id.
-5. Before conversion, count slide sections, verify every requested element, and rewrite or label every unsupported claim. Label any new review cadence or measurement procedure as proposed. Use validate_document when syntax, accessibility, retention, or target diagnostics need review; use preview_document when visual evidence such as overflow needs review. Repair findings in the complete Markdown.
-6. Only after content coverage is acceptable, replace selected \`content\` blocks with compatible visual templates such as \`definitionCard\`, \`dataTable\`, \`comparisonBar\`, or \`list\` when their semantic inputs fit. Preserve required content.
-7. Call convert_document with the complete source and a pptx target. Choose editable-native for editable Office structures, rendered-fidelity for exact Squisq visuals, or hybrid for rendered visuals plus semantic retention. Revise by editing the complete Markdown and converting again.
-8. Use get_conversion_report for provenance and save_artifact only when a durable file is required.`;
+1. For durable output, call list_roots before drafting. If no returned root is write-enabled, stop and explain that the MCP server must restart with --allow-write; do not use a shell or CLI converter.
+2. Author plain Markdown. One level-one heading (\`#\`) creates each deliberate slide boundary; unstructured text is also accepted. Squisq annotations are optional layout hints.${templateHint} Call get_authoring_context only when exact annotation examples or theme details would help.
+3. Pass the Markdown directly to convert_document with a pptx target${themeHint}${styleHint}. Use a bundle source only when assets must travel with the document. No validation, inspection, or preview is required.
+4. Use inspect_document or preview_document only when the user explicitly asks for document analysis or visual evidence.
+5. Call save_artifact only when a durable file is required.`;
 }
 function videoPrompt(topic, orientation, theme, template) {
+  const templateHint = template ? ` Use the requested \`${template}\` annotation where appropriate.` : "";
+  const themeHint = theme ? ` and themeId \`${theme}\`` : "";
   return `Create a video about: ${topic}
 
-1. Call get_authoring_context with targetFormat "mp4" for the complete linked-Squisq vocabulary and workflow.
-2. Author concise Markdown for a ${orientation ?? "landscape"} animated sequence using theme "${theme ?? "choose from the returned themes"}" and template "${template ?? "content until visual optimization"}". Bind annotations to headings.
-3. Keep the complete Markdown as the authoritative draft and pass it\u2014or a bundle source when assets are needed\u2014directly to convert_document. Use validate_document for uncertain target constraints and preview_document when representative-frame evidence is useful; repair findings in the complete Markdown.
-4. Call convert_document with the complete source, an mp4 target, and orientation "${orientation ?? "landscape"}"; monitor progress and honor cancellation. Revise by editing the complete Markdown and converting again.
-5. Use get_conversion_report for provenance and save_artifact only when a durable file is required.`;
+1. For durable output, call list_roots before drafting and stop if no root is write-enabled; do not use a shell or CLI converter.
+2. Author plain Markdown. Squisq annotations are optional layout hints.${templateHint} Call get_authoring_context only when exact annotation examples or theme details would help.
+3. Pass the Markdown directly to convert_document with an mp4 target, orientation "${orientation ?? "landscape"}"${themeHint}. Use a bundle source only when assets must travel with the document. No validation, inspection, or preview is required.
+4. Use preview_document only when the user explicitly asks for visual evidence.
+5. Call 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}
+  const templateHint = template ? ` Use the requested \`${template}\` annotation where appropriate.` : "";
+  const themeHint = theme ? ` and themeId \`${theme}\`` : "";
+  return `Create a document about: ${topic}
 
-1. Call get_authoring_context with targetFormat "${target}" for the complete linked-Squisq vocabulary and workflow.
-2. Treat the topic facts as a closed evidence set. Preserve them exactly, use temporal or correlational wording unless causality is supplied, and label calculations, assumptions, hypotheses, recommendations, and examples. Causal links, superlatives, sole causes, capabilities, owners, dates, channels, and operational details must be supplied or explicitly framed. When the requested genre needs unsupplied roles, gates, timelines, channels, or procedures, add one proposed operating model scope note that applies to those details.
-3. Honor the requested word range and document genre. Author structured Markdown using theme "${theme ?? "choose from the returned themes"}" and template "${template ?? "content until visual optimization"}". Bind annotations to headings. Use connected memo prose for executive decisions and native headings, tables, and checklists for operational documents; retain complete-body content when a visual template would discard detail.
-4. Before conversion, count document words, verify every requested element, and rewrite or label every unsupported claim. Keep the complete Markdown as the authoritative draft and pass it\u2014or a bundle source when assets are needed\u2014directly to convert_document. Use validate_document when syntax, accessibility, retention, or target diagnostics need review, and preview_document when page-layout evidence is useful; repair findings in the complete Markdown.
-5. Call convert_document with the complete source and a ${target} target to create an immutable artifact. Revise by editing the complete Markdown and converting again.
-6. Use get_conversion_report for provenance and save_artifact only when a durable file is required.`;
+1. For durable output, call list_roots before drafting and stop if no root is write-enabled; do not use a shell or CLI converter.
+2. Author plain Markdown. Squisq annotations are optional layout hints.${templateHint} Call get_authoring_context only when exact annotation examples or theme details would help.
+3. Pass the Markdown directly to convert_document with a ${target} target${themeHint}. Use a bundle source only when assets must travel with the document. No validation, inspection, or preview is required.
+4. Use inspect_document or preview_document only when the user explicitly asks for document analysis or visual evidence.
+5. Call save_artifact only when a durable file is required.`;
 }
 function complete(values, prefix) {
   const value = prefix ?? "";
@@ -5777,7 +5587,14 @@ function createMcpServer(options = {}) {
   const server = new McpServer(
     { name: "docblocks", version: getPackageVersion() },
     {
-      instructions: "Treat provided facts as a closed evidence set: preserve them exactly; use temporal or correlational wording unless causality is supplied; label calculations, assumptions, hypotheses, recommendations, and examples. Causal links, rhetorical performance labels, superlatives, sole causes, targets, capabilities, owners, dates, channels, and operational details must be supplied or explicitly framed. Do not connect separate metrics, audiences, segments, or workflows unless the relationship is supplied. Prefer observed, coincided with, intended to, or proposed over drove, addresses, protects, or proves. Add decision value through supplied baselines, goals, targets, rankings, and transparent calculations. Do not call choices a sequence or capacity allocation unless order, timing, or resources were supplied. When a requested policy, playbook, or training guide needs unsupplied operating details, add one proposed operating model scope note, then complete every requested element. Match explicit slide/page counts and word ranges exactly; target at most 80 words per presentation section. Make slide one a supported point-of-view thesis. For requested choices, state concrete opportunity costs grounded in supplied alternatives and one proposed accountable role per choice; label unsupplied capacity, outcome, or review-cadence assumptions. Before conversion, count sections or words, verify required elements, and audit unsupported claims. Start with get_authoring_context for the compact linked-Squisq contract and structured catalog. Author complete Squisq-compatible Markdown with template annotations on headings, for example `# Heading {[content]}`; standalone `{[template]}` creates an extra heading-less block. Ordinary headings default to the loss-averse `content` template. The canonical path is complete Markdown\u2014or a bundle source when assets are needed\u2014directly into convert_document; revise by editing the complete Markdown and converting again. When one draft will feed two or more validate, preview, or convert calls, stage it once with create_document_bundle and pass the returned artifact URI as each source instead of re-sending the Markdown. Use inspect_document, validate_document, and preview_document when their evidence is useful rather than as required phases. Save only the final durable artifact. Never invent root ids: call list_roots and use an id exactly as returned."
+      instructions: [
+        "For durable local output, call list_roots before drafting and use a returned write-enabled root id exactly as given. If none is writable, stop and explain that the server must restart with --allow-write; do not fall back to a shell or CLI converter.",
+        "Pass plain text or ordinary Markdown directly to convert_document; no preflight, inspection, preview, or template annotation is required. For deliberate PPTX slide boundaries, use one level-one heading per slide; unstructured text is still accepted.",
+        "convert_document chooses compatible templates automatically. Squisq annotations on headings are optional layout hints that take precedence. Call get_authoring_context only when exact starter examples, themes, transforms, or target details are useful; read the full authoring-guide or call describe_template only for advanced author control.",
+        "Use a bundle source when assets must travel with the document. Use create_document_bundle only when one complete draft will be reused by two or more inspect, preview, or convert calls.",
+        "Use inspect_document or preview_document only when the user asks for document analysis or visual evidence.",
+        "convert_document returns immutable artifacts and diagnostics. Save only final durable output with save_artifact; never invent root ids or switch conversion to a shell or CLI."
+      ].join(" ")
     }
   );
   registerAgenticTools(server, {