@nowline/mcp 0.7.0 → 0.8.0

package/src/server.ts

@@ -8,14 +8,14 @@
 
 import { promises as fs } from 'node:fs';
 import * as path from 'node:path';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import {
-    collectDocumentDiagnostics,
-    createNowlineServices,
-    type NowlineFile,
-    parseNowlineJson,
-    printNowlineFile,
-} from '@nowline/core';
+    getUiCapability,
+    RESOURCE_MIME_TYPE,
+    registerAppResource,
+    registerAppTool,
+} from '@modelcontextprotocol/ext-apps/server';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { parseNowlineJson, printNowlineFile } from '@nowline/core';
 import {
     type ExportFormat,
     exportDocument,
@@ -24,52 +24,78 @@ import {
 } from '@nowline/export';
 import { resolveFonts } from '@nowline/export-core';
 import { buildShareLink } from '@nowline/share-link';
-import { URI } from 'langium';
 import { z } from 'zod';
+import { NOWLINE_MCP_ICONS } from './branding.js';
 import { CAPABILITIES } from './capabilities.js';
-import { CONVERSIONS_GUIDE, EXAMPLES, REFERENCE_MAN_PAGE } from './generated/resources.js';
-import { UI_BUNDLE } from './generated/ui-bundle.js';
+import {
+    buildDocument,
+    collectMcpDiagnostics,
+    collectMcpLayoutInsights,
+    DEFAULT_RENDER_WIDTH,
+    diagnosticsErrorBlock,
+    LAYOUT_INSIGHT_HINT,
+    REVIEW_MAX_WIDTH,
+    toolDescriptionWithSyntax,
+} from './diagnostics.js';
+import {
+    CONVERSIONS_GUIDE,
+    EXAMPLES,
+    type ExampleFile,
+    REFERENCE_MAN_PAGE,
+} from './generated/resources.js';
+import { PREVIEW_HTML } from './generated/ui-bundle.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,
     UpdateOutputSchema,
     ValidateOutputSchema,
 } from './schemas.js';
 
 // ---- MCP Apps UI (in-chat live preview) -------------------------------------
 //
-// The MCP Apps extension (SEP-1865) lets a tool return an interactive HTML
-// resource the host renders in a sandboxed iframe. We use the embedded-resource
-// form: `render` returns a self-contained text/html resource that inlines the
-// browser preview bundle (UI_BUNDLE, the @nowline/browser + @nowline/preview-
-// shell pipeline) plus the injected source. It is emitted only when the client
-// advertises the UI extension capability or the caller passes `preview: true`,
-// so plain stdio operation is unchanged and non-UI hosts still receive the
-// SVG/PNG content block alongside it (graceful degradation).
+// Official MCP Apps model (SEP-1865): a pre-declared ui:// resource serves
+// static HTML; the render tool declares _meta.ui.resourceUri; per-call data
+// flows through the ontoolresult handshake. When an MCP Apps host is active,
+// render returns a lean nowline.preview JSON payload (no inline SVG/PNG) so
+// results stay under the host's ~150K inline cap. Non-apps hosts still get
+// the full SVG/PNG inline (graceful degradation).
 
 /** SEP-1865 UI extension capability id; also probed under common short keys. */
 const MCP_APPS_UI_CAPABILITY = 'io.modelcontextprotocol/ui';
