@nowline/mcp 0.7.0 → 0.8.1

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,81 @@ 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,
+    handleToolError,
+    InputRequiredError,
+    LAYOUT_INSIGHT_HINT,
+    PathOutsideRootError,
+    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,118 +107,49 @@ 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;
-}
+// ---- Tool annotation presets (Anthropic Software Directory Policy § 5.E) ---
 
-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;
+function readOnlyTool(title: string) {
+    return {
+        title,
+        readOnlyHint: true as const,
+        idempotentHint: true as const,
+        openWorldHint: false as const,
+    };
 }
 
-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;
+function mutatingTool(title: string, opts: { destructiveHint: boolean; idempotentHint?: boolean }) {
+    return {
+        title,
+        destructiveHint: opts.destructiveHint,
+        ...(opts.idempotentHint ? { idempotentHint: true as const } : {}),
+        openWorldHint: false as const,
+    };
 }
 
-// ---- Allowed-root enforcement -----------------------------------------------
+// ---- 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 Error(`Path ${filePath} is outside the allowed root ${allowedRoot}`);
+        throw new PathOutsideRootError(filePath, allowedRoot);
     }
     return abs;
 }
@@ -229,6 +189,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,
@@ -241,7 +210,7 @@ async function sourceAndPath(
         const source = args.source ?? (await fs.readFile(abs, 'utf-8'));
         return { source, filePath: abs };
     }
-    throw new Error('At least one of `source` or `path` is required.');
+    throw new InputRequiredError('At least one of `source` or `path` is required.');
 }
 
 // ---- Server factory ---------------------------------------------------------
@@ -257,10 +226,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 ----------------------------------------------------------
 
@@ -268,6 +249,7 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
         'nowline-reference',
         'nowline://reference',
         {
+            title: 'Roadmap Reference',
             description:
                 'Full DSL reference (nowline.5 man page): syntax, directives, and examples.',
             mimeType: 'text/plain',
@@ -283,6 +265,7 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
         'nowline-examples',
         'nowline://examples',
         {
+            title: 'Roadmap Examples',
             description: 'Canonical example .nowline files from the official examples/ directory.',
             mimeType: 'text/plain',
         },
@@ -299,6 +282,7 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
         'nowline-conversions',
         'nowline://conversions',
         {
+            title: 'Conversion Guide',
             description:
                 'LLM-mediated conversion guide: how to translate Mermaid gantt, MS Project, Excel, Google Sheets timeline, and generic CSV into Nowline DSL.',
             mimeType: 'text/plain',
@@ -314,6 +298,26 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
         }),
     );
 
+    registerAppResource(
+        server,
+        'nowline-preview',
+        PREVIEW_UI_URI,
+        {
+            title: 'Roadmap Preview',
+            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 +327,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
@@ -333,18 +338,41 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                     .describe('Absolute or relative path to a .nowline file to validate.'),
             }),
             outputSchema: ValidateOutputSchema,
-            annotations: { readOnlyHint: true, idempotentHint: true },
+            annotations: readOnlyTool('Validate Roadmap'),
         },
         async (args) => {
-            const { source, filePath } = await sourceAndPath(args, allowedRoot);
-            const doc = await buildDocument(source);
-            const diagnostics = collectMcpDiagnostics(doc, filePath);
-            const ok = diagnostics.every((d) => d.severity !== 'error');
-            const structured = { ok, diagnostics };
-            return {
-                content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
-                structuredContent: structured,
-            };
+            try {
+                const { source, filePath } = await sourceAndPath(args, allowedRoot);
+                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(),
+                          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) },
+                        ...(insights.length > 0
+                            ? [{ type: 'text' as const, text: LAYOUT_INSIGHT_HINT }]
+                            : []),
+                    ],
+                    structuredContent: structured,
+                };
+            } catch (err) {
+                return handleToolError(err, args.path);
+            }
         },
     );
 
@@ -360,16 +388,20 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                     .describe('Absolute or relative path to the .nowline file to read.'),
             }),
             outputSchema: ReadOutputSchema,
