@mesh-tech/mesh-cli 0.36.0 → 0.37.0

package/dist/src/docs/preview-source.js

@@ -0,0 +1,58 @@
+import { readFileSync, statSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { buildDocsSource } from "@mesh-tech/api-registry/docs-source-build";
+export function resolveDocsConfigPath(target) {
+    const abs = resolve(target);
+    let stat;
+    try {
+        stat = statSync(abs);
+    }
+    catch {
+        throw new Error(`No docs source at ${abs} — pass the directory that holds docs.yaml, or docs.yaml itself`);
+    }
+    if (stat.isFile()) {
+        if (basename(abs) !== "docs.yaml")
+            throw new Error(`${abs} is not a docs.yaml`);
+        return abs;
+    }
+    const configPath = join(abs, "docs.yaml");
+    try {
+        if (statSync(configPath).isFile())
+            return configPath;
+    }
+    catch {
+    }
+    throw new Error(`No docs.yaml in ${abs}`);
+}
+function missingEventsCatalogProblem(service) {
+    return `docs.yaml names events "${service}", but no events catalog was supplied`;
+}
+export function readPreviewSource(configPath, opts = {}) {
+    const built = buildDocsSource({ configPath, ...(opts.specPath ? { specPath: resolve(opts.specPath) } : {}) });
+    const { config } = built.bundle;
+    const notes = [];
+    let problems = built.problems;
+    if (config.events) {
+        const expected = missingEventsCatalogProblem(config.events);
+        if (problems.includes(expected)) {
+            problems = problems.filter((p) => p !== expected);
+            notes.push(`events: the catalog of ${config.events} is built from the app's event definitions at deploy, so the preview has no Events section`);
+        }
+    }
+    notes.push("availability: each operation's availability is published by the deploy, so the preview shows none");
+    let specText;
+    try {
+        specText = readFileSync(built.specPath, "utf8");
+    }
+    catch {
+        specText = undefined;
+    }
+    return {
+        configPath: resolve(configPath),
+        specPath: built.specPath,
+        bundle: built.bundle,
+        ...(specText !== undefined ? { specText } : {}),
+        problems,
+        notes,
+    };
+}

package/dist/src/docs/preview.d.ts

@@ -0,0 +1,32 @@
+import { type DocsEngine } from "@mesh-tech/api-docs-engine";
+import { type PreviewSource } from "./preview-source.js";
+export declare const PREVIEW_CSS_PATH = "/docs-preview.css";
+export declare function previewCssFile(): string;
+export interface PreviewPage {
+    status: number;
+    html: string;
+}
+export declare function renderPreviewPage(input: {
+    source: PreviewSource;
+    engine: DocsEngine | undefined;
+    search: URLSearchParams;
+}): PreviewPage;
+export interface PreviewServer {
+    url: string;
+    port: number;
+    close(): Promise<void>;
+}
+export declare function startPreviewServer(args: {
+    configPath: string;
+    specPath?: string;
+    port: number;
+    cssFile?: string;
+}): Promise<PreviewServer>;
+export interface DocsPreviewOptions {
+    target: string;
+    port: string;
+    out?: string;
+    check: boolean;
+    spec?: string;
+}
+export declare function runDocsPreview(opts: DocsPreviewOptions): Promise<boolean>;

package/dist/src/docs/preview.js

@@ -0,0 +1,279 @@
+import { createServer } from "node:http";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import * as React from "react";
+import { renderToString } from "react-dom/server";
+import { buildEngine } from "@mesh-tech/api-docs-engine";
+import { docsPage } from "@mesh-tech/api-registry";
+import { DocsSourceView, locationFromParams, locationToParams } from "@mesh-tech/canvas-api-docs/docs";
+import { logError, logInfo, logSuccess, logWarn } from "../utils/log.js";
+import { findPackageRoot } from "../commands/local/stack.js";
+import { readPreviewSource, resolveDocsConfigPath } from "./preview-source.js";
+globalThis.React ??= React;
+export const PREVIEW_CSS_PATH = "/docs-preview.css";
+export function previewCssFile() {
+    return join(findPackageRoot(), "assets", "docs-preview.css");
+}
+function displayPath(file) {
+    const rel = relative(process.cwd(), file);
+    return rel && !rel.startsWith("..") && !isAbsolute(rel) ? rel : file;
+}
+function escapeHtml(text) {
+    return text.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+}
+function engineCache() {
+    let last;
+    return (specText) => {
+        if (specText === undefined)
+            return undefined;
+        if (last?.text === specText)
+            return last.engine;
+        let engine;
+        try {
+            engine = buildEngine(JSON.parse(specText));
+        }
+        catch {
+            engine = undefined;
+        }
+        last = { text: specText, engine };
+        return engine;
+    };
+}
+export function renderPreviewPage(input) {
+    const { source, engine, search } = input;
+    const { bundle } = source;
+    const title = bundle.config.title;
+    const notices = [];
+    let status = 200;
+    let location = locationFromParams(search, bundle);
+    const askedPage = search.get("page");
+    if (askedPage && !(location.kind === "page" && location.page === askedPage)) {
+        status = 404;
+        notices.push(`This source has no page "${askedPage}".`);
+    }
+    if (search.get("section") === "events" && !bundle.events) {
+        notices.push(bundle.config.events
+            ? `The events of ${bundle.config.events} are documented from the catalog the deploy builds; the preview has none.`
+            : "This source documents no events.");
+    }
+    let op;
+    if (location.kind === "reference" && location.op) {
+        op = engine?.getOp(location.op) ?? undefined;
+        if (!op) {
+            status = 404;
+            notices.push(`The spec has no operation "${location.op}".`);
+            location = { kind: "reference" };
+        }
+    }
+    const view = React.createElement(DocsSourceView, {
+        bundle,
+        title,
+        index: engine?.index() ?? [],
+        tags: engine?.tags() ?? [],
+        location,
+        onNavigate: () => { },
+        hrefFor: (loc) => `?${locationToParams(loc).toString()}`,
+        host: {
+            loadOp: (id) => {
+                const slice = engine?.getOp(id);
+                return slice ? Promise.resolve(slice) : Promise.reject(new Error(`no operation ${id}`));
+            },
+        },
+        ...(op ? { preloadedOp: op } : {}),
+    });
+    const heading = location.kind === "page"
+        ? (docsPage(bundle, location.page)?.title ?? title)
+        : location.kind === "events"
+            ? "Events"
+            : op
+                ? (op.summary ?? op.name)
+                : ((bundle.config.reference || undefined)?.label ?? "API Reference");
+    return {
+        status,
+        html: previewDocument({
+            title: heading === title ? title : `${heading} · ${title}`,
+            source,
+            notices,
+            body: renderToString(view),
+        }),
+    };
+}
+function previewChrome(source) {
+    const where = displayPath(source.configPath);
+    return `<header class="border-b bg-muted/40">
+<div class="mx-auto flex max-w-7xl flex-wrap items-center gap-x-4 gap-y-1 px-6 py-3 text-sm">
+<span class="font-semibold">Docs preview</span>
+<code class="font-mono text-xs text-muted-foreground">${escapeHtml(where)}</code>
+<span class="ml-auto text-xs text-muted-foreground" data-preview-try-it>Try-it runs in the Hub — this preview renders the docs only.</span>
+</div>
+</header>`;
+}
+function list(items) {
+    return `<ul class="mt-2 list-disc space-y-1 pl-5">${items.map((i) => `<li>${escapeHtml(i)}</li>`).join("")}</ul>`;
+}
+function previewDocument(input) {
+    const { source, notices } = input;
+    const problems = source.problems.length
+        ? `<section role="alert" class="mx-auto max-w-7xl px-6 pt-4" data-preview-problems="${source.problems.length}">
+<div class="rounded-md border border-destructive/50 bg-destructive/5 p-4 text-sm">
+<p class="font-semibold text-destructive">${source.problems.length} problem${source.problems.length === 1 ? "" : "s"} — the deploy refuses this source until ${source.problems.length === 1 ? "it is" : "they are"} fixed</p>
+${list(source.problems)}
+</div>
+</section>`
+        : "";
+    const noticeBlock = notices.length
+        ? `<section class="mx-auto max-w-7xl px-6 pt-4" data-preview-notices>
+<div class="rounded-md border bg-muted/40 p-4 text-sm">${list(notices)}</div>
+</section>`
+        : "";
+    const notes = source.notes.length
+        ? `<details class="mx-auto max-w-7xl px-6 pt-4 text-xs text-muted-foreground">
+<summary class="cursor-pointer select-none">What the preview does not show</summary>
+${list(source.notes)}
+</details>`
+        : "";
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(input.title)} — docs preview</title>
+<link rel="stylesheet" href="${PREVIEW_CSS_PATH}">
+</head>
+<body class="bg-background text-foreground antialiased">
+${previewChrome(source)}
+${problems}
+${noticeBlock}
+${notes}
+<main class="mx-auto max-w-7xl px-6 py-6">${input.body}</main>
+</body>
+</html>
+`;
+}
+function errorDocument(configPath, heading, message) {
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(heading)} — docs preview</title>
+<link rel="stylesheet" href="${PREVIEW_CSS_PATH}">
+</head>
+<body class="bg-background text-foreground antialiased">
+${previewChrome({ configPath })}
+<section role="alert" class="mx-auto max-w-7xl px-6 pt-4">
+<div class="rounded-md border border-destructive/50 bg-destructive/5 p-4 text-sm">
+<p class="font-semibold text-destructive">${escapeHtml(heading)}</p>
+<pre class="mt-2 whitespace-pre-wrap font-mono text-xs">${escapeHtml(message)}</pre>
+</div>
+</section>
+</body>
+</html>
+`;
+}
+export async function startPreviewServer(args) {
+    const engineFor = engineCache();
+    const cssFile = args.cssFile ?? previewCssFile();
+    const message = (error) => (error instanceof Error ? error.message : String(error));
+    const pageFor = (search) => {
+        let source;
+        try {
+            source = readPreviewSource(args.configPath, { specPath: args.specPath });
+        }
+        catch (error) {
+            return { status: 500, html: errorDocument(args.configPath, "The source cannot be read", message(error)) };
+        }
+        try {
+            return renderPreviewPage({ source, engine: engineFor(source.specText), search });
+        }
+        catch (error) {
+            return { status: 500, html: errorDocument(args.configPath, "The page cannot be rendered", message(error)) };
+        }
+    };
+    const handle = (req, res) => {
+        const url = new URL(req.url ?? "/", "http://localhost");
+        if (req.method !== "GET" && req.method !== "HEAD") {
+            res.writeHead(405, { allow: "GET, HEAD", "content-type": "text/plain; charset=utf-8" }).end("Method not allowed\n");
+            return;
+        }
+        if (url.pathname === PREVIEW_CSS_PATH) {
+            let css;
+            try {
+                css = readFileSync(cssFile, "utf8");
+            }
+            catch {
+                res.writeHead(404, { "content-type": "text/plain; charset=utf-8" }).end("Stylesheet not found\n");
+                return;
+            }
+            res.writeHead(200, { "content-type": "text/css; charset=utf-8", "cache-control": "no-cache" }).end(css);
+            return;
+        }
+        if (url.pathname !== "/") {
+            res.writeHead(404, { "content-type": "text/plain; charset=utf-8" }).end("Not found — the preview is served at /\n");
+            return;
+        }
+        const page = pageFor(url.searchParams);
+        res.writeHead(page.status, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" });
+        res.end(req.method === "HEAD" ? undefined : page.html);
+    };
+    const server = createServer(handle);
+    await new Promise((resolvePromise, reject) => {
+        server.once("error", (error) => {
+            reject(error.code === "EADDRINUSE"
+                ? new Error(`Port ${args.port} is already in use — pass --port <n> for another one (0 picks a free port)`)
+                : error);
+        });
+        server.listen(args.port, "127.0.0.1", () => resolvePromise());
+    });
+    const address = server.address();
+    const port = typeof address === "object" && address ? address.port : args.port;
+    return {
+        url: `http://localhost:${port}`,
+        port,
+        close: () => new Promise((resolvePromise) => server.close(() => resolvePromise())),
+    };
+}
+function reportProblems(source) {
+    if (source.problems.length === 0) {
+        logSuccess(`${source.bundle.config.title}: no problems`);
+    }
+    else {
+        logWarn(`${source.bundle.config.title}: ${source.problems.length} problem${source.problems.length === 1 ? "" : "s"} — the deploy refuses this source until ${source.problems.length === 1 ? "it is" : "they are"} fixed:`);
+        for (const problem of source.problems)
+            console.error(`    - ${problem}`);
+    }
+    for (const note of source.notes)
+        logInfo(`note — ${note}`);
+}
+export async function runDocsPreview(opts) {
+    const configPath = resolveDocsConfigPath(opts.target);
+    if (opts.check || opts.out) {
+        const source = readPreviewSource(configPath, { specPath: opts.spec });
+        reportProblems(source);
+        if (opts.out) {
+            const outPath = resolve(opts.out);
+            mkdirSync(dirname(outPath), { recursive: true });
+            writeFileSync(outPath, `${JSON.stringify(source.bundle, null, 2)}\n`);
+            logSuccess(`Docs source bundle → ${displayPath(outPath)}`);
+        }
+        return !opts.check || source.problems.length === 0;
+    }
+    const port = Number(opts.port);
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        throw new Error(`--port must be a port number (0 picks a free one), not "${opts.port}"`);
+    }
+    try {
+        reportProblems(readPreviewSource(configPath, { specPath: opts.spec }));
+    }
+    catch (error) {
+        logError(error instanceof Error ? error.message : String(error));
+    }
+    const server = await startPreviewServer({ configPath, ...(opts.spec ? { specPath: opts.spec } : {}), port });
+    logSuccess(`Docs preview → ${server.url}/  (re-reads ${displayPath(configPath)} on every request; Ctrl-C to stop)`);
+    await new Promise((resolvePromise) => {
+        const stop = () => void server.close().then(resolvePromise);
+        process.once("SIGINT", stop);
+        process.once("SIGTERM", stop);
+    });
+    return true;
+}

