@nowline/mcp 0.8.6 → 0.10.0

package/src/server.ts

@@ -15,14 +15,19 @@ import {
     registerAppTool,
 } from '@modelcontextprotocol/ext-apps/server';
 import { McpServer } from '@modelcontextprotocol/server';
+import type { SurfaceOptions } from '@nowline/config';
 import { type NowlineFile, parseNowlineJson, printNowlineFile } from '@nowline/core';
 import {
+    acceptStagedRoadmap,
     type ExportFormat,
     exportDocument,
+    exportStaged,
     type HostEnv,
+    IncludeResolveError,
     type RenderInputs,
 } 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';
@@ -30,14 +35,20 @@ import { CAPABILITIES } from './capabilities.js';
 import {
     buildDocument,
     collectMcpDiagnostics,
-    collectMcpLayoutInsights,
     DEFAULT_RENDER_WIDTH,
     diagnosticsErrorBlock,
+    diagnosticsErrorResponse,
     handleToolError,
     InputRequiredError,
+    includeDiagnosticsResponse,
     LAYOUT_INSIGHT_HINT,
+    layoutInsightsFromStage,
+    type McpInsight,
     PathOutsideRootError,
     REVIEW_MAX_WIDTH,
+    routedResolveDiagnosticsToMcp,
+    stageMcpRoadmap,
+    stageRoutedDiagnostics,
     toolDescriptionWithSyntax,
 } from './diagnostics.js';
 import {
@@ -47,6 +58,7 @@ import {
     REFERENCE_MAN_PAGE,
 } from './generated/resources.js';
 import { PREVIEW_HTML } from './generated/ui-bundle.js';
+import { type McpResolvedOptions, resolveMcpOptions } from './options.js';
 import { registerPrompts } from './prompts.js';
 import { REFERENCE_CHEATSHEET } from './reference-cheatsheet.js';
 import { SCHEMA_VOCABULARY } from './schema-vocab.js';
@@ -67,6 +79,7 @@ import {
     UpdateOutputSchema,
     ValidateOutputSchema,
 } from './schemas.js';
+import { createWorkspaceRoots, isInsideRoots, type WorkspaceRoots } from './workspace-roots.js';
 
 // ---- MCP Apps UI (in-chat live preview) -------------------------------------
 //
@@ -107,9 +120,24 @@ interface PreviewPayload {
     theme?: string;
     now?: string;
     width?: number;
+    nonWorking?: 'hide' | 'show';
     locale?: string;
 }
 
+/**
+ * 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: { now?: string; timezone?: string },
+    today: Date | undefined,
+): string | undefined {
+    if (args.now !== undefined) return args.now;
+    if (args.timezone !== undefined && today) return today.toISOString().slice(0, 10);
+    return undefined;
+}
+
 function leanPreviewBlock(payload: PreviewPayload) {
     return {
         type: 'text' as const,
@@ -119,6 +147,7 @@ function leanPreviewBlock(payload: PreviewPayload) {
             theme: payload.theme,
             now: payload.now,
             width: payload.width,
+            nonWorking: payload.nonWorking,
             locale: payload.locale,
         }),
     };
@@ -146,11 +175,10 @@ function mutatingTool(title: string, opts: { destructiveHint: boolean; idempoten
 
 // ---- Server factory ---------------------------------------------------------
 
-function resolveAndGuard(filePath: string, allowedRoot: string): string {
-    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: string, roots: WorkspaceRoots): string {
+    const abs = path.resolve(roots.primary, filePath);
+    if (!isInsideRoots(abs, roots)) {
+        throw new PathOutsideRootError(filePath, roots.allowed.join(', '));
     }
     return abs;
 }
@@ -185,11 +213,6 @@ function createNodeHostEnv(sourcePath: string): HostEnv {
 
 // ---- Helpers ----------------------------------------------------------------
 
-function todayUtc(): Date {
-    const now = new Date();
-    return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
-}
-
 function exampleShortName(fullName: string): string {
     return fullName.endsWith('.nowline') ? fullName.slice(0, -'.nowline'.length) : fullName;
 }
@@ -201,13 +224,13 @@ function findExample(name: string): ExampleFile | undefined {
 
 async function sourceAndPath(
     args: { source?: string; path?: string },
-    allowedRoot: string,
+    roots: WorkspaceRoots,
 ): Promise<{ source: string; filePath: string }> {
     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 };
     }
@@ -217,7 +240,10 @@ async function sourceAndPath(
 // ---- Server factory ---------------------------------------------------------
 
 export interface McpServerOptions {
-    /** Working directory — all file paths are resolved relative to this root. Defaults to process.cwd(). */
+    /**
+     * Working directory: all file paths resolve relative to this root. When omitted, the
+     * server uses the client's MCP roots if it advertises them, else process.cwd().
+     */
     allowedRoot?: string;
     /** Whether the allowed root was explicitly configured (vs. defaulting to cwd). Controls smart export delivery for binary formats. Defaults to false. */
     rootConfigured?: boolean;
@@ -228,7 +254,6 @@ export interface McpServerOptions {
 }
 
 export function createMcpServer(opts: McpServerOptions = {}): McpServer {
-    const allowedRoot = opts.allowedRoot ?? process.cwd();
     const rootConfigured = opts.rootConfigured ?? false;
     const server = new McpServer(
         {
@@ -256,6 +281,8 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
         },
     );
 
+    const workspaceRoots = createWorkspaceRoots(server, opts.allowedRoot);
+
     // ---- Resources ----------------------------------------------------------
 
     server.registerResource(
@@ -335,6 +362,43 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
 
     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(
@@ -349,26 +413,39 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                     .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);
+                // 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: McpInsight[] = [];
+                if (diagnostics.every((d) => d.severity !== 'error')) {
+                    const stage = await stageMcpRoadmap(
+                        doc,
+                        source,
+                        {
+                            sourcePath: filePath,
+                            today: options.today,
+                            locale: 'en-US',
+                            theme: 'light',
+                        },
+                        createNodeHostEnv(filePath),
+                    );
+                    diagnostics.push(...stageRoutedDiagnostics(stage));
+                    if (stage.kind === 'staged') insights = layoutInsightsFromStage(stage);
+                }
                 const ok = diagnostics.every((d) => d.severity !== 'error');
-                const insights = ok
-                    ? await collectMcpLayoutInsights({
-                          source,
-                          filePath,
-                          today: todayUtc(),
-                          locale: 'en-US',
-                          readFile: createNodeHostEnv(filePath).readSource,
-                          doc,
-                      })
-                    : [];
                 const structured = {
                     ok,
                     diagnostics,
@@ -405,7 +482,7 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
         },
         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 {
@@ -439,7 +516,7 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
         },
         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;
                 await fs.mkdir(path.dirname(abs), { recursive: true });
@@ -477,7 +554,7 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
         },
         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;
                 await fs.writeFile(abs, args.source, 'utf-8');
@@ -508,7 +585,7 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
         },
         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 {
@@ -532,7 +609,7 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                     .string()
                     .optional()
                     .describe(
-                        'Directory to scan. Defaults to the allowed root (cwd or --root). Absolute or relative.',
+                        "Directory to scan. Defaults to the project root (--root, else the client's first MCP root, else cwd). Absolute or relative.",
                     ),
                 recursive: z
                     .boolean()
@@ -544,9 +621,8 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
         },
         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 };
