@honua/mcp-server 0.1.2-beta.0 → 0.1.8-beta.0

package/dist/src/tools/describe-layer.js

@@ -1,19 +1,110 @@
 import { z } from "zod";
 import { jsonText } from "../helpers.js";
+import { withCapabilityHonesty } from "../neutral/errors.js";
+import { ogcLayoutFor, resolveSource, sourceRefFields } from "../neutral/source-ref.js";
+/**
+ * `honua_describe_layer` — protocol-neutral source description (#1005).
+ *
+ * The envelope is the same for every protocol: the neutral source reference,
+ * its protocol, the capabilities the runtime will actually honor, and a field
+ * schema. Where the schema comes from is protocol-specific (GeoServices layer
+ * metadata, an OGC collection + its queryables); the shape the agent reads is
+ * not. Protocols with no metadata document report `schemaAvailable: false`
+ * with a reason instead of an empty field list, which would read as "this
+ * source has no attributes".
+ */
 export const schema = z.object({
-    serviceId: z.string().describe("The feature service ID"),
-    layerId: z.number().int().nonnegative().describe("The layer ID within the service"),
+    ...sourceRefFields,
 });
-export async function execute(client, input) {
-    const meta = await client.getLayerMetadata(input.serviceId, input.layerId);
-    return jsonText({
-        id: meta.id,
-        name: meta.name,
+async function describeGeoServices(client, resolved) {
+    const { serviceId, layerId } = resolved.descriptor.locator;
+    const meta = await client.getLayerMetadata(serviceId, layerId);
+    return {
+        name: meta.name ?? null,
         description: meta.description ?? null,
         geometryType: meta.geometryType ?? null,
-        fields: (meta.fields ?? []).map((f) => ({ name: f.name, type: f.type, alias: f.alias ?? f.name })),
+        fields: (meta.fields ?? []).map((f) => ({ name: f.name, type: f.type ?? null, alias: f.alias ?? f.name })),
         extent: meta.extent ?? null,
         spatialReference: meta.spatialReference ?? null,
         relationships: meta.relationships ?? [],
+        schemaAvailable: true,
+    };
+}
+function bboxToExtent(bbox) {
+    if (!bbox || bbox.length < 4)
+        return null;
+    const [xmin, ymin, xmax, ymax] = bbox;
+    return { xmin, ymin, xmax, ymax };
+}
+async function describeOgcCollection(client, resolved) {
+    const collectionId = resolved.descriptor.locator.collectionId;
+    const layout = await ogcLayoutFor(client, resolved.ref.layout);
+    const request = { collectionId, ...(layout ? { layout } : {}) };
+    const meta = resolved.descriptor.protocol === "ogc-records"
+        ? await client.getOgcRecordCollection(request)
+        : await client.getOgcCollection(request);
+    let fields = [];
+    let schemaAvailable = true;
+    let schemaReason;
+    try {
+        const queryables = await client.getOgcQueryables(request);
+        fields = Object.entries(queryables.properties ?? {}).map(([name, property]) => ({
+            name,
+            type: property.type ?? null,
+            alias: property.title ?? name,
+        }));
+        if (fields.length === 0) {
+            schemaAvailable = false;
+            schemaReason = "the collection advertises no queryable properties.";
+        }
+    }
+    catch (error) {
+        schemaAvailable = false;
+        schemaReason = `queryables are not published by this endpoint: ${error instanceof Error ? error.message : String(error)}`;
+    }
+    const temporal = meta.extent?.temporal?.interval?.[0];
+    return {
+        name: meta.title ?? meta.id ?? collectionId,
+        description: meta.description ?? null,
+        geometryType: null,
+        fields,
+        extent: bboxToExtent(meta.extent?.spatial?.bbox?.[0]),
+        spatialReference: meta.extent?.spatial?.crs ?? meta.crs?.[0] ?? null,
+        relationships: [],
+        ...(temporal ? { timeField: null } : {}),
+        schemaAvailable,
+        ...(schemaReason ? { schemaReason } : {}),
+    };
+}
+function describeFromDescriptorOnly(resolved) {
+    return {
+        name: resolved.ref.address,
+        description: null,
+        geometryType: null,
+        fields: [],
+        extent: null,
+        spatialReference: null,
+        relationships: [],
+        schemaAvailable: false,
+        schemaReason: `protocol "${resolved.descriptor.protocol}" publishes no schema document this server can read without a discovery pass; query the source and inspect the returned attributes instead.`,
+    };
+}
+export async function execute(client, input) {
+    return withCapabilityHonesty(async () => {
+        const resolved = resolveSource(client, input);
+        const protocol = resolved.descriptor.protocol;
+        const envelope = protocol === "geoservices-feature-service" || protocol === "geoservices-map-service" || protocol === "grpc"
+            ? await describeGeoServices(client, resolved)
+            : protocol === "ogc-features" || protocol === "ogc-records"
+                ? await describeOgcCollection(client, resolved)
+                : describeFromDescriptorOnly(resolved);
+        return jsonText({
+            source: resolved.ref.ref,
+            protocol,
+            capabilities: [...resolved.source.capabilities].sort(),
+            ...envelope,
+            // Retained for clients written against the pre-#1005 shape.
+            id: resolved.descriptor.locator.layerId ?? resolved.ref.address,
+        });
     });
 }

package/dist/src/tools/docs-search.d.ts

@@ -0,0 +1,100 @@
+import { z } from "zod";
+export declare const schema: z.ZodObject<{
+    query: z.ZodString;
+    limit: z.ZodOptional<z.ZodNumber>;
+    pathPrefix: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+    limit?: number | undefined;
+    pathPrefix?: string | undefined;
+}, {
+    query: string;
+    limit?: number | undefined;
+    pathPrefix?: string | undefined;
+}>;
+export type Input = z.infer<typeof schema>;
+/** One document sliced out of the concatenated corpus. */
+export interface CorpusDocument {
+    file: string;
+    title: string;
+    body: string;
+}
+export interface DocsVersionCitation {
+    package: string;
+    version: string;
+    channel: string;
+    /** Whether the corpus text is trunk development documentation or a release snapshot. */
+    documentationChannel: "development";
+    policy: string;
+    versionsManifest: string;
+}
+/**
+ * Split `llms-full.txt` into its constituent documents. The generator emits
+ * `# File: <path>` as the delimiter for each concatenated document.
+ */
+export declare function splitCorpus(corpus: string): CorpusDocument[];
+/**
+ * The terms a query is actually ranked and excerpted on: distinct tokens with
+ * the stopwords removed. A query made entirely of stopwords ("how do I") keeps
+ * its raw tokens rather than degrading to "no indexed document matched", so
+ * filtering can only ever improve a ranking, never empty one.
+ */
+export declare function queryTermsOf(query: string): string[];
+/** Deterministic lexical score: path and heading matches outweigh body matches. */
+export declare function scoreDocument(document: CorpusDocument, queryTerms: readonly string[]): number;
+/** The most relevant window of a document, trimmed to a token-friendly size. */
+export declare function excerptFor(document: CorpusDocument, queryTerms: readonly string[]): string;
+/** Where the corpus is, and the documentation root its citations resolve against. */
+export interface DocsCorpusLocation {
+    /** The file that is actually read — the configured override when there is one. */
+    corpusPath: string;
+    /** The directory `docs/versions.json`, `package.json`, and the manifest are read from. */
+    root: string;
+}
+/**
+ * Locate the corpus: an explicit `HONUA_DOCS_CORPUS_PATH` (the corpus file
+ * itself, or a directory holding one), otherwise the nearest ancestor directory
+ * holding `llms-full.txt`.
+ *
+ * The override names the file to read, so it is read — its basename is not
+ * assumed to be `llms-full.txt`. Discarding it and reading `<parent>/llms-full.txt`
+ * instead would throw `ENOENT` for a corpus under any other name, or silently
+ * answer from a different sibling file.
+ */
+export declare function resolveDocsCorpus(env?: NodeJS.ProcessEnv, from?: string): DocsCorpusLocation | undefined;
+/** The documentation root holding the corpus, or `undefined` when there is none. */
+export declare function resolveDocsRoot(env?: NodeJS.ProcessEnv, from?: string): string | undefined;
+/**
+ * The release the corpus documents, from the same authoritative sources as
+ * `scripts/docs-versions.mjs`. Prefers the generated `docs/versions.json` and
+ * falls back to `package.json` + `.release-please-manifest.json`.
+ */
+export declare function resolveDocsVersion(root: string): DocsVersionCitation | undefined;
+/**
+ * The exact commit the searched corpus bytes come from, or `undefined` when it
+ * cannot be established.
+ *
+ * `docs/documentation-versions.md` is explicit that a matching version string
+ * is not proof that development documentation describes the npm artifact, and
+ * that every built page identifies its 40-character source commit. A citation
+ * pinned to `trunk` breaks that: `trunk` moves, and the text a reader is sent
+ * to can stop being the text that was searched. So citations are pinned to the
+ * commit instead, using the same `HONUA_SOURCE_REVISION` override
+ * `scripts/build-docs-site.mjs` honours.
+ *
+ * The commit is only used when the corpus at `HEAD` is byte-identical to the
+ * corpus that was read (`git hash-object` against `HEAD:<path>`). A locally
+ * regenerated or edited `llms-full.txt` is not at any commit, and pinning it to
+ * `HEAD` would produce a citation that looks exact and is wrong. When nothing
+ * can be established — an installed package with no checkout, no `git`, a dirty
+ * corpus — the URL stays on `trunk` and the citation reports
+ * `sourceRevision: null` so the consumer can see the link is floating.
+ */
+export declare function resolveCorpusRevision(root: string, corpusPath: string, env?: NodeJS.ProcessEnv): string | undefined;
+export declare function execute(_client: unknown, input: Input): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+}>;
+//# sourceMappingURL=docs-search.d.ts.map

package/dist/src/tools/docs-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-search.d.ts","sourceRoot":"","sources":["../../../src/tools/docs-search.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAmHxB,eAAO,MAAM,MAAM;;;;;;;;;;;;EAUjB,CAAC;AAEH,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,MAAM,CAAC,CAAC;AAE3C,0DAA0D;AAC1D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,wFAAwF;IACxF,oBAAoB,EAAE,aAAa,CAAC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,EAAE,CAe5D;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAIpD;AAYD,mFAAmF;AACnF,wBAAgB,aAAa,CAAC,QAAQ,EAAE,cAAc,EAAE,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAgB7F;AAED,gFAAgF;AAChF,wBAAgB,UAAU,CAAC,QAAQ,EAAE,cAAc,EAAE,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAgB1F;AAED,qFAAqF;AACrF,MAAM,WAAW,kBAAkB;IACjC,kFAAkF;IAClF,UAAU,EAAE,MAAM,CAAC;IACnB,0FAA0F;IAC1F,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAkBrH;AAED,oFAAoF;AACpF,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEvG;AAeD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS,CAoBhF;AAcD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,GAAG,SAAS,CAepB;AAMD,wBAAsB,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK;;;;;GA4D3D"}

package/dist/src/tools/docs-search.js

@@ -0,0 +1,381 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import { capabilityUnavailable } from "../capability.js";
+import { jsonText } from "../helpers.js";
+/**
+ * `honua_docs_search` — answer a documentation question from the repository's
+ * own versioned documentation corpus, with citations.
+ *
+ * The corpus is `llms-full.txt` (generated by `npm run docs:llms`), which
+ * concatenates the documents indexed in `llms.txt` under `# File: <path>`
+ * headers. Every hit therefore carries the exact source file it came from and
+ * the commit those bytes are at (so the citation keeps naming the text that was
+ * actually searched once `trunk` moves), and the version block carries the
+ * release that documentation describes — derived
+ * from `docs/versions.json` when it has been generated
+ * (`npm run docs:versions:write`) and otherwise directly from `package.json` +
+ * `.release-please-manifest.json`, the same authoritative pair
+ * `scripts/docs-versions.mjs` uses. The policy those citations follow is
+ * documented in `docs/documentation-versions.md`.
+ *
+ * This is a LOCAL tool: it reads committed files and never makes a network
+ * request. When the corpus cannot be located (for example inside an installed
+ * `@honua/mcp-server` that does not ship the corpus), it degrades the same way
+ * every other surface-dependent tool does — a structured `available: false`
+ * result with guidance, not a crash and not a misleading empty answer.
+ */
+const REPOSITORY = "honua-io/honua-sdk-js";
+const SITE_URL = "https://honua-io.github.io/honua-sdk-js/";
+const CORPUS_FILE = "llms-full.txt";
+const MAX_EXCERPT_CHARS = 1200;
+const EXCERPT_CONTEXT_LINES = 6;
+const COMMIT_PATTERN = /^[0-9a-f]{40}$/;
+/**
+ * Function words carry no retrieval signal but appear in every document, so on
+ * a natural-language question ("how do I handle a capability error") they match
+ * everywhere, add frequency weight everywhere, and inflate the matched-term
+ * multiplier everywhere -- which is exactly enough to push `docs/errors.md`
+ * below `docs/guide.md` and out of the default three results. Terms shorter
+ * than two characters are already dropped by the tokenizer.
+ */
+const STOPWORDS = new Set([
+    "about",
+    "all",
+    "an",
+    "and",
+    "any",
+    "are",
+    "as",
+    "at",
+    "be",
+    "been",
+    "but",
+    "by",
+    "can",
+    "do",
+    "does",
+    "doing",
+    "done",
+    "for",
+    "from",
+    "get",
+    "getting",
+    "has",
+    "have",
+    "how",
+    "if",
+    "in",
+    "into",
+    "is",
+    "it",
+    "its",
+    "me",
+    "my",
+    "not",
+    "of",
+    "on",
+    "onto",
+    "or",
+    "our",
+    "should",
+    "so",
+    "some",
+    "that",
+    "the",
+    "their",
+    "them",
+    "then",
+    "there",
+    "these",
+    "they",
+    "this",
+    "to",
+    "up",
+    "use",
+    "used",
+    "using",
+    "via",
+    "want",
+    "was",
+    "we",
+    "what",
+    "when",
+    "where",
+    "which",
+    "who",
+    "why",
+    "will",
+    "with",
+    "would",
+    "you",
+    "your",
+]);
+export const schema = z.object({
+    query: z
+        .string()
+        .min(2)
+        .describe("Natural-language or keyword documentation question, e.g. 'how do I handle a capability error'"),
+    limit: z.number().int().min(1).max(10).optional().describe("Maximum documents to return (default 3)"),
+    pathPrefix: z
+        .string()
+        .optional()
+        .describe("Restrict results to source files whose path starts with this value, e.g. 'docs/' or 'mcp/'"),
+});
+/**
+ * Split `llms-full.txt` into its constituent documents. The generator emits
+ * `# File: <path>` as the delimiter for each concatenated document.
+ */
+export function splitCorpus(corpus) {
+    const documents = [];
+    const pattern = /^# File: (.+)$/gm;
+    const matches = [...corpus.matchAll(pattern)];
+    for (const [index, match] of matches.entries()) {
+        const start = (match.index ?? 0) + match[0].length;
+        const end = index + 1 < matches.length ? (matches[index + 1].index ?? corpus.length) : corpus.length;
+        const body = corpus
+            .slice(start, end)
+            .replace(/\n-{3,}\s*$/, "")
+            .trim();
+        const heading = /^#\s+(.+)$/m.exec(body);
+        documents.push({ file: match[1].trim(), title: heading?.[1]?.trim() ?? match[1].trim(), body });
+    }
+    return documents;
+}
+/**
+ * The terms a query is actually ranked and excerpted on: distinct tokens with
+ * the stopwords removed. A query made entirely of stopwords ("how do I") keeps
+ * its raw tokens rather than degrading to "no indexed document matched", so
+ * filtering can only ever improve a ranking, never empty one.
+ */
+export function queryTermsOf(query) {
+    const tokens = [...new Set(query.toLowerCase().match(/[a-z0-9_./-]{2,}/g) ?? [])];
+    const significant = tokens.filter((token) => !STOPWORDS.has(token));
+    return significant.length > 0 ? significant : tokens;
+}
+function countOccurrences(haystack, needle) {
+    let count = 0;
+    let index = haystack.indexOf(needle);
+    while (index !== -1) {
+        count += 1;
+        index = haystack.indexOf(needle, index + needle.length);
+    }
+    return count;
+}
+/** Deterministic lexical score: path and heading matches outweigh body matches. */
+export function scoreDocument(document, queryTerms) {
+    const file = document.file.toLowerCase();
+    const body = document.body.toLowerCase();
+    const headings = (document.body.match(/^#{1,4} .+$/gm) ?? []).join("\n").toLowerCase();
+    let score = 0;
+    let matched = 0;
+    for (const term of queryTerms) {
+        const inBody = countOccurrences(body, term);
+        const inHeadings = countOccurrences(headings, term);
+        const inPath = countOccurrences(file, term);
+        if (inBody + inHeadings + inPath > 0)
+            matched += 1;
+        score += Math.min(inBody, 20) + inHeadings * 3 + inPath * 8;
+    }
+    // Require more than a single incidental term hit on multi-term queries.
+    if (matched === 0)
+        return 0;
+    return score * matched;
+}
+/** The most relevant window of a document, trimmed to a token-friendly size. */
+export function excerptFor(document, queryTerms) {
+    const lines = document.body.split("\n");
+    let bestLine = 0;
+    let bestHits = 0;
+    for (const [index, line] of lines.entries()) {
+        const lower = line.toLowerCase();
+        const hits = queryTerms.reduce((total, term) => total + countOccurrences(lower, term), 0);
+        if (hits > bestHits) {
+            bestHits = hits;
+            bestLine = index;
+        }
+    }
+    const start = Math.max(0, bestLine - EXCERPT_CONTEXT_LINES);
+    const end = Math.min(lines.length, bestLine + EXCERPT_CONTEXT_LINES + 1);
+    const excerpt = lines.slice(start, end).join("\n").trim();
+    return excerpt.length > MAX_EXCERPT_CHARS ? `${excerpt.slice(0, MAX_EXCERPT_CHARS)}…` : excerpt;
+}
+/**
+ * Locate the corpus: an explicit `HONUA_DOCS_CORPUS_PATH` (the corpus file
+ * itself, or a directory holding one), otherwise the nearest ancestor directory
+ * holding `llms-full.txt`.
+ *
+ * The override names the file to read, so it is read — its basename is not
+ * assumed to be `llms-full.txt`. Discarding it and reading `<parent>/llms-full.txt`
+ * instead would throw `ENOENT` for a corpus under any other name, or silently
+ * answer from a different sibling file.
+ */
+export function resolveDocsCorpus(env = process.env, from) {
+    const override = env.HONUA_DOCS_CORPUS_PATH;
+    if (override) {
+        const resolved = path.resolve(override);
+        if (!fs.existsSync(resolved))
+            return undefined;
+        const corpusPath = fs.statSync(resolved).isDirectory() ? path.join(resolved, CORPUS_FILE) : resolved;
+        if (!fs.existsSync(corpusPath))
+            return undefined;
+        return { corpusPath, root: path.dirname(corpusPath) };
+    }
+    let dir = from ?? path.dirname(fileURLToPath(import.meta.url));
+    for (let depth = 0; depth < 10; depth += 1) {
+        const corpusPath = path.join(dir, CORPUS_FILE);
+        if (fs.existsSync(corpusPath))
+            return { corpusPath, root: dir };
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return undefined;
+}
+/** The documentation root holding the corpus, or `undefined` when there is none. */
+export function resolveDocsRoot(env = process.env, from) {
+    return resolveDocsCorpus(env, from)?.root;
+}
+function readJson(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function channelOf(version) {
+    const prerelease = version.split("-", 2)[1];
+    return prerelease ? prerelease.split(".", 1)[0] : "stable";
+}
+/**
+ * The release the corpus documents, from the same authoritative sources as
+ * `scripts/docs-versions.mjs`. Prefers the generated `docs/versions.json` and
+ * falls back to `package.json` + `.release-please-manifest.json`.
+ */
+export function resolveDocsVersion(root) {
+    const generated = readJson(path.join(root, "docs", "versions.json"));
+    const packageName = typeof generated?.package === "string" ? generated.package : "@honua/sdk-js";
+    const citation = (version) => ({
+        package: packageName,
+        version,
+        channel: channelOf(version),
+        documentationChannel: "development",
+        policy: "docs/documentation-versions.md",
+        versionsManifest: `${SITE_URL}versions.json`,
+    });
+    if (typeof generated?.latestRelease === "string")
+        return citation(generated.latestRelease);
+    const pkg = readJson(path.join(root, "package.json"));
+    const manifest = readJson(path.join(root, ".release-please-manifest.json"));
+    const version = typeof pkg?.version === "string" ? pkg.version : undefined;
+    const manifestVersion = typeof manifest?.["."] === "string" ? manifest["."] : undefined;
+    if (!version || !manifestVersion || version !== manifestVersion)
+        return undefined;
+    return citation(version);
+}
+function git(root, args) {
+    try {
+        return execFileSync("git", [...args], {
+            cwd: root,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The exact commit the searched corpus bytes come from, or `undefined` when it
+ * cannot be established.
+ *
+ * `docs/documentation-versions.md` is explicit that a matching version string
+ * is not proof that development documentation describes the npm artifact, and
+ * that every built page identifies its 40-character source commit. A citation
+ * pinned to `trunk` breaks that: `trunk` moves, and the text a reader is sent
+ * to can stop being the text that was searched. So citations are pinned to the
+ * commit instead, using the same `HONUA_SOURCE_REVISION` override
+ * `scripts/build-docs-site.mjs` honours.
+ *
+ * The commit is only used when the corpus at `HEAD` is byte-identical to the
+ * corpus that was read (`git hash-object` against `HEAD:<path>`). A locally
+ * regenerated or edited `llms-full.txt` is not at any commit, and pinning it to
+ * `HEAD` would produce a citation that looks exact and is wrong. When nothing
+ * can be established — an installed package with no checkout, no `git`, a dirty
+ * corpus — the URL stays on `trunk` and the citation reports
+ * `sourceRevision: null` so the consumer can see the link is floating.
+ */
+export function resolveCorpusRevision(root, corpusPath, env = process.env) {
+    const declared = env.HONUA_SOURCE_REVISION?.trim().toLowerCase();
+    if (declared && COMMIT_PATTERN.test(declared))
+        return declared;
+    const top = git(root, ["rev-parse", "--show-toplevel"]);
+    if (!top)
+        return undefined;
+    const head = git(root, ["rev-parse", "HEAD"])?.toLowerCase();
+    if (!head || !COMMIT_PATTERN.test(head))
+        return undefined;
+    const relative = path.relative(top, path.resolve(corpusPath)).split(path.sep).join("/");
+    if (relative.startsWith(".."))
+        return undefined;
+    const committed = git(root, ["rev-parse", `HEAD:${relative}`]);
+    const working = git(root, ["hash-object", corpusPath]);
+    if (!committed || !working || committed !== working)
+        return undefined;
+    return head;
+}
+function sourceUrl(file, revision) {
+    return `https://github.com/${REPOSITORY}/blob/${revision ?? "trunk"}/${file}`;
+}
+export async function execute(_client, input) {
+    const located = resolveDocsCorpus();
+    if (!located) {
+        return capabilityUnavailable("Honua documentation corpus", `${CORPUS_FILE} was not found in this installation or any parent directory`, "Run `npm run docs:llms` in a honua-sdk-js checkout, or point HONUA_DOCS_CORPUS_PATH at a generated llms-full.txt.");
+    }
+    const { corpusPath, root } = located;
+    const version = resolveDocsVersion(root);
+    if (!version) {
+        return capabilityUnavailable("Honua documentation versions", "package.json and .release-please-manifest.json disagree or are unavailable, so no release can be cited", "Run `npm run docs:versions:write` in a honua-sdk-js checkout so documentation answers can cite a release.");
+    }
+    const documents = splitCorpus(fs.readFileSync(corpusPath, "utf8"));
+    const revision = resolveCorpusRevision(root, corpusPath);
+    const queryTerms = queryTermsOf(input.query);
+    const prefix = input.pathPrefix?.toLowerCase();
+    const results = documents
+        .filter((document) => (prefix ? document.file.toLowerCase().startsWith(prefix) : true))
+        .map((document) => ({ document, score: scoreDocument(document, queryTerms) }))
+        .filter((entry) => entry.score > 0)
+        .sort((a, b) => b.score - a.score || a.document.file.localeCompare(b.document.file))
+        .slice(0, input.limit ?? 3)
+        .map((entry) => ({
+        title: entry.document.title,
+        score: entry.score,
+        excerpt: excerptFor(entry.document, queryTerms),
+        citation: {
+            file: entry.document.file,
+            url: sourceUrl(entry.document.file, revision),
+            // The commit the cited text was read at. `null` means the URL floats on
+            // `trunk` and the text there may already differ from what was searched.
+            sourceRevision: revision ?? null,
+            package: version.package,
+            version: version.version,
+            channel: version.channel,
+        },
+    }));
+    return jsonText({
+        available: true,
+        query: input.query,
+        release: version,
+        corpus: { file: path.basename(corpusPath), documents: documents.length, sourceRevision: revision ?? null },
+        results,
+        ...(results.length === 0
+            ? {
+                guidance: "No indexed document matched. Try fewer or more specific terms, or drop pathPrefix. An empty result means the corpus has no matching text, not that the capability is missing.",
+            }
+            : {}),
+    });
+}