@adaptabletools/adaptable-mcp 0.0.0-stage → 0.1.0-canary.1

package/dist/core/context/resolve.js

@@ -0,0 +1,85 @@
+/**
+ * Context resolution (plan §7.2). Precedence, first hit wins:
+ *   1. explicit `--major` / `--framework`
+ *   2. session pin — reserved for a future remote transport; never set by the CLI or the stdio server
+ *   3. detection — the nearest project declaring `@adaptabletools/*` (workspace-aware)
+ *   4. `latest` from the docs manifest (or the snapshot offline), with a mandatory warning
+ */
+import { resolve as resolvePath } from 'node:path';
+import { MIGRATION_FLOOR } from '../constants.js';
+import { docsHostFor } from '../docs/hosts.js';
+import { CapabilityError } from '../envelope.js';
+import { findProjects } from './projects.js';
+const docsHostInfo = (latest) => ({
+    latestMajor: latest?.adaptableMajor,
+    docsHosts: latest?.docsHosts,
+});
+/** A0.2 placeholder; A0.6 replaces it with the hosted-manifest / snapshot lookup. */
+export const noLatest = async () => undefined;
+function assertSupportedMajor(major) {
+    if (!Number.isInteger(major) || major < MIGRATION_FLOOR) {
+        throw new CapabilityError('VERSION_NOT_SUPPORTED', `AdapTable ${major} is not a supported major version.`, `Pass --major with a value of ${MIGRATION_FLOOR} or later.`);
+    }
+}
+export async function resolveContext(options, deps = {}) {
+    const cwd = resolvePath(options.cwd ?? process.cwd());
+    const warnings = [];
+    if (options.major !== undefined) {
+        assertSupportedMajor(options.major);
+    }
+    const projects = findProjects(cwd);
+    const project = projects.length === 1 ? projects[0] : undefined;
+    let source;
+    let major;
+    let version;
+    let latest;
+    if (options.major !== undefined) {
+        source = 'explicit';
+        major = options.major;
+        version = project?.adaptable.major === major ? project.adaptable.installed : undefined;
+    }
+    else if (deps.session) {
+        source = 'session';
+        major = deps.session.adaptableMajor;
+        version = project?.adaptable.major === major ? project.adaptable.installed : undefined;
+    }
+    else if (projects.length > 1) {
+        throw new CapabilityError('MULTIPLE_PROJECTS', `${projects.length} projects at or below ${cwd} depend on AdapTable: ${projects.map((p) => p.path).join(', ')}.`, 'Run from one project folder, or pass --cwd <folder> (or --major to skip detection).');
+    }
+    else if (project?.adaptable.major !== undefined) {
+        source = 'detected';
+        major = project.adaptable.major;
+        version = project.adaptable.installed;
+        if (!version && project.adaptable.range) {
+            warnings.push(`${project.adaptable.name} is declared (${project.adaptable.range}) but not installed at ${project.path}; using major ${major} from the declared range. Install dependencies so checks use the exact version.`);
+        }
+    }
+    else {
+        source = 'latest';
+        latest = await (deps.latest ?? noLatest)();
+        major = latest?.adaptableMajor;
+        version = latest?.adaptableVersion;
+        const where = project
+            ? `${project.adaptable.name} at ${project.path} declares "${project.adaptable.range}", which names no major`
+            : `No @adaptabletools/* dependency found at or above ${cwd}`;
+        warnings.push(major !== undefined
+            ? `${where}; assuming AdapTable ${major}, the latest release. Pass --major to override.`
+            : `${where}, and the latest release could not be determined (offline without a manifest snapshot). Pass --major.`);
+    }
+    const framework = options.framework ?? deps.session?.framework ?? project?.framework;
+    if (!options.docsHost && !latest) {
+        latest = await (deps.latest ?? noLatest)();
+    }
+    const docsHost = docsHostFor(major, docsHostInfo(latest), options.docsHost ?? process.env.ADAPTABLE_MCP_DOCS_HOST);
+    const context = {
+        ...(version !== undefined ? { adaptableVersion: version } : {}),
+        ...(major !== undefined ? { adaptableMajor: major } : {}),
+        ...(project?.agGrid?.installed ? { agGridVersion: project.agGrid.installed } : {}),
+        ...(framework ? { framework } : {}),
+        source,
+        docsHost,
+        codeSource: version !== undefined && project?.adaptable.installed === version ? 'installed' : 'none',
+    };
+    return { context, warnings, project };
+}
+//# sourceMappingURL=resolve.js.map

