@bendyline/docblocks-cli 2.3.2 → 2.3.4

package/README.md

@@ -69,12 +69,18 @@ For durable output, call `list_roots` before drafting. If no root is write-enabl
 restart the server with `--allow-write`; do not bypass MCP with the direct `convert`
 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
+and explicit Squisq annotations remain optional overrides. For PPTX, a level-one
+heading creates each deliberate slide boundary by itself; do not add `---` between
+slide headings unless a visible horizontal rule is intended. `get_authoring_context`
+is optional discovery for exact annotation examples, safe defaults, and semantically
+described theme/Summarize choices. MCP guidance tells agents to infer and choose a
+style from the brief rather than presenting raw IDs, asking one compact high-level
+question only when the choice is materially ambiguous. 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;
+import-capable linked-registry formats. `build`/`serve` standalone HTML includes
+Copy controls for ordinary fenced code blocks; Mermaid fences remain diagrams. `build` replaces generated HTML files;
 `convert` and `video` refuse existing destinations unless `--allow-overwrite` is
 passed. Multi-target conversion stages the complete batch and rolls back replacements
 if publication fails. Build traversal, input bytes, and output bytes are bounded, as

package/THIRD_PARTY_NOTICES.txt

@@ -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.4 | MIT | https://github.com/bendyline/squisq |
-| @bendyline/squisq-cli | 2.4.5 | MIT | https://github.com/bendyline/squisq |
-| @bendyline/squisq-formats | 2.3.9 | MIT | https://github.com/bendyline/squisq |
-| @bendyline/squisq-react | 2.4.7 | MIT | https://github.com/bendyline/squisq |
-| @bendyline/squisq-video | 2.2.8 | MIT | https://github.com/bendyline/squisq |
+| @bendyline/squisq | 2.7.0 | MIT | https://github.com/bendyline/squisq |
+| @bendyline/squisq-cli | 2.5.2 | MIT | https://github.com/bendyline/squisq |
+| @bendyline/squisq-formats | 2.4.1 | MIT | https://github.com/bendyline/squisq |
+| @bendyline/squisq-react | 2.7.0 | MIT | https://github.com/bendyline/squisq |
+| @bendyline/squisq-video | 2.2.11 | 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 |
@@ -403,7 +403,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
 ==============================================================================
-Components: @bendyline/squisq-cli@2.4.5, @bendyline/squisq-formats@2.3.9, @bendyline/squisq-react@2.4.7, @bendyline/squisq-video@2.2.8, @bendyline/squisq@2.4.4
+Components: @bendyline/squisq-cli@2.5.2, @bendyline/squisq-formats@2.4.1, @bendyline/squisq-react@2.7.0, @bendyline/squisq-video@2.2.11, @bendyline/squisq@2.7.0
 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
@@ -673,7 +673,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.5
+Components: @bendyline/squisq-cli@2.5.2
 Source files: node_modules/@bendyline/squisq-cli/NOTICE.md
 ==============================================================================
 # Third-Party Notices for @bendyline/squisq-cli
@@ -693,7 +693,7 @@ Copyright and complete license texts for these dependencies are included in
 their respective npm distributions and source repositories.
 
 ==============================================================================
-Components: @bendyline/squisq-cli@2.4.5
+Components: @bendyline/squisq-cli@2.5.2
 Source files: node_modules/@bendyline/squisq-cli/THIRD_PARTY_LICENSES.txt
 ==============================================================================
 THIRD-PARTY LICENSES FOR @bendyline/squisq-cli
@@ -5181,7 +5181,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.9
+Components: @bendyline/squisq-formats@2.4.1
 Source files: node_modules/@bendyline/squisq-formats/NOTICE.md
 ==============================================================================
 # Third-Party Notices for @bendyline/squisq-formats
@@ -5206,7 +5206,7 @@ texts for these dependencies are included in their respective npm
 distributions and source repositories.
 
 ==============================================================================
-Components: @bendyline/squisq-formats@2.3.9
+Components: @bendyline/squisq-formats@2.4.1
 Source files: node_modules/@bendyline/squisq-formats/THIRD_PARTY_LICENSES.txt
 ==============================================================================
 THIRD-PARTY LICENSES FOR @bendyline/squisq-formats
@@ -5388,7 +5388,7 @@ 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.7
+Components: @bendyline/squisq-react@2.7.0
 Source files: node_modules/@bendyline/squisq-react/NOTICE.md
 ==============================================================================
 # Third-Party Notices for @bendyline/squisq-react
@@ -5413,7 +5413,7 @@ third-party license texts for the complete standalone bundle graph are shipped
 in THIRD_PARTY_LICENSES.txt.
 
 ==============================================================================
