@nanisoft/prism-mcp-server 0.2.0 → 0.4.0

package/dist/render.js

@@ -1,156 +1,433 @@
-/**
- * The markdown every tool answers with — the corpus is Markdown, so JSON
- * envelopes would only add tokens and quoting (ADR-0004 §2). All of these are
- * pure string builders over already-resolved data; lookup/search logic lives
- * elsewhere. Result text always prints the next call to make (§7).
- */
-import { ITEM_KINDS } from './lookup.js';
-/** The one import rule every description and every miss carries. */
-export const IMPORT_RULE = "Always import from '@nanisoft/prism-ui', never from antd directly.";
-const KIND_LABEL = { component: 'component', block: 'block', page: 'page' };
-const KIND_HEADING = { component: 'Components', block: 'Blocks', page: 'Pages' };
-const plural = (count, noun) => (count === 1 ? `1 ${noun}` : `${count} ${noun}s`);
-/**
- * `list_items` — the cold-start catalog. The header line carries the corpus
- * version (mismatch detection) and, when the bundler supplies one, the build
- * date; pass-throughs are marked with their antd base so the delegation seam
- * is visible before any per-item call.
- */
-export function catalogMarkdown(docs, kind, built) {
-    const counts = new Map(ITEM_KINDS.map((entry) => [entry, docs.items.filter((item) => item.kind === entry).length]));
-    const summary = ITEM_KINDS.map((entry) => plural(counts.get(entry) ?? 0, KIND_LABEL[entry])).join(', ');
-    const lines = [`Prism ${docs.prismVersion} — ${summary}${built ? ` (built ${built})` : ''}`, ''];
+import { STORE_SECTION_TITLES, STORE_SECTIONS, } from '@nanisoft/prism-llms';
+import { IMPORT_RULE, NO_INVENTION_RULE, SURFACE_RULE } from './rules.js';
+import { TOKEN_GROUPS } from './vocab.js';
+/* -------------------------------------------------------------------------- */
+/* Result helpers                                                             */
+/* -------------------------------------------------------------------------- */
+const text = (value) => ({ content: [{ type: 'text', text: value }] });
+const error = (value) => ({
+    content: [{ type: 'text', text: value }],
+    isError: true,
+});
+function fence(code, language = 'tsx') {
+    return `\`\`\`${language}\n${code.replace(/\r\n/g, '\n').replace(/\n$/, '')}\n\`\`\``;
+}
+function kindLabel(kind) {
+    if (kind === 'component')
+        return 'Component';
+    if (kind === 'block')
+        return 'Block';
+    return 'Page';
+}
+function countKinds(items) {
+    const counts = { component: 0, block: 0, page: 0 };
+    for (const item of items)
+        counts[item.kind] += 1;
+    return counts;
+}
+/* -------------------------------------------------------------------------- */
+/* Lookup                                                                     */
+/* -------------------------------------------------------------------------- */
+/** Every exact name or slug match in the optional kind, case-insensitively. */
+export function matchesFor(store, name, kind) {
+    const needle = name.trim().toLowerCase();
+    const pool = store.items.filter((item) => !kind || item.kind === kind);
+    const byName = pool.filter((item) => item.name.toLowerCase() === needle);
+    if (byName.length > 0)
+        return byName;
+    return pool.filter((item) => item.slug.toLowerCase() === needle);
+}
+function suggestItems(store, name, kind) {
+    const needle = name.trim().toLowerCase();
+    const pool = store.items.filter((item) => !kind || item.kind === kind);
+    return pool
+        .map((item) => {
+        const candidate = `${item.name} ${item.slug}`.toLowerCase();
+        let score = candidate.includes(needle) ? 3 : 0;
+        let common = 0;
+        while (common < item.name.length && common < needle.length && item.name[common]?.toLowerCase() === needle[common]) {
+            common += 1;
+        }
+        score += common;
+        return { item, score };
+    })
+        .filter((entry) => entry.score > 0)
+        .sort((a, b) => b.score - a.score || a.item.name.localeCompare(b.item.name))
+        .slice(0, 3)
+        .map((entry) => entry.item);
+}
+function itemMiss(store, name, kind) {
+    const suggestions = suggestItems(store, name, kind);
+    const did = suggestions.length > 0
+        ? ` Did you mean ${suggestions.map((item) => `\`${item.name}\` (${item.kind})`).join(', ')}?`
+        : '';
+    return error(`No Prism item named \`${name}\`${kind ? ` of kind \`${kind}\`` : ''}.${did} Browse the catalogue with \`list_items\` or search with \`search_docs\`.`);
+}
+function resolveItem(store, name, kind) {
+    const matches = matchesFor(store, name, kind);
+    if (matches.length === 0)
+        return { ok: false, result: itemMiss(store, name, kind) };
+    if (matches.length > 1) {
+        const kinds = matches.map((item) => `\`${item.kind}\``).join(', ');
+        return {
+            ok: false,
+            result: error(`\`${name}\` matches more than one kind: ${kinds}. Pass \`kind\` to disambiguate.`),
+        };
+    }
+    const item = matches[0];
+    if (!item)
+        return { ok: false, result: itemMiss(store, name, kind) };
+    return { ok: true, item };
+}
+function renderListItem(item) {
+    const category = item.kind === 'component' && item.category ? ` _(${item.category})_` : '';
+    return `- **${item.name}** - ${item.description}${category}`;
+}
+export function renderListItems(store, args, built) {
+    const { kind, category } = args;
+    if (category && kind && kind !== 'component') {
+        return error(`\`category\` is a Component-only field. Kind \`${kind}\` has no categories; omit \`category\` or pass \`kind: "component"\`.`);
+    }
+    const counts = countKinds(store.items);
+    const stamp = built ? ` (built ${built})` : '';
+    const header = `# Prism ${store.version} - ${counts.component} components, ${counts.block} blocks, ${counts.page} pages${stamp}`;
+    const filters = [];
     if (kind)
-        lines.push(`Filtered to ${KIND_LABEL[kind]}s — omit \`kind\` for the whole catalog.`, '');
-    for (const entry of ITEM_KINDS) {
-        if (kind && entry !== kind)
-            continue;
-        const inKind = docs.items.filter((item) => item.kind === entry);
-        lines.push(`## ${KIND_HEADING[entry]}`, '');
-        if (inKind.length === 0) {
-            lines.push(`No ${KIND_LABEL[entry]}s in this build.`, '');
+        filters.push(`kind = \`${kind}\``);
+    if (category)
+        filters.push(`category = \`${category}\``);
+    const note = filters.length > 0 ? `\n\nFiltered to ${filters.join(', ')}.` : '';
+    let items = store.items;
+    if (kind)
+        items = items.filter((item) => item.kind === kind);
+    if (category) {
+        items = items.filter((item) => item.kind === 'component' && item.category === category);
+    }
+    const groups = [
+        { kind: 'component', heading: 'Components' },
+        { kind: 'block', heading: 'Blocks' },
+        { kind: 'page', heading: 'Pages' },
+    ];
+    const sections = [];
+    for (const group of groups) {
+        const groupItems = items.filter((item) => item.kind === group.kind);
+        if (groupItems.length === 0)
             continue;
+        sections.push(`## ${group.heading}\n\n${groupItems.map(renderListItem).join('\n')}`);
+    }
+    if (sections.length === 0) {
+        const label = kind ? `${groupPlural(kind)}` : 'items';
+        sections.push(`No ${label} in this build.`);
+    }
+    const footer = `Use \`get_item_doc\`, \`get_item_props\` or \`search_docs\` to read an item.\n\nImport rule: ${IMPORT_RULE}\n\nSurface rule: ${SURFACE_RULE}`;
+    return text([`${header}${note}`, ...sections, footer].join('\n\n'));
+}
+function groupPlural(kind) {
+    if (kind === 'component')
+        return 'components';
+    if (kind === 'block')
+        return 'blocks';
+    return 'pages';
+}
+export function renderItemDoc(store, args) {
+    const resolved = resolveItem(store, args.name, args.kind);
+    if (!resolved.ok)
+        return resolved.result;
+    const item = resolved.item;
+    return text(`${item.doc.trimEnd()}\n\n---\n\nPublic import: \`${item.importLine}\`\n\nImport rule: ${IMPORT_RULE}`);
+}
+/* -------------------------------------------------------------------------- */
+/* get_item_props                                                             */
+/* -------------------------------------------------------------------------- */
+export function renderItemProps(store, args) {
+    const resolved = resolveItem(store, args.name, args.kind);
+    if (!resolved.ok)
+        return resolved.result;
+    const item = resolved.item;
+    // Both sections, when both are recorded. A Block and a Page publish an
+    // interface section AND a composition section, and reading one while calling
+    // the other "no own props" is the type-level lie the published surface exists
+    // to prevent: the store carried both and the tool reported one and denied the
+    // other.
+    if (item.props && item.composition) {
+        return text(`# ${item.name} - props and composition\n\n## Props\n\n${item.props}\n\n## Composition\n\n${item.composition}\n\n` +
+            `This is the complete public Prism API for \`${item.name}\`; internal primitive props are not a consumer contract.\n\n` +
+            `Import rule: ${IMPORT_RULE}`);
+    }
+    if (item.props) {
+        return text(`# ${item.name} - props\n\n${item.props}\n\nThis is the complete public Prism API for \`${item.name}\`; internal primitive props are not a consumer contract.\n\nImport rule: ${IMPORT_RULE}`);
+    }
+    if (item.composition) {
+        return text(`# ${item.name} - composition\n\nThe public surface of this ${kindLabel(item.kind)} is the composition below.\n\n${item.composition}\n\nImport rule: ${IMPORT_RULE}`);
+    }
+    return error(`No props or composition are recorded for \`${item.name}\`. Use \`get_item_doc\` for its documentation.`);
+}
+/* -------------------------------------------------------------------------- */
+/* get_item_source                                                            */
+/* -------------------------------------------------------------------------- */
+export function renderItemSource(store, args) {
+    const resolved = resolveItem(store, args.name, args.kind);
+    if (!resolved.ok)
+        return resolved.result;
+    const item = resolved.item;
+    if (!item.example) {
+        return error(`No demo source is recorded for \`${item.name}\`. Use \`get_item_doc\` for its documentation.`);
+    }
+    return text([
+        `# ${item.name} - example source`,
+        `Public import:\n\n${fence(item.importLine)}`,
+        `${item.example.title}\n\n${fence(item.example.code)}`,
+        'This demo is self-contained: it imports only `@nanisoft/prism-ui/*` or `react`, and exposes one default export.',
+        `Import rule: ${IMPORT_RULE}`,
+    ].join('\n\n'));
+}
+export function renderThemeDoc(store, args) {
+    const pack = args.pack ?? 'default';
+    const mode = args.mode ?? 'light';
+    const group = args.group;
+    if (!store.tokens.packs.includes(pack)) {
+        return error(`Unknown pack \`${pack}\`. Valid packs: ${store.tokens.packs.join(', ')}.`);
+    }
+    if (!store.tokens.modes.includes(mode)) {
+        return error(`Unknown mode \`${mode}\`. Valid modes: ${store.tokens.modes.join(', ')}.`);
+    }
+    if (group !== undefined && !TOKEN_GROUPS.includes(group)) {
+        return error(`Unknown group \`${group}\`. Valid groups: ${TOKEN_GROUPS.join(', ')}.`);
+    }
+    const preamble = [
+        `Packs: ${store.tokens.packs.join(', ')}.`,
+        `Modes: ${store.tokens.modes.join(', ')}.`,
+        `Queryable groups: ${TOKEN_GROUPS.join(', ')}.`,
+        // The attribute is not root-only, and the correction is in this string
+        // because this string is the agent-facing surface: a tool that prints the
+        // pack's radius below and tells the reader the attribute belongs on `<html>`
+        // is worse than a tool that says nothing, because the reader then places a
+        // boundary where a boundary is not needed and believes a subtree cannot carry
+        // one. A boundary moves BOTH axes beneath it, and radius is the axis people
+        // forget.
+        'Selection: `data-pack="<id>"` on any element makes that element and its subtree a theme boundary. ' +
+            'It wears the mode of the nearest ancestor carrying `.dark`, and carries that class itself only to hold a fixed mode. ' +
+            'A boundary also moves the pack corner radius, which is why a boundary belongs on a fully-rounded element, on one carrying no radius utility, or on a shape with no radius concept.',
+    ].join('\n\n');
+    const footer = `Import rule: ${IMPORT_RULE}\n\n${NO_INVENTION_RULE}`;
+    if (group === undefined || group === 'semantic') {
+        const theme = store.tokens.themes.find((entry) => entry.pack === pack && entry.mode === mode);
+        if (!theme) {
+            return error(`No resolved values are recorded for pack \`${pack}\` in mode \`${mode}\`.`);
+        }
+        const lines = theme.semantic.map((token) => `--${token.token}: ${token.value}`).join('\n');
+        return text([`# Prism theme: ${pack} / ${mode}`, preamble, lines, footer].join('\n\n'));
+    }
+    const scale = store.tokens.scales[group];
+    const lines = scale
+        .map((token) => token.binding
+        ? `--${token.token}: ${token.value} (binding: --${token.binding})`
+        : `--${token.token}: ${token.value}`)
+        .join('\n');
+    const close = group === 'breakpoint'
+        ? '\n\nThe scale closes with `--breakpoint-xl: initial` and `--breakpoint-2xl: initial`.'
+        : '';
+    return text([`# Prism token scale: ${group}`, preamble, `${lines}${close}`, footer].join('\n\n'));
+}
+/* -------------------------------------------------------------------------- */
+/* list_pages / get_page                                                      */
+/* -------------------------------------------------------------------------- */
+export function renderListPages(store) {
+    // The Sections and the label each is read under are both the Store's own, so a
+    // Section added to the content tree appears here from the same edit that added
+    // it there. A hand-kept list of the three prose Sections is what would leave
+    // the Changelogs out of the one tool that exists to list pages.
+    const groups = STORE_SECTIONS.map((section) => ({
+        section,
+        heading: STORE_SECTION_TITLES[section],
+        pages: store.pages.filter((page) => page.section === section),
+    }));
+    const counted = groups.map((group) => `${group.pages.length} ${group.heading.toLowerCase()}`);
+    const header = `# Prism pages - ${store.pages.length} pages (${counted.join(', ')})`;
+    const sections = groups
+        .filter((group) => group.pages.length > 0)
+        .map((group) => `## ${group.heading}\n\n${group.pages
+        .map((page) => `- **${page.title}** - ${page.description} (\`${page.url}\`)`)
+        .join('\n')}`);
+    const footer = `Use \`get_page({ url })\` to read one, or \`get_changelog\` for a published package's changes.\n\nImport rule: ${IMPORT_RULE}`;
+    return text([header, ...sections, footer].join('\n\n'));
+}
+function suggestPages(store, normalized) {
+    const needle = normalized.replace(/^\//, '').toLowerCase();
+    return store.pages
+        .map((page) => {
+        const candidate = `${page.section}/${page.slug}`.toLowerCase();
+        let score = candidate.includes(needle) || needle.includes(candidate) ? 3 : 0;
+        let common = 0;
+        while (common < candidate.length && common < needle.length && candidate[common] === needle[common]) {
+            common += 1;
+        }
+        score += common;
+        return { page, score };
+    })
+        .filter((entry) => entry.score > 0)
+        .sort((a, b) => b.score - a.score || a.page.title.localeCompare(b.page.title))
+        .slice(0, 3)
+        .map((entry) => entry.page);
+}
+export function renderPage(store, args) {
+    const raw = args.url.trim();
+    const withoutMd = raw.endsWith('.md') ? raw.slice(0, -3) : raw;
+    const normalized = withoutMd.startsWith('/') ? withoutMd : `/${withoutMd}`;
+    if (/^\/(components|blocks|pages)\//.test(normalized)) {
+        return error(`\`${args.url}\` is a catalogue item URL, not a documentation page. Use \`get_item_doc\` or \`get_item_source\` for an item.`);
+    }
+    const page = store.pages.find((entry) => entry.url === normalized || entry.mirror === raw || entry.url === withoutMd);
+    if (!page) {
+        const suggestions = suggestPages(store, normalized);
+        const did = suggestions.length > 0
+            ? ` Did you mean ${suggestions.map((entry) => `\`${entry.url}\``).join(', ')}?`
+            : '';
+        return error(`No Prism page at \`${args.url}\`.${did} List the pages with \`list_pages\`.`);
+    }
+    return text(`${page.markdown.trimEnd()}\n\n---\n\nMirror: \`${page.mirror}\`\n\nImport rule: ${IMPORT_RULE}`);
+}
+export function searchCandidates(store, kind) {
+    const candidates = [];
+    if (kind === undefined || kind !== 'doc') {
+        for (const item of store.items) {
+            if (kind !== undefined && item.kind !== kind)
+                continue;
+            candidates.push({
+                title: item.name,
+                kind: item.kind,
+                url: item.url,
+                snippet: item.description,
+                content: item.doc,
+                followUp: `get_item_doc({ name: "${item.name}", kind: "${item.kind}" })`,
+            });
+        }
+    }
+    if (kind === undefined || kind === 'doc') {
+        for (const page of store.pages) {
+            candidates.push({
+                title: page.title,
+                kind: 'doc',
+                url: page.url,
+                snippet: page.description,
+                content: page.markdown,
+                followUp: `get_page({ url: "${page.url}" })`,
+            });
         }
-        for (const item of inKind)
-            lines.push(catalogEntry(item));
-        lines.push('');
     }
-    lines.push('---', '', `Next: \`get_item_doc\` for an item's full doc, \`get_item_props\` for its Prism-added props, \`search_docs\` to search everything. Items marked _(extends antd …)_ are pass-throughs — their inherited antd props live in the antd MCP. ${IMPORT_RULE}`);
-    return lines.join('\n');
+    return candidates;
 }