-            annotations: { readOnlyHint: true, idempotentHint: true },
+            annotations: readOnlyTool('Read Roadmap'),
         },
         async (args) => {
-            const abs = resolveAndGuard(args.path, allowedRoot);
-            const source = await fs.readFile(abs, 'utf-8');
-            const structured = { path: abs, source };
-            return {
-                content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
-                structuredContent: structured,
-            };
+            try {
+                const abs = resolveAndGuard(args.path, allowedRoot);
+                const source = await fs.readFile(abs, 'utf-8');
+                const structured = { path: abs, source };
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
+                    structuredContent: structured,
+                };
+            } catch (err) {
+                return handleToolError(err, args.path);
+            }
         },
     );
 
@@ -378,39 +410,35 @@ 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.'),
             }),
             outputSchema: CreateOutputSchema,
             // Overwrites silently → destructive; same source always produces same file → idempotent.
-            annotations: { destructiveHint: true, idempotentHint: true },
+            annotations: mutatingTool('Create Roadmap', {
+                destructiveHint: true,
+                idempotentHint: true,
+            }),
         },
         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) {
+            try {
+                const abs = resolveAndGuard(args.path, allowedRoot);
+                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 };
                 return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: JSON.stringify({ ok: false, path: abs, diagnostics }, null, 2),
-                        },
-                    ],
-                    isError: true,
+                    content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
+                    structuredContent: structured,
                 };
+            } catch (err) {
+                return handleToolError(err, args.path);
             }
-            await fs.mkdir(path.dirname(abs), { recursive: true });
-            await fs.writeFile(abs, args.source, 'utf-8');
-            const structured = { ok: true, path: abs };
-            return {
-                content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
-                structuredContent: structured,
-            };
         },
     );
 
@@ -419,7 +447,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()
@@ -427,30 +457,25 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                 source: z.string().describe('The new .nowline source text.'),
             }),
             outputSchema: UpdateOutputSchema,
-            annotations: { idempotentHint: true },
+            annotations: mutatingTool('Update Roadmap', {
+                destructiveHint: true,
+                idempotentHint: true,
+            }),
         },
         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) {
+            try {
+                const abs = resolveAndGuard(args.path, allowedRoot);
+                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 {
-                    content: [
-                        {
-                            type: 'text',
-                            text: JSON.stringify({ ok: false, path: abs, diagnostics }, null, 2),
-                        },
-                    ],
-                    isError: true,
+                    content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
+                    structuredContent: structured,
                 };
+            } catch (err) {
+                return handleToolError(err, args.path);
             }
-            await fs.writeFile(abs, args.source, 'utf-8');
-            const structured = { ok: true, path: abs };
-            return {
-                content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
-                structuredContent: structured,
-            };
         },
     );
 
@@ -466,16 +491,20 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                     .describe('Absolute or relative path of the .nowline file to delete.'),
             }),
             outputSchema: DeleteOutputSchema,
-            annotations: { destructiveHint: true },
+            annotations: mutatingTool('Delete Roadmap', { destructiveHint: true }),
         },
         async (args) => {
-            const abs = resolveAndGuard(args.path, allowedRoot);
-            await fs.unlink(abs);
-            const structured = { path: abs };
-            return {
-                content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
-                structuredContent: structured,
-            };
+            try {
+                const abs = resolveAndGuard(args.path, allowedRoot);
+                await fs.unlink(abs);
+                const structured = { path: abs };
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
+                    structuredContent: structured,
+                };
+            } catch (err) {
+                return handleToolError(err, args.path);
+            }
         },
     );
 
@@ -498,30 +527,46 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                     .describe('Whether to scan subdirectories. Defaults to false.'),
             }),
             outputSchema: ListOutputSchema,