@@ -585,15 +661,16 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                     .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()
@@ -631,10 +708,17 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
             // 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: McpResolvedOptions;
+            try {
+                resolved = resolveMcpOptions(args);
+            } catch (err) {
+                return handleToolError(err);
+            }
+            const { theme, options } = resolved;
             let source: string;
             let filePath: string;
             try {
-                ({ source, filePath } = await sourceAndPath(args, allowedRoot));
+                ({ source, filePath } = await sourceAndPath(args, await workspaceRoots()));
             } catch (err) {
                 return handleToolError(err, args.path);
             }
@@ -643,13 +727,14 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
             if (!blocked.ok) return blocked.response;
 
             const format: ExportFormat = args.format ?? 'svg';
-            const today = args.now ? new Date(`${args.now}T00:00:00Z`) : todayUtc();
+            const today = options.today;
             const inputs: RenderInputs = {
                 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);
@@ -662,32 +747,49 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                 const result = await resolveFonts({ headless: true });
                 inputs.fonts = { sans: result.sans, mono: result.mono };
             }
-            const bytes = needsRender
-                ? await exportDocument(source, 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,
-            });
+            // 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 previewPayload: 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 =
@@ -696,7 +798,7 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
 
             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 = {
@@ -802,10 +904,17 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                             '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()
@@ -834,10 +943,16 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
             // 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: SurfaceOptions;
+            try {
+                ({ options } = resolveMcpOptions(args));
+            } catch (err) {
+                return handleToolError(err);
+            }
             let source: string;
             let filePath: string;
             try {
-                ({ source, filePath } = await sourceAndPath(args, allowedRoot));
+                ({ source, filePath } = await sourceAndPath(args, await workspaceRoots()));
             } catch (err) {
                 return handleToolError(err, args.path);
             }
@@ -846,14 +961,14 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
             if (!blocked.ok) return blocked.response;
 
             const format: ExportFormat = args.format as NonRenderFormat;
-            const today = args.now ? new Date(`${args.now}T00:00:00Z`) : todayUtc();
             const inputs: RenderInputs = {
                 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,
@@ -863,7 +978,21 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                 inputs.fonts = { sans: result.sans, mono: result.mono };
             }
             const host = createNodeHostEnv(filePath);
-            const bytes = await exportDocument(source, format, inputs, host);
+            let bytes: Uint8Array;
+            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<ExportFormat>(['png', 'pdf', 'xlsx']);
             const isBinary = BINARY_FORMATS.has(format);
@@ -917,11 +1046,12 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
             }
 
             // 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: string | undefined;
             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;
