@bendyline/docblocks-cli 2.2.2 → 2.3.0

package/README.md

@@ -8,7 +8,7 @@ agents.
 
 ## Installation
 
-Node.js 22.14 or newer is required.
+Node.js 22.22.2+, 24.15.0+, or 26+ is required.
 
 ```bash
 npm install -g @bendyline/docblocks-cli
@@ -67,8 +67,11 @@ docblocks mcp --allow-read ./documents --allow-write ./exports
 
 For durable output, call `list_roots` before drafting. If no root is write-enabled,
 restart the server with `--allow-write`; do not bypass MCP with the direct `convert`
-command. `get_authoring_context` returns a focused contract and safe defaults, while
-the complete catalog remains available at `docblocks://authoring-guide`.
+command. Plain text or ordinary Markdown can be passed directly to
+`convert_document` without a preflight; compatible templates are chosen automatically,
+and explicit Squisq annotations remain optional overrides. `get_authoring_context` is
+optional discovery for exact annotation examples and safe defaults; the complete catalog remains
+available at `docblocks://authoring-guide`.
 
 `convert` and `video` accept Markdown, Squisq JSON Doc, DBK/ZIP, folders, and
 import-capable linked-registry formats. `build` replaces generated HTML files;

package/THIRD_PARTY_NOTICES.txt

@@ -6,7 +6,7 @@ Run `npm run generate:notices` from the repository root.
 Resolved runtime and optional dependency closure declared by packages/cli/package.json.
 
 Inventory source: package-lock.json.
-Components: 347.
+Components: 348.
 
 This notice is included in the published npm tarball. Transitive packages installed by npm also retain their package-local license files.
 
@@ -15,11 +15,11 @@ This notice is included in the published npm tarball. Transitive packages instal
 | Package | Version | License | Source |
 | --- | --- | --- | --- |
 | @antfu/install-pkg | 1.1.0 | MIT | https://github.com/antfu/install-pkg |
-| @bendyline/squisq | 2.4.1 | MIT | https://github.com/bendyline/squisq |
-| @bendyline/squisq-cli | 2.4.1 | MIT | https://github.com/bendyline/squisq |
-| @bendyline/squisq-formats | 2.3.5 | MIT | https://github.com/bendyline/squisq |
-| @bendyline/squisq-react | 2.4.1 | MIT | https://github.com/bendyline/squisq |
-| @bendyline/squisq-video | 2.2.5 | MIT | https://github.com/bendyline/squisq |
+| @bendyline/squisq | 2.4.3 | MIT | https://github.com/bendyline/squisq |
+| @bendyline/squisq-cli | 2.4.3 | MIT | https://github.com/bendyline/squisq |
+| @bendyline/squisq-formats | 2.3.7 | MIT | https://github.com/bendyline/squisq |
+| @bendyline/squisq-react | 2.4.5 | MIT | https://github.com/bendyline/squisq |
+| @bendyline/squisq-video | 2.2.7 | MIT | https://github.com/bendyline/squisq |
 | @braintree/sanitize-url | 7.1.2 | MIT | https://github.com/braintree/sanitize-url |
 | @chevrotain/types | 11.1.2 | Apache-2.0 | https://github.com/Chevrotain/chevrotain |
 | @ffmpeg/ffmpeg | 0.12.15 | MIT | https://github.com/ffmpegwasm/ffmpeg.wasm |
@@ -42,6 +42,7 @@ This notice is included in the published npm tarball. Transitive packages instal
 | @napi-rs/canvas-linux-x64-musl | 0.1.100 | MIT | https://www.npmjs.com/package/@napi-rs/canvas-linux-x64-musl |
 | @napi-rs/canvas-win32-arm64-msvc | 0.1.100 | MIT | https://www.npmjs.com/package/@napi-rs/canvas-win32-arm64-msvc |
 | @napi-rs/canvas-win32-x64-msvc | 0.1.100 | MIT | https://github.com/Brooooooklyn/canvas |
