@bridgeline-digital/hawk-app-cli 0.1.0-dev.20261020202308 → 0.1.0

package/src/mcp-hawksearch.mjs

@@ -1,342 +1,342 @@
-// The MCP server's `hawksearch_api` tool: HawkSearch's own API reference (developerdocs.hawksearch.com), with what an app
-// can call of it and how. The operations come from the site's llms.txt; each operation's page embeds its OpenAPI
-// definition (path, parameters, body and response schemas), which is read when one operation is asked for. What apps
-// may call of it (which dashboard resources take writes, which Indexing API operations exist for apps, their scopes and
-// limits) is the platform's own GET /meta/rules (mcp-rules.mjs). Public docs: no key, no client data.
-import { FALLBACK } from './mcp-rules.mjs';
-
-export const INDEX_URL = 'https://developerdocs.hawksearch.com/llms.txt';
-const CACHE_MS = 10 * 60_000;
-const TIMEOUT_MS = 10_000;
-const MAX_TEXT = 8000;
-
-/** The bridge's own helpers for some Indexing API operations; the rest go through index.call(operation, body). */
-const INDEX_HELPERS = {
-    indexes: 'index.indexes()',
-    current: 'index.current()',
-    'index-items': 'index.items.upsert(items, { indexName })',
-    'update-items': 'index.items.update(items, { indexName })',
-    'delete-items': 'index.items.delete(ids, { indexName })',
-    create: "index.create({ suffix: 'spring' })",
-    'set-current': 'index.setCurrent(indexName)',
-    'delete-index': 'index.deleteIndex(indexName)',
-    'rebuild-all': 'index.rebuildAll(indexName)',
-};
-
-export const APIS = {
-    dashboard: 'Dashboard API: app.dashboard.get/post/put/delete',
-    search: 'Search API: app.hawksearch.search / autocomplete',
-    recommendations: 'Recommendation API: app.hawksearch.recommendations',
-    indexing: 'Indexing API: app.hawksearch.index',
-    tracking: 'Tracking API',
-};
-
-/** Which API an llms.txt "## API Reference: …" section is, or null for the overview. */
-function apiOf(section) {
-    if (/overview/i.test(section)) return null;
-    if (/hawksearch\.api\s*$/i.test(section)) return 'dashboard';
-    if (/search\s*api/i.test(section)) return 'search';
-    if (/recommend/i.test(section)) return 'recommendations';
-    if (/index/i.test(section)) return 'indexing';
-    if (/track/i.test(section)) return 'tracking';
-    return section.trim();
-}
-
-/** The API reference operations in llms.txt: [{ id, title, url, summary, api, group }]. */
-export function operationsIn(text) {
-    const operations = [];
-    let api = null;
-    let group = null;
-    // Some summaries hold a bare \r (a line break in HawkSearch's own text): part of the line, not the end of it.
-    for (const line of text.replace(/\r\n/g, '\n').replace(/\r/g, ' ').split('\n')) {
-        const section = /^## (.*)$/.exec(line);
-        if (section) {
-            const reference = /^API Reference:\s*(.+)$/.exec(section[1]);
-            api = reference ? apiOf(reference[1]) : null;
-            group = null;
-            continue;
-        }
-        if (!api) continue;
-        const heading = /^- ([^[\]]+?)\s*$/.exec(line);
-        if (heading) {
-            group = heading[1];
-            continue;
-        }
-        const link = /^\s*- \[(.+?)\]\((https:\/\/developerdocs\.hawksearch\.com\/reference\/([\w.-]+?)\.md)\)(?::\s*(.*))?$/.exec(line);
-        if (link) operations.push({ id: link[3], title: link[1], url: link[2], summary: stripHtml(link[4] ?? ''), api, group: group ?? '' });
-    }
-    return operations;
-}
-
-const stripHtml = (text) => text.replace(/<[^>]+>/g, '').replace(/\s+/g, ' ').trim();
-
-/** What an app can do with a whole group of operations, for the list (the exact answer is per operation). */
-function groupAccess(api, group, rules) {
-    const name = group.toLowerCase();
-    switch (api) {
-        case 'dashboard':
-            if (name === 'index') return 'not through app.dashboard: app.hawksearch.index.rebuild() (hawksearch:index)';
-            if (name.startsWith('report')) return 'reads with hawksearch:read; for reporting prefer app.analytics.report() (analytics_reports)';
-            return writable(rules, name) ? 'reads hawksearch:read, writes hawksearch:write' : 'read only (hawksearch:read)';
-        case 'search':
-            if (name === 'searchv2') return 'app.hawksearch.search (hawksearch:search)';
-            if (name === 'autocompletev2') return 'app.hawksearch.autocomplete (hawksearch:search)';
-            return null;
-        case 'recommendations':
-            return rules.recommendations.available ? 'app.hawksearch.recommendations (hawksearch:recommendations)' : null;
-        case 'indexing':
-            if (['indexv2', 'hierarchy', 'mapping', 'embedding'].includes(name)) return 'some operations, scope per operation (hawksearch:index, :index:items, :index:manage)';
-            return null;
-        default:
-            return null;
-    }
-}
-
-const writable = (rules, resource) => rules.dashboard.writeResources.some((r) => r.toLowerCase() === resource.toLowerCase());
-
-function list(operations, api, rules, from) {
-    const apis = api ? [api] : [...new Set(operations.map((o) => o.api))];
-    const lines = [
-        `HawkSearch's API reference (${INDEX_URL}), with what apps can call through the bridge (the platform's rules, from ${from}).`,
-        api ? 'Call again with operation: "<id>" for its path, parameters, body and response fields, and the bridge call.' : 'Call again with api: "<name>" for each operation\'s title, or operation: "<id or words>" for one in full.',
-    ];
-    for (const name of apis) {
-        const ofApi = operations.filter((o) => o.api === name);
-        if (!ofApi.length) continue;
-        lines.push('', `## ${name}: ${APIS[name] ?? name}`);
-        for (const group of [...new Set(ofApi.map((o) => o.group))]) {
-            const ofGroup = ofApi.filter((o) => o.group === group);
-            const access = groupAccess(name, group, rules);
-            if (!access) {
-                lines.push(`- ${group || '(no group)'}: not available to apps (${ofGroup.length} operation${ofGroup.length === 1 ? '' : 's'})`);
-            } else if (api) {
-                lines.push(`- ${group}: ${access}`, ...ofGroup.map((o) => `  - ${o.id}: ${o.title}${o.summary && o.summary !== o.title ? ` (${o.summary.slice(0, 120)})` : ''}`));
-            } else {
-                lines.push(`- ${group}: ${access}. ${ofGroup.map((o) => o.id).join(', ')}`);
-            }
-        }
-    }
-    return lines.join('\n');
-}
-
-/** The OpenAPI definition a reference page embeds (its first ```json block), or null. */
-export function definitionIn(markdown) {
-    const block = /```json\s*\n([\s\S]*?)\n```/.exec(markdown);
-    if (!block) return null;
-    try {
-        return JSON.parse(block[1]);
-    } catch {
-        return null;
-    }
-}
-
-const quote = (path) => (path.includes('{') ? `\`${path.replace(/\{(\w+)\}/g, (_, name) => `\${${name}}`)}\`` : `'${path}'`);
-
-/** A path with its {placeholders} blanked, to compare HawkSearch's paths with the platform's ({notificationId} vs {id}). */
-const shape = (path) => path.replace(/^\/+/, '').toLowerCase().replace(/\{[^}]*\}/g, '{}');
-
-/** How an app calls one operation under the platform's rules: { call, scope, note } or { unavailable }. */
-export function bridgeCall(api, method, path, rules = FALLBACK) {
-    const m = method.toUpperCase();
-    const rel = path.replace(/^\/+/, '');
-    if (api === 'dashboard') {
-        const { writeResources, writesPerMinute, maxBulkItems } = rules.dashboard;
-        const resourcePath = rel.replace(/^api\/(v\d+\/)?/i, '');
-        const resource = resourcePath.split('/')[0];
-        if (m === 'GET') return { call: `await app.dashboard.get(${quote(resourcePath)})`, scope: 'hawksearch:read', note: 'Query parameters go in { query: { … } } as the second argument.' };
-        if (resource.toLowerCase() === 'index') return { unavailable: 'Index rebuilds go through app.hawksearch.index.rebuild() (hawksearch:index, elevated), not the dashboard API.' };
-        if (!writable(rules, resource)) return { unavailable: `Writes to ${resource} aren't allowed (403 path_not_allowed): apps write only ${writeResources.join(', ')}.` };
-        if (m === 'DELETE' && resource.toLowerCase() === 'landingpage' && /^bulk/i.test(resourcePath.split('/')[1] ?? '')) return { unavailable: 'Bulk landing-page deletes are blocked (403 path_not_allowed).' };
-        const verb = m.toLowerCase();
-        return {
-            call: `await app.dashboard.${verb}(${quote(resourcePath)}${verb === 'delete' ? '' : ', body'})`,
-            scope: 'hawksearch:write (elevated)',
-            note: `Site keys only; ${writesPerMinute} writes a minute; bulk paths up to ${maxBulkItems} items; audit-logged, never retried.`,
-        };
-    }
-    if (api === 'search') {
-        const limit = `${rules.search.perMinute} calls a minute.`;
-        if (rel === 'api/v2/search') return { call: "await app.hawksearch.search({ Keyword: 'boots' })", scope: 'hawksearch:search', note: `The platform sets ClientGuid to the engine's; IsInPreview: true runs on the preview search API. ${limit}` };
-        if (rel === 'api/v2/autocomplete') return { call: "await app.hawksearch.autocomplete({ Keyword: 'boo' })", scope: 'hawksearch:search', note: `The platform sets ClientGuid to the engine's. ${limit}` };
-        return { unavailable: 'Apps can call only search and autocomplete of the Search API.' };
-    }
-    if (api === 'recommendations') {
-        const { available, perMinute, maxBulkWidgets } = rules.recommendations;
-        if (!available) return { unavailable: "This platform has no recommendation API set up (503 recommendations_not_configured)." };
-        const note = `The platform sets clientGuid, adds visitorId/visitId when you send none, and keeps the call out of the recommendation reports. ${perMinute} calls a minute.`;
-        if (rel === 'api/recommendation/v2/getwidgetitems') return { call: 'await app.hawksearch.recommendations({ widgetUids: [{ widgetGuid, uniqueId }] })', scope: 'hawksearch:recommendations', note };
-        if (rel === 'api/recommendation/v2/getbulkwidgetitems') return { call: 'await app.hawksearch.recommendations({ widgets: [ … ] })', scope: 'hawksearch:recommendations', note: `Up to ${maxBulkWidgets} widgets. ${note}` };
-        return { unavailable: 'Apps get recommendation widgets only (getwidgetitems and getbulkwidgetitems).' };
-    }
-    if (api === 'indexing') {
-        const { operations, maxItemsPerCall, maxIdsPerCall, itemWritesPerMinute, managePerMinute } = rules.indexing;
-        const found = operations.find((o) => o.method.toUpperCase() === m && shape(o.path) === shape(rel));
-        if (!found) return { unavailable: "Not on the platform's Indexing API list (group indexing, index templates, unset-current and internal endpoints are left out on purpose)." };
-        // The app's operation with HawkSearch's own placeholder names (embedding/status/{id} → `embedding/status/${notificationId}`).
-        const names = [...rel.matchAll(/\{(\w+)\}/g)].map((p) => p[1]);
-        const operation = found.operation.includes('{') ? quote(found.operation.replace(/\{[^}]*\}/g, () => `{${names.shift() ?? 'id'}}`)) : `'${found.operation}'`;
-        const helper = INDEX_HELPERS[found.operation];
-        const write = found.scope !== 'hawksearch:index';
-        return {
-            call: `await app.hawksearch.${helper ?? `index.call(${operation}${m === 'POST' ? ', body' : ''})`}`,
-            scope: `${found.scope} (elevated)`,
-            note: write
-                ? `Site keys only; ${maxItemsPerCall} items (or ${maxIdsPerCall} ids) a call; ${found.scope === 'hawksearch:index:items' ? `${itemWritesPerMinute} item writes` : `${managePerMinute} management calls`} a minute; audit-logged, never retried.${found.scope === 'hawksearch:index:items' ? ' Item writes are live at once.' : ''}`
-                : undefined,
-        };
-    }
-    return { unavailable: "Apps can't call this API." };
-}
-
-const HIDDEN_PARAMETERS = /^x-hawksearch-(group)?apikey$/i;
-
-function resolve(schema, spec) {
-    let current = schema;
-    for (let i = 0; current?.$ref && i < 10; i++) current = spec.components?.schemas?.[current.$ref.split('/').pop()];
-    return current ?? {};
-}
-
-function typeOf(schema) {
-    if (!schema) return 'any';
-    if (schema.$ref) return schema.$ref.split('/').pop();
-    if (schema.type === 'array') return `${typeOf(schema.items)}[]`;
-    if (schema.enum) return schema.enum.map((v) => JSON.stringify(v)).join(' | ');
-    if (schema.pattern && /^\^\([\w|]+\)\$$/.test(schema.pattern)) return schema.pattern.slice(2, -2).split('|').map((v) => `"${v}"`).join(' | ');
-    if (schema.type === 'object' && schema.additionalProperties) return `{ [key]: ${typeOf(schema.additionalProperties)} }`;
-    return [schema.type ?? 'object', schema.format].filter(Boolean).join(' ');
-}
-
-const refsOf = (schema) => {
-    if (!schema) return [];
-    if (schema.$ref) return [schema.$ref.split('/').pop()];
-    if (schema.type === 'array') return refsOf(schema.items);
-    if (schema.additionalProperties) return refsOf(schema.additionalProperties);
-    return [];
-};
-
-/** A schema's fields, then those of the schemas it refers to (breadth first, each once). */
-function describeSchema(label, schema, spec) {
-    const lines = [`${label}: ${typeOf(schema)}`];
-    const queue = refsOf(schema);
-    if (!queue.length) {
-        const own = resolve(schema, spec);
-        if (own.properties) lines.push(...fieldLines(own));
-        return lines;
-    }
-    const seen = new Set();
-    while (queue.length) {
-        const name = queue.shift();
-        if (seen.has(name)) continue;
-        seen.add(name);
-        const own = spec.components?.schemas?.[name];
-        if (!own) continue;
-        lines.push('', `${name}${own.description ? ` (${stripHtml(own.description)})` : ''}:`, ...fieldLines(own));
-        for (const property of Object.values(own.properties ?? {})) queue.push(...refsOf(property));
-    }
-    return lines;
-}
-
-function fieldLines(schema) {
-    const required = new Set(schema.required ?? []);
-    return Object.entries(schema.properties ?? {}).map(([name, property]) => {
-        const description = property.description ? `: ${stripHtml(property.description)}` : '';
-        return `- ${name} (${typeOf(property)}${required.has(name) ? ', required' : ''}${property.nullable ? ', nullable' : ''})${description}`;
-    });
-}
-
-const jsonContent = (content) => content?.['application/json'] ?? Object.values(content ?? {})[0];
-
-function detail(operation, definition, rules) {
-    const [path, item] = Object.entries(definition?.paths ?? {})[0] ?? [];
-    const [method, op] = Object.entries(item ?? {}).find(([key]) => /^(get|post|put|delete|patch)$/i.test(key)) ?? [];
-    if (!op) return `# ${operation.title}\n\nThe page has no OpenAPI definition to read: ${operation.url.replace(/\.md$/, '')}`;
-    const access = bridgeCall(operation.api, method, path, rules);
-    const parameters = (op.parameters ?? []).filter((p) => !HIDDEN_PARAMETERS.test(p.name));
-    const body = jsonContent(op.requestBody?.content)?.schema;
-    const response = jsonContent(op.responses?.['200']?.content ?? op.responses?.['201']?.content)?.schema;
-    return [
-        `# ${operation.id}: ${op.summary ?? operation.title}`,
-        `${method.toUpperCase()} ${path} (HawkSearch ${operation.api === 'dashboard' ? 'Dashboard' : operation.api} API, ${operation.group})`,
-        '',
-        stripHtml(op.description ?? operation.summary ?? ''),
-        '',
-        ...(access.unavailable
-            ? [`Not available to apps: ${access.unavailable}`]
-            : ['From an app:', access.call, `Scope: ${access.scope}.${access.note ? ` ${access.note}` : ''}`]),
-        ...(parameters.length
-            ? ['', 'Parameters:', ...parameters.map((p) => `- ${p.name} (${p.in}, ${typeOf(p.schema)}${p.required ? ', required' : ''})${p.description ? `: ${stripHtml(p.description)}` : ''}`)]
-            : []),
-        ...(body ? ['', ...describeSchema('Request body', body, definition)] : []),
-        ...(response ? ['', ...describeSchema('Response', response, definition)] : []),
-        '',
-        `Source: ${operation.url.replace(/\.md$/, '')}`,
-    ]
-        .filter((line, i, all) => line !== '' || all[i - 1] !== '')
-        .join('\n');
-}
-
-async function fetchText(url) {
-    const response = await fetch(url, { signal: AbortSignal.timeout(TIMEOUT_MS) });
-    if (!response.ok) throw new Error(`${url} answered ${response.status}`);
-    return response.text();
-}
-
-/** The platform's default rules, for a reference made without the platform (tests, or no platform at all). */
-const builtInRules = async () => ({ rules: FALLBACK, from: 'the CLI (the platform\'s defaults)' });
-
-/**
- * describe({ api, operation, offset }) for the tool. llms.txt and each page are cached for a while; when the site
- * can't be reached, an earlier copy is used if there is one. `rules` is mcp-rules.mjs's createPlatformRules().
- */
-export function createHawkSearchReference({ load = fetchText, now = Date.now, rules = builtInRules } = {}) {
-    const cache = new Map();
-    async function get(url) {
-        const hit = cache.get(url);
-        if (hit && now() - hit.at < CACHE_MS) return { text: hit.text };
-        try {
-            const text = await load(url);
-            cache.set(url, { text, at: now() });
-            return { text };
-        } catch (error) {
-            if (hit) return { text: hit.text, stale: `(developerdocs.hawksearch.com couldn't be reached just now: ${error.message}. This is the copy from earlier.)` };
-            throw error;
-        }
-    }
-
-    return async function describe({ api, operation, offset = 0 } = {}) {
-        let index;
-        try {
-            index = await get(INDEX_URL);
-        } catch (error) {
-            return { ok: false, text: `Couldn't read HawkSearch's API reference (${error.message}). It's at https://developerdocs.hawksearch.com/reference/getting-started-with-your-api.` };
-        }
-        const operations = operationsIn(index.text);
-        const platform = await rules();
-        const stale = (loaded) => [loaded.stale, platform.note].filter(Boolean).map((note) => `\n\n${note}`).join('');
-        if (api && !operations.some((o) => o.api === api)) return { ok: false, text: `No API "${api}". The APIs: ${Object.keys(APIS).join(', ')}.` };
-        if (operation === undefined) return { ok: true, text: list(operations, api, platform.rules, platform.from) + stale(index) };
-
-        const wanted = operation.trim().toLowerCase();
-        const pool = api ? operations.filter((o) => o.api === api) : operations;
-        let matches = pool.filter((o) => o.id.toLowerCase() === wanted);
-        if (!matches.length) {
-            const words = wanted.split(/[^a-z0-9_]+/).filter((w) => w.length > 1);
-            matches = pool.filter((o) => words.length && words.every((w) => `${o.id} ${o.title} ${o.summary} ${o.group}`.toLowerCase().includes(w)));
-        }
-        if (!matches.length) return { ok: false, text: `No operation matches "${operation}". Call without operation for the list.` };
-        if (matches.length > 1) {
-            return { ok: true, text: `Several operations match "${operation}"; call again with one id:\n${matches.slice(0, 20).map((o) => `- ${o.id}: ${o.title} (${o.api}, ${o.group})`).join('\n')}${matches.length > 20 ? `\n… and ${matches.length - 20} more: use more words.` : ''}` };
-        }
-
-        const [found] = matches;
-        let page;
-        try {
-            page = await get(found.url);
-        } catch (error) {
-            return { ok: false, text: `Couldn't read ${found.url} (${error.message}).` };
-        }
-        const text = detail(found, definitionIn(page.text), platform.rules).slice(offset);
-        const cut = text.length > MAX_TEXT ? `${text.slice(0, MAX_TEXT)}\n… (more: call again with offset ${offset + MAX_TEXT})` : text;
-        return { ok: true, text: cut + stale(page) };
-    };
-}
+// The MCP server's `hawksearch_api` tool: HawkSearch's own API reference (developerdocs.hawksearch.com), with what an app
+// can call of it and how. The operations come from the site's llms.txt; each operation's page embeds its OpenAPI
+// definition (path, parameters, body and response schemas), which is read when one operation is asked for. What apps
+// may call of it (which dashboard resources take writes, which Indexing API operations exist for apps, their scopes and
+// limits) is the platform's own GET /meta/rules (mcp-rules.mjs). Public docs: no key, no client data.
+import { FALLBACK } from './mcp-rules.mjs';
+
+export const INDEX_URL = 'https://developerdocs.hawksearch.com/llms.txt';
+const CACHE_MS = 10 * 60_000;
+const TIMEOUT_MS = 10_000;
+const MAX_TEXT = 8000;
+
+/** The bridge's own helpers for some Indexing API operations; the rest go through index.call(operation, body). */
+const INDEX_HELPERS = {
+    indexes: 'index.indexes()',
+    current: 'index.current()',
+    'index-items': 'index.items.upsert(items, { indexName })',
+    'update-items': 'index.items.update(items, { indexName })',
+    'delete-items': 'index.items.delete(ids, { indexName })',
+    create: "index.create({ suffix: 'spring' })",
+    'set-current': 'index.setCurrent(indexName)',
+    'delete-index': 'index.deleteIndex(indexName)',
+    'rebuild-all': 'index.rebuildAll(indexName)',
+};
+
+export const APIS = {
+    dashboard: 'Dashboard API: app.dashboard.get/post/put/delete',
+    search: 'Search API: app.hawksearch.search / autocomplete',
+    recommendations: 'Recommendation API: app.hawksearch.recommendations',
+    indexing: 'Indexing API: app.hawksearch.index',
+    tracking: 'Tracking API',
+};
+
+/** Which API an llms.txt "## API Reference: …" section is, or null for the overview. */
+function apiOf(section) {
+    if (/overview/i.test(section)) return null;
+    if (/hawksearch\.api\s*$/i.test(section)) return 'dashboard';
+    if (/search\s*api/i.test(section)) return 'search';
+    if (/recommend/i.test(section)) return 'recommendations';
+    if (/index/i.test(section)) return 'indexing';
+    if (/track/i.test(section)) return 'tracking';
+    return section.trim();
+}
+
+/** The API reference operations in llms.txt: [{ id, title, url, summary, api, group }]. */
+export function operationsIn(text) {
+    const operations = [];
+    let api = null;
+    let group = null;
+    // Some summaries hold a bare \r (a line break in HawkSearch's own text): part of the line, not the end of it.
+    for (const line of text.replace(/\r\n/g, '\n').replace(/\r/g, ' ').split('\n')) {
+        const section = /^## (.*)$/.exec(line);
+        if (section) {
+            const reference = /^API Reference:\s*(.+)$/.exec(section[1]);
+            api = reference ? apiOf(reference[1]) : null;
+            group = null;
+            continue;
+        }
+        if (!api) continue;
+        const heading = /^- ([^[\]]+?)\s*$/.exec(line);
+        if (heading) {
+            group = heading[1];
+            continue;
+        }
+        const link = /^\s*- \[(.+?)\]\((https:\/\/developerdocs\.hawksearch\.com\/reference\/([\w.-]+?)\.md)\)(?::\s*(.*))?$/.exec(line);
+        if (link) operations.push({ id: link[3], title: link[1], url: link[2], summary: stripHtml(link[4] ?? ''), api, group: group ?? '' });
+    }
+    return operations;
+}
+
+const stripHtml = (text) => text.replace(/<[^>]+>/g, '').replace(/\s+/g, ' ').trim();
+
+/** What an app can do with a whole group of operations, for the list (the exact answer is per operation). */
+function groupAccess(api, group, rules) {
+    const name = group.toLowerCase();
+    switch (api) {
+        case 'dashboard':
+            if (name === 'index') return 'not through app.dashboard: app.hawksearch.index.rebuild() (hawksearch:index)';
+            if (name.startsWith('report')) return 'reads with hawksearch:read; for reporting prefer app.analytics.report() (analytics_reports)';
+            return writable(rules, name) ? 'reads hawksearch:read, writes hawksearch:write' : 'read only (hawksearch:read)';
+        case 'search':
+            if (name === 'searchv2') return 'app.hawksearch.search (hawksearch:search)';
+            if (name === 'autocompletev2') return 'app.hawksearch.autocomplete (hawksearch:search)';
+            return null;
+        case 'recommendations':
+            return rules.recommendations.available ? 'app.hawksearch.recommendations (hawksearch:recommendations)' : null;
+        case 'indexing':
+            if (['indexv2', 'hierarchy', 'mapping', 'embedding'].includes(name)) return 'some operations, scope per operation (hawksearch:index, :index:items, :index:manage)';
+            return null;
+        default:
+            return null;
+    }
+}
+
+const writable = (rules, resource) => rules.dashboard.writeResources.some((r) => r.toLowerCase() === resource.toLowerCase());
+
+function list(operations, api, rules, from) {
+    const apis = api ? [api] : [...new Set(operations.map((o) => o.api))];
+    const lines = [
+        `HawkSearch's API reference (${INDEX_URL}), with what apps can call through the bridge (the platform's rules, from ${from}).`,
+        api ? 'Call again with operation: "<id>" for its path, parameters, body and response fields, and the bridge call.' : 'Call again with api: "<name>" for each operation\'s title, or operation: "<id or words>" for one in full.',
+    ];
+    for (const name of apis) {
+        const ofApi = operations.filter((o) => o.api === name);
+        if (!ofApi.length) continue;
+        lines.push('', `## ${name}: ${APIS[name] ?? name}`);
+        for (const group of [...new Set(ofApi.map((o) => o.group))]) {
+            const ofGroup = ofApi.filter((o) => o.group === group);
+            const access = groupAccess(name, group, rules);
+            if (!access) {
+                lines.push(`- ${group || '(no group)'}: not available to apps (${ofGroup.length} operation${ofGroup.length === 1 ? '' : 's'})`);
+            } else if (api) {
+                lines.push(`- ${group}: ${access}`, ...ofGroup.map((o) => `  - ${o.id}: ${o.title}${o.summary && o.summary !== o.title ? ` (${o.summary.slice(0, 120)})` : ''}`));
+            } else {
+                lines.push(`- ${group}: ${access}. ${ofGroup.map((o) => o.id).join(', ')}`);
+            }
+        }
+    }
+    return lines.join('\n');
+}
+
+/** The OpenAPI definition a reference page embeds (its first ```json block), or null. */
+export function definitionIn(markdown) {
+    const block = /```json\s*\n([\s\S]*?)\n```/.exec(markdown);
+    if (!block) return null;
+    try {
+        return JSON.parse(block[1]);
+    } catch {
+        return null;
+    }
+}
+
+const quote = (path) => (path.includes('{') ? `\`${path.replace(/\{(\w+)\}/g, (_, name) => `\${${name}}`)}\`` : `'${path}'`);
+
+/** A path with its {placeholders} blanked, to compare HawkSearch's paths with the platform's ({notificationId} vs {id}). */
+const shape = (path) => path.replace(/^\/+/, '').toLowerCase().replace(/\{[^}]*\}/g, '{}');
+
+/** How an app calls one operation under the platform's rules: { call, scope, note } or { unavailable }. */
+export function bridgeCall(api, method, path, rules = FALLBACK) {
+    const m = method.toUpperCase();
+    const rel = path.replace(/^\/+/, '');
+    if (api === 'dashboard') {
+        const { writeResources, writesPerMinute, maxBulkItems } = rules.dashboard;
+        const resourcePath = rel.replace(/^api\/(v\d+\/)?/i, '');
+        const resource = resourcePath.split('/')[0];
+        if (m === 'GET') return { call: `await app.dashboard.get(${quote(resourcePath)})`, scope: 'hawksearch:read', note: 'Query parameters go in { query: { … } } as the second argument.' };
+        if (resource.toLowerCase() === 'index') return { unavailable: 'Index rebuilds go through app.hawksearch.index.rebuild() (hawksearch:index, elevated), not the dashboard API.' };
+        if (!writable(rules, resource)) return { unavailable: `Writes to ${resource} aren't allowed (403 path_not_allowed): apps write only ${writeResources.join(', ')}.` };
+        if (m === 'DELETE' && resource.toLowerCase() === 'landingpage' && /^bulk/i.test(resourcePath.split('/')[1] ?? '')) return { unavailable: 'Bulk landing-page deletes are blocked (403 path_not_allowed).' };
+        const verb = m.toLowerCase();
+        return {
+            call: `await app.dashboard.${verb}(${quote(resourcePath)}${verb === 'delete' ? '' : ', body'})`,
+            scope: 'hawksearch:write (elevated)',
+            note: `Site keys only; ${writesPerMinute} writes a minute; bulk paths up to ${maxBulkItems} items; audit-logged, never retried.`,
+        };
+    }
+    if (api === 'search') {
+        const limit = `${rules.search.perMinute} calls a minute.`;
+        if (rel === 'api/v2/search') return { call: "await app.hawksearch.search({ Keyword: 'boots' })", scope: 'hawksearch:search', note: `The platform sets ClientGuid to the engine's; IsInPreview: true runs on the preview search API. ${limit}` };
+        if (rel === 'api/v2/autocomplete') return { call: "await app.hawksearch.autocomplete({ Keyword: 'boo' })", scope: 'hawksearch:search', note: `The platform sets ClientGuid to the engine's. ${limit}` };
+        return { unavailable: 'Apps can call only search and autocomplete of the Search API.' };
+    }
+    if (api === 'recommendations') {
+        const { available, perMinute, maxBulkWidgets } = rules.recommendations;
+        if (!available) return { unavailable: "This platform has no recommendation API set up (503 recommendations_not_configured)." };
+        const note = `The platform sets clientGuid, adds visitorId/visitId when you send none, and keeps the call out of the recommendation reports. ${perMinute} calls a minute.`;
+        if (rel === 'api/recommendation/v2/getwidgetitems') return { call: 'await app.hawksearch.recommendations({ widgetUids: [{ widgetGuid, uniqueId }] })', scope: 'hawksearch:recommendations', note };
+        if (rel === 'api/recommendation/v2/getbulkwidgetitems') return { call: 'await app.hawksearch.recommendations({ widgets: [ … ] })', scope: 'hawksearch:recommendations', note: `Up to ${maxBulkWidgets} widgets. ${note}` };
+        return { unavailable: 'Apps get recommendation widgets only (getwidgetitems and getbulkwidgetitems).' };
+    }
+    if (api === 'indexing') {
+        const { operations, maxItemsPerCall, maxIdsPerCall, itemWritesPerMinute, managePerMinute } = rules.indexing;
+        const found = operations.find((o) => o.method.toUpperCase() === m && shape(o.path) === shape(rel));
+        if (!found) return { unavailable: "Not on the platform's Indexing API list (group indexing, index templates, unset-current and internal endpoints are left out on purpose)." };
+        // The app's operation with HawkSearch's own placeholder names (embedding/status/{id} → `embedding/status/${notificationId}`).
+        const names = [...rel.matchAll(/\{(\w+)\}/g)].map((p) => p[1]);
+        const operation = found.operation.includes('{') ? quote(found.operation.replace(/\{[^}]*\}/g, () => `{${names.shift() ?? 'id'}}`)) : `'${found.operation}'`;
+        const helper = INDEX_HELPERS[found.operation];
+        const write = found.scope !== 'hawksearch:index';
+        return {
+            call: `await app.hawksearch.${helper ?? `index.call(${operation}${m === 'POST' ? ', body' : ''})`}`,
+            scope: `${found.scope} (elevated)`,
+            note: write
+                ? `Site keys only; ${maxItemsPerCall} items (or ${maxIdsPerCall} ids) a call; ${found.scope === 'hawksearch:index:items' ? `${itemWritesPerMinute} item writes` : `${managePerMinute} management calls`} a minute; audit-logged, never retried.${found.scope === 'hawksearch:index:items' ? ' Item writes are live at once.' : ''}`
+                : undefined,
+        };
+    }
+    return { unavailable: "Apps can't call this API." };
+}
+
+const HIDDEN_PARAMETERS = /^x-hawksearch-(group)?apikey$/i;
+
+function resolve(schema, spec) {
+    let current = schema;
+    for (let i = 0; current?.$ref && i < 10; i++) current = spec.components?.schemas?.[current.$ref.split('/').pop()];
+    return current ?? {};
+}
+
+function typeOf(schema) {
+    if (!schema) return 'any';
+    if (schema.$ref) return schema.$ref.split('/').pop();
+    if (schema.type === 'array') return `${typeOf(schema.items)}[]`;
+    if (schema.enum) return schema.enum.map((v) => JSON.stringify(v)).join(' | ');
+    if (schema.pattern && /^\^\([\w|]+\)\$$/.test(schema.pattern)) return schema.pattern.slice(2, -2).split('|').map((v) => `"${v}"`).join(' | ');
+    if (schema.type === 'object' && schema.additionalProperties) return `{ [key]: ${typeOf(schema.additionalProperties)} }`;
+    return [schema.type ?? 'object', schema.format].filter(Boolean).join(' ');
+}
+
+const refsOf = (schema) => {
+    if (!schema) return [];
+    if (schema.$ref) return [schema.$ref.split('/').pop()];
+    if (schema.type === 'array') return refsOf(schema.items);
+    if (schema.additionalProperties) return refsOf(schema.additionalProperties);
+    return [];
+};
+
+/** A schema's fields, then those of the schemas it refers to (breadth first, each once). */
+function describeSchema(label, schema, spec) {
+    const lines = [`${label}: ${typeOf(schema)}`];
+    const queue = refsOf(schema);
+    if (!queue.length) {
+        const own = resolve(schema, spec);
+        if (own.properties) lines.push(...fieldLines(own));
+        return lines;
+    }
+    const seen = new Set();
+    while (queue.length) {
+        const name = queue.shift();
+        if (seen.has(name)) continue;
+        seen.add(name);
+        const own = spec.components?.schemas?.[name];
+        if (!own) continue;
+        lines.push('', `${name}${own.description ? ` (${stripHtml(own.description)})` : ''}:`, ...fieldLines(own));
+        for (const property of Object.values(own.properties ?? {})) queue.push(...refsOf(property));
+    }
+    return lines;
+}
+
+function fieldLines(schema) {
+    const required = new Set(schema.required ?? []);
+    return Object.entries(schema.properties ?? {}).map(([name, property]) => {
+        const description = property.description ? `: ${stripHtml(property.description)}` : '';
+        return `- ${name} (${typeOf(property)}${required.has(name) ? ', required' : ''}${property.nullable ? ', nullable' : ''})${description}`;
+    });
+}
+
+const jsonContent = (content) => content?.['application/json'] ?? Object.values(content ?? {})[0];
+
+function detail(operation, definition, rules) {
+    const [path, item] = Object.entries(definition?.paths ?? {})[0] ?? [];
+    const [method, op] = Object.entries(item ?? {}).find(([key]) => /^(get|post|put|delete|patch)$/i.test(key)) ?? [];
+    if (!op) return `# ${operation.title}\n\nThe page has no OpenAPI definition to read: ${operation.url.replace(/\.md$/, '')}`;
+    const access = bridgeCall(operation.api, method, path, rules);
+    const parameters = (op.parameters ?? []).filter((p) => !HIDDEN_PARAMETERS.test(p.name));
+    const body = jsonContent(op.requestBody?.content)?.schema;
+    const response = jsonContent(op.responses?.['200']?.content ?? op.responses?.['201']?.content)?.schema;
+    return [
+        `# ${operation.id}: ${op.summary ?? operation.title}`,
+        `${method.toUpperCase()} ${path} (HawkSearch ${operation.api === 'dashboard' ? 'Dashboard' : operation.api} API, ${operation.group})`,
+        '',
+        stripHtml(op.description ?? operation.summary ?? ''),
+        '',
+        ...(access.unavailable
+            ? [`Not available to apps: ${access.unavailable}`]
+            : ['From an app:', access.call, `Scope: ${access.scope}.${access.note ? ` ${access.note}` : ''}`]),
+        ...(parameters.length
+            ? ['', 'Parameters:', ...parameters.map((p) => `- ${p.name} (${p.in}, ${typeOf(p.schema)}${p.required ? ', required' : ''})${p.description ? `: ${stripHtml(p.description)}` : ''}`)]
+            : []),
+        ...(body ? ['', ...describeSchema('Request body', body, definition)] : []),
+        ...(response ? ['', ...describeSchema('Response', response, definition)] : []),
+        '',
+        `Source: ${operation.url.replace(/\.md$/, '')}`,
+    ]
+        .filter((line, i, all) => line !== '' || all[i - 1] !== '')
+        .join('\n');
+}
+
+async function fetchText(url) {
+    const response = await fetch(url, { signal: AbortSignal.timeout(TIMEOUT_MS) });
+    if (!response.ok) throw new Error(`${url} answered ${response.status}`);
+    return response.text();
+}
+
+/** The platform's default rules, for a reference made without the platform (tests, or no platform at all). */
+const builtInRules = async () => ({ rules: FALLBACK, from: 'the CLI (the platform\'s defaults)' });
+
+/**
+ * describe({ api, operation, offset }) for the tool. llms.txt and each page are cached for a while; when the site
+ * can't be reached, an earlier copy is used if there is one. `rules` is mcp-rules.mjs's createPlatformRules().
+ */
+export function createHawkSearchReference({ load = fetchText, now = Date.now, rules = builtInRules } = {}) {
+    const cache = new Map();
+    async function get(url) {
+        const hit = cache.get(url);
+        if (hit && now() - hit.at < CACHE_MS) return { text: hit.text };
+        try {
+            const text = await load(url);
+            cache.set(url, { text, at: now() });
+            return { text };
+        } catch (error) {
+            if (hit) return { text: hit.text, stale: `(developerdocs.hawksearch.com couldn't be reached just now: ${error.message}. This is the copy from earlier.)` };
+            throw error;
+        }
+    }
+
+    return async function describe({ api, operation, offset = 0 } = {}) {
+        let index;
+        try {
+            index = await get(INDEX_URL);
+        } catch (error) {
+            return { ok: false, text: `Couldn't read HawkSearch's API reference (${error.message}). It's at https://developerdocs.hawksearch.com/reference/getting-started-with-your-api.` };
+        }
+        const operations = operationsIn(index.text);
+        const platform = await rules();
+        const stale = (loaded) => [loaded.stale, platform.note].filter(Boolean).map((note) => `\n\n${note}`).join('');
+        if (api && !operations.some((o) => o.api === api)) return { ok: false, text: `No API "${api}". The APIs: ${Object.keys(APIS).join(', ')}.` };
+        if (operation === undefined) return { ok: true, text: list(operations, api, platform.rules, platform.from) + stale(index) };
+
+        const wanted = operation.trim().toLowerCase();
+        const pool = api ? operations.filter((o) => o.api === api) : operations;
+        let matches = pool.filter((o) => o.id.toLowerCase() === wanted);
+        if (!matches.length) {
+            const words = wanted.split(/[^a-z0-9_]+/).filter((w) => w.length > 1);
+            matches = pool.filter((o) => words.length && words.every((w) => `${o.id} ${o.title} ${o.summary} ${o.group}`.toLowerCase().includes(w)));
+        }
+        if (!matches.length) return { ok: false, text: `No operation matches "${operation}". Call without operation for the list.` };
+        if (matches.length > 1) {
+            return { ok: true, text: `Several operations match "${operation}"; call again with one id:\n${matches.slice(0, 20).map((o) => `- ${o.id}: ${o.title} (${o.api}, ${o.group})`).join('\n')}${matches.length > 20 ? `\n… and ${matches.length - 20} more: use more words.` : ''}` };
+        }
+
+        const [found] = matches;
+        let page;
+        try {
+            page = await get(found.url);
+        } catch (error) {
+            return { ok: false, text: `Couldn't read ${found.url} (${error.message}).` };
+        }
+        const text = detail(found, definitionIn(page.text), platform.rules).slice(offset);
+        const cut = text.length > MAX_TEXT ? `${text.slice(0, MAX_TEXT)}\n… (more: call again with offset ${offset + MAX_TEXT})` : text;
+        return { ok: true, text: cut + stale(page) };
+    };
+}