-const PREVIEW_UI_URI = 'ui://nowline/preview';
-/** SEP-1865 mandates the text/html;profile=mcp-app media type for UI resources. */
-const PREVIEW_UI_MIME = 'text/html;profile=mcp-app';
+/** Versioned URI doubles as a cache key — bump suffix on bundle changes. */
+export const PREVIEW_UI_URI = 'ui://nowline/preview-v1';
 
 function clientSupportsAppsUi(server: McpServer): boolean {
-    // Extension capabilities are negotiated under `experimental` in SDK 1.29
-    // (it does not yet model SEP-1724 extensions as a first-class field), so
-    // probe the canonical id plus the short `ui` / `apps` aliases some hosts use.
-    const experimental = server.server.getClientCapabilities()?.experimental as
-        | Record<string, unknown>
+    // SEP-1724 negotiated extensions: canonical id under `extensions`.
+    const caps = server.server.getClientCapabilities() as
+        | {
+              experimental?: Record<string, unknown>;
+              extensions?: Record<string, unknown>;
+          }
         | undefined;
-    if (!experimental) return false;
-    return Boolean(experimental[MCP_APPS_UI_CAPABILITY] || experimental.ui || experimental.apps);
+    if (!caps) return false;
+    if (getUiCapability(caps as Parameters<typeof getUiCapability>[0])) return true;
+
+    // Hosts also advertise under `experimental` or short `ui` / `apps` aliases.
+    const buckets = [caps.extensions, caps.experimental].filter(
+        (bucket): bucket is Record<string, unknown> => Boolean(bucket),
+    );
+    return buckets.some((bucket) =>
+        Boolean(bucket[MCP_APPS_UI_CAPABILITY] || bucket.ui || bucket.apps),
+    );
 }
 
 interface PreviewPayload {
@@ -78,112 +104,23 @@ interface PreviewPayload {
     now?: string;
     width?: number;
     locale?: string;
-    showLinks?: boolean;
-}
-
-function buildPreviewHtml(payload: PreviewPayload): string {
-    // The payload (including the .nowline source) is injected as a JSON
-    // <script> block rather than interpolated into executable JS, so source
-    // text with quotes/backticks can't break out. Escaping `<` as \u003c keeps
-    // any embedded "</script>" from closing the block early; JSON.parse in the
-    // bundle decodes it back. The bundle injects its own stylesheet at runtime,
-    // so only the root-element sizing CSS is inlined here.
-    const data = JSON.stringify(payload).replace(/</g, '\\u003c');
-    return [
-        '<!doctype html>',
-        '<html lang="en">',
-        '<head>',
-        '<meta charset="utf-8" />',
-        '<meta name="viewport" content="width=device-width, initial-scale=1" />',
-        '<title>Nowline preview</title>',
-        '<style>html,body,#nl-preview-root{margin:0;padding:0;height:100%;width:100%;overflow:hidden;}</style>',
-        '</head>',
-        '<body>',
-        '<div id="nl-preview-root"></div>',
-        `<script id="nl-preview-data" type="application/json">${data}</script>`,
-        `<script>${UI_BUNDLE}</script>`,
-        '</body>',
-        '</html>',
-        '',
-    ].join('\n');
 }
 
-function previewResourceBlock(payload: PreviewPayload) {
+function leanPreviewBlock(payload: PreviewPayload) {
     return {
-        type: 'resource' as const,
-        resource: {
-            uri: PREVIEW_UI_URI,
-            mimeType: PREVIEW_UI_MIME,
-            text: buildPreviewHtml(payload),
-        },
+        type: 'text' as const,
+        text: JSON.stringify({
+            kind: 'nowline.preview',
+            source: payload.source,
+            theme: payload.theme,
+            now: payload.now,
+            width: payload.width,
+            locale: payload.locale,
+        }),
     };
 }
 
-// ---- Diagnostic helpers -----------------------------------------------------
-
-interface McpDiagnostic {
-    file: string;
-    line: number;
-    column: number;
-    severity: 'error' | 'warning';
-    code: string;
-    message: string;
-}
-
-function collectMcpDiagnostics(
-    doc: Awaited<ReturnType<typeof buildDocument>>,
-    filePath: string,
-): McpDiagnostic[] {
-    const raw = collectDocumentDiagnostics(doc);
-    const out: McpDiagnostic[] = [];
-    for (const d of raw) {
-        if (d.origin === 'lexer' || d.origin === 'parser') {
-            out.push({
-                file: filePath,
-                line: 1,
-                column: 1,
-                severity: 'error',
-                code: d.origin === 'lexer' ? 'lexing-error' : 'parsing-error',
-                message: d.error.message,
-            });
-        } else {
-            const diag = d.diagnostic;
-            const range = diag.range;
-            out.push({
-                file: filePath,
-                line: (range?.start.line ?? 0) + 1,
-                column: (range?.start.character ?? 0) + 1,
-                severity: diag.severity === 1 ? 'error' : 'warning',
-                code: String(diag.code ?? 'unknown'),
-                message: diag.message,
-            });
-        }
-    }
-    return out;
-}
-
-// ---- Langium services -------------------------------------------------------
-
-let cachedServices: ReturnType<typeof createNowlineServices> | undefined;
-let docCounter = 0;
-
-function getServices() {
-    if (!cachedServices) cachedServices = createNowlineServices();
-    return cachedServices;
-}
-
-async function buildDocument(source: string) {
-    const services = getServices();
-    const uri = URI.parse(`memory:///mcp-${++docCounter}.nowline`);
-    const doc = services.shared.workspace.LangiumDocumentFactory.fromString<NowlineFile>(
-        source,
-        uri,
-    );
-    await services.shared.workspace.DocumentBuilder.build([doc], { validation: true });
-    return doc;
-}
-
-// ---- Allowed-root enforcement -----------------------------------------------
+// ---- Server factory ---------------------------------------------------------
 
 function resolveAndGuard(filePath: string, allowedRoot: string): string {
     const abs = path.resolve(allowedRoot, filePath);
@@ -229,6 +166,15 @@ function todayUtc(): 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;
+}
+
+function findExample(name: string): ExampleFile | undefined {
+    const withExt = name.endsWith('.nowline') ? name : `${name}.nowline`;
+    return EXAMPLES.find((e) => e.name === withExt || e.name === name);
+}
+
 async function sourceAndPath(
     args: { source?: string; path?: string },
     allowedRoot: string,
@@ -257,10 +203,22 @@ export interface McpServerOptions {
 
 export function createMcpServer(opts: McpServerOptions = {}): McpServer {
     const allowedRoot = opts.allowedRoot ?? process.cwd();
-    const server = new McpServer({
-        name: opts.name ?? 'nowline',
-        version: opts.version ?? '0.6.0',
-    });
+    const server = new McpServer(
+        {
+            name: opts.name ?? 'nowline',
+            version: opts.version ?? '0.6.0',
+            icons: [...NOWLINE_MCP_ICONS],
+        },
+        {
+            instructions:
+                'Nowline manages roadmaps written in the .nowline plain-text DSL — NOT JSON or any other ' +
+                'structured format. All `source` parameters expect `.nowline` DSL text (starts with `nowline v1`). ' +
+                'Workflow: 1. call `reference` or `examples` to learn syntax → 2. write `.nowline` → ' +
+                '3. call `render` (validates + renders; or `validate` alone) → 4. fix errors keyed on `NL.E####` ' +
+                'and re-render → 5. review returned layout `insights` (what reflowed) → 6. when uncertain, ' +
+                'call `render` with `review:true` for a final visual check. JSON in `convert` is AST conversion only.',
+        },
+    );
 
     // ---- Resources ----------------------------------------------------------
 
@@ -314,6 +272,25 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
         }),
     );
 
+    registerAppResource(
+        server,
+        'nowline-preview',
+        PREVIEW_UI_URI,
+        {
+            description:
+                'Interactive in-chat roadmap preview (MCP Apps). Hydrates via ontoolresult.',
+        },
+        async () => ({
+            contents: [
+                {
+                    uri: PREVIEW_UI_URI,
+                    mimeType: RESOURCE_MIME_TYPE,
+                    text: PREVIEW_HTML,
+                },
+            ],
+        }),
+    );
+
     // ---- Prompts ------------------------------------------------------------
 
     registerPrompts(server);
@@ -323,8 +300,9 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
     server.registerTool(
         'validate',
         {
-            description:
-                'Parse and validate a .nowline roadmap. Returns ok=true and an empty diagnostics array if valid, or ok=false with structured diagnostics.',
+            description: toolDescriptionWithSyntax(
+                'Parse and validate a .nowline roadmap. Returns ok=true with optional layout insights when valid, or ok=false with structured diagnostics.',
+            ),
             inputSchema: z.object({
                 source: z.string().optional().describe('Inline .nowline source text to validate.'),
                 path: z
@@ -340,9 +318,24 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
             const doc = await buildDocument(source);
             const diagnostics = collectMcpDiagnostics(doc, filePath);
             const ok = diagnostics.every((d) => d.severity !== 'error');
-            const structured = { ok, diagnostics };
+            const insights = ok
+                ? await collectMcpLayoutInsights({
+                      source,
+                      filePath,
+                      today: todayUtc(),
+                      locale: 'en-US',
+                      readFile: createNodeHostEnv(filePath).readSource,
+                      doc,
+                  })
+                : [];
+            const structured = { ok, diagnostics, ...(insights.length > 0 ? { insights } : {}) };
             return {
-                content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
+                content: [
+                    { type: 'text', text: JSON.stringify(structured, null, 2) },
+                    ...(insights.length > 0
+                        ? [{ type: 'text' as const, text: LAYOUT_INSIGHT_HINT }]
+                        : []),
+                ],
                 structuredContent: structured,
             };
         },
@@ -378,8 +371,9 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
     server.registerTool(
         'create',
         {
-            description:
+            description: toolDescriptionWithSyntax(
                 'Write a new .nowline file after validation. Overwrites if the path already exists.',
+            ),
             inputSchema: z.object({
                 path: z.string().describe('Absolute or relative path to write the .nowline file.'),
                 source: z.string().describe('The .nowline source text to write.'),
@@ -390,20 +384,8 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
         },
         async (args) => {
             const abs = resolveAndGuard(args.path, allowedRoot);
-            const doc = await buildDocument(args.source);
-            const diagnostics = collectMcpDiagnostics(doc, abs);
-            const errors = diagnostics.filter((d) => d.severity === 'error');
-            if (errors.length > 0) {
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: JSON.stringify({ ok: false, path: abs, diagnostics }, null, 2),
-                        },
-                    ],
-                    isError: true,
-                };
-            }
+            const blocked = await diagnosticsErrorBlock(args.source, abs);
+            if (!blocked.ok) return blocked.response;
             await fs.mkdir(path.dirname(abs), { recursive: true });
             await fs.writeFile(abs, args.source, 'utf-8');
             const structured = { ok: true, path: abs };
@@ -419,7 +401,9 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
     server.registerTool(
         'update',
         {
-            description: 'Replace an existing .nowline file after validation.',
+            description: toolDescriptionWithSyntax(
+                'Replace an existing .nowline file after validation.',
+            ),
             inputSchema: z.object({
                 path: z
                     .string()
@@ -431,20 +415,8 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
         },
         async (args) => {
             const abs = resolveAndGuard(args.path, allowedRoot);
-            const doc = await buildDocument(args.source);
-            const diagnostics = collectMcpDiagnostics(doc, abs);
-            const errors = diagnostics.filter((d) => d.severity === 'error');
-            if (errors.length > 0) {
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: JSON.stringify({ ok: false, path: abs, diagnostics }, null, 2),
-                        },
-                    ],
-                    isError: true,
-                };
-            }
+            const blocked = await diagnosticsErrorBlock(args.source, abs);
+            if (!blocked.ok) return blocked.response;
             await fs.writeFile(abs, args.source, 'utf-8');
             const structured = { ok: true, path: abs };
             return {
@@ -514,14 +486,24 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
 
     // ---- render -------------------------------------------------------------
 
-    server.registerTool(
+    registerAppTool(
+        server,
         'render',
         {
-            description:
-                'Render a .nowline roadmap to SVG or PNG using the shared export kernel. Byte-identical to `nowline -f svg/png` for the same source and inputs.',
+            description: toolDescriptionWithSyntax(
+                'Validate then render a .nowline roadmap to SVG or PNG (combined validate+render+share). ' +
+                    'Returns structured diagnostics on error-severity input instead of a raw kernel error.',
+            ),
             inputSchema: z.object({
                 source: z.string().optional().describe('Inline .nowline source text.'),
-                path: z.string().optional().describe('Path to the .nowline file.'),
+                path: z
+                    .string()
+                    .optional()
+                    .describe(
+                        'Real local filesystem path to the .nowline file (e.g. /Users/name/Desktop/foo.nowline). ' +
+                            'Never pass a virtual or sandbox path such as /mnt/user-data/… — ' +
+                            'those do not exist on the host filesystem. Pass `source` instead.',
+                    ),
                 format: z
                     .enum(['svg', 'png'])
                     .optional()
@@ -542,25 +524,42 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                 output: z
                     .string()
                     .optional()
-                    .describe('Write output to this path instead of returning inline.'),
+                    .describe(
+                        'Real local filesystem path to write the output file (e.g. /Users/name/Desktop/roadmap.svg). ' +
+                            'Never pass a virtual or sandbox path such as /mnt/user-data/… — ' +
+                            'omit this parameter to receive output inline instead.',
+                    ),
                 share: z
                     .boolean()
                     .optional()
                     .describe(
                         'When true, include a shareUrl pointing to https://free.nowline.io/open.',
                     ),
+                review: z
+                    .boolean()
+                    .optional()
+                    .describe(
+                        'When true, also attach a downscaled PNG so a multimodal model can visually check layout (label overflow, lane crowding, off-range now-line). Off by default.',
+                    ),
                 preview: z
                     .boolean()
                     .optional()
                     .describe(
-                        'When true, also return an interactive in-chat HTML preview (MCP Apps UI). Auto-enabled when the client advertises MCP Apps UI support.',
+                        'When true, force the in-chat MCP Apps preview. On MCP Apps hosts the preview auto-renders via _meta.ui without this flag.',
                     ),
             }),
             outputSchema: RenderOutputSchema,
             annotations: { readOnlyHint: true, idempotentHint: true },
+            _meta: {
+                ui: { resourceUri: PREVIEW_UI_URI },
+                'openai/outputTemplate': PREVIEW_UI_URI,
+            },
         },
         async (args) => {
             const { source, filePath } = await sourceAndPath(args, allowedRoot);
+            const blocked = await diagnosticsErrorBlock(source, filePath);
+            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 inputs: RenderInputs = {
@@ -571,48 +570,90 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                 width: args.width,
                 pngScale: args.scale,
             };
-            if (format === 'png') {
+            const host = createNodeHostEnv(filePath);
+            const appActive = args.preview === true || clientSupportsAppsUi(server);
+            // Skip the full render when the bytes won't be used: apps host with
+            // no write-to-disk path and no review attachment requested.
+            const needsRender = !appActive || !!args.output || args.review === true;
+            if (needsRender && (format === 'png' || args.review === true)) {
                 const result = await resolveFonts({ headless: true });
                 inputs.fonts = { sans: result.sans, mono: result.mono };
             }
-            const host = createNodeHostEnv(filePath);
-            const bytes = await exportDocument(source, format, inputs, host);
+            const bytes = needsRender
+                ? await exportDocument(source, format, inputs, host)
+                : new Uint8Array(0);
             const shareUrl = args.share
                 ? (buildShareLink({ source, share: true }) ?? undefined)
                 : undefined;
 
-            // Optional MCP Apps in-chat preview. Emitted alongside the normal
-            // content so non-UI hosts still get the SVG/PNG; the bundle renders
-            // the live SVG itself, so the preview is format-agnostic.
-            const wantPreview = args.preview === true || clientSupportsAppsUi(server);
-            const previewBlocks = wantPreview
-                ? [
-                      previewResourceBlock({
-                          source,
-                          theme: args.theme,
-                          now: args.now,
-                          width: args.width,
-                          locale: 'en-US',
-                      }),
-                  ]
-                : [];
+            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: PreviewPayload = {
+                source,
+                theme: args.theme,
+                now: args.now,
+                width: args.width,
+                locale: 'en-US',
+            };
+
+            const reviewBlocks =
+                args.review === true
+                    ? await buildReviewContentBlocks(source, format, bytes, inputs, host)
+                    : [];
+
+            const insightHintBlocks =
+                insights.length > 0 ? [{ type: 'text' as const, text: LAYOUT_INSIGHT_HINT }] : [];
+            const insightsField = insights.length > 0 ? { insights } : {};
 
             if (args.output) {
                 const outAbs = resolveAndGuard(args.output, allowedRoot);
                 await fs.mkdir(path.dirname(outAbs), { recursive: true });
                 await fs.writeFile(outAbs, bytes);
-                const structured = { format, path: outAbs, bytes: bytes.byteLength, shareUrl };
+                const structured = {
+                    format,
+                    path: outAbs,
+                    bytes: bytes.byteLength,
+                    shareUrl,
+                    ...insightsField,
+                };
+                return {
+                    content: [
+                        ...(appActive ? [leanPreviewBlock(previewPayload)] : []),
+                        { type: 'text' as const, text: JSON.stringify(structured, null, 2) },
+                        ...insightHintBlocks,
+                        ...reviewBlocks,
+                    ],
+                    structuredContent: structured,
+                };
+            }
+
+            if (appActive) {
+                const structured = {
+                    format,
+                    shareUrl,
+                    ...insightsField,
+                };
                 return {
                     content: [
-                        { type: 'text', text: JSON.stringify(structured, null, 2) },
-                        ...previewBlocks,
+                        leanPreviewBlock(previewPayload),
+                        ...insightHintBlocks,
+                        ...reviewBlocks,
                     ],
                     structuredContent: structured,
                 };
             }
 
             if (format === 'png') {
-                const structured = { format, bytes: bytes.byteLength, shareUrl };
+                const structured = { format, bytes: bytes.byteLength, shareUrl, ...insightsField };
                 return {
                     content: [
                         {
@@ -620,17 +661,19 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                             data: Buffer.from(bytes).toString('base64'),
                             mimeType: 'image/png',
                         },
-                        ...previewBlocks,
+                        ...insightHintBlocks,
+                        ...reviewBlocks,
                     ],
                     structuredContent: structured,
                 };
             }
             const svgText = new TextDecoder('utf-8').decode(bytes);
-            const structured = { format, shareUrl };
+            const structured = { format, shareUrl, ...insightsField };
             return {
                 content: [
                     { type: 'text', text: svgText, mimeType: 'image/svg+xml' },
-                    ...previewBlocks,
+                    ...insightHintBlocks,
+                    ...reviewBlocks,
                 ],
                 structuredContent: structured,
             };
@@ -649,14 +692,26 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                 'Export a .nowline roadmap to any of the eight canonical formats. Byte-identical to `nowline -f <format>` for the same source and inputs.',
             inputSchema: z.object({
                 source: z.string().optional().describe('Inline .nowline source text.'),
-                path: z.string().optional().describe('Path to the .nowline file.'),
+                path: z
+                    .string()
+                    .optional()
+                    .describe(
+                        'Real local filesystem path to the .nowline file (e.g. /Users/name/Desktop/foo.nowline). ' +
+                            'Never pass a virtual or sandbox path such as /mnt/user-data/… — ' +
+                            'those do not exist on the host filesystem. Pass `source` instead.',
+                    ),
                 format: z
                     .enum(EXPORT_FORMATS)
                     .describe('Export format: pdf, html, mermaid, xlsx, msproj, or png.'),
                 output: z
                     .string()
                     .optional()
-                    .describe('Path to write the output file. Required for binary formats.'),
+                    .describe(
+                        'Real local filesystem path to write the output (e.g. /Users/name/Desktop/roadmap.pdf). ' +
+                            'Required for binary formats (pdf, xlsx, msproj, png). ' +
+                            'Never pass a virtual or sandbox path such as /mnt/user-data/… — ' +
+                            '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(),
                 scale: z.number().optional().describe('PNG scale factor.'),
@@ -682,6 +737,9 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
         },
         async (args) => {
             const { source, filePath } = await sourceAndPath(args, allowedRoot);
+            const blocked = await diagnosticsErrorBlock(source, filePath);
+            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 = {
@@ -755,7 +813,14 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                 'Convert between .nowline source text and its JSON AST representation. `to:json` serializes a .nowline file to the JSON AST; `to:nowline` pretty-prints a JSON AST back to canonical .nowline source.',
             inputSchema: z.object({
                 source: z.string().optional().describe('Inline source text to convert.'),
-                path: z.string().optional().describe('Path to the source file.'),
+                path: z
+                    .string()
+                    .optional()
+                    .describe(
+                        'Real local filesystem path to the source file. ' +
+                            'Never pass a virtual or sandbox path such as /mnt/user-data/… — ' +
+                            'pass `source` instead.',
+                    ),
                 to: z
                     .enum(['json', 'nowline'])
                     .describe(
@@ -930,11 +995,165 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
         },
     );
 
+    // ---- reference / examples / schema (discovery tools) --------------------
+
+    server.registerTool(
+        'reference',
+        {
+            description:
+                'Return the Nowline DSL reference (condensed cheatsheet or full man page). Callable alternative to the nowline://reference resource.',
+            inputSchema: z.object({
+                format: z
+                    .enum(['condensed', 'full'])
+                    .optional()
+                    .describe('Reference format. Defaults to condensed.'),
+            }),
+            outputSchema: ReferenceOutputSchema,
+            annotations: { readOnlyHint: true, idempotentHint: true },
+        },
+        async (args) => {
+            const format = args.format ?? 'condensed';
+            const text = format === 'full' ? REFERENCE_MAN_PAGE : REFERENCE_CHEATSHEET;
+            const structured = { format, text };
+            return {
+                content: [{ type: 'text', text }],
+                structuredContent: structured,
+            };
+        },
+    );
+
+    server.registerTool(
+        'examples',
+        {
+            description:
+                'Return canonical .nowline example sources. Callable alternative to the nowline://examples resource.',
+            inputSchema: z.object({
+                name: z
+                    .string()
+                    .optional()
+                    .describe('Example name. Omit for the catalog plus minimal inline.'),
+            }),
+            outputSchema: ExamplesOutputSchema,
+            annotations: { readOnlyHint: true, idempotentHint: true },
+        },
+        async (args) => {
+            const exampleNames = EXAMPLES.map((e) => exampleShortName(e.name));
+            if (args.name) {
+                const ex = findExample(args.name);
+                if (!ex) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify({
+                                    error: `Unknown example "${args.name}".`,
+                                    names: exampleNames,
+                                }),
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                const structured = { name: exampleShortName(ex.name), source: ex.content };
+                return {
+                    content: [{ type: 'text', text: ex.content }],
+                    structuredContent: structured,
+                };
+            }
+            const minimal = findExample('minimal') ?? EXAMPLES[0];
+            const structured = {
+                names: exampleNames,
+                name: exampleShortName(minimal.name),
+                source: minimal.content,
+            };
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `# Examples\n\n${exampleNames.map((n) => `- ${n}`).join('\n')}\n\n## ${structured.name}\n\n${minimal.content}`,
+                    },
+                ],
+                structuredContent: structured,
+            };
+        },
+    );
+
+    server.registerTool(
+        'schema',
+        {
+            description:
+                'Return the structured Nowline DSL key vocabulary (directive keys, entity types, item properties).',
+            inputSchema: z.object({}),
+            outputSchema: SchemaOutputSchema,
+            annotations: { readOnlyHint: true, idempotentHint: true },
+        },
+        async () => {
+            const structured = {
+                directiveKeys: [...SCHEMA_VOCABULARY.directiveKeys],
+                entityTypes: [...SCHEMA_VOCABULARY.entityTypes],
+                itemPropertyKeys: [...SCHEMA_VOCABULARY.itemPropertyKeys],
+            };
+            return {
+                content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
+                structuredContent: structured,
+            };
+        },
+    );
+
     return server;
 }
 
 // ---- Helpers ----------------------------------------------------------------
 
+type ContentBlock =
+    | { type: 'text'; text: string; mimeType?: string }
+    | { type: 'image'; data: string; mimeType: string };
+
+async function buildReviewContentBlocks(
+    source: string,
+    format: ExportFormat,
+    artifactBytes: Uint8Array,
+    inputs: RenderInputs,
+    host: HostEnv,
+): Promise<ContentBlock[]> {
+    const blocks: ContentBlock[] = [
+        {
+            type: 'text',
+            text:
+                'Review this raster for layout issues (truncated labels, crowded lanes, ' +
+                'now-line position) before finalizing.',
+        },
+    ];
+
+    const artifactWidth = inputs.width ?? DEFAULT_RENDER_WIDTH;
+    let inspectionBytes: Uint8Array;
+
+    if (format === 'png' && artifactWidth <= REVIEW_MAX_WIDTH) {
+        inspectionBytes = artifactBytes;
+    } else {
+        const reviewInputs: RenderInputs = {
+            ...inputs,
+            width: Math.min(artifactWidth, REVIEW_MAX_WIDTH),
+            pngScale: 1,
+        };
+        if (!reviewInputs.fonts) {
+            const fonts = await resolveFonts({ headless: true });
+            reviewInputs.fonts = { sans: fonts.sans, mono: fonts.mono };
+        }
+        inspectionBytes = await exportDocument(source, 'png', reviewInputs, host);
+    }
+
+    if (format !== 'png' || inspectionBytes.byteLength !== artifactBytes.byteLength) {
+        blocks.push({
+            type: 'image',
+            data: Buffer.from(inspectionBytes).toString('base64'),
+            mimeType: 'image/png',
+        });
+    }
+
+    return blocks;
+}
+
 async function listNowlineFiles(dir: string, recursive: boolean): Promise<string[]> {
     const results: string[] = [];
     try {