+| @pdf-lib/fontkit | 1.1.1 | MIT | https://github.com/Hopding/fontkit |
 | @pdf-lib/standard-fonts | 1.0.0 | MIT | https://github.com/Hopding/standard-fonts |
 | @pdf-lib/upng | 1.0.1 | MIT | https://github.com/Hopding/upng |
 | @types/d3 | 7.4.3 | MIT | https://github.com/DefinitelyTyped/DefinitelyTyped |
@@ -366,6 +367,14 @@ This notice is included in the published npm tarball. Transitive packages instal
 
 Package-local license, copying, and notice files are reproduced below. Where a published package omits its repository license, the reviewed aggregate or README identified in `Source files` supplies the retained material.
 
+### Packages whose npm archive omits license text
+
+The following locked packages declare a license identifier but publish no package-local license/copying/notice file. Their identifiers and source locations are retained here for distribution review:
+
+| Package | Version | Declared license | Source |
+| --- | --- | --- | --- |
+| @pdf-lib/fontkit | 1.1.1 | MIT | https://github.com/Hopding/fontkit |
+
 ==============================================================================
 Components: @antfu/install-pkg@1.1.0
 Source files: node_modules/@antfu/install-pkg/LICENSE
@@ -393,7 +402,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
 ==============================================================================
-Components: @bendyline/squisq-cli@2.4.1, @bendyline/squisq-formats@2.3.5, @bendyline/squisq-react@2.4.1, @bendyline/squisq-video@2.2.5, @bendyline/squisq@2.4.1
+Components: @bendyline/squisq-cli@2.4.3, @bendyline/squisq-formats@2.3.7, @bendyline/squisq-react@2.4.5, @bendyline/squisq-video@2.2.7, @bendyline/squisq@2.4.3
 Source files: node_modules/@bendyline/squisq-cli/LICENSE, node_modules/@bendyline/squisq-formats/LICENSE, node_modules/@bendyline/squisq-react/LICENSE, node_modules/@bendyline/squisq-video/LICENSE, node_modules/@bendyline/squisq/LICENSE
 ==============================================================================
 MIT License