-function catalogEntry(item) {
-    const base = item.antdBase ? ` _(extends antd ${item.antdBase})_` : '';
-    return `- **${item.name}** — ${item.description}${base}`;
+export function searchDocs(store, args) {
+    const limit = Math.min(Math.max(args.limit ?? 5, 1), 10);
+    const terms = args.query
+        .toLowerCase()
+        .split(/\s+/)
+        .filter(Boolean);
+    const hits = [];
+    for (const candidate of searchCandidates(store, args.kind)) {
+        const name = candidate.title.toLowerCase();
+        const description = candidate.snippet.toLowerCase();
+        const content = candidate.content.toLowerCase();
+        const matched = new Set();
+        let score = 0;
+        let matchesAll = true;
+        for (const term of terms) {
+            let termScore = 0;
+            if (name.includes(term)) {
+                matched.add('name');
+                termScore += 5;
+            }
+            if (description.includes(term)) {
+                matched.add('description');
+                termScore += 3;
+            }
+            if (content.includes(term)) {
+                matched.add('content');
+                termScore += 1;
+            }
+            if (termScore === 0) {
+                matchesAll = false;
+                break;
+            }
+            score += termScore;
+        }
+        if (!matchesAll)
+            continue;
+        hits.push({ ...candidate, matched: [...matched], score });
+    }
+    hits.sort((a, b) => b.score - a.score || a.title.localeCompare(b.title));
+    const top = hits.slice(0, limit);
+    if (top.length === 0) {
+        return text(`No matches for \`${args.query}\`${args.kind ? ` in kind \`${args.kind}\`` : ''}. It searches item names, descriptions and page bodies. Try a shorter query, or browse with \`list_items\` and \`list_pages\`.`);
+    }
+    const header = `# Search: ${args.query}\n\n${top.length} hit${top.length === 1 ? '' : 's'}${args.kind ? ` in kind \`${args.kind}\`` : ''}.`;
+    const lines = top.map((hit) => `- **${hit.title}** (${hit.kind}) - ${hit.snippet} [matched: ${hit.matched.join(', ')}] -> \`${hit.followUp}\``);
+    const footer = `Read the body with the follow-up call, or repeat a narrower search.\n\nImport rule: ${IMPORT_RULE}`;
+    return text([header, lines.join('\n'), footer].join('\n\n'));
 }
 /**
- * `get_item_doc` — the generator's page verbatim (usage rules, props, example,
- * the `> Extends:` seam), plus at most one steering footer built from the data.
+ * Every published package that ships a changelog, named and routed, for a miss.
+ *
+ * The miss carries the whole set rather than a "did you mean", because the
+ * argument is a free string rather than a closed enum: an agent that guessed a
+ * package name gets the real names in one round trip instead of guessing again.
  */