package/fragments/agents/AGENTS.md.hbs

@@ -18,33 +18,33 @@ Every mesh app follows 5 steps in `index.ts`:
 {{#if service}}
 ## API docs
 
-`api/openapi.json` is the API's OpenAPI document and `docs/pages/` holds its
-guides; `index.ts` declares a `mesh.apps.ApiDocs` site from both, reachable
-under `mesh dev`. **The Hub docs door is the path a docs site is published
-on**: declare the API as a `mesh.apps.AppApiSurface` whose `docs` block builds
-the site, and the Hub serves it through that door to the readers the app's
-`docs` role admits. Giving the site a hostname of its own instead — `ingress`,
-with the `auth` proxy and the in-page `authentication` sign-in — is the
-deprecated public shape: it still deploys, as the compatibility path for the
-sites that are public today, and warns at every `pulumi preview`. Nothing here
-writes one, and a new app has no reason to. A site declared on a
-`mesh.apps.VendorApiSurface` (a third-party core's raw reference) is read
-through the same door by holders of the Hub's `vendor-docs` add-on only —
-never by a partner — and declaring `audience: { roles: [] }` on one fails
-the deploy. Add `actAs: true` on an app surface to let Hub operators execute
-requests against the deployed API as one of the app's API keys from the Docs
-tab (the Hub's act-as playground) — the surface then verifies the Hub's
-signed assertion and runs the request as the key. `mesh app check` flags a
-docs site put on an ingress (`DOCS_SITE_PUBLIC`). A vendor surface's site is
-built from the enabled-ops cut of the core's spec, not the whole document, and
-a spec over 1 MiB is split into per-entity variants at build time
-(`docs.split: { above }` moves the threshold, `false` turns it off) — an app's
-own spec is already the shape it serves and gets neither. Keep the spec in
-step with the routes in
-`api/src/index.ts` — the site renders what the file says. Keep pages `.md`,
-not `.mdx`: a site an API surface declares is served by the Hub under its own
-origin, which carries data and never code, so an `.mdx` page fails that
-deploy (the bare `ApiDocs` here accepts it, which is exactly the trap).
+`api/openapi.json` is the API's OpenAPI document, `docs/pages/` holds its
+guides, and `docs/docs.yaml` arranges them — a **native docs source** (title,
+landing page, nav). **The Hub renders it on the app's Docs tab**, with its own
+components, once the API is declared as a `mesh.apps.AppApiSurface` whose
+`docs` block names it: `docs: { spec: "./api/openapi.json", config:
+"./docs/docs.yaml" }`. No docs site, container or door is built, and no app
+code reaches the Hub. Run `mesh docs preview docs` to see it as the Hub shows
+it, with every problem the deploy would refuse (`--check` for CI). A page's
+front-matter `title` is its heading, so a page never opens with its own `#`
+heading, and pages are `.md` — Markdown data, never code. An image is a PNG,
+JPEG, GIF or WebP file under `docs/pages/`, referenced relatively
+(`![Flow](img/flow.png)`): it is bundled with the source and rendered from
+those bytes, while an external image is never loaded. Under
+`mesh dev --local`, `package.json`'s `mesh.docs` publishes the same source to
+the local Hub's Docs tab.
+
+A `docs` block that builds a Zudoku site instead (`pages`, `landingPage`,
+`playground`, `audience`, `site`) is **deprecated**: it deploys, with a preview
+warning, for one more minor release and is then removed with the Hub docs
+door. `mesh docs convert --spec … --pages … --landing … --fix-pages` writes the
+`docs.yaml` from such a block and prints the edit; `mesh app check` names it
+(`DOCS_SITE_DEPRECATED`), and a site on a hostname of its own
+(`DOCS_SITE_PUBLIC`). Add `actAs: true` on an app surface to let Hub operators
+execute requests against the deployed API as one of the app's API keys from
+the Docs tab (the Hub's act-as playground) — the surface then verifies the
+Hub's signed assertion and runs the request as the key. Keep the spec in step
+with the routes in `api/src/index.ts` — the docs render what the file says.
 {{/if}}
 
 {{#if temporal}}

package/fragments/base/README.md.hbs

@@ -4,8 +4,11 @@ A Mesh app for tenant `{{tenant}}`. The Pulumi program is `index.ts`; run it
 locally with `mesh dev`, deploy it with `mesh deploy up`.
 {{#if service}}
 
-The API's reference site is built by the platform from `api/openapi.json` and
-the guides in `docs/pages/` — this README is its landing page.
+The API's docs are `api/openapi.json` and the guides in `docs/pages/`, arranged
+by `docs/docs.yaml` — a native docs source, which the Hub renders on the app's
+Docs tab once an API surface names it. `mesh docs preview docs` shows it
+locally, and `mesh dev --local` publishes it to the local Hub's Docs tab
+(`mesh.docs` in `package.json`).
 {{/if}}
 
 ## The version this app reports

package/fragments/base/index.ts.hbs

@@ -199,23 +199,23 @@ const worker = new mesh.apps.TemporalWorker("worker", {
 {{#if service}}
 
 // =============================================================================
-// Docs — the API's reference site, built by the platform from the spec and
-// the guides in docs/pages/ (this README is its landing page — `landingPage`
-// names another file, or `false` — and every guide is listed after it, in
-// path order). The Hub docs door is the path a docs site is published on:
-// here the site is reachable under `mesh dev`, and to publish it you declare
-// the API as a `mesh.apps.AppApiSurface` whose `docs` block builds this same
-// site (`docs: { spec, pages }`) — the Hub then serves it through that door.
-// A site given a hostname of its own instead (`ingress`, with the `auth`
-// proxy and the in-page `authentication` sign-in) is the deprecated public
-// shape: it still deploys, for the sites that are public today, and warns at
-// every preview. This declaration names none of it, and a new app needs
-// none. The site's readers hold this app's `docs` project role: declare the
-// role on the ZitadelAppIdentity and grant it from Access → Users; that same
-// role is what the Hub reads when a partner holding the Hub's `docs:<tenant>`
-// role opens this app's Docs tab, and the app then appears in their Apps list.
-// `mesh app check` flags a docs site put on an ingress instead
-// (`DOCS_SITE_PUBLIC`). Declaring `actAs: true`
+// Docs — the spec (api/openapi.json) and the guides in docs/pages/, arranged
+// by docs/docs.yaml: a native docs source. To publish it, declare the API as
+// a `mesh.apps.AppApiSurface` whose docs block names it —
+// `docs: { spec: "./api/openapi.json", config: "./docs/docs.yaml" }` — and
+// the Hub renders it on the app's Docs tab itself: no docs site, container
+// or door. `mesh docs preview docs` shows it locally, with every problem the
+// deploy would refuse, and under `mesh dev --local` the app's package.json
+// (`mesh.docs`) publishes it to the local Hub's Docs tab. A docs block that builds a
+// site instead (`pages`, `landingPage`, `playground`, `audience`) is
+// deprecated — `mesh docs convert` moves one, and `mesh app check` names it
+// (`DOCS_SITE_DEPRECATED`); a site given a hostname of its own (`ingress`,
+// with the `auth` proxy and the in-page `authentication` sign-in) is the
+// older public shape (`DOCS_SITE_PUBLIC`). The readers hold this app's
+// `docs` project role: declare the role on the ZitadelAppIdentity and grant
+// it from Access → Users; that same role is what the Hub reads when a
+// partner holding the Hub's `docs:<tenant>` role opens this app's Docs tab,
+// and the app then appears in their Apps list. Declaring `actAs: true`
 // on that same surface opens the Hub's act-as playground: an operator picks
 // one of this app's API keys on the Docs tab and the Hub executes the request
 // against the deployed API as that key, over the cluster network, with a
@@ -230,19 +230,6 @@ const worker = new mesh.apps.TemporalWorker("worker", {
 // `externalService`; its registry entry publishes the name, and the Hub reads
 // the app's Core connection from the vendor's shared health measurement.
 // =============================================================================
-
-new mesh.apps.ApiDocs("docs", {
-  env,
-  sources: { openapi: "./api/openapi.json" },
-  pages: "./docs/pages",
-  serverUrl: api.url,
-  zudoku: {
-    metadata: {
-      title: "{{titleCase name}} API",
-      description: "HTTP API for {{titleCase name}}",
-    },
-  },
-});
 {{/if}}
 
 // =============================================================================

package/fragments/base/package.json.hbs

@@ -29,5 +29,8 @@
 {{/if}}
     "tsx": "{{#if workspaceDeps}}catalog:{{else}}{{tsxRange}}{{/if}}",
     "typescript": "{{#if workspaceDeps}}catalog:{{else}}{{typescriptRange}}{{/if}}"
-  }
+  }{{#if service}},
+  "mesh": {
+    "docs": { "config": "docs/docs.yaml", "service": "api" }
+  }{{/if}}
 }

package/fragments/service/api/openapi.json.hbs

@@ -3,7 +3,7 @@
   "info": {
     "title": "{{titleCase name}} API",
     "version": "0.0.1",
-    "description": "HTTP API for {{titleCase name}}. This document is what the docs site renders — keep it in step with api/src/index.ts."
+    "description": "HTTP API for {{titleCase name}}. This document is the API reference of the app's docs source (docs/docs.yaml) — keep it in step with api/src/index.ts."
   },
   "paths": {
     "/": {

package/fragments/service/docs/docs.yaml.hbs

@@ -0,0 +1,10 @@
+# The {{titleCase name}} API's docs source: the guides under pages/ and the API
+# reference from the spec, as data the Hub renders on the app's Docs tab once
+# an API surface names this file (docs: { spec, config }). Check it with
+# `mesh docs preview docs`.
+title: {{titleCase name}} API
+spec: ../api/openapi.json
+pages: pages
+landing: getting-started
+reference:
+  label: API Reference

package/fragments/service/docs/pages/getting-started.md.hbs

@@ -2,15 +2,12 @@
 title: Getting started
 ---
 
-# Getting started with the {{titleCase name}} API
-
-Guides for this API live in `docs/pages/` as Markdown and are published next to
-the reference generated from `api/openapi.json`. Add a page per topic — each
-is listed in the sidebar after the README landing page, in path order, under
-the `title` in its front matter; the platform builds the site on every deploy.
-Keep pages as `.md`, not `.mdx`: a
-site an API surface declares is also read inside the Hub (the docs door),
-which serves data, never code — an `.mdx` page fails that deploy.
+Guides for the {{titleCase name}} API live in `docs/pages/` as Markdown and are
+published next to the reference generated from `api/openapi.json`; add a page
+per topic and list it in `docs/docs.yaml`'s `nav`. A page's `title` in its
+front matter is also its heading, so a page does not open with its own `#`
+heading. Keep pages as `.md`, not `.mdx`: the Hub renders them as Markdown
+data and never runs code. `mesh docs preview docs` shows the result.
 
 ## Calling the API
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mesh-tech/mesh-cli",
-  "version": "0.36.0",
+  "version": "0.37.0",
   "description": "CLI for Mesh platform development utilities",
   "type": "module",
   "license": "UNLICENSED",
@@ -42,11 +42,13 @@
   },
   "devDependencies": {
     "@mesh-tech/agent-contracts": "0.2.0",
-    "@mesh-tech/tsconfig": "2.37.0",
+    "@mesh-tech/tsconfig": "2.38.0",
     "@mesh-tech/workflow-viz": "0.3.1",
     "@tanstack/intent": "^0.3.6",
     "@types/node": "^20.0.0",
-    "tsx": "^4.20.4"
+    "@types/react": "^19.1.8",
+    "@types/react-dom": "^19.1.6",
+    "tailwindcss": "^4.2.2"
   },
   "dependencies": {
     "@aws-sdk/client-route-53": "^3.700.0",
@@ -61,9 +63,23 @@
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
     "handlebars": "^4.7.8",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "react-markdown": "^10.1.0",
+    "rehype-highlight": "^7.0.2",
+    "remark-gfm": "^4.0.1",
+    "tsx": "^4.20.4",
     "yaml": "^2.8.1",
     "zod": "^4.2.1"
   },
+  "peerDependencies": {
+    "mermaid": "^11.12.2"
+  },
+  "peerDependenciesMeta": {
+    "mermaid": {
+      "optional": true
+    }
+  },
   "optionalDependencies": {
     "@aws-sdk/client-s3": "^3.864.0",
     "@temporalio/client": "^1.17.0",