-Components: @bendyline/squisq-react@2.4.7
+Components: @bendyline/squisq-react@2.7.0
 Source files: node_modules/@bendyline/squisq-react/THIRD_PARTY_LICENSES.txt
 ==============================================================================
 THIRD-PARTY LICENSES FOR @bendyline/squisq-react
@@ -9950,7 +9950,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
 ==============================================================================
-Components: @bendyline/squisq-video@2.2.8
+Components: @bendyline/squisq-video@2.2.11
 Source files: node_modules/@bendyline/squisq-video/NOTICE.md
 ==============================================================================
 # Third-Party Notices for @bendyline/squisq-video
@@ -9975,7 +9975,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.8
+Components: @bendyline/squisq-video@2.2.11
 Source files: node_modules/@bendyline/squisq-video/THIRD_PARTY_LICENSES.txt
 ==============================================================================
 THIRD-PARTY LICENSES FOR @bendyline/squisq-video
@@ -9987,7 +9987,7 @@ repository license, the pinned upstream copy is vendored and identified below.
 COMPONENTS
 
 ==============================================================================
-Components: @bendyline/squisq@2.4.4
+Components: @bendyline/squisq@2.7.0
 Source files: node_modules/@bendyline/squisq/NOTICE.md
 ==============================================================================
 # Third-Party Notices for @bendyline/squisq
@@ -10018,7 +10018,7 @@ third-party license texts for bundled code and data are shipped in
 THIRD_PARTY_LICENSES.txt.
 
 ==============================================================================
-Components: @bendyline/squisq@2.4.4
+Components: @bendyline/squisq@2.7.0
 Source files: node_modules/@bendyline/squisq/THIRD_PARTY_LICENSES.txt
 ==============================================================================
 THIRD-PARTY LICENSES FOR @bendyline/squisq

package/dist/bin.js