-            annotations: { readOnlyHint: true, idempotentHint: true },
+            annotations: readOnlyTool('List Roadmaps'),
         },
         async (args) => {
-            const dir = args.directory ? resolveAndGuard(args.directory, allowedRoot) : allowedRoot;
-            const recursive = args.recursive ?? false;
-            const paths = await listNowlineFiles(dir, recursive);
-            const structured = { paths };
-            return {
-                content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
-                structuredContent: structured,
-            };
+            try {
+                const dir = args.directory
+                    ? resolveAndGuard(args.directory, allowedRoot)
+                    : allowedRoot;
+                const recursive = args.recursive ?? false;
+                const paths = await listNowlineFiles(dir, recursive);
+                const structured = { paths };
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
+                    structuredContent: structured,
+                };
+            } catch (err) {
+                return handleToolError(err, args.directory);
+            }
         },
     );
 
     // ---- 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 +587,52 @@ 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 },
+            annotations: readOnlyTool('Render Roadmap'),
+            _meta: {
+                ui: { resourceUri: PREVIEW_UI_URI },
+                'openai/outputTemplate': PREVIEW_UI_URI,
+            },
         },
         async (args) => {
-            const { source, filePath } = await sourceAndPath(args, allowedRoot);
+            // 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 source: string;
+            let filePath: string;
+            try {
+                ({ source, filePath } = await sourceAndPath(args, allowedRoot));
+            } catch (err) {
+                return handleToolError(err, args.path);
+            }
+
+            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 +643,99 @@ 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 };
+                try {
+                    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,
+                        ...insightsField,
+                    };
+                    return {
+                        content: [
+                            ...(appActive ? [leanPreviewBlock(previewPayload)] : []),
+                            { type: 'text' as const, text: JSON.stringify(structured, null, 2) },
+                            ...insightHintBlocks,
+                            ...reviewBlocks,
+                        ],
+                        structuredContent: structured,
+                    };
+                } catch (err) {
+                    return handleToolError(err, args.output);
+                }
+            }
+
+            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 +743,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 +774,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.'),
@@ -678,10 +815,23 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                     ),
             }),
             outputSchema: ExportOutputSchema,
-            annotations: { readOnlyHint: true, idempotentHint: true },
+            annotations: readOnlyTool('Export Roadmap'),
         },
         async (args) => {
-            const { source, filePath } = await sourceAndPath(args, allowedRoot);
+            // 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 source: string;
+            let filePath: string;
+            try {
+                ({ source, filePath } = await sourceAndPath(args, allowedRoot));
+            } catch (err) {
+                return handleToolError(err, args.path);
+            }
+
+            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 = {
@@ -709,14 +859,18 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
             const isBinary = BINARY_FORMATS.has(format);
 
             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 };
-                return {
-                    content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
-                    structuredContent: structured,
-                };
+                try {
+                    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 };
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
+                        structuredContent: structured,
+                    };
+                } catch (err) {
+                    return handleToolError(err, args.output);
+                }
             }
 
             if (isBinary) {
@@ -755,7 +909,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(
@@ -763,47 +924,51 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                     ),
             }),
             outputSchema: ConvertOutputSchema,
