@nowline/mcp 0.8.6 → 0.10.0

package/dist/server.js

@@ -10,19 +10,22 @@ import * as path from 'node:path';
 import { getUiCapability, RESOURCE_MIME_TYPE, registerAppResource, registerAppTool, } from '@modelcontextprotocol/ext-apps/server';
 import { McpServer } from '@modelcontextprotocol/server';
 import { parseNowlineJson, printNowlineFile } from '@nowline/core';
-import { exportDocument, } from '@nowline/export';
+import { acceptStagedRoadmap, exportDocument, exportStaged, IncludeResolveError, } from '@nowline/export';
 import { resolveFonts } from '@nowline/export-core';
+import { NON_WORKING_DISPLAYS, THEME_NAMES } from '@nowline/layout';
 import { buildShareLink } from '@nowline/share-link';
 import { z } from 'zod';
 import { NOWLINE_MCP_ICONS } from './branding.js';
 import { CAPABILITIES } from './capabilities.js';
-import { buildDocument, collectMcpDiagnostics, collectMcpLayoutInsights, DEFAULT_RENDER_WIDTH, diagnosticsErrorBlock, handleToolError, InputRequiredError, LAYOUT_INSIGHT_HINT, PathOutsideRootError, REVIEW_MAX_WIDTH, toolDescriptionWithSyntax, } from './diagnostics.js';
+import { buildDocument, collectMcpDiagnostics, DEFAULT_RENDER_WIDTH, diagnosticsErrorBlock, diagnosticsErrorResponse, handleToolError, InputRequiredError, includeDiagnosticsResponse, LAYOUT_INSIGHT_HINT, layoutInsightsFromStage, PathOutsideRootError, REVIEW_MAX_WIDTH, routedResolveDiagnosticsToMcp, stageMcpRoadmap, stageRoutedDiagnostics, toolDescriptionWithSyntax, } from './diagnostics.js';
 import { CONVERSIONS_GUIDE, EXAMPLES, REFERENCE_MAN_PAGE, } from './generated/resources.js';
 import { PREVIEW_HTML } from './generated/ui-bundle.js';
+import { resolveMcpOptions } from './options.js';
 import { registerPrompts } from './prompts.js';
 import { REFERENCE_CHEATSHEET } from './reference-cheatsheet.js';
 import { SCHEMA_VOCABULARY } from './schema-vocab.js';
 import { CapabilitiesOutputSchema, ConvertOutputSchema, CreateOutputSchema, DeleteOutputSchema, ExamplesOutputSchema, ExportOutputSchema, ListItemsOutputSchema, ListOutputSchema, ReadOutputSchema, ReferenceOutputSchema, RenderOutputSchema, SchemaOutputSchema, ShareOutputSchema, UpdateOutputSchema, ValidateOutputSchema, } from './schemas.js';
+import { createWorkspaceRoots, isInsideRoots } from './workspace-roots.js';
 // ---- MCP Apps UI (in-chat live preview) -------------------------------------
 //
 // Official MCP Apps model (SEP-1865): a pre-declared ui:// resource serves
@@ -46,6 +49,18 @@ function clientSupportsAppsUi(server) {
     const buckets = [caps.extensions, caps.experimental].filter((bucket) => Boolean(bucket));
     return buckets.some((bucket) => Boolean(bucket[MCP_APPS_UI_CAPABILITY] || bucket.ui || bucket.apps));
 }
+/**
+ * The preview payload's now-line. An explicit `now` passes through. With only a
+ * `timezone`, the payload carries the date that zone resolved to: the preview
+ * draws an omitted `now` at the viewer's own date and cannot read the zone.
+ */
+function previewNow(args, today) {
+    if (args.now !== undefined)
+        return args.now;
+    if (args.timezone !== undefined && today)
+        return today.toISOString().slice(0, 10);
+    return undefined;
+}
 function leanPreviewBlock(payload) {
     return {
         type: 'text',
@@ -55,6 +70,7 @@ function leanPreviewBlock(payload) {
             theme: payload.theme,
             now: payload.now,
             width: payload.width,
+            nonWorking: payload.nonWorking,
             locale: payload.locale,
         }),
     };
@@ -77,11 +93,10 @@ function mutatingTool(title, opts) {
     };
 }
 // ---- Server factory ---------------------------------------------------------