-export function itemDocMarkdown(item) {
-    const pointers = [];
-    if (item.props)
-        pointers.push(`Prism-added props only: \`get_item_props { "name": "${item.name}" }\``);
-    if ((item.examples?.length ?? 0) > 0)
-        pointers.push(`Copyable example source: \`get_item_source { "name": "${item.name}" }\``);
-    if (item.antdBase)
-        pointers.push(`Inherited antd props and demos: antd MCP \`antd_info ${item.antdBase}\``);
-    return pointers.length > 0 ? `${item.doc}\n\n---\n\n${pointers.join(' · ')}` : item.doc;
+function changelogMiss(store, wanted) {
+    const available = store.changelogs.length === 0
+        ? 'This build carries no package changelogs.'
+        : `Prism publishes a changelog for: ${store.changelogs
+            .map((entry) => `\`${entry.package}\` (\`${entry.route}\`)`)
+            .join(', ')}.`;
+    return error(`No Prism changelog for \`${wanted}\`. ${available} Read one with \`get_changelog({ package })\`.`);
+}
+/** The entry a package name, unscoped name or route segment resolves to. */
+function changelogFor(store, wanted) {
+    const needle = wanted.trim().toLowerCase();
+    return store.changelogs.find((entry) => entry.package.toLowerCase() === needle || entry.slug.toLowerCase() === needle);
 }
 /**
- * `get_item_props` — only the Prism-added delta. A pass-through's answer *is*
- * the routing instruction (ADR-0004 §4: plasma's `_No additional props…_` line
- * is the switch-servers signal).
+ * One published package's changelog, or one version entry of it.
+ *
+ * The text is the package's own file, byte for byte, because the Store carries
+ * the bytes rather than a summary of them. A generated summary would drift the
+ * moment a release was published, which is the one thing a changelog cannot do:
+ * a breaking change in a published package has to be discoverable by an agent
+ * that never saw the release notes anywhere else. The reference design system
+ * shipped a breaking module-system change that no agent using it could find, and
+ * the reason is precisely that its corpus had no changelog and no tool to return
+ * one.
+ *
+ * The footers state where the text is published, so an agent holding an older
+ * corpus can still fetch the same bytes over HTTP, and which versions exist, so
+ * one call can pick the next `version` to ask for.
  */