package/dist/core/context/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../../../src/core/context/resolve.ts"],"names":[],"mappings":"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"}

package/dist/core/docs/areas.js

@@ -0,0 +1,22 @@
+/** `--area` of `docs list|search` (plan §8.3) → the `pages.json` categories it covers */
+export const AREAS = ['handbook', 'dev-guide', 'reference', 'tutorial', 'support', 'all'];
+const AREA_CATEGORIES = {
+    handbook: ['handbook', 'ui', 'adaptable-ql', 'framework', 'integrations', 'adaptable-server'],
+    'dev-guide': ['dev-guide'],
+    reference: ['api', 'technical-reference'],
+    tutorial: ['getting-started', 'demos', 'documentation'],
+    support: ['support', 'release-notes'],
+};
+/** Categories for an area; undefined for `all` */
+export function categoriesFor(area) {
+    return area && area !== 'all' ? AREA_CATEGORIES[area] : undefined;
+}
+export function areaOf(category) {
+    for (const [area, categories] of Object.entries(AREA_CATEGORIES)) {
+        if (categories.includes(category)) {
+            return area;
+        }
+    }
+    return 'handbook';
+}
+//# sourceMappingURL=areas.js.map

package/dist/core/docs/areas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"areas.js","sourceRoot":"","sources":["../../../src/core/docs/areas.ts"],"names":[],"mappings":"AAAA,yFAAyF;AACzF,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,KAAK,CAAU,CAAC;AAGnG,MAAM,eAAe,GAA2C;IAC9D,QAAQ,EAAE,CAAC,UAAU,EAAE,IAAI,EAAE,cAAc,EAAE,WAAW,EAAE,cAAc,EAAE,kBAAkB,CAAC;IAC7F,WAAW,EAAE,CAAC,WAAW,CAAC;IAC1B,SAAS,EAAE,CAAC,KAAK,EAAE,qBAAqB,CAAC;IACzC,QAAQ,EAAE,CAAC,iBAAiB,EAAE,OAAO,EAAE,eAAe,CAAC;IACvD,OAAO,EAAE,CAAC,SAAS,EAAE,eAAe,CAAC;CACtC,CAAC;AAEF,kDAAkD;AAClD,MAAM,UAAU,aAAa,CAAC,IAAsB;IAClD,OAAO,IAAI,IAAI,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACpE,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,QAAgB;IACrC,KAAK,MAAM,CAAC,IAAI,EAAE,UAAU,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,eAAe,CAAuC,EAAE,CAAC;QACvG,IAAI,UAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YAClC,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/dist/core/docs/cache.js