-function resolveAndGuard(filePath, allowedRoot) {
-    const abs = path.resolve(allowedRoot, filePath);
-    const guard = path.resolve(allowedRoot);
-    if (!abs.startsWith(guard + path.sep) && abs !== guard) {
-        throw new PathOutsideRootError(filePath, allowedRoot);
+function resolveAndGuard(filePath, roots) {
+    const abs = path.resolve(roots.primary, filePath);
+    if (!isInsideRoots(abs, roots)) {
+        throw new PathOutsideRootError(filePath, roots.allowed.join(', '));
     }
     return abs;
 }
@@ -112,10 +127,6 @@ function createNodeHostEnv(sourcePath) {
     };
 }
 // ---- Helpers ----------------------------------------------------------------
-function todayUtc() {
-    const now = new Date();
-    return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
-}
 function exampleShortName(fullName) {
     return fullName.endsWith('.nowline') ? fullName.slice(0, -'.nowline'.length) : fullName;
 }
@@ -123,19 +134,18 @@ function findExample(name) {
     const withExt = name.endsWith('.nowline') ? name : `${name}.nowline`;
     return EXAMPLES.find((e) => e.name === withExt || e.name === name);
 }
-async function sourceAndPath(args, allowedRoot) {
+async function sourceAndPath(args, roots) {
     if (args.source !== undefined && args.path === undefined) {
-        return { source: args.source, filePath: path.join(allowedRoot, 'unnamed.nowline') };
+        return { source: args.source, filePath: path.join(roots.primary, 'unnamed.nowline') };
     }
     if (args.path !== undefined) {
-        const abs = resolveAndGuard(args.path, allowedRoot);
+        const abs = resolveAndGuard(args.path, roots);
         const source = args.source ?? (await fs.readFile(abs, 'utf-8'));
         return { source, filePath: abs };
     }
     throw new InputRequiredError('At least one of `source` or `path` is required.');
 }
 export function createMcpServer(opts = {}) {
-    const allowedRoot = opts.allowedRoot ?? process.cwd();
     const rootConfigured = opts.rootConfigured ?? false;
     const server = new McpServer({
         name: opts.name ?? 'nowline',
@@ -158,6 +168,7 @@ export function createMcpServer(opts = {}) {
             'Use the `share` tool only when the user explicitly wants a link they can open or share ' +
             '(opens the free Nowline web app, where they can also export).',
     });
+    const workspaceRoots = createWorkspaceRoots(server, opts.allowedRoot);
     // ---- Resources ----------------------------------------------------------
     server.registerResource('nowline-reference', 'nowline://reference', {
         title: 'Roadmap Reference',
@@ -206,6 +217,31 @@ export function createMcpServer(opts = {}) {
     }));
     // ---- Prompts ------------------------------------------------------------
     registerPrompts(server);
+    const nonWorkingSchema = z
+        .enum(NON_WORKING_DISPLAYS)
+        .optional()
+        .describe("How a business calendar's non-working days appear: hide collapses them, " +
+        "show draws them as shaded bands. Overrides the file's `default roadmap non-working:` key; " +
+        'omit to let the key apply (then hide). The schedule exports (mermaid, msproj, xlsx) are the same either way.');
+    // A string, not an enum, so `Greyscale` and the `greyscale` alias reach
+    // `resolveMcpOptions`, which rejects an unknown name with the theme list.
+    const themeSchema = z
+        .string()
+        .optional()
+        .describe(`Color theme: ${THEME_NAMES.join(', ')} ("greyscale" is accepted). Defaults to light.`);
+    const nowSchema = z
+        .string()
+        .regex(/^(\d{4}-\d{2}-\d{2}|-)$/, 'Expected YYYY-MM-DD or "-".')
+        .optional()
+        .describe("Now-line date as YYYY-MM-DD. Omit to draw it at today's date in `timezone` " +
+        "(the server's local zone when `timezone` is omitted too); " +
+        'pass "-" to suppress the now-line (same as the CLI\'s `--now -`).');
+    const timezoneSchema = z
+        .string()
+        .optional()
+        .describe("Timezone that decides today's date when `now` is omitted (ignored when `now` is a date): " +
+        '"local" (the default), "UTC", an ISO 8601 offset ("+05:30", "-07:00", "Z"), ' +
+        'or an IANA name ("America/Los_Angeles"). The same forms as the CLI\'s `--timezone`.');
     // ---- validate -----------------------------------------------------------
     server.registerTool('validate', {
         description: toolDescriptionWithSyntax('Parse and validate a .nowline roadmap. Returns ok=true with optional layout insights when valid, or ok=false with structured diagnostics.'),
@@ -215,25 +251,34 @@ export function createMcpServer(opts = {}) {
                 .string()
                 .optional()
                 .describe('Absolute or relative path to a .nowline file to validate.'),
+            now: nowSchema,
+            timezone: timezoneSchema,
         }),
         outputSchema: ValidateOutputSchema,
         annotations: readOnlyTool('Validate Roadmap'),
     }, async (args) => {
         try {
-            const { source, filePath } = await sourceAndPath(args, allowedRoot);
+            const { options } = resolveMcpOptions(args);
+            const { source, filePath } = await sourceAndPath(args, await workspaceRoots());
             const doc = await buildDocument(source);
             const diagnostics = collectMcpDiagnostics(doc, filePath);
-            const ok = diagnostics.every((d) => d.severity !== 'error');
-            const insights = ok
-                ? await collectMcpLayoutInsights({
-                    source,
-                    filePath,
-                    today: todayUtc(),
+            // One stage: the routed (wave-rule) include diagnostics join
+            // the validator's, with the file and line they point into
+            // (specs/waves.md §6.1), and the insights come from the same
+            // layout, logo included.
+            let insights = [];
+            if (diagnostics.every((d) => d.severity !== 'error')) {
+                const stage = await stageMcpRoadmap(doc, source, {
+                    sourcePath: filePath,
+                    today: options.today,
                     locale: 'en-US',
-                    readFile: createNodeHostEnv(filePath).readSource,
-                    doc,
-                })
-                : [];
+                    theme: 'light',
+                }, createNodeHostEnv(filePath));
+                diagnostics.push(...stageRoutedDiagnostics(stage));
+                if (stage.kind === 'staged')
+                    insights = layoutInsightsFromStage(stage);
+            }
+            const ok = diagnostics.every((d) => d.severity !== 'error');
             const structured = {
                 ok,
                 diagnostics,
@@ -265,7 +310,7 @@ export function createMcpServer(opts = {}) {
         annotations: readOnlyTool('Read Roadmap'),
     }, async (args) => {
         try {
-            const abs = resolveAndGuard(args.path, allowedRoot);
+            const abs = resolveAndGuard(args.path, await workspaceRoots());
             const source = await fs.readFile(abs, 'utf-8');
             const structured = { path: abs, source };
             return {
@@ -292,7 +337,7 @@ export function createMcpServer(opts = {}) {
         }),
     }, async (args) => {
         try {
-            const abs = resolveAndGuard(args.path, allowedRoot);
+            const abs = resolveAndGuard(args.path, await workspaceRoots());
             const blocked = await diagnosticsErrorBlock(args.source, abs);
             if (!blocked.ok)
                 return blocked.response;
@@ -324,7 +369,7 @@ export function createMcpServer(opts = {}) {
         }),
     }, async (args) => {
         try {
-            const abs = resolveAndGuard(args.path, allowedRoot);
+            const abs = resolveAndGuard(args.path, await workspaceRoots());
             const blocked = await diagnosticsErrorBlock(args.source, abs);
             if (!blocked.ok)
                 return blocked.response;
@@ -351,7 +396,7 @@ export function createMcpServer(opts = {}) {
         annotations: mutatingTool('Delete Roadmap', { destructiveHint: true }),
     }, async (args) => {
         try {
-            const abs = resolveAndGuard(args.path, allowedRoot);
+            const abs = resolveAndGuard(args.path, await workspaceRoots());
             await fs.unlink(abs);
             const structured = { path: abs };
             return {
@@ -370,7 +415,7 @@ export function createMcpServer(opts = {}) {
             directory: z
                 .string()
                 .optional()
-                .describe('Directory to scan. Defaults to the allowed root (cwd or --root). Absolute or relative.'),
+                .describe("Directory to scan. Defaults to the project root (--root, else the client's first MCP root, else cwd). Absolute or relative."),
             recursive: z
                 .boolean()
                 .optional()
@@ -380,9 +425,8 @@ export function createMcpServer(opts = {}) {
         annotations: readOnlyTool('List Roadmaps'),
     }, async (args) => {
         try {
-            const dir = args.directory
-                ? resolveAndGuard(args.directory, allowedRoot)
-                : allowedRoot;
+            const roots = await workspaceRoots();
+            const dir = args.directory ? resolveAndGuard(args.directory, roots) : roots.primary;
             const recursive = args.recursive ?? false;
             const paths = await listNowlineFiles(dir, recursive);
             const structured = { paths };
@@ -412,15 +456,14 @@ export function createMcpServer(opts = {}) {
                 .enum(['svg', 'png'])
                 .optional()
                 .describe('Output format. Defaults to svg.'),
-            theme: z
-                .enum(['light', 'dark', 'grayscale'])
-                .optional()
-                .describe('Color theme. Defaults to light.'),
-            now: z
-                .string()
+            theme: themeSchema,
+            now: nowSchema,
+            timezone: timezoneSchema,
+            width: z
+                .number()
                 .optional()
-                .describe('Now-line date as YYYY-MM-DD (UTC). Omit to suppress.'),
-            width: z.number().optional().describe('Canvas width in px.'),
+                .describe('Maximum canvas width in px, an integer of at least 320. Unset fits the content; a wider roadmap shrinks its timeline to fit.'),
+            nonWorking: nonWorkingSchema,
             scale: z
                 .number()
                 .optional()
@@ -451,10 +494,18 @@ export function createMcpServer(opts = {}) {
         // Only the filesystem touchpoints (reading the input, writing the
         // output) map to structured NL.MCP.* errors; a kernel render fault
         // bubbles unchanged so it is never mislabeled as a path/IO failure.
+        let resolved;
+        try {
+            resolved = resolveMcpOptions(args);
+        }
+        catch (err) {
+            return handleToolError(err);
+        }
+        const { theme, options } = resolved;
         let source;
         let filePath;
         try {
-            ({ source, filePath } = await sourceAndPath(args, allowedRoot));
+            ({ source, filePath } = await sourceAndPath(args, await workspaceRoots()));
         }
         catch (err) {
             return handleToolError(err, args.path);
@@ -463,13 +514,14 @@ export function createMcpServer(opts = {}) {
         if (!blocked.ok)
             return blocked.response;
         const format = args.format ?? 'svg';
-        const today = args.now ? new Date(`${args.now}T00:00:00Z`) : todayUtc();
+        const today = options.today;
         const inputs = {
             sourcePath: filePath,
             today,
             locale: 'en-US',
-            theme: args.theme ?? 'light',
-            width: args.width,
+            theme: options.theme,
+            width: options.width,
+            nonWorking: options.nonWorking,
             pngScale: args.scale,
         };
         const host = createNodeHostEnv(filePath);
@@ -482,34 +534,42 @@ export function createMcpServer(opts = {}) {
             const result = await resolveFonts({ headless: true });
             inputs.fonts = { sans: result.sans, mono: result.mono };
         }
-        const bytes = needsRender
-            ? await exportDocument(source, format, inputs, host)
+        // One stage serves the render, the insights and the include check.
+        const stage = await stageMcpRoadmap(blocked.doc, source, inputs, host);
+        if (stage.kind === 'invalid') {
+            return diagnosticsErrorResponse(filePath, collectMcpDiagnostics(blocked.doc, filePath));
+        }
+        // Wave-rule include errors are reported as diagnostics. An uncoded
+        // include error throws from a render, as the kernel's does; the
+        // preview path, which draws nothing here, keeps the preview it
+        // returned before waves existed (specs/waves.md §6.1).
+        const routed = stageRoutedDiagnostics(stage);
+        if (routed.some((d) => d.severity === 'error')) {
+            return includeDiagnosticsResponse(blocked.doc, filePath, routed);
+        }
+        if (stage.kind === 'include-error' && needsRender)
+            acceptStagedRoadmap(stage, inputs);
+        const staged = stage.kind === 'staged' ? stage : undefined;
+        const insights = staged ? layoutInsightsFromStage(staged) : [];
+        const bytes = needsRender && staged
+            ? await exportStaged(staged, format, inputs, host)
             : new Uint8Array(0);
-        const insights = await collectMcpLayoutInsights({
-            source,
-            filePath,
-            today,
-            theme: args.theme ?? 'light',
-            width: args.width,
-            locale: 'en-US',
-            readFile: host.readSource,
-            doc: blocked.doc,
-        });
         const previewPayload = {
             source,
-            theme: args.theme,
-            now: args.now,
-            width: args.width,
+            theme,
+            now: previewNow(args, options.today),
+            width: options.width,
+            nonWorking: options.nonWorking,
             locale: 'en-US',
         };
         const reviewBlocks = args.review === true
-            ? await buildReviewContentBlocks(source, format, bytes, inputs, host)
+            ? await buildReviewContentBlocks(blocked.doc, source, format, bytes, inputs, host)
             : [];
         const insightHintBlocks = insights.length > 0 ? [{ type: 'text', text: LAYOUT_INSIGHT_HINT }] : [];
         const insightsField = insights.length > 0 ? { insights } : {};
         if (args.output) {
             try {
-                const outAbs = resolveAndGuard(args.output, allowedRoot);
+                const outAbs = resolveAndGuard(args.output, await workspaceRoots());
                 await fs.mkdir(path.dirname(outAbs), { recursive: true });
                 await fs.writeFile(outAbs, bytes);
                 const structured = {
@@ -602,10 +662,15 @@ export function createMcpServer(opts = {}) {
                 'To choose a filename, pass a bare filename (e.g. "roadmap.pdf") — it is saved into the configured folder. ' +
                 'Never pass a virtual or sandbox path such as /home/claude/…, /mnt/user-data/…, or any path ' +
                 'outside the configured output folder — those do not exist on the host filesystem.'),
-            now: z.string().optional().describe('Now-line date as YYYY-MM-DD (UTC).'),
-            theme: z.enum(['light', 'dark', 'grayscale']).optional(),
+            now: nowSchema,
+            timezone: timezoneSchema,
+            theme: themeSchema,
+            nonWorking: nonWorkingSchema,
             scale: z.number().optional().describe('PNG scale factor.'),
-            pageSize: z.string().optional().describe('PDF page size.'),
+            pageSize: z
+                .string()
+                .optional()
+                .describe('PDF page size: a preset name, "content", or <W>x<H><unit> (e.g. 8.5x11in). Validated for every format.'),
             orientation: z
                 .enum(['portrait', 'landscape', 'auto'])
                 .optional()
@@ -631,10 +696,17 @@ export function createMcpServer(opts = {}) {
         // Only the filesystem touchpoints (reading the input, writing the
         // output) map to structured NL.MCP.* errors; a kernel export fault
         // bubbles unchanged so it is never mislabeled as a path/IO failure.
+        let options;
+        try {
+            ({ options } = resolveMcpOptions(args));
+        }
+        catch (err) {
+            return handleToolError(err);
+        }
         let source;
         let filePath;
         try {
-            ({ source, filePath } = await sourceAndPath(args, allowedRoot));
+            ({ source, filePath } = await sourceAndPath(args, await workspaceRoots()));
         }
         catch (err) {
             return handleToolError(err, args.path);
@@ -643,14 +715,14 @@ export function createMcpServer(opts = {}) {
         if (!blocked.ok)
             return blocked.response;
         const format = args.format;
-        const today = args.now ? new Date(`${args.now}T00:00:00Z`) : todayUtc();
         const inputs = {
             sourcePath: filePath,
-            today,
+            today: options.today,
             locale: 'en-US',
-            theme: args.theme ?? 'light',
+            theme: options.theme,
+            nonWorking: options.nonWorking,
             pngScale: args.scale,
-            pageSize: args.pageSize,
+            pageSize: options.pageSize,
             orientation: args.orientation,
             marginPt: args.marginPt,
             msprojStart: args.msprojStart,
@@ -660,7 +732,16 @@ export function createMcpServer(opts = {}) {
             inputs.fonts = { sans: result.sans, mono: result.mono };
         }
         const host = createNodeHostEnv(filePath);
-        const bytes = await exportDocument(source, format, inputs, host);
+        let bytes;
+        try {
+            const staged = acceptStagedRoadmap(await stageMcpRoadmap(blocked.doc, source, inputs, host), inputs);
+            bytes = await exportStaged(staged, format, inputs, host);
+        }
+        catch (err) {
+            if (!(err instanceof IncludeResolveError))
+                throw err;
+            return includeDiagnosticsResponse(blocked.doc, filePath, routedResolveDiagnosticsToMcp(err.diagnostics));
+        }
         const BINARY_FORMATS = new Set(['png', 'pdf', 'xlsx']);
         const isBinary = BINARY_FORMATS.has(format);
         // Default filename: <roadmap-id>.<ext>, used when no output path is given.
@@ -713,11 +794,12 @@ export function createMcpServer(opts = {}) {
             }
         }
         // Write to disk if needed.
-        const outTarget = args.output ?? path.join(allowedRoot, defaultFilename);
+        const roots = await workspaceRoots();
+        const outTarget = args.output ?? path.join(roots.primary, defaultFilename);
         let writtenPath;
         if (doWrite) {
             try {
-                const outAbs = resolveAndGuard(outTarget, allowedRoot);
+                const outAbs = resolveAndGuard(outTarget, roots);
                 await fs.mkdir(path.dirname(outAbs), { recursive: true });
                 await fs.writeFile(outAbs, bytes);
                 writtenPath = outAbs;
@@ -785,7 +867,7 @@ export function createMcpServer(opts = {}) {
         let source;
         let filePath;
         try {
-            ({ source, filePath } = await sourceAndPath(args, allowedRoot));
+            ({ source, filePath } = await sourceAndPath(args, await workspaceRoots()));
         }
         catch (err) {
             return handleToolError(err, args.path);
@@ -822,11 +904,14 @@ export function createMcpServer(opts = {}) {
     }, async (args) => {
         try {
             if (args.to === 'json') {
-                const { source, filePath } = await sourceAndPath(args, allowedRoot);
+                const { source, filePath } = await sourceAndPath(args, await workspaceRoots());
                 const host = createNodeHostEnv(filePath);
+                // The JSON AST does not depend on today's date, so convert
+                // takes no `now`; the kernel still wants a concrete one.
+                const { options } = resolveMcpOptions({});
                 const jsonBytes = await exportDocument(source, 'json', {
                     sourcePath: filePath,
-                    today: todayUtc(),
+                    today: options.today,
                     locale: 'en-US',
                     theme: 'light',
                 }, host);
@@ -840,7 +925,7 @@ export function createMcpServer(opts = {}) {
             // to: 'nowline' — input is a JSON AST string
             const jsonSource = args.source ??
                 (args.path
-                    ? await fs.readFile(resolveAndGuard(args.path, allowedRoot), 'utf-8')
+                    ? await fs.readFile(resolveAndGuard(args.path, await workspaceRoots()), 'utf-8')
                     : null);
             if (!jsonSource) {
                 throw new InputRequiredError('At least one of `source` or `path` is required.');
@@ -878,7 +963,7 @@ export function createMcpServer(opts = {}) {
     });
     // ---- list-themes --------------------------------------------------------
     server.registerTool('list-themes', {
-        description: 'List supported color themes: light, dark, grayscale.',
+        description: `List supported color themes: ${THEME_NAMES.join(', ')}.`,
         inputSchema: z.object({}),
         outputSchema: ListItemsOutputSchema,
         annotations: readOnlyTool('List Themes'),
@@ -1012,7 +1097,7 @@ export function createMcpServer(opts = {}) {
         };
     });
     server.registerTool('schema', {
-        description: 'Return the structured Nowline DSL key vocabulary (directive keys, entity types, item properties).',
+        description: 'Return the structured Nowline DSL key vocabulary (directive keys, entity types, item properties, config keywords, calendar declaration keys).',
         inputSchema: z.object({}),
         outputSchema: SchemaOutputSchema,
         annotations: readOnlyTool('View Roadmap Schema'),
@@ -1021,6 +1106,8 @@ export function createMcpServer(opts = {}) {
             directiveKeys: [...SCHEMA_VOCABULARY.directiveKeys],
             entityTypes: [...SCHEMA_VOCABULARY.entityTypes],
             itemPropertyKeys: [...SCHEMA_VOCABULARY.itemPropertyKeys],
+            configKeywords: [...SCHEMA_VOCABULARY.configKeywords],
+            calendarDeclarationKeys: [...SCHEMA_VOCABULARY.calendarDeclarationKeys],
         };
         return {
             content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
@@ -1068,7 +1155,7 @@ function buildExportInlineContentBlocks(format, bytes, showHint = true, rootConf
     }
     return blocks;
 }
-async function buildReviewContentBlocks(source, format, artifactBytes, inputs, host) {
+async function buildReviewContentBlocks(doc, source, format, artifactBytes, inputs, host) {
     const blocks = [
         {
             type: 'text',
@@ -1091,7 +1178,10 @@ async function buildReviewContentBlocks(source, format, artifactBytes, inputs, h
             const fonts = await resolveFonts({ headless: true });
             reviewInputs.fonts = { sans: fonts.sans, mono: fonts.mono };
         }
-        inspectionBytes = await exportDocument(source, 'png', reviewInputs, host);
+        // A narrower review width is a different layout, so it stages again
+        // (the parsed document is reused).
+        const reviewStage = acceptStagedRoadmap(await stageMcpRoadmap(doc, source, reviewInputs, host), reviewInputs);
+        inspectionBytes = await exportStaged(reviewStage, 'png', reviewInputs, host);
     }
     if (format !== 'png' || inspectionBytes.byteLength !== artifactBytes.byteLength) {
         blocks.push({