@@ -663,7 +672,7 @@ This software contains code derived from the Puppeteer project (https://github.c
 available under the Apache 2.0 license (https://github.com/puppeteer/puppeteer/blob/master/LICENSE).
 
 ==============================================================================
-Components: @bendyline/squisq-cli@2.4.1
+Components: @bendyline/squisq-cli@2.4.3
 Source files: node_modules/@bendyline/squisq-cli/NOTICE.md
 ==============================================================================
 # Third-Party Notices for @bendyline/squisq-cli
@@ -683,12 +692,12 @@ Copyright and complete license texts for these dependencies are included in
 their respective npm distributions and source repositories.
 
 ==============================================================================
-Components: @bendyline/squisq-cli@2.4.1
+Components: @bendyline/squisq-cli@2.4.3
 Source files: node_modules/@bendyline/squisq-cli/THIRD_PARTY_LICENSES.txt
 ==============================================================================
 THIRD-PARTY LICENSES FOR @bendyline/squisq-cli
 
-The inventory below covers the bundled light standalone player artifact.
+The inventory below covers the bundled light and full standalone player artifacts.
 
 Generated from the actual esbuild input graph. Package-local license, copying,
 and notice files are reproduced verbatim. When an npm tarball omits its
@@ -5171,7 +5180,7 @@ The above copyright notice and this permission notice shall be included in all c
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 ==============================================================================
-Components: @bendyline/squisq-formats@2.3.5
+Components: @bendyline/squisq-formats@2.3.7
 Source files: node_modules/@bendyline/squisq-formats/NOTICE.md
 ==============================================================================
 # Third-Party Notices for @bendyline/squisq-formats
@@ -5182,20 +5191,21 @@ Third-party components remain under their respective license terms.
 
 ## Runtime dependencies
 
-| Package        | Version | License                 | Repository                       |
-| -------------- | ------- | ----------------------- | -------------------------------- |
-| @pdf-lib/upng  | 1.0.1   | MIT                     | https://github.com/Hopding/upng  |
-| @xmldom/xmldom | 0.9.10  | MIT                     | https://github.com/xmldom/xmldom |
-| jszip          | 3.10.1  | MIT OR GPL-3.0-or-later | https://github.com/Stuk/jszip    |
-| pdf-lib        | 1.17.1  | MIT                     | https://pdf-lib.js.org           |
-| pdfjs-dist     | 4.10.38 | Apache-2.0              | https://mozilla.github.io/pdf.js |
+| Package          | Version | License                 | Repository                         |
+| ---------------- | ------- | ----------------------- | ---------------------------------- |
+| @pdf-lib/fontkit | 1.1.1   | MIT                     | https://github.com/Hopding/fontkit |
+| @pdf-lib/upng    | 1.0.1   | MIT                     | https://github.com/Hopding/upng    |
+| @xmldom/xmldom   | 0.9.10  | MIT                     | https://github.com/xmldom/xmldom   |
+| jszip            | 3.10.1  | MIT OR GPL-3.0-or-later | https://github.com/Stuk/jszip      |
+| pdf-lib          | 1.17.1  | MIT                     | https://pdf-lib.js.org             |
+| pdfjs-dist       | 4.10.38 | Apache-2.0              | https://mozilla.github.io/pdf.js   |
 
 Squisq uses jszip under its MIT license option. Copyright and complete license
 texts for these dependencies are included in their respective npm
 distributions and source repositories.
 
 ==============================================================================
-Components: @bendyline/squisq-formats@2.3.5
+Components: @bendyline/squisq-formats@2.3.7
 Source files: node_modules/@bendyline/squisq-formats/THIRD_PARTY_LICENSES.txt
 ==============================================================================
 THIRD-PARTY LICENSES FOR @bendyline/squisq-formats
@@ -5205,9 +5215,179 @@ and notice files are reproduced verbatim. When an npm tarball omits its
 repository license, the pinned upstream copy is vendored and identified below.
 
 COMPONENTS
+- @fortawesome/fontawesome-free@7.2.0 ((CC-BY-4.0 AND OFL-1.1 AND MIT)); files: LICENSE.txt
+
+==============================================================================
+@fortawesome/fontawesome-free@7.2.0 - LICENSE.txt
+==============================================================================
+Fonticons, Inc. (https://fontawesome.com)
+
+--------------------------------------------------------------------------------
+
+Font Awesome Free License
+
+Font Awesome Free is free, open source, and GPL friendly. You can use it for
+commercial projects, open source projects, or really almost whatever you want.
+Full Font Awesome Free license: https://fontawesome.com/license/free.
+
+--------------------------------------------------------------------------------
+
+# Icons: CC BY 4.0 License (https://creativecommons.org/licenses/by/4.0/)
+
+The Font Awesome Free download is licensed under a Creative Commons
+Attribution 4.0 International License and applies to all icons packaged
+as SVG and JS file types.
+
+--------------------------------------------------------------------------------
+
+# Fonts: SIL OFL 1.1 License
+
+In the Font Awesome Free download, the SIL OFL license applies to all icons
+packaged as web and desktop font files.
+
+Copyright (c) 2026 Fonticons, Inc. (https://fontawesome.com)
+with Reserved Font Name: "Font Awesome".
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+SIL OPEN FONT LICENSE
+Version 1.1 - 26 February 2007
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting — in part or in whole — any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
+
+--------------------------------------------------------------------------------
+
+# Code: MIT License (https://opensource.org/licenses/MIT)
+
+In the Font Awesome Free download, the MIT license applies to all non-font and
+non-icon files.
+
+Copyright 2026 Fonticons, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in the
+Software without restriction, including without limitation the rights to use, copy,
+modify, merge, publish, distribute, sublicense, and/or sell copies of the Software,
+and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+--------------------------------------------------------------------------------
+
+# Attribution
+
+Attribution is required by MIT, SIL OFL, and CC BY licenses. Downloaded Font
+Awesome Free files already contain embedded comments with sufficient
+attribution, so you shouldn't need to do anything additional when using these
+files normally.
+
+We've kept attribution comments terse, so we ask that you do not actively work
+to remove them from files, especially code. They're a great way for folks to
+learn about Font Awesome.
+
+--------------------------------------------------------------------------------
+
+# Brand Icons
+
+All brand icons are trademarks of their respective owners. The use of these
+trademarks does not indicate endorsement of the trademark holder by Font
+Awesome, nor vice versa. **Please do not use brand logos for any purpose except
+to represent the company, product, or service to which they refer.**
 
 ==============================================================================
-Components: @bendyline/squisq-react@2.4.1
+Components: @bendyline/squisq-react@2.4.5
 Source files: node_modules/@bendyline/squisq-react/NOTICE.md
 ==============================================================================
 # Third-Party Notices for @bendyline/squisq-react
@@ -5231,7 +5411,7 @@ third-party license texts for the complete standalone bundle graph are shipped
 in THIRD_PARTY_LICENSES.txt.
 
 ==============================================================================
-Components: @bendyline/squisq-react@2.4.1
+Components: @bendyline/squisq-react@2.4.5
 Source files: node_modules/@bendyline/squisq-react/THIRD_PARTY_LICENSES.txt
 ==============================================================================
 THIRD-PARTY LICENSES FOR @bendyline/squisq-react
@@ -9768,7 +9948,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
 ==============================================================================
-Components: @bendyline/squisq-video@2.2.5
+Components: @bendyline/squisq-video@2.2.7
 Source files: node_modules/@bendyline/squisq-video/NOTICE.md
 ==============================================================================
 # Third-Party Notices for @bendyline/squisq-video
@@ -9793,7 +9973,7 @@ Copyright and complete license texts for the listed dependencies are included
 in their respective npm distributions and source repositories.
 
 ==============================================================================
-Components: @bendyline/squisq-video@2.2.5
+Components: @bendyline/squisq-video@2.2.7
 Source files: node_modules/@bendyline/squisq-video/THIRD_PARTY_LICENSES.txt
 ==============================================================================
 THIRD-PARTY LICENSES FOR @bendyline/squisq-video
@@ -9805,7 +9985,7 @@ repository license, the pinned upstream copy is vendored and identified below.
 COMPONENTS
 
 ==============================================================================
-Components: @bendyline/squisq@2.4.1
+Components: @bendyline/squisq@2.4.3
 Source files: node_modules/@bendyline/squisq/NOTICE.md
 ==============================================================================
 # Third-Party Notices for @bendyline/squisq
@@ -9836,7 +10016,7 @@ third-party license texts for bundled code and data are shipped in
 THIRD_PARTY_LICENSES.txt.
 
 ==============================================================================
-Components: @bendyline/squisq@2.4.1
+Components: @bendyline/squisq@2.4.3
 Source files: node_modules/@bendyline/squisq/THIRD_PARTY_LICENSES.txt
 ==============================================================================
 THIRD-PARTY LICENSES FOR @bendyline/squisq

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,
@@ -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: "Stage Markdown plus authority-scoped assets as a reusable immutable DBK artifact when the same complete draft will be passed to two or more validate, inspect, preview, or convert calls. Pass its artifact URI instead of repeating the Markdown.",
+      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 bounded semantic structure, block provenance, assets, metadata, theme, and diagnostics. Use for those details; do not pair it with validate_document for a routine export preflight.",
+      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: "Primary pre-export review for structure, template content retention, annotations, assets, accessibility, and target fidelity. Diagnostics include repairs; normally do not also call inspect_document.",
-      inputSchema: z.object({
-        source: documentSourceSchema,
-        targetFormat: formatInputSchema.nullable().optional()
-      }).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",
     {
@@ -4628,18 +4410,14 @@ function registerAuthoringGuideResource(server) {
         import("@bendyline/squisq/transform")
       ]);
       const guide = {
-        version: 7,
+        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 when the same complete draft will be passed to two or more validate, inspect, preview, or convert calls, then pass its artifact URI instead of repeating Markdown",
-          "use validate_document as the routine export preflight; use inspect_document only for semantic structure, provenance, assets, metadata, or theme details; use preview_document only when visual evidence is useful",
-          "for visual polish, replace selected content blocks with compatible visual templates while preserving required content",
-          "convert_document creates one or more immutable artifacts from the authoritative complete source",
-          "save_artifact only when a durable file is required"
+          "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 focused authoring contract, target capability, safe default template, themes, transforms, and optional source-based recommendations. Exact full template inputs remain on demand through describe_template or docblocks://authoring-guide.",
+      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(),
@@ -4751,17 +4529,14 @@ function registerTemplateTools(server, context) {
             goal,
             targetFormat: normalizedTarget,
             defaultTemplateId: "content",
-            defaultFidelity: authoringDefaultFidelity(normalizedTarget, goal),
+            defaultFidelity: authoringDefaultFidelity(normalizedTarget),
             workflow: [
               "For durable local output, call list_roots before drafting. If no returned root is write-enabled, stop and explain that the MCP server must restart with --allow-write; do not fall back to a shell or CLI converter. A transient artifact is acceptable only when the user did not require a file.",
-              "Treat supplied facts as a closed evidence set. Preserve them exactly; label calculations, assumptions, hypotheses, recommendations, causal claims, capabilities, owners, dates, and unsupplied operating details. When a requested policy or playbook needs invented procedures, introduce one proposed operating model scope note before those details.",
-              normalizedTarget === "pptx" ? "Match every explicitly requested slide count exactly. Use exactly one level-one Markdown heading (#) per slide and no level-two through level-six headings because every heading becomes a slide by default. Target at most 80 words per slide, and use lists, tables, or bold labels for within-slide structure." : "Honor the requested word range and document genre. Prefer connected memo prose for executive decisions and native headings, tables, and checklists for operational documents.",
-              "Author the complete Squisq-compatible Markdown with annotations bound to headings. Ordinary headings default to the loss-averse content template; keep that default until the complete content is sound.",
-              "Before conversion, count slide sections or document words, verify every requested element, and rewrite or label unsupported claims. For decisions, ground tradeoffs in supplied alternatives and label unsupplied accountability, capacity, outcomes, and review cadences as proposed or assumed.",
-              "Use validate_document as the routine export preflight and follow its repair diagnostics. Call inspect_document only when semantic structure, provenance, assets, metadata, or theme details are needed.",
-              "When the same complete draft will feed two or more validate, inspect, preview, or convert calls, stage it once with create_document_bundle and reuse its artifact URI; after edits, stage the revised draft again.",
-              normalizedTarget === "pptx" ? "For visual polish, call recommend_templates on the complete draft, then describe_template only for selected candidates before replacing content blocks. Preserve required content and use preview_document only when visual evidence is needed." : annotationHandling === "ignored" ? "This target flattens template annotations to semantic content, so visual templates have no effect on the exported file: rely on native headings, tables, and checklists for structure and scanning." : "For visual polish, use native headings, tables, and checklists where they improve scanning; describe a selected visual template before use and keep complete-body content when it would discard detail.",
-              "Pass the authoritative Markdown or bundle source directly to convert_document. It returns immutable artifacts; call save_artifact only for final durable outputs and never switch to a shell or CLI converter."
+              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]}",
@@ -4769,7 +4544,11 @@ function registerTemplateTools(server, context) {
               standaloneWarning: "A standalone annotation creates an additional heading-less block. Bind it to a heading unless that extra block is deliberate."
             },
             formats: normalizedTarget ? formats.filter((format) => format.id === normalizedTarget) : formats,
-            templates: focusedAuthoringTemplates(candidateTemplates, recommendations),
+            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),
@@ -4838,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,
@@ -4935,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({
@@ -5222,8 +5001,13 @@ function rootDiscoveryText(roots) {
 
 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) {
+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);
@@ -5237,14 +5021,15 @@ function compactAuthoringContextText(context) {
     `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(
@@ -5332,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";
   }
@@ -5663,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) => ({
@@ -5688,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) => ({
@@ -5713,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) => ({
@@ -5731,39 +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. For durable output, call list_roots before drafting. If no returned root is write-enabled, stop and explain that the MCP server must restart with --allow-write; do not use a shell or CLI converter.
-2. Call get_authoring_context with targetFormat "pptx" and goal "content-first" for the focused linked-Squisq workflow and safe default. Read the full authoring-guide resource only if focused follow-up tools are insufficient.
-3. Treat the topic facts as a closed evidence set. Preserve them exactly, use temporal or correlational wording unless causality is supplied, and label calculations, assumptions, hypotheses, recommendations, and examples. Causal links, rhetorical performance labels, superlatives, sole causes, capabilities, owners, dates, channels, and operational details must be supplied or explicitly framed. Do not connect separate metrics, audiences, segments, or workflows unless the relationship is supplied. Prefer observed, coincided with, intended to, or proposed over drove, addresses, protects, or proves. Add decision value through supplied baselines, goals, targets, rankings, and transparent calculations. Do not call choices a sequence or capacity allocation unless order, timing, or resources were supplied. When the requested content needs unsupplied operating details, add one proposed operating model scope note that applies to them.
-4. Match every explicitly requested slide count exactly. Use exactly one level-one Markdown heading (\`#\`) per slide and no level-two through level-six headings because every heading becomes a slide by default; use lists, tables, or bold labels within a slide. Target at most 80 words per slide. Make slide one a supported point-of-view thesis, not a generic title or unsupported flourish. For requested choices, state concrete opportunity costs grounded in supplied alternatives and one clearly labeled proposed accountable role per choice. Label any unsupplied capacity or outcome assumption as \`Assumption:\` or \`Potential tradeoff:\`. Author complete Markdown sections with accessible alt text. Put annotations on headings, for example \`# Heading {[content]}\`; a standalone \`{[template]}\` creates an extra block. Prefer style "${style ?? "choose from the returned transform styles"}", theme "${theme ?? "choose from the returned themes"}", and template "${template ?? "content until visual optimization"}".
-5. Keep the complete Markdown as the authoritative draft. If it will feed two or more validate, inspect, preview, or convert calls, stage it once with create_document_bundle and reuse the artifact URI. Otherwise pass it\u2014or a bundle source when assets are needed\u2014directly to convert_document. Do not write a temporary local Markdown file or invent a root id.
-6. Before conversion, count slide sections, verify every requested element, and rewrite or label every unsupported claim. Use validate_document as the routine export preflight; use inspect_document only for semantic or metadata detail and preview_document only for visual evidence such as overflow. Repair findings in the complete Markdown.
-7. Only after content coverage is acceptable, call recommend_templates, describe only selected candidates, and replace compatible \`content\` blocks when their semantic inputs fit. Preserve required content.
-8. Call convert_document with the complete source and a pptx target. Choose editable-native for editable Office structures, rendered-fidelity for exact Squisq visuals, or hybrid for rendered visuals plus semantic retention. Revise by editing the complete Markdown and converting again.
-9. Use get_conversion_report for provenance and save_artifact only when a durable file is required.`;
+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. For durable output, call list_roots before drafting and stop if no root is write-enabled; do not use a shell or CLI converter.
-2. Call get_authoring_context with targetFormat "mp4" for the focused linked-Squisq workflow.
-3. Author concise Markdown for a ${orientation ?? "landscape"} animated sequence using theme "${theme ?? "choose from the returned themes"}" and template "${template ?? "content until visual optimization"}". Bind annotations to headings.
-4. Keep the complete Markdown as the authoritative draft and pass it\u2014or a bundle source when assets are needed\u2014directly to convert_document. Use validate_document for uncertain target constraints and preview_document when representative-frame evidence is useful; repair findings in the complete Markdown.
-5. Call convert_document with the complete source, an mp4 target, and orientation "${orientation ?? "landscape"}"; monitor progress and honor cancellation. Revise by editing the complete Markdown and converting again.
-6. Use get_conversion_report for provenance and save_artifact only when a durable file is required.`;
+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. For durable output, call list_roots before drafting and stop if no root is write-enabled; do not use a shell or CLI converter.
-2. Call get_authoring_context with targetFormat "${target}" for the focused linked-Squisq workflow.
-3. Treat the topic facts as a closed evidence set. Preserve them exactly, use temporal or correlational wording unless causality is supplied, and label calculations, assumptions, hypotheses, recommendations, and examples. Causal links, superlatives, sole causes, capabilities, owners, dates, channels, and operational details must be supplied or explicitly framed. When the requested genre needs unsupplied roles, gates, timelines, channels, or procedures, add one proposed operating model scope note that applies to those details.
-4. Honor the requested word range and document genre. Author structured Markdown using theme "${theme ?? "choose from the returned themes"}" and template "${template ?? "content until visual optimization"}". Bind annotations to headings. Use connected memo prose for executive decisions and native headings, tables, and checklists for operational documents; retain complete-body content when a visual template would discard detail.
-5. Before conversion, count document words, verify every requested element, and rewrite or label every unsupported claim. If the complete draft will feed two or more review or conversion calls, stage it with create_document_bundle and reuse the artifact URI. Use validate_document as the routine export preflight and preview_document only when page-layout evidence is useful; repair findings in the complete Markdown.
-6. Call convert_document with the complete source and a ${target} target to create an immutable artifact. Revise by editing the complete Markdown and converting again.
-7. Use get_conversion_report for provenance and save_artifact only when a durable file is required.`;
+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 ?? "";
@@ -5807,13 +5589,11 @@ function createMcpServer(options = {}) {
     {
       instructions: [
         "For durable local output, call list_roots before drafting and use a returned write-enabled root id exactly as given. If none is writable, stop and explain that the server must restart with --allow-write; do not fall back to a shell or CLI converter.",
-        "Call get_authoring_context once for the focused linked-Squisq contract. Read the full authoring-guide resource or call describe_template only when exact additional catalog detail is needed; do not also enumerate catalogs by default.",
-        "Treat supplied facts as a closed evidence set: preserve them exactly, use temporal or correlational wording unless causality is supplied, and label calculations, assumptions, hypotheses, recommendations, capabilities, owners, dates, and unsupplied operating details. For a policy or playbook, introduce one proposed operating model scope note before invented procedures.",
-        "Honor explicit slide/page counts and word ranges. For PPTX use one level-one heading per slide, no lower-level headings, and at most 80 words per slide. Ground decision tradeoffs in supplied alternatives and label unsupplied accountability, capacity, outcomes, or review cadences as proposed or assumed.",
-        "Author complete Squisq-compatible Markdown with annotations on headings, for example `# Heading {[content]}`. Ordinary headings default to the loss-averse content template; standalone annotations create an extra heading-less block.",
-        "Use validate_document as the routine export preflight and repair its diagnostics. Use inspect_document only for semantic structure, provenance, assets, metadata, or theme details, and preview_document only when visual evidence is useful.",
-        "When the same complete draft will feed two or more validate, inspect, preview, or convert calls, stage it once with create_document_bundle and reuse its artifact URI instead of resending Markdown.",
-        "Pass the complete Markdown or bundle source directly into convert_document. Save only the final durable artifact with save_artifact; never invent root ids or switch conversion to a shell or CLI."
+        "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(" ")
     }
   );

package/dist/eval/cli.js

@@ -4,8 +4,8 @@ import { Command } from "commander";
 
 // src/eval/cases.ts
 var EVAL_PROMPT_PROFILES = Object.freeze({
-  baseline: `Use the DocBlocks MCP server for authoring, validation, conversion, and saving. Do not create the Office artifact with shell commands or another document library. Return the exact Squisq-flavored Markdown supplied to the final convert_document call.`,
-  "content-first": `Use the DocBlocks MCP server for the complete workflow. Start with get_authoring_context, author a lossless content-first draft, validate it, then use compatible visual templates selectively and preview before the final conversion. Repair actionable diagnostics. Do not create the Office artifact with shell commands or another document library. Return the exact Squisq-flavored Markdown supplied to the final convert_document call.`
+  baseline: `Use the DocBlocks MCP server for conversion and saving. Author Markdown and pass it directly to convert_document; no validation, inspection, preview, or authoring-context call is required. Do not create the Office artifact with shell commands or another document library. Return the exact Squisq-flavored Markdown supplied to the final convert_document call.`,
+  "content-first": `Use the DocBlocks MCP server for the complete workflow. Author the complete Markdown first and pass it directly to convert_document. Squisq annotations are optional layout hints; use get_authoring_context only when exact examples help, and use inspection or preview only when the brief explicitly requires that evidence. Do not create the Office artifact with shell commands or another document library. Return the exact Squisq-flavored Markdown supplied to the final convert_document call.`
 });
 var MCP_CONTENT_EVAL_CASES = Object.freeze([
   {
@@ -1190,7 +1190,7 @@ function collectToolMarkdown(value, candidates) {
   if (!isRecord2(value)) return;
   const toolName = [value.tool, value.name, value.tool_name].find((candidate) => typeof candidate === "string")?.toString();
   if (toolName) {
-    const priority = toolName.endsWith("convert_document") ? 3 : toolName.endsWith("create_document_bundle") ? 2 : toolName.endsWith("validate_document") ? 1 : 0;
+    const priority = toolName.endsWith("convert_document") ? 3 : toolName.endsWith("create_document_bundle") ? 2 : 0;
     if (priority > 0) {
       for (const args of [value.arguments, value.args, value.input]) {
         const parsed = parsePossibleJson(args);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bendyline/docblocks-cli",
-  "version": "2.2.2",
+  "version": "2.3.0",
   "description": "Build, preview, convert, render, inspect, and automate documents",
   "license": "MIT",
   "author": "Bendyline",
@@ -36,7 +36,7 @@
     "docblocks": "./dist/bin.js"
   },
   "engines": {
-    "node": ">=22.14.0"
+    "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
   },
   "files": [
     "dist",
@@ -47,12 +47,12 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@bendyline/docblocks": "2.2.2",
-    "@bendyline/squisq": "2.4.1",
-    "@bendyline/squisq-cli": "2.4.1",
-    "@bendyline/squisq-formats": "2.3.5",
-    "@bendyline/squisq-react": "2.4.1",
-    "@bendyline/squisq-video": "2.2.5",
+    "@bendyline/docblocks": "2.3.0",
+    "@bendyline/squisq": "2.4.3",
+    "@bendyline/squisq-cli": "2.4.3",
+    "@bendyline/squisq-formats": "2.3.7",
+    "@bendyline/squisq-react": "2.4.5",
+    "@bendyline/squisq-video": "2.2.7",
     "@modelcontextprotocol/sdk": "1.29.0",
     "commander": "13.1.0",
     "jszip": "3.10.1",