@atbas/m-mcp 0.1.0

package/dist/knowledge/corpus.d.ts

@@ -0,0 +1,15 @@
+import { type CorpusSource } from './source.js';
+import { type CorpusDocument, type DocumentSection } from './types.js';
+export declare function documentUri(docId: string, sectionId?: string): string;
+export interface KnowledgeCorpus {
+    readonly corpusVersion: string;
+    documents(): readonly CorpusDocument[];
+    document(docId: string): CorpusDocument;
+    findDocument(docId: string): CorpusDocument | undefined;
+    section(docId: string, sectionId: string): DocumentSection;
+    sections(): readonly DocumentSection[];
+    documentsForFlow(flowId: string): readonly CorpusDocument[];
+}
+/** Load and index the documentation corpus. Throws if it is malformed. */
+export declare function loadKnowledgeCorpus(source?: CorpusSource | string): KnowledgeCorpus;
+//# sourceMappingURL=corpus.d.ts.map

package/dist/knowledge/corpus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"corpus.d.ts","sourceRoot":"","sources":["../../src/knowledge/corpus.ts"],"names":[],"mappings":"AAEA,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,EAAuB,KAAK,cAAc,EAAyB,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AA4BnH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAErE;AA+DD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,SAAS,IAAI,SAAS,cAAc,EAAE,CAAC;IACvC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAAC;IACxC,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAAC;IACxD,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,eAAe,CAAC;IAC3D,QAAQ,IAAI,SAAS,eAAe,EAAE,CAAC;IACvC,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,cAAc,EAAE,CAAC;CAC7D;AAED,0EAA0E;AAC1E,wBAAgB,mBAAmB,CAAC,MAAM,GAAE,YAAY,GAAG,MAA8B,GAAG,eAAe,CAgE1G"}

package/dist/knowledge/corpus.js