-export function itemPropsMarkdown(item) {
-    if (item.props) {
-        return item.antdBase
-            ? `${item.props}\n\n---\n\nBeyond these Prism-added props, the inherited antd surface lives in the antd MCP (\`antd_info ${item.antdBase}\`). ${IMPORT_RULE}`
-            : item.props;
-    }
-    if (item.antdBase) {
-        return [
-            `## ${item.name} — props`,
-            '',
-            `${item.name} — antd ${item.antdBase}, unchanged. Props: use the antd MCP (\`antd_info ${item.antdBase}\`). ${IMPORT_RULE}`,
-            '',
-            '_No additional props beyond the antd base component._',
-        ].join('\n');
-    }
-    return [
-        `## ${item.name} — props`,
-        '',
-        `\`${item.name}\` documents no Prism-added props in this build. Its usage rules and example live in the full doc: \`get_item_doc { "name": "${item.name}" }\`.`,
-    ].join('\n');
-}
-/** `get_item_source` — the documented example, verbatim, in one fenced block. */
-export function itemSourceMarkdown(item, example) {
-    const labelled = example.title ? `${example.title} (\`${example.slug}\`)` : `\`${example.slug}\``;
-    const others = (item.examples ?? []).filter((entry) => entry.slug !== example.slug).map((entry) => `\`${entry.slug}\``);
-    const lines = [
-        `# ${item.name} — example source: ${labelled}`,
-        '',
-        '```tsx',
-        example.code,
-        '```',
-        '',
-        `Verbatim from the docs demo — self-contained (imports only \`@nanisoft/prism-ui\` and \`react\`). ${IMPORT_RULE}`,
-    ];
-    if (others.length > 0)
-        lines.push('', `Other examples: ${others.join(', ')} — pass \`example\` to pick one.`);
-    return lines.join('\n');
-}
-/** `get_theme_doc` — the pack × mode atom verbatim, plus the sibling slugs. */
-export function themeMarkdown(theme, all) {
-    const others = all.filter((entry) => entry.slug !== theme.slug).map((entry) => `\`${entry.slug}\``);
-    const footer = others.length > 0 ? `\n\n---\n\nOther theme atoms: ${others.join(', ')} — pass \`pack\`/\`mode\` to switch.` : '';
-    return `${theme.markdown}${footer}`;
-}
-/** `list_pages` — the site's llms.txt body as an index. */
-export function pagesIndexMarkdown(pages, baseUrl) {
-    const lines = ['# Prism docs pages', ''];
-    if (pages.length === 0) {
-        lines.push('This build carries no docs pages — the catalog is the whole corpus for now.');
-    }
-    else {
-        lines.push(`Found ${pages.length}:`, '');
-        for (const page of pages) {
-            lines.push(`- **${page.title}** — \`${page.url}\`${page.description ? ` — ${page.description}` : ''}`);
-            lines.push(`  → \`get_page { "url": "${page.url}" }\``);
-        }
-        lines.push('');
-    }
-    lines.push('---', '', `Full site index: ${baseUrl}/llms.txt · Catalog: \`list_items\`.`);
-    return lines.join('\n');
-}
-/** `get_page` — the prerendered page verbatim, cited back to the site. */
-export function pageMarkdown(page, baseUrl) {
-    return `${page.markdown}\n\n---\n\nSource: ${baseUrl}${page.url} · More: \`list_pages\`.`;
-}
-/** `search_docs` — ranked hits, each printing its own next call. */
-export function searchResultsMarkdown(query, hits) {
-    const lines = [`# Search results for "${query}"`, ''];
-    if (hits.length === 0) {
-        lines.push('No matches.', '', 'Try broader terms — or browse: `list_items` for the catalog, `list_pages` for docs pages.');
-        return lines.join('\n');
-    }
-    lines.push(`Found ${hits.length} result(s):`, '');
-    hits.forEach((hit, index) => {
-        if (index > 0)
-            lines.push('---', '');
-        lines.push(`## ${hit.title} (${hit.kind})`, hit.snippet, `→ \`${hit.followUp}\`${hit.followUp.startsWith('get_item_source') ? ' for the copyable source.' : ''}`);
-    });
-    return lines.join('\n');
-}
-/** A lookup miss: the closest names plus the browse pointer, as an error. */
-export function missMarkdown(target, suggestions, browseHint) {
-    const lines = [`\`${target}\` not found.`];
-    if (suggestions.length > 0)
-        lines.push('', `Did you mean: ${suggestions.map((name) => `**${name}**`).join(', ')}?`);
-    lines.push('', browseHint);
-    return lines.join('\n');
-}
-/** A name hit whose `kind` argument pointed somewhere else. */
-export function kindMismatchMarkdown(item, requested) {
-    return `\`${item.name}\` is a ${item.kind}, not a ${requested}. Retry with \`kind\` omitted — or with \`"${item.kind}"\`.`;
-}
-//# sourceMappingURL=render.js.map
+export function renderChangelog(store, args) {
+    const changelog = changelogFor(store, args.package);
+    if (changelog === undefined)
+        return changelogMiss(store, args.package);
+    const versions = changelog.versions.join(', ');
+    const published = `Published at \`${changelog.route}\` and its mirror \`${changelog.route}.md\`, byte for byte from the package.`;
+    if (args.version === undefined) {
+        return text([
+            `# ${changelog.package} - changelog`,
+            `Versions, newest first as the file records them: ${versions}.`,
+            changelog.text.trimEnd(),
+            '---',
+            `${published} Ask for one entry with \`get_changelog({ package: "${changelog.package}", version: "<version>" })\`.`,
+            `Import rule: ${IMPORT_RULE}`,
+        ].join('\n\n'));
+    }
+    const wanted = args.version.trim();
+    const release = changelog.releases.find((entry) => entry.version === wanted);
+    if (release === undefined) {
+        return error(`\`${wanted}\` is not a version \`${changelog.package}\` records. It records: ${versions}. ` +
+            `Read the whole changelog with \`get_changelog({ package: "${changelog.package}" })\`.`);
+    }
+    return text([
+        `# ${changelog.package} - ${release.version}`,
+        release.body,
+        '---',
+        `${published} Every version: ${versions}. Read the whole changelog with \`get_changelog({ package: "${changelog.package}" })\`.`,
+        `Import rule: ${IMPORT_RULE}`,
+    ].join('\n\n'));
+}