-            annotations: { readOnlyHint: true, idempotentHint: true },
+            annotations: readOnlyTool('Convert Roadmap'),
         },
         async (args) => {
-            if (args.to === 'json') {
-                const { source, filePath } = await sourceAndPath(args, allowedRoot);
-                const host = createNodeHostEnv(filePath);
-                const jsonBytes = await exportDocument(
-                    source,
-                    'json',
-                    {
-                        sourcePath: filePath,
-                        today: todayUtc(),
-                        locale: 'en-US',
-                        theme: 'light',
-                    },
-                    host,
-                );
-                const result = new TextDecoder('utf-8').decode(jsonBytes);
-                const structured = { to: 'json' as const, result };
+            try {
+                if (args.to === 'json') {
+                    const { source, filePath } = await sourceAndPath(args, allowedRoot);
+                    const host = createNodeHostEnv(filePath);
+                    const jsonBytes = await exportDocument(
+                        source,
+                        'json',
+                        {
+                            sourcePath: filePath,
+                            today: todayUtc(),
+                            locale: 'en-US',
+                            theme: 'light',
+                        },
+                        host,
+                    );
+                    const result = new TextDecoder('utf-8').decode(jsonBytes);
+                    const structured = { to: 'json' as const, result };
+                    return {
+                        content: [{ type: 'text', text: result }],
+                        structuredContent: structured,
+                    };
+                }
+
+                // to: 'nowline' — input is a JSON AST string
+                const jsonSource =
+                    args.source ??
+                    (args.path
+                        ? await fs.readFile(resolveAndGuard(args.path, allowedRoot), 'utf-8')
+                        : null);
+                if (!jsonSource) {
+                    throw new InputRequiredError('At least one of `source` or `path` is required.');
+                }
+                const { ast } = parseNowlineJson(jsonSource, args.path ?? 'input.json');
+                const result = printNowlineFile(ast);
+                const structured = { to: 'nowline' as const, result };
                 return {
                     content: [{ type: 'text', text: result }],
                     structuredContent: structured,
                 };
+            } catch (err) {
+                return handleToolError(err, args.path);
             }
-
-            // to: 'nowline' — input is a JSON AST string
-            const jsonSource =
-                args.source ??
-                (args.path
-                    ? await fs.readFile(resolveAndGuard(args.path, allowedRoot), 'utf-8')
-                    : null);
-            if (!jsonSource) {
-                throw new Error('At least one of `source` or `path` is required.');
-            }
-            const { ast } = parseNowlineJson(jsonSource, args.path ?? 'input.json');
-            const result = printNowlineFile(ast);
-            const structured = { to: 'nowline' as const, result };
-            return {
-                content: [{ type: 'text', text: result }],
-                structuredContent: structured,
-            };
         },
     );
 
@@ -816,7 +981,7 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                 'Return all supported themes, icons, locales, export formats, and template names in a single response.',
             inputSchema: z.object({}),
             outputSchema: CapabilitiesOutputSchema,
-            annotations: { readOnlyHint: true, idempotentHint: true },
+            annotations: readOnlyTool('View Roadmap Capabilities'),
         },
         async () => {
             const structured = {
@@ -841,7 +1006,7 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
             description: 'List supported color themes: light, dark, grayscale.',
             inputSchema: z.object({}),
             outputSchema: ListItemsOutputSchema,
-            annotations: { readOnlyHint: true, idempotentHint: true },
+            annotations: readOnlyTool('List Themes'),
         },
         async () => {
             const structured = { items: [...CAPABILITIES.themes] };
@@ -861,7 +1026,7 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                 'List built-in capacity-icon names usable in the `capacity-icon:` style property.',
             inputSchema: z.object({}),
             outputSchema: ListItemsOutputSchema,
-            annotations: { readOnlyHint: true, idempotentHint: true },
+            annotations: readOnlyTool('List Icons'),
         },
         async () => {
             const structured = { items: [...CAPABILITIES.icons] };
@@ -880,7 +1045,7 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
             description: 'List supported BCP-47 locale tags.',
             inputSchema: z.object({}),
             outputSchema: ListItemsOutputSchema,
-            annotations: { readOnlyHint: true, idempotentHint: true },
+            annotations: readOnlyTool('List Locales'),
         },
         async () => {
             const structured = { items: [...CAPABILITIES.locales] };
@@ -900,7 +1065,7 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
                 'List all supported export formats (svg, png, pdf, html, mermaid, xlsx, msproj, json).',
             inputSchema: z.object({}),
             outputSchema: ListItemsOutputSchema,
-            annotations: { readOnlyHint: true, idempotentHint: true },
+            annotations: readOnlyTool('List Export Formats'),
         },
         async () => {
             const structured = { items: [...CAPABILITIES.formats] };
@@ -919,7 +1084,7 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
             description: 'List built-in template names usable with `nowline --init --template`.',
             inputSchema: z.object({}),
             outputSchema: ListItemsOutputSchema,
-            annotations: { readOnlyHint: true, idempotentHint: true },
+            annotations: readOnlyTool('List Templates'),
         },
         async () => {
             const structured = { items: [...CAPABILITIES.templates] };
@@ -930,11 +1095,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: readOnlyTool('View Roadmap Reference'),
+        },
+        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: readOnlyTool('View Roadmap Examples'),
+        },
+        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: readOnlyTool('View Roadmap Schema'),
+        },
+        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 {