@@ -1000,7 +1130,7 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
             let source: string;
             let filePath: string;
             try {
-                ({ source, filePath } = await sourceAndPath(args, allowedRoot));
+                ({ source, filePath } = await sourceAndPath(args, await workspaceRoots()));
             } catch (err) {
                 return handleToolError(err, args.path);
             }
@@ -1049,14 +1179,17 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
         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',
                         },
@@ -1074,7 +1207,10 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                 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.');
@@ -1123,7 +1259,7 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
     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'),
@@ -1302,7 +1438,7 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
         'schema',
         {
             description:
-                'Return the structured Nowline DSL key vocabulary (directive keys, entity types, item properties).',
+                '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'),
@@ -1312,6 +1448,8 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                 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) }],
@@ -1385,6 +1523,7 @@ function buildExportInlineContentBlocks(
 }
 
 async function buildReviewContentBlocks(
+    doc: Awaited<ReturnType<typeof buildDocument>>,
     source: string,
     format: ExportFormat,
     artifactBytes: Uint8Array,
@@ -1415,7 +1554,13 @@ async function buildReviewContentBlocks(
             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) {

package/src/ui/entry.ts

@@ -25,12 +25,15 @@
 declare const __MCP_VERSION__: string;
 
 import { App } from '@modelcontextprotocol/ext-apps';
+import { normalizeThemeName } from '@nowline/layout';
 import { type LivePreviewHandle, mountLivePreview } from '@nowline/preview';
 import type { NowOverride, ThemeOverride } from '@nowline/preview-shell';
 import {
     type PreviewPayload,
     parsePreviewFromArguments,
     parsePreviewFromContent,
+    toNonWorkingOverride,
+    toNowOverride,
 } from './payload.js';
 
 function readPayload(): PreviewPayload | undefined {
@@ -45,16 +48,7 @@ function readPayload(): PreviewPayload | undefined {
 
 /** Coerce a raw theme token from the payload to the shell's ThemeOverride. */
 function toThemeOverride(theme: string | undefined): ThemeOverride {
-    switch (theme) {
-        case 'light':
-        case 'dark':
-        case 'grayscale':
-        case 'greyscale':
-        case 'auto':
-            return theme;
-        default:
-            return 'auto';
-    }
+    return (theme !== undefined ? normalizeThemeName(theme) : undefined) ?? 'auto';
 }
 
 let mounted = false;
@@ -87,7 +81,8 @@ function mountFromPayload(payload: PreviewPayload, app: App): void {
         mode: hostTheme(app) ?? 'system',
         initialView: {
             theme: toThemeOverride(payload.theme),
-            now: (payload.now ?? 'today') as NowOverride,
+            now: toNowOverride(payload.now) as NowOverride,
+            nonWorking: toNonWorkingOverride(payload.nonWorking),
             showLinks: payload.showLinks !== false,
         },
         renderOptions: {