@@ -0,0 +1,133 @@
+/**
+ * The docs corpus cache (plan §8.3 "Freshness"): `pages.json` and `llms-full.txt`
+ * live under `docs/<host>/<files hash>/`, where the hash is taken from the
+ * manifest's `files` block, so a deploy that changes the docs changes the folder
+ * and nothing else triggers a download. Offline, the newest cached corpus for the
+ * host is used with a warning.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { hostCacheDir } from '../compat/manifest.js';
+import { splitPages, splitSections } from './corpus.js';
+import { docsNotAvailable, resolveDocsSource } from './hosts.js';
+import { SectionIndex } from './search.js';
+const CORPUS_FILES = { full: 'llms-full.txt', pages: 'pages.json' };
+const FETCH_TIMEOUT_MS = 60_000;
+/** Short hash of the manifest's file hashes: the corpus folder name */
+export function corpusKey(manifest) {
+    const hashes = Object.keys(manifest.files)
+        .sort()
+        .map((name) => `${name}:${manifest.files[name].sha256}`)
+        .join('\n');
+    return createHash('sha256').update(hashes).digest('hex').slice(0, 16);
+}
+export function corpusDir(host, manifest) {
+    return join(hostCacheDir(host), corpusKey(manifest));
+}
+const isComplete = (dir) => Object.values(CORPUS_FILES).every((file) => existsSync(join(dir, file)));
+/** The newest complete corpus folder cached for a host, by modification time */
+function newestCachedCorpus(host) {
+    const root = hostCacheDir(host);
+    let entries;
+    try {
+        entries = readdirSync(root);
+    }
+    catch {
+        return undefined;
+    }
+    return entries
+        .map((name) => join(root, name))
+        .filter((dir) => statSync(dir).isDirectory() && isComplete(dir))
+        .sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs)[0];
+}
+async function download(host, path) {
+    const url = `${host}${path}`;
+    const response = await fetch(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+    if (!response.ok) {
+        throw new Error(`${url} returned ${response.status}`);
+    }
+    return response.text();
+}
+function buildCorpus(source, origin, dir) {
+    const pagesJson = readFileSync(join(dir, CORPUS_FILES.pages), 'utf8');
+    const llmsFull = readFileSync(join(dir, CORPUS_FILES.full), 'utf8');
+    const pageMeta = new Map(JSON.parse(pagesJson).map((meta) => [meta.routePath, meta]));
+    const pages = new Map();
+    const sections = [];
+    for (const page of splitPages(llmsFull, pageMeta)) {
+        pages.set(page.routePath, page);
+        sections.push(...splitSections(page, sections.length));
+    }
+    return {
+        manifest: source.manifest,
+        host: source.host,
+        origin,
+        pages,
+        pageMeta,
+        sections,
+        index: new SectionIndex(sections),
+    };
+}
+async function loadUncached(source, options) {
+    const warnings = [...source.warnings];
+    const { host, manifest } = source;
+    const files = manifest.files ?? {};
+    if (!files.pages?.path || !files.llmsFullTxt?.path) {
+        throw docsNotAvailable(host, 'The docs manifest lists no pages.json / llms-full.txt');
+    }
+    const dir = corpusDir(host, manifest);
+    if (isComplete(dir)) {
+        return { corpus: buildCorpus(source, 'cache', dir), warnings };
+    }
+    if (options.offline) {
+        const fallback = newestCachedCorpus(host);
+        if (!fallback) {
+            throw docsNotAvailable(host, '--offline and no docs corpus is cached');
+        }
+        warnings.push(`--offline: using the most recent docs corpus cached for ${host}, which predates the current manifest.`);
+        return { corpus: buildCorpus(source, 'cache', fallback), warnings };
+    }
+    try {
+        const [pagesJson, llmsFull] = await Promise.all([download(host, files.pages.path), download(host, files.llmsFullTxt.path)]);
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(join(dir, CORPUS_FILES.pages), pagesJson);
+        writeFileSync(join(dir, CORPUS_FILES.full), llmsFull);
+        writeFileSync(join(dir, 'manifest.json'), JSON.stringify(manifest, null, 2));
+    }
+    catch (error) {
+        const fallback = newestCachedCorpus(host);
+        const reason = error instanceof Error ? error.message : String(error);
+        if (!fallback) {
+            throw docsNotAvailable(host, `Could not download the docs corpus: ${reason}`);
+        }
+        warnings.push(`Could not download the docs corpus (${reason}); using the most recent one cached for ${host}.`);
+        return { corpus: buildCorpus(source, 'cache', fallback), warnings };
+    }
+    return { corpus: buildCorpus(source, 'host', dir), warnings };
+}
+const corpora = new Map();
+/**
+ * The corpus for a major (or the current host): host resolution, manifest
+ * re-validation, cache lookup or download. Memoised per host + manifest hash
+ * within the process; the manifest re-validation is governed by `revalidateTtlMs`.
+ */
+export async function loadCorpus(options = {}) {
+    const source = await resolveDocsSource(options);
+    const key = `${source.host}/${corpusKey(source.manifest)}`;
+    let loaded = corpora.get(key);
+    if (!loaded) {
+        loaded = loadUncached(source, options);
+        loaded.catch(() => corpora.delete(key));
+        corpora.set(key, loaded);
+    }
+    const result = await loaded;
+    // the memoised load carries its own warnings; the fresh source resolution may add new ones
+    const warnings = [...new Set([...result.warnings, ...source.warnings])];
+    return { corpus: result.corpus, warnings };
+}
+/** Test hook: forget memoised corpora */
+export function resetCorpusCache() {
+    corpora.clear();
+}
+//# sourceMappingURL=cache.js.map

package/dist/core/docs/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../../src/core/docs/cache.ts"],"names":[],"mappings":"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"}

package/dist/core/docs/capabilities.js

@@ -0,0 +1,381 @@
+/**
+ * `adaptable docs list|search|get|demos|demo` · MCP `search_docs`, `get_doc`, `get_demo` (plan §8.3).
+ */
+import { z } from 'zod';
+import { registerCapability } from '../capabilities.js';
+import { CapabilityError, ok } from '../envelope.js';
+import { AREAS, areaOf, categoriesFor } from './areas.js';
+import { loadCorpus } from './cache.js';
+import { filterFramework, FRAMEWORKS } from './corpus.js';
+import { estimateTokens, extractHeading, findPage, outline, slugOf, suggestSlugs, trimDemos, truncateAtHeadings, } from './get-page.js';
+import { closestDemoNames, demosOnPage, loadDemoMarkdown, loadDemosIndex, parseDemoMarkdown, selectFiles } from './demos.js';
+import { pageUrl } from './hosts.js';
+const DEFAULT_MAX_TOKENS = 8_000;
+const EXCERPT_CHARS = 240;
+async function corpusFor(ctx) {
+    const { context, warnings } = await ctx.resolveContext();
+    const loaded = await loadCorpus({
+        major: context.adaptableMajor,
+        offline: ctx.globals.offline,
+        docsHost: ctx.globals.docsHost,
+    });
+    return { corpus: loaded.corpus, context, warnings: [...warnings, ...loaded.warnings] };
+}
+const frameworkOf = (ctx, explicit, detected) => explicit ?? ctx.globals.framework ?? detected;
+// ---------------------------------------------------------------- docs list
+const ListPage = z.object({
+    slug: z.string(),
+    title: z.string(),
+    area: z.enum(AREAS),
+    category: z.string(),
+    description: z.string().optional(),
+    /** `technical-reference-*` page for a feature, when one exists */
+    technicalReference: z.string().optional(),
+    demos: z.array(z.string()).optional(),
+    children: z.array(z.string()).optional(),
+});
+const ListOutput = z.object({
+    /** `section` when pages.json carries the sidebar sections, else `category` */
+    groupedBy: z.enum(['section', 'category']),
+    sections: z.array(z.object({ name: z.string(), pages: z.array(ListPage) })),
+    pageCount: z.number(),
+});
+function featureKey(meta) {
+    // handbook-layouts → layouts; technical-reference-layouts → layouts
+    const match = meta.routePath.match(/^\/docs\/(?:handbook|technical-reference|dev-guide|ui)-([a-z0-9-]+)$/);
+    return match?.[1];
+}
+export function buildList(corpus, options) {
+    const metas = [...corpus.pageMeta.values()];
+    const hasSections = metas.some((m) => m.section);
+    const categories = categoriesFor(options.area);
+    const technicalRefs = new Map();
+    for (const meta of metas) {
+        if (meta.category === 'technical-reference') {
+            const key = featureKey(meta);
+            if (key) {
+                technicalRefs.set(key, slugOf(meta.routePath));
+            }
+        }
+    }
+    const children = new Map();
+    for (const meta of metas) {
+        if (meta.parent) {
+            children.set(meta.parent, [...(children.get(meta.parent) ?? []), slugOf(meta.routePath)]);
+        }
+    }
+    const groups = new Map();
+    for (const meta of metas) {
+        if (categories && !categories.includes(meta.category)) {
+            continue;
+        }
+        // reference entries (700+ generated pages) are listed only when asked for explicitly
+        if (!options.area && meta.category === 'api') {
+            continue;
+        }
+        const group = hasSections ? (meta.section ?? meta.category) : meta.category;
+        if (options.section && group.toLowerCase() !== options.section.toLowerCase()) {
+            continue;
+        }
+        const key = featureKey(meta);
+        const page = {
+            slug: slugOf(meta.routePath),
+            title: meta.title,
+            area: areaOf(meta.category),
+            category: meta.category,
+            ...(meta.description ? { description: meta.description } : {}),
+            ...(key && meta.category !== 'technical-reference' && technicalRefs.has(key)
+                ? { technicalReference: technicalRefs.get(key) }
+                : {}),
+            ...(meta.demos?.length ? { demos: meta.demos } : {}),
+            ...(children.has(meta.routePath) ? { children: children.get(meta.routePath) } : {}),
+        };
+        groups.set(group, [...(groups.get(group) ?? []), page]);
+    }
+    const sections = [...groups.entries()]
+        .map(([name, pages]) => ({ name, pages: pages.sort((a, b) => a.slug.localeCompare(b.slug)) }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+    return {
+        groupedBy: hasSections ? 'section' : 'category',
+        sections,
+        pageCount: sections.reduce((n, s) => n + s.pages.length, 0),
+    };
+}
+registerCapability({
+    name: 'docs-list',
+    description: 'Lists the docs pages for the project’s AdapTable version, grouped by sidebar section: the feature index.',
+    cli: { command: ['docs', 'list'] },
+    mcp: null,
+    input: z.object({
+        section: z.string().optional().describe('Only this sidebar section (or category)'),
+        area: z.enum(AREAS).optional().describe('handbook | dev-guide | reference | tutorial | support | all; reference pages are listed only when asked for'),
+    }),
+    output: ListOutput,
+    run: async (input, ctx) => {
+        const { corpus, context, warnings } = await corpusFor(ctx);
+        return ok(buildList(corpus, input), { resolvedContext: context, warnings });
+    },
+    markdown: (data) => data.sections
+        .map((section) => `## ${section.name} (${section.pages.length})\n\n${section.pages
+        .map((p) => `- \`${p.slug}\` — ${p.title}${p.technicalReference ? ` · ref \`${p.technicalReference}\`` : ''}${p.demos?.length ? ` · demos: ${p.demos.join(', ')}` : ''}`)
+        .join('\n')}`)
+        .join('\n\n'),
+});
+// ---------------------------------------------------------------- docs search
+const SearchResult = z.object({
+    slug: z.string(),
+    title: z.string(),
+    section: z.string(),
+    heading: z.string(),
+    url: z.string(),
+    tokens: z.number(),
+    excerpt: z.string(),
+    score: z.number(),
+});
+const SearchOutput = z.object({ query: z.string(), results: z.array(SearchResult) });
+export function runSearch(corpus, query, options) {
+    const categories = categoriesFor(options.area);
+    const hits = corpus.index.search(query, {
+        framework: options.framework,
+        categories,
+        // release notes describe old syntax; they are searched only when asked for
+        excludeCategories: categories ? undefined : ['release-notes'],
+        limit: options.limit ?? 8,
+    });
+    return {
+        query,
+        results: hits.map(({ section, score }) => {
+            const meta = corpus.pageMeta.get(section.routePath);
+            const text = section.text.replace(/\s+/g, ' ').trim();
+            return {
+                slug: slugOf(section.routePath),
+                title: section.pageTitle,
+                section: meta?.section ?? section.category,
+                heading: section.headings.join(' > '),
+                url: pageUrl(corpus.host, section.routePath, options.framework),
+                tokens: estimateTokens(section.text),
+                excerpt: text.length > EXCERPT_CHARS ? `${text.slice(0, EXCERPT_CHARS)}…` : text,
+                score: Math.round(score * 100) / 100,
+            };
+        }),
+    };
+}
+registerCapability({
+    name: 'docs-search',
+    description: 'Searches the docs for the project’s AdapTable version and framework; returns matching sections with slugs and URLs.',
+    cli: { command: ['docs', 'search'], positionals: ['query'] },
+    mcp: { tool: 'search_docs' },
+    input: z.object({
+        query: z.string().min(1).describe('What to look for: exact API names (LayoutApi, GROUP_BY) or a plain question'),
+        limit: z.number().int().min(1).max(50).optional().describe('Results to return (default 8)'),
+        area: z.enum(AREAS).optional().describe('Restrict to one docs area; release notes are searched only with support or all'),
+        framework: z.enum(FRAMEWORKS).optional().describe('Defaults to the detected framework'),
+    }),
+    output: SearchOutput,
+    run: async (input, ctx) => {
+        const { corpus, context, warnings } = await corpusFor(ctx);
+        const framework = frameworkOf(ctx, input.framework, context.framework);
+        return ok(runSearch(corpus, input.query, { limit: input.limit, area: input.area, framework }), {
+            resolvedContext: context,
+            warnings,
+        });
+    },
+    markdown: (data) => data.results.length
+        ? data.results
+            .map((r, i) => `${i + 1}. **${r.title}**${r.heading ? ` › ${r.heading}` : ''} — \`${r.slug}\` (${r.section}, ~${r.tokens} tokens)\n   ${r.url}\n   ${r.excerpt}`)
+            .join('\n\n')
+        : `No matches for "${data.query}".`,
+});
+// ---------------------------------------------------------------- docs get
+const GotPage = z.object({
+    slug: z.string(),
+    title: z.string(),
+    url: z.string(),
+    markdown: z.string(),
+    tokens: z.number(),
+    truncated: z.boolean(),
+    /** headings cut by --max-tokens; pass one to --section to read it */
+    omitted: z.array(z.string()),
+    /** demo blocks replaced by a one-line summary (use `docs demo` or --full) */
+    demosTrimmed: z.number(),
+    outline: z.array(z.string()),
+});
+const GetOutput = z.object({
+    pages: z.array(GotPage),
+    /** requested pages that do not exist, each with the closest slugs */
+    missing: z.array(z.object({ requested: z.string(), suggestions: z.array(z.string()) })),
+});
+export function getPages(corpus, requested, options) {
+    const pages = [];
+    const missing = [];
+    for (const request of requested) {
+        const page = findPage(corpus, request);
+        if (!page) {
+            missing.push({ requested: request, suggestions: suggestSlugs(corpus, request) });
+            continue;
+        }
+        let markdown = filterFramework(page.markdown, options.framework);
+        let demosTrimmed = 0;
+        if (!options.full) {
+            const trimmed = trimDemos(markdown);
+            markdown = trimmed.markdown;
+            demosTrimmed = trimmed.trimmed;
+        }
+        const fullOutline = outline(markdown);
+        if (options.section) {
+            const section = extractHeading(markdown, options.section);
+            if (section === undefined) {
+                throw new CapabilityError('NOT_FOUND', `No heading matching "${options.section}" in ${slugOf(page.routePath)}.`, `Headings on this page: ${fullOutline.map((h) => h.replace(/^#+\s*/, '')).join(' · ') || '(none)'}`);
+            }
+            markdown = section;
+        }
+        const truncation = options.full
+            ? { markdown, truncated: false, omitted: [] }
+            : truncateAtHeadings(markdown, options.maxTokens ?? DEFAULT_MAX_TOKENS);
+        pages.push({
+            slug: slugOf(page.routePath),
+            title: page.title,
+            url: pageUrl(corpus.host, page.routePath, options.framework),
+            markdown: truncation.markdown,
+            tokens: estimateTokens(truncation.markdown),
+            truncated: truncation.truncated,
+            omitted: truncation.omitted,
+            demosTrimmed,
+            outline: fullOutline,
+        });
+    }
+    if (!pages.length && missing.length) {
+        const [first] = missing;
+        throw new CapabilityError('NOT_FOUND', `No docs page "${first.requested}"${missing.length > 1 ? ` (and ${missing.length - 1} more)` : ''}.`, first.suggestions.length
+            ? `Closest pages: ${first.suggestions.join(', ')}. Use \`adaptable docs search\` to find others.`
+            : 'Use `adaptable docs search "<topic>"` or `adaptable docs list` to find the slug.');
+    }
+    return { pages, missing };
+}
+registerCapability({
+    name: 'docs-get',
+    description: 'Reads docs pages as Markdown for the project’s version and framework; one section with --section, demo code trimmed unless --full.',
+    cli: { command: ['docs', 'get'], positionals: ['pages'] },
+    mcp: { tool: 'get_doc' },
+    input: z.object({
+        pages: z
+            .array(z.string().min(1))
+            .min(1)
+            .describe('Slugs (handbook-layouts), reference names (LayoutApi), routes (/docs/…) or docs URLs'),
+        framework: z.enum(FRAMEWORKS).optional().describe('Defaults to the detected framework'),
+        section: z.string().optional().describe('Return only the section under this heading'),
+        maxTokens: z.number().int().min(200).optional().describe(`Cut at a heading boundary above this many tokens (default ${DEFAULT_MAX_TOKENS})`),
+        full: z.boolean().optional().describe('Inline demo code and never truncate'),
+    }),
+    output: GetOutput,
+    run: async (input, ctx) => {
+        const { corpus, context, warnings } = await corpusFor(ctx);
+        const framework = frameworkOf(ctx, input.framework, context.framework);
+        const data = getPages(corpus, input.pages, { ...input, framework });
+        for (const miss of data.missing) {
+            warnings.push(`No docs page "${miss.requested}"${miss.suggestions.length ? `; closest: ${miss.suggestions.join(', ')}` : ''}.`);
+        }
+        return ok(data, { resolvedContext: context, warnings });
+    },
+    markdown: (data) => data.pages
+        .map((p) => {
+        const notes = [];
+        if (p.truncated) {
+            notes.push(`truncated at a heading boundary; omitted: ${p.omitted.map((h) => h.replace(/^#+\s*/, '')).join(' · ')} — pass --section "<heading>" or --max-tokens`);
+        }
+        if (p.demosTrimmed) {
+            notes.push(`${p.demosTrimmed} demo${p.demosTrimmed > 1 ? 's' : ''} trimmed — \`docs demo <name>\` or --full`);
+        }
+        return `<!-- ${p.slug} · ${p.url}${notes.length ? ` · ${notes.join(' · ')}` : ''} -->\n\n${p.markdown}`;
+    })
+        .join('\n\n---\n\n'),
+});
+// ---------------------------------------------------------------- docs demos | docs demo
+const DemoSummary = z.object({
+    name: z.string(),
+    title: z.string(),
+    description: z.string(),
+    framework: z.string(),
+    files: z.array(z.string()),
+});
+registerCapability({
+    name: 'docs-demos',
+    description: 'Lists the demos embedded in a docs page, with the files each demo owns.',
+    cli: { command: ['docs', 'demos'], positionals: ['page'] },
+    mcp: null,
+    input: z.object({
+        page: z.string().min(1).describe('Slug, route or URL of the page'),
+    }),
+    output: z.object({ page: z.string(), demos: z.array(DemoSummary) }),
+    run: async (input, ctx) => {
+        const { corpus, context, warnings } = await corpusFor(ctx);
+        const page = findPage(corpus, input.page);
+        if (!page) {
+            const suggestions = suggestSlugs(corpus, input.page);
+            throw new CapabilityError('NOT_FOUND', `No docs page "${input.page}".`, suggestions.length ? `Closest pages: ${suggestions.join(', ')}.` : 'Use `adaptable docs search` to find the slug.');
+        }
+        const index = await loadDemosIndex(corpus, { offline: ctx.globals.offline });
+        const demos = demosOnPage(index, corpus, page.routePath).map(({ name, title, description, framework, files }) => ({
+            name,
+            title,
+            description,
+            framework,
+            files,
+        }));
+        return ok({ page: slugOf(page.routePath), demos }, { resolvedContext: context, warnings });
+    },
+    markdown: (data) => data.demos.length
+        ? data.demos
+            .map((d) => `- \`${d.name}\` — ${d.title}${d.description ? `: ${d.description}` : ''} (${d.framework}; files: ${d.files.join(', ') || 'none of its own'})`)
+            .join('\n')
+        : `No demos on \`${data.page}\`.`,
+});
+registerCapability({
+    name: 'docs-demo',
+    description: 'Returns one demo’s own files (adaptableOptions.ts by default; --files for others). Template files are never returned.',
+    cli: { command: ['docs', 'demo'], positionals: ['name'] },
+    mcp: { tool: 'get_demo' },
+    input: z.object({
+        name: z.string().min(1).describe('Demo name, as listed by `docs demos` or in the page'),
+        files: z.array(z.string()).optional().describe('File names or paths to return, e.g. columnDefs.ts rowData.ts'),
+    }),
+    output: z.object({
+        name: z.string(),
+        title: z.string(),
+        page: z.string().nullable(),
+        url: z.string().nullable(),
+        framework: z.string(),
+        files: z.array(z.object({ path: z.string(), language: z.string(), code: z.string() })),
+        /** every file the demo owns, for a follow-up --files */
+        available: z.array(z.string()),
+    }),
+    run: async (input, ctx) => {
+        const { corpus, context, warnings } = await corpusFor(ctx);
+        const index = await loadDemosIndex(corpus, { offline: ctx.globals.offline });
+        const demo = index.find((d) => d.name === input.name) ?? index.find((d) => d.name.toLowerCase() === input.name.toLowerCase());
+        if (!demo) {
+            const closest = closestDemoNames(index, input.name);
+            throw new CapabilityError('NOT_FOUND', `No demo named "${input.name}".`, closest.length ? `Closest demos: ${closest.join(', ')}.` : 'List a page’s demos with `adaptable docs demos <page>`.');
+        }
+        const markdown = await loadDemoMarkdown(corpus, demo, { offline: ctx.globals.offline });
+        const parsed = parseDemoMarkdown(markdown);
+        const { selected, unknown } = selectFiles(parsed, input.files);
+        for (const name of unknown) {
+            warnings.push(`Demo "${demo.name}" has no file "${name}"; it owns: ${parsed.map((f) => f.path).join(', ') || 'none'}.`);
+        }
+        return ok({
+            name: demo.name,
+            title: demo.title,
+            page: demo.page ? slugOf(demo.page) : null,
+            url: demo.page ? pageUrl(corpus.host, demo.page) : null,
+            framework: demo.framework,
+            files: selected,
+            available: parsed.map((f) => f.path),
+        }, { resolvedContext: context, warnings });
+    },
+    markdown: (data) => [
+        `<!-- demo ${data.name} (${data.framework})${data.url ? ` · ${data.url}` : ''} · files: ${data.available.join(', ')} -->`,
+        ...data.files.map((f) => `**\`${f.path}\`**\n\n\`\`\`${f.language}\n${f.code}\n\`\`\``),
+    ].join('\n\n'),
+});
+//# sourceMappingURL=capabilities.js.map