package/dist/rules.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The three rules every tool description carries.
+ *
+ * Ticket 13 requires each description to state the import rule and the surface
+ * rule, so a client that reads only `tools/list` learns the contract without a
+ * round-trip. The no-invention rule is repeated by `get_theme_doc`.
+ */
+export declare const IMPORT_RULE = "Import from `@nanisoft/prism-ui/components/<slug>`, `./blocks/<slug>` or `./pages/<slug>`. Base UI and internal paths are never a consumer import.";
+export declare const SURFACE_RULE = "Prism answers its complete owned surface; Base UI and native elements are internal implementation details.";
+export declare const NO_INVENTION_RULE = "Motion and typography are named by token, never by a millisecond or a `cubic-bezier` literal.";
+/** Compose a tool description: the intro, then the two standing rules. */
+export declare function describe(intro: string): string;

package/dist/rules.js

@@ -0,0 +1,14 @@
+/**
+ * The three rules every tool description carries.
+ *
+ * Ticket 13 requires each description to state the import rule and the surface
+ * rule, so a client that reads only `tools/list` learns the contract without a
+ * round-trip. The no-invention rule is repeated by `get_theme_doc`.
+ */
+export const IMPORT_RULE = 'Import from `@nanisoft/prism-ui/components/<slug>`, `./blocks/<slug>` or `./pages/<slug>`. Base UI and internal paths are never a consumer import.';
+export const SURFACE_RULE = 'Prism answers its complete owned surface; Base UI and native elements are internal implementation details.';
+export const NO_INVENTION_RULE = 'Motion and typography are named by token, never by a millisecond or a `cubic-bezier` literal.';
+/** Compose a tool description: the intro, then the two standing rules. */
+export function describe(intro) {
+    return `${intro}\n\nImport rule: ${IMPORT_RULE}\n\nSurface rule: ${SURFACE_RULE}`;
+}