@@ -0,0 +1,129 @@
+import { JazzCashConfigError, JazzCashNotFoundError } from '../errors.js';
+import { knowledgePath } from '../paths.js';
+import { toCorpusSource } from './source.js';
+import { documentIndexSchema } from './types.js';
+/**
+ * Loader for the curated documentation corpus in `knowledge/docs/`.
+ *
+ * Document metadata comes from `index.json`; sections are derived from the
+ * markdown headings themselves, so a heading and its index entry cannot drift
+ * apart. Every section is addressable as `jazzcash://docs/{docId}#{sectionId}`.
+ *
+ * Files arrive through a `CorpusSource`, so the same loader indexes a corpus
+ * that is not a directory on this machine.
+ */
+/** The manifest naming every document in the corpus. */
+const INDEX_ENTRY = 'index.json';
+/** Matches `## Section title {#section-id}`. */
+const SECTION_HEADING = /^##\s+(.+?)\s*\{#([a-z0-9-]+)\}\s*$/;
+/**
+ * Matches an anchored heading nested deeper than `##`.
+ *
+ * Only `##` headings become addressable sections, so an anchor on a `###`
+ * heading is a citation target that can never resolve. Rejecting it at load
+ * turns a silently broken link into a start-up failure.
+ */
+const NESTED_ANCHORED_HEADING = /^#{3,}\s+.+?\{#([a-z0-9-]+)\}\s*$/;
+export function documentUri(docId, sectionId) {
+    return sectionId === undefined ? `jazzcash://docs/${docId}` : `jazzcash://docs/${docId}#${sectionId}`;
+}
+function parseSections(metadata, markdown) {
+    const lines = markdown.split(/\r?\n/);
+    const sections = [];
+    const preambleLines = [];
+    let current;
+    const flush = () => {
+        if (current === undefined) {
+            return;
+        }
+        sections.push({
+            docId: metadata.docId,
+            sectionId: current.sectionId,
+            title: current.title,
+            text: current.body.join('\n').trim(),
+            uri: documentUri(metadata.docId, current.sectionId),
+        });
+    };
+    for (const line of lines) {
+        const nested = NESTED_ANCHORED_HEADING.exec(line);
+        if (nested !== null) {
+            throw new JazzCashConfigError(`Document ${metadata.docId} anchors "{#${nested[1] ?? ''}}" on a heading deeper than "##". Only "##" headings become addressable sections, so that anchor could never be cited. Promote the heading to "##".`);
+        }
+        const heading = SECTION_HEADING.exec(line);
+        if (heading !== null) {
+            flush();
+            current = { title: heading[1] ?? '', sectionId: heading[2] ?? '', body: [] };
+            continue;
+        }
+        if (current === undefined) {
+            preambleLines.push(line);
+        }
+        else {
+            current.body.push(line);
+        }
+    }
+    flush();
+    if (sections.length === 0) {
+        throw new JazzCashConfigError(`Document ${metadata.docId} declares no sections. Every section needs a heading of the form "## Title {#section-id}".`);
+    }
+    const duplicates = sections.map((section) => section.sectionId).filter((id, index, all) => all.indexOf(id) !== index);
+    if (duplicates.length > 0) {
+        throw new JazzCashConfigError(`Document ${metadata.docId} declares duplicate section anchors: ${[...new Set(duplicates)].join(', ')}. Anchors must be unique so citations resolve.`);
+    }
+    return { preamble: preambleLines.join('\n').trim(), sections };
+}
+/** Load and index the documentation corpus. Throws if it is malformed. */
+export function loadKnowledgeCorpus(source = knowledgePath('docs')) {
+    const files = toCorpusSource(source);
+    let indexJson;
+    try {
+        indexJson = JSON.parse(files.readText(INDEX_ENTRY));
+    }
+    catch (cause) {
+        throw new JazzCashConfigError(`Unable to read the documentation index at ${files.locate(INDEX_ENTRY)}.`, {
+            cause,
+        });
+    }
+    const parsed = documentIndexSchema.safeParse(indexJson);
+    if (!parsed.success) {
+        const issues = parsed.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`).join('; ');
+        throw new JazzCashConfigError(`The documentation index is invalid. ${issues}`);
+    }
+    const documents = parsed.data.documents.map((metadata) => {
+        const entry = `${metadata.docId}.md`;
+        let markdown;
+        try {
+            markdown = files.readText(entry);
+        }
+        catch (cause) {
+            throw new JazzCashConfigError(`Document ${metadata.docId} is listed in index.json but ${files.locate(entry)} could not be read.`, { cause });
+        }
+        const { preamble, sections } = parseSections(metadata, markdown);
+        return { metadata, preamble, sections, markdown };
+    });
+    const byId = new Map(documents.map((document) => [document.metadata.docId, document]));
+    const allSections = documents.flatMap((document) => document.sections);
+    return {
+        corpusVersion: parsed.data.corpusVersion,
+        documents: () => documents,
+        findDocument: (docId) => byId.get(docId),
+        document(docId) {
+            const document = byId.get(docId);
+            if (document === undefined) {
+                throw new JazzCashNotFoundError(`No document with id "${docId}". Available documents: ${[...byId.keys()].join(', ')}.`);
+            }
+            return document;
+        },
+        section(docId, sectionId) {
+            const document = this.document(docId);
+            const section = document.sections.find((entry) => entry.sectionId === sectionId);
+            if (section === undefined) {
+                throw new JazzCashNotFoundError(`Document "${docId}" has no section "${sectionId}". Available sections: ${document.sections.map((entry) => entry.sectionId).join(', ')}.`);
+            }
+            return section;
+        },
+        sections: () => allSections,
+        documentsForFlow: (flowId) => documents.filter((document) => document.metadata.flowIds.includes(flowId)),
+    };
+}
+//# sourceMappingURL=corpus.js.map

package/dist/knowledge/corpus.js.map

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

package/dist/knowledge/search.d.ts

@@ -0,0 +1,29 @@
+import type { KnowledgeCorpus } from './corpus.js';
+/**
+ * Split text into searchable tokens.
+ *
+ * Underscores are preserved so `pp_SecureHash` survives as one token, and the
+ * bare word forms are emitted too, so a query for "secure hash" still matches it.
+ */
+export declare function tokenise(text: string): string[];
+export interface SearchResult {
+    readonly docId: string;
+    readonly sectionId: string;
+    readonly documentTitle: string;
+    readonly sectionTitle: string;
+    readonly uri: string;
+    readonly score: number;
+    /** Passage around the strongest match, for display without the whole section. */
+    readonly excerpt: string;
+}
+export interface SearchOptions {
+    /** Restrict results to documents describing this flow. */
+    readonly flowId?: string | undefined;
+    readonly limit?: number | undefined;
+}
+export interface KnowledgeSearchIndex {
+    search(query: string, options?: SearchOptions): readonly SearchResult[];
+}
+/** Build a search index over the corpus. Cheap enough to build once at start-up. */
+export declare function buildSearchIndex(corpus: KnowledgeCorpus): KnowledgeSearchIndex;
+//# sourceMappingURL=search.d.ts.map

package/dist/knowledge/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/knowledge/search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAwEnD;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAoB/C;AAiBD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACrC;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,SAAS,YAAY,EAAE,CAAC;CACzE;AAyBD,oFAAoF;AACpF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,eAAe,GAAG,oBAAoB,CA6E9E"}

package/dist/knowledge/search.js

@@ -0,0 +1,181 @@
+/**
+ * Offline lexical search over the documentation corpus.
+ *
+ * BM25 over section text, with boosts for the section title, the document title
+ * and the curated keyword list. Deliberately dependency-free and deterministic:
+ * the server must give the same answer on an air-gapped merchant machine as it
+ * does anywhere else, and a payment integration tool should not be shipping
+ * merchant questions to a third-party embedding service.
+ */
+const BM25_K1 = 1.5;
+const BM25_B = 0.75;
+/**
+ * Boosts are applied by repeating high-signal text before tokenising, which
+ * keeps the scoring function a plain BM25 with no special cases. They must
+ * therefore be whole numbers of repetitions.
+ */
+const TITLE_BOOST = 3;
+const KEYWORD_BOOST = 3;
+const DOC_TITLE_BOOST = 2;
+function repeatText(text, times) {
+    return Array.from({ length: times }, () => text).join(' ');
+}
+/** Very small suffix stripper. Full stemming is not worth the failure modes here. */
+function stem(token) {
+    for (const suffix of ['ing', 'ies', 'es', 's']) {
+        if (token.length > suffix.length + 2 && token.endsWith(suffix)) {
+            return token.slice(0, -suffix.length);
+        }
+    }
+    return token;
+}
+const STOP_WORDS = new Set([
+    'a',
+    'an',
+    'and',
+    'are',
+    'as',
+    'at',
+    'be',
+    'but',
+    'by',
+    'do',
+    'for',
+    'from',
+    'how',
+    'i',
+    'in',
+    'is',
+    'it',
+    'my',
+    'of',
+    'on',
+    'or',
+    'the',
+    'to',
+    'was',
+    'what',
+    'when',
+    'why',
+    'with',
+    'you',
+    'your',
+]);
+/**
+ * Split text into searchable tokens.
+ *
+ * Underscores are preserved so `pp_SecureHash` survives as one token, and the
+ * bare word forms are emitted too, so a query for "secure hash" still matches it.
+ */
+export function tokenise(text) {
+    const tokens = [];
+    for (const raw of text.toLowerCase().split(/[^a-z0-9_.]+/)) {
+        if (raw === '') {
+            continue;
+        }
+        if (!STOP_WORDS.has(raw)) {
+            tokens.push(stem(raw));
+        }
+        if (raw.includes('_')) {
+            for (const part of raw.split('_')) {
+                if (part.length > 1 && !STOP_WORDS.has(part)) {
+                    tokens.push(stem(part));
+                }
+            }
+        }
+    }
+    return tokens;
+}
+function termFrequencies(tokens) {
+    const counts = new Map();
+    for (const token of tokens) {
+        counts.set(token, (counts.get(token) ?? 0) + 1);
+    }
+    return counts;
+}
+/** Pick the passage around the densest concentration of query terms. */
+function buildExcerpt(text, queryTokens, maxLength = 400) {
+    const paragraphs = text.split(/\n{2,}/).filter((paragraph) => paragraph.trim() !== '');
+    if (paragraphs.length === 0) {
+        return text.slice(0, maxLength);
+    }
+    let best = paragraphs[0] ?? '';
+    let bestScore = -1;
+    for (const paragraph of paragraphs) {
+        const tokens = new Set(tokenise(paragraph));
+        const score = queryTokens.filter((token) => tokens.has(token)).length;
+        if (score > bestScore) {
+            bestScore = score;
+            best = paragraph;
+        }
+    }
+    const trimmed = best.trim();
+    return trimmed.length <= maxLength ? trimmed : `${trimmed.slice(0, maxLength)}…`;
+}
+/** Build a search index over the corpus. Cheap enough to build once at start-up. */
+export function buildSearchIndex(corpus) {
+    const indexed = [];
+    for (const document of corpus.documents()) {
+        const { metadata } = document;
+        for (const section of document.sections) {
+            const boosted = [
+                section.text,
+                repeatText(section.title, TITLE_BOOST),
+                repeatText(metadata.title, DOC_TITLE_BOOST),
+                repeatText(metadata.keywords.join(' '), KEYWORD_BOOST),
+            ].join(' ');
+            const tokens = tokenise(boosted);
+            indexed.push({
+                section,
+                frequencies: termFrequencies(tokens),
+                length: tokens.length,
+                flowIds: metadata.flowIds,
+            });
+        }
+    }
+    const averageLength = indexed.reduce((total, entry) => total + entry.length, 0) / Math.max(indexed.length, 1);
+    const documentFrequency = new Map();
+    for (const entry of indexed) {
+        for (const token of entry.frequencies.keys()) {
+            documentFrequency.set(token, (documentFrequency.get(token) ?? 0) + 1);
+        }
+    }
+    const titleByDocId = new Map(corpus.documents().map((document) => [document.metadata.docId, document.metadata.title]));
+    return {
+        search(query, options = {}) {
+            const queryTokens = tokenise(query);
+            if (queryTokens.length === 0) {
+                return [];
+            }
+            const { flowId } = options;
+            const candidates = flowId === undefined ? indexed : indexed.filter((entry) => entry.flowIds.includes(flowId));
+            const scored = candidates
+                .map((entry) => {
+                let score = 0;
+                for (const token of new Set(queryTokens)) {
+                    const frequency = entry.frequencies.get(token);
+                    if (frequency === undefined) {
+                        continue;
+                    }
+                    const containing = documentFrequency.get(token) ?? 0;
+                    const idf = Math.log(1 + (indexed.length - containing + 0.5) / (containing + 0.5));
+                    const normalisation = BM25_K1 * (1 - BM25_B + (BM25_B * entry.length) / averageLength);
+                    score += idf * ((frequency * (BM25_K1 + 1)) / (frequency + normalisation));
+                }
+                return {
+                    docId: entry.section.docId,
+                    sectionId: entry.section.sectionId,
+                    documentTitle: titleByDocId.get(entry.section.docId) ?? entry.section.docId,
+                    sectionTitle: entry.section.title,
+                    uri: entry.section.uri,
+                    score: Number(score.toFixed(4)),
+                    excerpt: buildExcerpt(entry.section.text, queryTokens),
+                };
+            })
+                .filter((result) => result.score > 0)
+                .sort((left, right) => right.score - left.score);
+            return scored.slice(0, options.limit ?? 5);
+        },
+    };
+}
+//# sourceMappingURL=search.js.map

package/dist/knowledge/search.js.map

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

package/dist/knowledge/source.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Where the loaders read corpus files from.
+ *
+ * Each source is rooted at one part of the corpus — the flow specifications, the
+ * documents, the templates, the diagnostics — and addresses entries by name
+ * within it. Every loader takes one instead of calling `node:fs` itself, so a
+ * corpus served from somewhere other than a sibling directory costs one new
+ * implementation of this interface rather than an edit to every loader.
+ *
+ * Deliberately synchronous. The loaders run at start-up, on a synchronous path
+ * that reaches the composition root; making the seam asynchronous would push
+ * `await` through every caller for no benefit while the only implementation
+ * reads local files.
+ */
+export interface CorpusSource {
+    /** The root this source reads from. Named in errors so a failure says where it looked. */
+    readonly location: string;
+    /** Where `segments` resolves to. For error messages; never opened. */
+    locate(...segments: readonly string[]): string;
+    /** Read one entry as UTF-8 text. Throws when it cannot be read. */
+    readText(...segments: readonly string[]): string;
+    /** Names of the entries directly under `segments`. Throws when there is no such directory. */
+    entryNames(...segments: readonly string[]): readonly string[];
+}
+/**
+ * Read corpus entries from a local directory.
+ *
+ * Nothing is cached here. A source that memoised reads would serve an edited
+ * flow specification or template stale until the process restarts, which is the
+ * failure mode `loadTemplate` is deliberately built to avoid.
+ */
+export declare function localCorpusSource(directory: string): CorpusSource;
+/**
+ * Read corpus entries from a map held in memory, keyed by entry name.
+ *
+ * The published package cannot rely on a corpus directory surviving beside it.
+ * A consumer that installs the server gets whatever `files` shipped, and a
+ * flow specification read from disk at run time is one packaging mistake away
+ * from a start-up failure on someone else's machine. Serialising the
+ * specifications into generated source and handing the loaders this source
+ * instead makes the catalogue part of the module graph: it is present wherever
+ * the code is, and the loaders keep their existing behaviour because they never
+ * knew what was behind the seam.
+ *
+ * Keys are the '/'-joined segments a loader addresses, so `flows/a.json` is
+ * reached as `readText('flows', 'a.json')` or, from a source already rooted at
+ * the flows, as `readText('a.json')`.
+ *
+ * Nothing is cached beyond the map itself. The map is the corpus, so there is
+ * no slower store behind it for a cache to spare.
+ */
+export declare function memoryCorpusSource(entries: Readonly<Record<string, string>>, location?: string): CorpusSource;
+/**
+ * Accept either a source or a plain directory.
+ *
+ * The loaders have always taken a directory, and a caller pointing at one on
+ * disk should not have to construct a source to do it.
+ */
+export declare function toCorpusSource(source: CorpusSource | string): CorpusSource;
+//# sourceMappingURL=source.d.ts.map

package/dist/knowledge/source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../../src/knowledge/source.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,YAAY;IAC3B,0FAA0F;IAC1F,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,sEAAsE;IACtE,MAAM,CAAC,GAAG,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAAC;IAC/C,mEAAmE;IACnE,QAAQ,CAAC,GAAG,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAAC;IACjD,8FAA8F;IAC9F,UAAU,CAAC,GAAG,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,MAAM,EAAE,CAAC;CAC/D;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,CAOjE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,QAAQ,SAAa,GAAG,YAAY,CA6CjH;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,GAAG,YAAY,CAE1E"}

package/dist/knowledge/source.js

@@ -0,0 +1,91 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Read corpus entries from a local directory.
+ *
+ * Nothing is cached here. A source that memoised reads would serve an edited
+ * flow specification or template stale until the process restarts, which is the
+ * failure mode `loadTemplate` is deliberately built to avoid.
+ */
+export function localCorpusSource(directory) {
+    return {
+        location: directory,
+        locate: (...segments) => join(directory, ...segments),
+        readText: (...segments) => readFileSync(join(directory, ...segments), 'utf8'),
+        entryNames: (...segments) => readdirSync(join(directory, ...segments)),
+    };
+}
+/**
+ * Read corpus entries from a map held in memory, keyed by entry name.
+ *
+ * The published package cannot rely on a corpus directory surviving beside it.
+ * A consumer that installs the server gets whatever `files` shipped, and a
+ * flow specification read from disk at run time is one packaging mistake away
+ * from a start-up failure on someone else's machine. Serialising the
+ * specifications into generated source and handing the loaders this source
+ * instead makes the catalogue part of the module graph: it is present wherever
+ * the code is, and the loaders keep their existing behaviour because they never
+ * knew what was behind the seam.
+ *
+ * Keys are the '/'-joined segments a loader addresses, so `flows/a.json` is
+ * reached as `readText('flows', 'a.json')` or, from a source already rooted at
+ * the flows, as `readText('a.json')`.
+ *
+ * Nothing is cached beyond the map itself. The map is the corpus, so there is
+ * no slower store behind it for a cache to spare.
+ */
+export function memoryCorpusSource(entries, location = '<memory>') {
+    return {
+        location,
+        locate: (...segments) => `${location}:${segments.join('/')}`,
+        readText: (...segments) => {
+            const key = segments.join('/');
+            const text = entries[key];
+            if (text === undefined) {
+                throw new Error(`No entry "${key}" in ${location}.`);
+            }
+            return text;
+        },
+        entryNames: (...segments) => {
+            // With no prefix the whole map is the answer, keys intact. A source built
+            // for one part of the corpus is flat, and a loader that lists the root
+            // and reads each name back expects the names it can read.
+            if (segments.length === 0) {
+                return Object.keys(entries).sort();
+            }
+            const prefix = `${segments.join('/')}/`;
+            const names = new Set();
+            for (const key of Object.keys(entries)) {
+                if (!key.startsWith(prefix)) {
+                    continue;
+                }
+                // Entries nested deeper than the prefix contribute only the segment
+                // directly beneath it, matching what `readdirSync` reports for a
+                // subdirectory rather than leaking the whole path. Sliced at the
+                // separator rather than destructured from `split`, because
+                // `noUncheckedIndexedAccess` would type the first element as possibly
+                // absent and the guard against that could never run — `split` always
+                // yields at least one element.
+                const remainder = key.slice(prefix.length);
+                const boundary = remainder.indexOf('/');
+                const name = boundary === -1 ? remainder : remainder.slice(0, boundary);
+                // An entry whose name *is* the prefix addresses the directory itself and
+                // names nothing under it.
+                if (name !== '') {
+                    names.add(name);
+                }
+            }
+            return [...names].sort();
+        },
+    };
+}
+/**
+ * Accept either a source or a plain directory.
+ *
+ * The loaders have always taken a directory, and a caller pointing at one on
+ * disk should not have to construct a source to do it.
+ */
+export function toCorpusSource(source) {
+    return typeof source === 'string' ? localCorpusSource(source) : source;
+}
+//# sourceMappingURL=source.js.map

package/dist/knowledge/source.js.map

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

package/dist/knowledge/types.d.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+/** Metadata for one curated document, from `knowledge/docs/index.json`. */
+export declare const documentMetadataSchema: z.ZodObject<{
+    docId: z.ZodString;
+    title: z.ZodString;
+    sourcePdf: z.ZodString;
+    version: z.ZodString;
+    flowIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    keywords: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const documentIndexSchema: z.ZodObject<{
+    corpusVersion: z.ZodString;
+    note: z.ZodOptional<z.ZodString>;
+    documents: z.ZodArray<z.ZodObject<{
+        docId: z.ZodString;
+        title: z.ZodString;
+        sourcePdf: z.ZodString;
+        version: z.ZodString;
+        flowIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        keywords: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strict>;
+export type DocumentMetadata = z.infer<typeof documentMetadataSchema>;
+/** One `## Heading {#anchor}` block within a document. */
+export interface DocumentSection {
+    readonly docId: string;
+    readonly sectionId: string;
+    readonly title: string;
+    readonly text: string;
+    /** `jazzcash://docs/{docId}#{sectionId}` */
+    readonly uri: string;
+}
+export interface CorpusDocument {
+    readonly metadata: DocumentMetadata;
+    /** Everything before the first `##` heading. */
+    readonly preamble: string;
+    readonly sections: readonly DocumentSection[];
+    readonly markdown: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/knowledge/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/knowledge/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,2EAA2E;AAC3E,eAAO,MAAM,sBAAsB;;;;;;;iBAUjC,CAAC;AAEH,eAAO,MAAM,mBAAmB;;;;;;;;;;;kBAI9B,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,0DAA0D;AAC1D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4CAA4C;IAC5C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;IAC9C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B"}

package/dist/knowledge/types.js

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+/** Metadata for one curated document, from `knowledge/docs/index.json`. */
+export const documentMetadataSchema = z.object({
+    docId: z.string().min(1),
+    title: z.string().min(1),
+    /** Path of the PDF this was transcribed from, for provenance and re-checking. */
+    sourcePdf: z.string().min(1),
+    version: z.string().min(1),
+    /** Flows this document describes, used to scope a search. */
+    flowIds: z.array(z.string()).default([]),
+    /** Search boosts. Terms a merchant is likely to use that the prose may not contain. */
+    keywords: z.array(z.string()).default([]),
+});
+export const documentIndexSchema = z.strictObject({
+    corpusVersion: z.string().min(1),
+    note: z.string().optional(),
+    documents: z.array(documentMetadataSchema).min(1),
+});
+//# sourceMappingURL=types.js.map

package/dist/knowledge/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/knowledge/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,2EAA2E;AAC3E,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACxB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACxB,iFAAiF;IACjF,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1B,6DAA6D;IAC7D,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IACxC,uFAAuF;IACvF,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;CAC1C,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,YAAY,CAAC;IAChD,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAChC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;CAClD,CAAC,CAAC"}

package/dist/paths.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Walk upwards to the nearest directory that owns a `package.json`.
+ *
+ * Exported so the walk can be exercised from somewhere other than this module's
+ * own directory, which is the only way to prove that moving the corpus leaves
+ * root discovery intact.
+ */
+export declare function findPackageRoot(startDirectory: string): string;
+/** Absolute path to the package root. Cached after the first successful walk. */
+export declare function packageRoot(): string;
+/**
+ * Absolute path to the directory holding the bundled corpus.
+ *
+ * Derived from the package root rather than being what identifies it, so this is
+ * the single place that has to change if the corpus stops shipping beside the
+ * code — and the single place `MCP_CORPUS_DIR` has to override.
+ *
+ * The override is validated on every call rather than memoised: the check is one
+ * `stat` in front of a file read that is about to happen anyway, and a cached
+ * answer would make the variable unreadable to anything that sets it after this
+ * module was first imported.
+ */
+export declare function corpusRoot(): string;
+/** Absolute path to `knowledge/`, optionally joined with further segments. */
+export declare function knowledgePath(...segments: readonly string[]): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAkDA;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAe9D;AAED,iFAAiF;AACjF,wBAAgB,WAAW,IAAI,MAAM,CAGpC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,IAAI,MAAM,CA4BnC;AAED,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,GAAG,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAEpE"}