@@ -1398,6 +1398,13 @@ function warningDiagnostic(message, stage, format = null) {
 }
 function classifyWarning(message, format) {
   const normalized = message.toLowerCase();
+  if (normalized.includes("redundant thematic break")) {
+    return {
+      code: "redundant-slide-separator",
+      count: warningCount(message, /removed\s+(\d+)\s+redundant thematic break/iu),
+      remediation: "Remove --- between slide headings because heading-based slide breaks already create the boundaries. Keep --- only for an intentional visible horizontal rule within a slide."
+    };
+  }
   if (normalized.includes("unsupported markdown node")) {
     return {
       code: "unsupported-markdown-node",
@@ -3217,7 +3224,16 @@ Placeholder`).join("\n\n");
   const converted = await convert(
     { kind: "markdown", markdown: scaffold, baseName: "rendered" },
     "pptx",
-    { ...title === void 0 ? {} : { title }, signal }
+    {
+      ...title === void 0 ? {} : { title },
+      signal,
+      // The scaffold is a throwaway 1:1 frame->slide vehicle whose slides are
+      // all overwritten below with captured images. Squisq's cover slide is on
+      // by default; here it would prepend a slide built from the placeholder
+      // text, shifting every frame by one and leaving the last scaffold slide
+      // un-overwritten as a visible "Rendered slide N / Placeholder" page.
+      formatOptions: { pptx: { includeCoverSlide: false } }
+    }
   );
   throwIfAborted5(signal);
   const archive = await JSZip.loadAsync(converted.bytes);
@@ -4037,6 +4053,17 @@ var init_progress = __esm({
   }
 });
 
+// src/mcp/style-guidance.ts
+var STYLE_SELECTION_GUIDANCE, TRANSFORM_SELECTION_GUIDANCE, MOTION_SELECTION_GUIDANCE;
+var init_style_guidance = __esm({
+  "src/mcp/style-guidance.ts"() {
+    "use strict";
+    STYLE_SELECTION_GUIDANCE = 'Choose theme and Squisq Summarize/transform style automatically from the user brief, audience, tone, content shape, brand constraints, and accessibility needs. Do not present raw theme/transform ids to the user or ask separate theme, summarization, animation, and template questions. If the choice is materially ambiguous and interactive clarification is available, ask one concise high-level preference question with at most four semantic directions plus a "choose for me" option; otherwise use safe defaults and proceed.';
+    TRANSFORM_SELECTION_GUIDANCE = "Treat transformId as the Squisq Summarize control: it can change content emphasis, density, pacing, and structure. For an existing source whose exact language or coverage matters, leave transformId unset unless the user requests or permits summarization or visual restructuring. When transformId is selected and the user did not request an exact theme, omit themeId so Squisq can apply that transform style's preferred compatible theme.";
+    MOTION_SELECTION_GUIDANCE = "Treat motion as a high-level none, subtle, or dynamic preference instead of listing individual transitions. Themes provide motion defaults; use animationsEnabled only to honor an explicit MP4 or GIF motion preference.";
+  }
+});
+
 // src/mcp/agentic-tools.ts
 import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
@@ -4099,12 +4126,16 @@ function registerAgenticTools(server, context) {
   server.registerTool(
     "convert_document",
     {
-      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.",
+      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. For PPTX, heading-based slide boundaries do not need --- separators. 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(),
+        themeId: identifierSchema.optional().describe(
+          "Exact Squisq theme id. Infer it from the brief when the visual direction is clear. If transformId is set and no exact theme was requested, omit themeId so the transform can apply its preferred compatible theme."
+        ),
+        transformId: identifierSchema.optional().describe(
+          "Optional Squisq Summarize style id. It can change content emphasis, density, pacing, and structure; leave it unset for source-preserving work unless summarization or visual restructuring is requested or permitted."
+        ),
         autoTemplates: z.boolean().optional().describe(
           "Enable content-aware automatic template selection. Defaults to true; explicit annotations still take precedence."
         ),
@@ -4135,8 +4166,10 @@ function registerAgenticTools(server, context) {
           );
           for (const result of results) requireWire(parseConversionResult2(result), "conversion");
           const payload = { results };
+          const warningSummary = conversionWarningSummary(results);
           return {
             content: [
+              ...warningSummary ? [{ type: "text", text: warningSummary }] : [],
               { type: "text", text: JSON.stringify(payload) },
               ...results.map((result) => artifactLink(result.artifact))
             ],
@@ -4410,11 +4443,14 @@ function registerAuthoringGuideResource(server) {
         import("@bendyline/squisq/transform")
       ]);
       const guide = {
-        version: 8,
+        version: 10,
         workflow: [
           "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",
+          "for deliberate PPTX slide boundaries, use one level-one Markdown heading per slide; headings alone create the boundaries, so do not add --- between them unless a visible horizontal rule is intended",
           "convert_document chooses compatible templates automatically; Squisq annotations on headings are optional layout hints that take precedence",
+          STYLE_SELECTION_GUIDANCE,
+          TRANSFORM_SELECTION_GUIDANCE,
+          MOTION_SELECTION_GUIDANCE,
           "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"
@@ -4458,7 +4494,7 @@ function registerTemplateTools(server, context) {
   server.registerTool(
     "get_authoring_context",
     {
-      description: "Optionally discover target capabilities, safe defaults, themes, transforms, and exact starter annotation examples. Plain Markdown can be converted without calling this tool.",
+      description: "Optionally discover target capabilities, safe defaults, semantically described themes and Squisq Summarize styles, and exact starter annotation examples. Use these descriptions to choose for the user rather than presenting raw ids. Plain Markdown can be converted without calling this tool.",
       inputSchema: z.object({
         targetFormat: formatInputSchema.optional(),
         goal: z.enum(["content-first", "visual-polish"]).optional(),
@@ -4532,7 +4568,10 @@ function registerTemplateTools(server, context) {
             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.",
-              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.",
+              normalizedTarget === "pptx" ? "Plain text and ordinary Markdown convert directly. Use one level-one Markdown heading (#) for each deliberate slide boundary. Headings alone create the boundaries, so do not add --- between them unless a visible horizontal rule is intended; unstructured text is still accepted." : "Plain text and ordinary Markdown convert directly without a preflight.",
+              STYLE_SELECTION_GUIDANCE,
+              TRANSFORM_SELECTION_GUIDANCE,
+              ...normalizedTarget === "pptx" || normalizedTarget === "html" || normalizedTarget === "htmlzip" || normalizedTarget === "mp4" || normalizedTarget === "gif" ? [MOTION_SELECTION_GUIDANCE] : [],
               "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.",
@@ -4982,6 +5021,29 @@ function artifactLink(artifact) {
     size: artifact.size
   };
 }
+function conversionWarningSummary(results) {
+  const warnings = results.flatMap(
+    (result) => result.diagnostics.filter((diagnostic) => diagnostic.severity === "warning").map((diagnostic) => ({ format: result.targetFormat, diagnostic }))
+  );
+  if (warnings.length === 0) return null;
+  const totalOccurrences = warnings.reduce((total, { diagnostic }) => total + diagnostic.count, 0);
+  const visible = warnings.slice(0, 10);
+  const lines = [
+    `Conversion warnings: ${totalOccurrences} occurrence(s) across ${warnings.length} diagnostic(s).`,
+    ...visible.map(({ format, diagnostic }) => {
+      const count = diagnostic.count > 1 ? ` x${diagnostic.count}` : "";
+      const remediation = diagnostic.remediation ? ` Remediation: ${diagnostic.remediation}` : "";
+      return `- [${diagnostic.code}] ${format}${count}: ${diagnostic.message}${remediation}`;
+    })
+  ];
+  if (visible.length < warnings.length) {
+    lines.push(
+      `- ${warnings.length - visible.length} additional diagnostic(s) remain in structuredContent.`
+    );
+  }
+  lines.push("The complete JSON result follows in the next text content item.");
+  return lines.join("\n");
+}
 async function sendProgress(extra, progress, total, message) {
   await reportMcpProgress(extra, progress, total, message);
 }
@@ -5028,8 +5090,16 @@ function compactAuthoringContextText(context) {
     `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(", ")}.`
+    "",
+    `Theme choices with descriptions (${context.themes.length}):`,
+    ...context.themes.map(
+      ({ id, name, description }) => `- ${id} (${name}): ${description ?? "No additional description."}`
+    ),
+    "",
+    `Squisq Summarize choices for transformId (${context.transformStyles.length}):`,
+    ...context.transformStyles.map(
+      ({ id, name, description }) => `- ${id} (${name}): ${description}`
+    )
   ];
   if (context.recommendations.length > 0) {
     lines.push(
@@ -5152,6 +5222,7 @@ var init_agentic_tools = __esm({
     init_error_result();
     init_progress();
     init_output_bounds();
+    init_style_guidance();
     READ_ONLY = {
       readOnlyHint: true,
       destructiveHint: false,
@@ -5207,7 +5278,9 @@ var init_agentic_tools = __esm({
         format: z.literal("pptx"),
         fidelity: fidelitySchemas.pptx.optional(),
         ...metadataFields,
-        slideBreak: z.enum(["h1", "h2", "heading"]).optional(),
+        slideBreak: z.enum(["h1", "h2", "heading"]).optional().describe(
+          "Heading depths that start slides. Headings alone create slide boundaries; do not add --- between them unless a visible horizontal rule is intended."
+        ),
         defaultFont: z.string().max(256).optional(),
         defaultFontSize: z.number().min(6).max(96).optional(),
         width: z.number().int().min(160).max(1920).optional(),
@@ -5257,7 +5330,9 @@ var init_agentic_tools = __esm({
         height: z.number().int().min(16).max(3840).optional(),
         captionStyle: z.enum(["standard", "social"]).optional(),
         coverPreRoll: z.number().min(0).max(60).optional(),
-        animationsEnabled: z.boolean().optional()
+        animationsEnabled: z.boolean().optional().describe(
+          "Explicit rendered-media motion switch. Use it only to honor a user preference such as no motion or dynamic motion; otherwise rely on the theme/target default. It does not select an individual transition."
+        )
       }).strict(),
       z.object({
         format: z.literal("gif"),
@@ -5268,7 +5343,9 @@ var init_agentic_tools = __esm({
         height: z.number().int().min(16).max(1920).optional(),
         captionStyle: z.enum(["standard", "social"]).optional(),
         coverPreRoll: z.number().min(0).max(60).optional(),
-        animationsEnabled: z.boolean().optional(),
+        animationsEnabled: z.boolean().optional().describe(
+          "Explicit rendered-media motion switch. Use it only to honor a user preference such as no motion or dynamic motion; otherwise rely on the theme/target default. It does not select an individual transition."
+        ),
         loop: z.number().int().min(-1).max(65535).optional(),
         maxColors: z.number().int().min(2).max(256).optional(),
         dither: z.enum(["none", "bayer", "heckbert", "floyd_steinberg", "sierra2", "sierra2_4a"]).optional(),
@@ -5416,14 +5493,18 @@ import { completable } from "@modelcontextprotocol/sdk/server/completable.js";
 import { z as z3 } from "zod";
 function registerAuthoringPrompts(server) {
   const style = completable(
-    z3.string().max(MAX_ID_CHARACTERS).optional().describe("Preferred transform style id."),
+    z3.string().max(MAX_ID_CHARACTERS).optional().describe(
+      "Optional exact Squisq Summarize/transform style id. Usually let the model infer this from the brief."
+    ),
     async (prefix) => {
       const { getTransformStyleIds } = await import("@bendyline/squisq/transform");
       return complete(getTransformStyleIds(), prefix);
     }
   );
   const theme = completable(
-    z3.string().max(MAX_ID_CHARACTERS).optional().describe("Preferred Squisq theme id."),
+    z3.string().max(MAX_ID_CHARACTERS).optional().describe(
+      "Optional exact Squisq theme id. Usually let the model infer this from the brief or the selected transform."
+    ),
     async (prefix) => {
       const { getAvailableThemes } = await import("@bendyline/squisq/schemas");
       return complete(getAvailableThemes(), prefix);
@@ -5516,13 +5597,15 @@ 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}\`` : "";
+  const selectionHint = style || theme ? `Honor the caller-supplied ${style ? `transform style \`${style}\`` : ""}${style && theme ? " and " : ""}${theme ? `theme \`${theme}\`` : ""}; do not ask for another style choice.${style && !theme ? " Because no exact theme was requested, omit themeId so Squisq can apply the transform style's preferred compatible theme." : ""}` : `${STYLE_SELECTION_GUIDANCE} ${TRANSFORM_SELECTION_GUIDANCE}`;
   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. 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.`;
+2. ${selectionHint} ${MOTION_SELECTION_GUIDANCE} Call get_authoring_context only when the linked theme and Summarize descriptions would materially improve the choice.
+3. Author plain Markdown. One level-one heading (\`#\`) creates each deliberate slide boundary; headings alone create the boundaries, so do not add \`---\` between them unless a visible horizontal rule is intended. Unstructured text is also accepted. Squisq annotations are optional layout hints.${templateHint}
+4. 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.
+5. Use inspect_document or preview_document only when the user explicitly asks for document analysis or visual evidence.
+6. 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.` : "";
@@ -5555,6 +5638,7 @@ var MAX_ID_CHARACTERS, MAX_TOPIC_CHARACTERS;
 var init_prompts = __esm({
   "src/mcp/prompts.ts"() {
     "use strict";
+    init_style_guidance();
     MAX_ID_CHARACTERS = 256;
     MAX_TOPIC_CHARACTERS = 1e4;
   }
@@ -5589,8 +5673,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.",
-        "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.",
+        "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. Headings alone create slide boundaries; do not add --- between them unless a visible horizontal rule is intended.",
         "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.",
+        STYLE_SELECTION_GUIDANCE,
+        TRANSFORM_SELECTION_GUIDANCE,
+        MOTION_SELECTION_GUIDANCE,
         "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."
@@ -5662,6 +5749,7 @@ var init_server = __esm({
     init_authority();
     init_discovery_tools();
     init_prompts();
+    init_style_guidance();
     DEFAULT_MAX_CONCURRENT_OPERATIONS = 2;
     DEFAULT_OPERATION_TIMEOUT_MS = 2 * 60 * 1e3;
     DEFAULT_SHUTDOWN_DRAIN_TIMEOUT_MS = 5e3;
@@ -5877,7 +5965,8 @@ async function renderMarkdownHtml(markdown, options) {
     images,
     title: options.title,
     mode: options.mode ?? "static",
-    themeId: options.themeId
+    themeId: options.themeId,
+    showCodeCopyButton: true
   });
 }
 async function readReferencedImages(doc, sourcePath, assetRoot, maxAssetBytes, allowReferencedAsset, warn) {

package/dist/index.js

@@ -138,7 +138,8 @@ async function renderMarkdownHtml(markdown, options) {
     images,
     title: options.title,
     mode: options.mode ?? "static",
-    themeId: options.themeId
+    themeId: options.themeId,
+    showCodeCopyButton: true
   });
 }
 async function readReferencedImages(doc, sourcePath, assetRoot, maxAssetBytes, allowReferencedAsset, warn) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bendyline/docblocks-cli",
-  "version": "2.3.2",
+  "version": "2.3.4",
   "description": "Build, preview, convert, render, inspect, and automate documents",
   "license": "MIT",
   "author": "Bendyline",
@@ -47,12 +47,12 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@bendyline/docblocks": "2.3.2",
-    "@bendyline/squisq": "2.5.0",
-    "@bendyline/squisq-cli": "2.5.0",
-    "@bendyline/squisq-formats": "2.3.10",
-    "@bendyline/squisq-react": "2.5.0",
-    "@bendyline/squisq-video": "2.2.9",
+    "@bendyline/docblocks": "2.3.4",
+    "@bendyline/squisq": "2.7.1",
+    "@bendyline/squisq-cli": "2.5.3",
+    "@bendyline/squisq-formats": "2.4.2",
+    "@bendyline/squisq-react": "2.7.1",
+    "@bendyline/squisq-video": "2.2.12",
     "@modelcontextprotocol/sdk": "1.29.0",
     "commander": "13.1.0",
     "jszip": "3.10.1",