@yadsh/dsh-qa-surface 0.11.1 → 0.12.0

package/lib/qa-tools/catalog.js

@@ -10,6 +10,9 @@ import { createDocsReadTool, createDocsSearchTool } from "./docs-tools.js";
  * Bump it whenever the catalog's tool set or their schemas change.
  */
 export const QA_TOOL_CATALOG_VERSION = "3";
+function current(value) {
+    return typeof value === "function" ? value() : (value ?? "");
+}
 function createSelfcheckTool(deps) {
     return defineTool({
         name: "qa_tools_selfcheck",
@@ -75,6 +78,14 @@ function createSelfcheckTool(deps) {
  * activation manager owns every registration.
  */
 export function createQaToolCatalog(deps) {
+    const docsOptions = {
+        get root() {
+            return current(deps.docsRoot);
+        },
+        get defaultVersion() {
+            return current(deps.docsDefaultVersion);
+        },
+    };
     return [
         {
             definition: createSelfcheckTool(deps),
@@ -82,12 +93,12 @@ export function createQaToolCatalog(deps) {
             tags: ["activation", "diagnostics"],
         },
         {
-            definition: createDocsSearchTool(),
+            definition: createDocsSearchTool(docsOptions),
             group: "documentation",
             tags: ["docs", "search"],
         },
         {
-            definition: createDocsReadTool(),
+            definition: createDocsReadTool(docsOptions),
             group: "documentation",
             tags: ["docs", "read"],
         },

package/lib/qa-tools/catalog.js.map

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

package/lib/qa-tools/docs-tools.js

@@ -1,6 +1,7 @@
 import { lstat, readFile, readdir } from "node:fs/promises";
-import { isAbsolute, join, relative, resolve } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { defineTool } from "@deepseek-ai/dsh-tools";
+import { isDocumentationVersion } from "../shared/docs-version.js";
 import { canonicalCandidate, pathIsInside } from "../user-workspace.js";
 /**
  * `docs_search` and `docs_read` — the documentation surface of the QA catalog.
@@ -22,6 +23,14 @@ import { canonicalCandidate, pathIsInside } from "../user-workspace.js";
  * names are accepted as filters. A path the convention does not describe is
  * still searched and still read — it simply carries no identity.
  *
+ * A real corpus also carries its own working material: the stand publishes an
+ * asset tree, inventories and triage notes beside the documents, under leading
+ * underscores. None of that is what a question is asked about, and an inventory
+ * names every module and version there is, so a walk that met it first spent the
+ * whole answer on it. The walk therefore visits the documented modules first,
+ * loose files next, and the underscored service material last — searched, but
+ * never at the expense of the documents.
+ *
  * Nothing here is destructive and building it registers nothing: like the rest
  * of the catalog these are side-effect-free definitions, and the workspace root
  * is read from `exec.agent` at call time.
@@ -36,10 +45,76 @@ export const QA_DOCS_READ_DEFAULT_LINES = 120;
 export const QA_DOCS_READ_MAX_LINES = 400;
 /** One file larger than this is not documentation a chat needs to search. */
 const MAX_FILE_BYTES = 2 * 1024 * 1024;
-/** Bound on the walk itself, so a huge tree cannot stall the turn. */
+/** Bound on how many documents one search reads. */
 const MAX_FILES_SCANNED = 2_000;
+/**
+ * Bound on how many entries one walk may look at, so a corpus with a huge asset
+ * tree cannot stall the turn even though nothing in it is read.
+ */
+const MAX_WALK_ENTRIES = 50_000;
 /** A matched line is trimmed to this many characters before it is reported. */
 const MAX_LINE_CHARS = 240;
+/**
+ * Extensions of material that is not documentation text: pictures, audio and
+ * video, archives, office binaries, fonts. A published corpus keeps them beside
+ * its prose — four fifths of the stand's own tree is images — and learning that
+ * by reading each one spends a search's whole document budget before it reaches
+ * a document. These are counted as skipped material, never as documents read.
+ */
+const NON_TEXT_EXTENSIONS = new Set([
+    "avif",
+    "bmp",
+    "bz2",
+    "class",
+    "dll",
+    "doc",
+    "docx",
+    "dylib",
+    "eot",
+    "exe",
+    "flac",
+    "gif",
+    "gz",
+    "heic",
+    "ico",
+    "jar",
+    "jpeg",
+    "jfif",
+    "jpg",
+    "m4a",
+    "m4v",
+    "mkv",
+    "mov",
+    "mp3",
+    "mp4",
+    "odp",
+    "ods",
+    "odt",
+    "ogg",
+    "otf",
+    "pdf",
+    "png",
+    "ppt",
+    "pptx",
+    "rar",
+    "sqlite",
+    "svg",
+    "tar",
+    "tgz",
+    "tif",
+    "tiff",
+    "ttf",
+    "wav",
+    "wasm",
+    "webm",
+    "webp",
+    "woff",
+    "woff2",
+    "xls",
+    "xlsx",
+    "xz",
+    "zip",
+]);
 const TEXT_DECODER = new TextDecoder("utf-8", { fatal: true });
 /**
  * A typed refusal of one documentation call.
@@ -61,14 +136,38 @@ const DOCS_UNAVAILABLE = `this chat's workspace has no ${QA_DOCS_DIRECTORY}/ dir
 const DOCS_NOT_A_DIRECTORY = `the ${QA_DOCS_DIRECTORY}/ entry in this chat's workspace is not a real directory (it is a file or a link), and documentation is never followed through a link.`;
 const DOCS_ESCAPE = `the ${QA_DOCS_DIRECTORY}/ directory resolves outside the calling chat's workspace, so the documentation tree is refused.`;
 const INVALID_QUERY = "no query was given: pass the phrase to look for.";
-const OUTSIDE_DOCS = `this path resolves outside the documentation directory (${QA_DOCS_DIRECTORY}/) of the calling chat's workspace. Documentation is only read where the stand publishes it; pass a path inside ${QA_DOCS_DIRECTORY}/.`;
+const OUTSIDE_DOCS = `this path resolves outside the documentation tree (${QA_DOCS_DIRECTORY}/) this stand reads. Documentation is only read where the stand publishes it; pass a path inside ${QA_DOCS_DIRECTORY}/.`;
+/**
+ * Refusals of a configured root. The operator named the path, so the message
+ * names it too: a typo in a deployment file is not something the model can
+ * diagnose from "documentation is unavailable".
+ */
+const configuredMissing = (root) => `this deployment publishes its documentation at ${root}, and nothing is there. Report that documentation is unavailable rather than guessing its contents.`;
+const configuredNotADirectory = (root) => `this deployment publishes its documentation at ${root}, which is not a real directory (it is a file or a link), and documentation is never followed through a link.`;
+const CONFIGURED_NOT_ABSOLUTE = "the configured documentation root is not an absolute path, so the documentation tree cannot be located. Report that documentation is unavailable rather than guessing its contents.";
 const SYMLINK_ESCAPE = "this path leaves the documentation tree through a symbolic link, and links are not followed out of it.";
 const NOT_FOUND = "no documentation file or directory exists at this path. Check the spelling against a path docs_search reported.";
 const NOT_A_FILE = "this path is a directory, not a documentation file: pass the file to read, or use docs_search to find one.";
 const NOT_TEXT = "this path does not read as UTF-8 text (or is larger than the readable limit), so it is not documentation this tool can return.";
-const VERSION_SEGMENT = /^v?\d+(?:\.\d+)*$/iu;
+/**
+ * The version one search runs under: the caller's own, the deployment's
+ * default, or none.
+ *
+ * An explicit `version` is the model saying which edition it means. An explicit
+ * `path` names a subtree the default has no business overriding — a corpus
+ * scoped to `platform/3.5` stays reachable on a stand whose default is `3.8` —
+ * so a call that named a path is left to that path alone.
+ */
+function versionFor(options, args) {
+    const asked = (args.version ?? "").trim();
+    if (asked !== "")
+        return asked;
+    if ((args.path ?? "").trim() !== "")
+        return "";
+    return (options.defaultVersion ?? "").trim();
+}
 function normalizeVersion(value) {
-    return value.replace(/^v/u, "").toLowerCase();
+    return value.toLowerCase().replace(/^v/u, "");
 }
 /**
  * Identity of one documentation path, read relative to the documentation root.
@@ -86,7 +185,7 @@ export function docsIdentityOf(pathFromDocsRoot) {
         .filter((segment) => segment !== "");
     if (segments.length === 0)
         return identityOf(undefined, undefined);
-    const versionIndex = segments.findIndex((segment) => VERSION_SEGMENT.test(segment));
+    const versionIndex = segments.findIndex((segment) => isDocumentationVersion(segment));
     if (versionIndex === -1)
         return identityOf(undefined, segments[0]);
     return identityOf(segments[versionIndex], versionIndex > 0 ? segments[versionIndex - 1] : undefined);
@@ -113,8 +212,15 @@ function moduleMatches(identity, wanted) {
  * The root is a real directory inside the canonical workspace: a `docs` entry
  * that is a link or a file is refused rather than followed, because the fence
  * is the point of the tool and a link is how a fence is left.
+ *
+ * A deployment that names its corpus once (`QaDocsOptions.root`) skips the
+ * per-chat lookup entirely — that layout is exactly why it configures the root —
+ * and is held to the same rules: absolute, a real directory, no links.
  */
-export async function docsRootOf(exec) {
+export async function docsRootOf(exec, options = {}) {
+    const configured = (options.root ?? "").trim();
+    if (configured !== "")
+        return await configuredDocsRoot(configured);
     const cwd = exec.agent?.session.header.cwd;
     if (typeof cwd !== "string" || cwd.trim() === "") {
         throw new QaDocsError("workspace-unavailable", WORKSPACE_UNAVAILABLE);
@@ -149,6 +255,37 @@ export async function docsRootOf(exec) {
     }
     return { workspace, docs };
 }
+/**
+ * The documentation root a deployment named.
+ *
+ * The parent directory plays the part the chat's workspace plays in the
+ * per-chat layout: `docs/`-relative reporting, the fence and every path rule
+ * below are unchanged, so a configured corpus is read by the same rules as a
+ * published-into-the-workspace one.
+ */
+async function configuredDocsRoot(configured) {
+    if (!isAbsolute(configured)) {
+        throw new QaDocsError("docs-unavailable", CONFIGURED_NOT_ABSOLUTE);
+    }
+    const entry = await lstat(configured).catch((error) => error);
+    if (entry instanceof Error) {
+        if (entry.code === "ENOENT") {
+            throw new QaDocsError("docs-unavailable", configuredMissing(configured));
+        }
+        throw new QaDocsError("workspace-unavailable", WORKSPACE_UNAVAILABLE);
+    }
+    if (entry.isSymbolicLink() || !entry.isDirectory()) {
+        throw new QaDocsError("docs-unavailable", configuredNotADirectory(configured));
+    }
+    let docs;
+    try {
+        docs = canonicalCandidate(configured);
+    }
+    catch {
+        throw new QaDocsError("workspace-unavailable", WORKSPACE_UNAVAILABLE);
+    }
+    return { workspace: dirname(docs), docs };
+}
 /**
  * Resolve one tool path against the documentation root.
  *
@@ -163,11 +300,15 @@ async function docsTargetOf(root, input) {
         throw new QaDocsError("outside-docs", OUTSIDE_DOCS);
     }
     const normalized = trimmed.replace(/\\/gu, "/").replace(/^\.\//u, "");
-    const inside = normalized === QA_DOCS_DIRECTORY ||
-        normalized.startsWith(`${QA_DOCS_DIRECTORY}/`)
-        ? normalized
-        : `${QA_DOCS_DIRECTORY}/${normalized}`;
-    const spelled = resolve(root.workspace, inside);
+    // `docs/` is the stable public spelling, not necessarily the configured
+    // directory's basename. Resolve both accepted spellings from the canonical
+    // root itself so `/srv/published-corpus` still reads `docs/module/file.md`.
+    const pathFromDocs = normalized === QA_DOCS_DIRECTORY
+        ? ""
+        : normalized.startsWith(`${QA_DOCS_DIRECTORY}/`)
+            ? normalized.slice(QA_DOCS_DIRECTORY.length + 1)
+            : normalized;
+    const spelled = resolve(root.docs, pathFromDocs);
     if (!pathIsInside(spelled, root.docs)) {
         throw new QaDocsError("outside-docs", OUTSIDE_DOCS);
     }
@@ -232,20 +373,95 @@ function clamp(value, low, high) {
     return Math.min(Math.max(Math.trunc(value), low), high);
 }
 /**
- * Visit every documentation file of one target, in path order.
+ * Whether a name is the corpus's own working material: the asset tree, the
+ * inventories, the triage notes and anything else a publisher underscored or
+ * dotted.
+ */
+function isServiceName(name) {
+    return name.startsWith("_") || name.startsWith(".");
+}
+/** Whether any segment of a path is such material. */
+function isServicePath(pathFromDocs) {
+    return pathFromDocs.split(/[\\/]/u).some(isServiceName);
+}
+/**
+ * How the entries of one directory are ordered: documents before service
+ * material.
+ *
+ * A corpus keeps its own working material beside the documents, and the stand's
+ * names it with a leading underscore. Name order puts that material first (`_`
+ * sorts before letters), which is exactly where a bounded answer must not spend
+ * itself: an inventory names every module and version the corpus has, so it
+ * matches the question and consumes the budget before a document is opened.
+ * Module directories come first, then loose files at the same level, then
+ * everything underscored or dotted — which is still searched, just after the
+ * documentation. Material inside a service directory stays service material,
+ * however its own entries are named.
+ */
+function entryRank(parentIsService, entry) {
+    if (parentIsService || isServiceName(entry.name))
+        return 2;
+    return entry.isDirectory() ? 0 : 1;
+}
+function entryComparator(parentIsService) {
+    return (left, right) => {
+        const rank = entryRank(parentIsService, left) - entryRank(parentIsService, right);
+        if (rank !== 0)
+            return rank;
+        return left.name < right.name ? -1 : left.name > right.name ? 1 : 0;
+    };
+}
+/**
+ * Which queued directory the walk opens next.
  *
- * Symbolic links are counted as skipped and never followed. The visitor
- * returns `stop` to end the walk, which is how the output budget ends it
- * early.
+ * Rank and path decide, not the order directories happened to be queued in: the
+ * corpus's own `_meta` at the top of the tree must not be read before a
+ * documented module's edition one level below it, which is what a breadth-first
+ * queue did — the inventories answered every question about the product before
+ * a document was reached.
  */
-async function visitDocumentation(target, visit) {
+function scopeComparator(left, right) {
+    const rank = Number(isServicePath(left.pathFromDocs)) -
+        Number(isServicePath(right.pathFromDocs));
+    if (rank !== 0)
+        return rank;
+    if (left.pathFromDocs === right.pathFromDocs)
+        return 0;
+    return left.pathFromDocs < right.pathFromDocs ? -1 : 1;
+}
+/**
+ * Whether a name is material the walk never reads: pictures, media, archives,
+ * office binaries and fonts, recognised by extension.
+ */
+function isNonTextName(name) {
+    const dot = name.lastIndexOf(".");
+    if (dot <= 0)
+        return false;
+    return NON_TEXT_EXTENSIONS.has(name.slice(dot + 1).toLowerCase());
+}
+/**
+ * Visit every documentation file of one target, in walk order.
+ *
+ * Symbolic links are counted as skipped and never followed. A file the caller's
+ * scope excludes is neither read nor counted, and material that is not text is
+ * counted as skipped rather than read, so the document budget below is spent on
+ * documents. The visitor returns `stop` to end the walk, which is how the output
+ * budget ends it early.
+ */
+async function visitDocumentation(target, accept, descend, visit) {
     let filesScanned = 0;
+    let entriesSeen = 0;
     let skipped = 0;
     const info = await lstat(target.absolute).catch(() => undefined);
     if (info === undefined) {
         throw new QaDocsError("not-found", NOT_FOUND);
     }
     if (info.isFile()) {
+        // A path the caller named explicitly is read as it is: out of scope means
+        // no hits, not a refusal, and the refusal it may get comes from the reader.
+        if (!accept(target.pathFromDocs)) {
+            return { filesScanned, skipped, stopped: false };
+        }
         return {
             filesScanned: 1,
             skipped,
@@ -257,24 +473,47 @@ async function visitDocumentation(target, visit) {
     }
     const pending = [target];
     while (pending.length > 0) {
+        // Ranked by path, so the queue's order is the walk's order.
+        pending.sort(scopeComparator);
         const scope = pending.shift();
+        const serviceScope = isServicePath(scope.pathFromDocs);
         const entries = await readdir(scope.absolute, {
             withFileTypes: true,
         }).catch(() => []);
-        entries.sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+        entries.sort(entryComparator(serviceScope));
         for (const entry of entries) {
             const child = join(scope.absolute, entry.name);
             const pathFromDocs = join(scope.pathFromDocs, entry.name);
             if (entry.isSymbolicLink()) {
+                entriesSeen += 1;
+                if (entriesSeen > MAX_WALK_ENTRIES) {
+                    return { filesScanned, skipped, stopped: true };
+                }
                 skipped += 1;
                 continue;
             }
             if (entry.isDirectory()) {
+                if (!descend(pathFromDocs))
+                    continue;
+                entriesSeen += 1;
+                if (entriesSeen > MAX_WALK_ENTRIES) {
+                    return { filesScanned, skipped, stopped: true };
+                }
                 pending.push({ absolute: child, pathFromDocs });
                 continue;
             }
             if (!entry.isFile())
                 continue;
+            if (!accept(pathFromDocs))
+                continue;
+            entriesSeen += 1;
+            if (entriesSeen > MAX_WALK_ENTRIES) {
+                return { filesScanned, skipped, stopped: true };
+            }
+            if (isNonTextName(entry.name)) {
+                skipped += 1;
+                continue;
+            }
             filesScanned += 1;
             if (filesScanned > MAX_FILES_SCANNED) {
                 return { filesScanned, skipped, stopped: true };
@@ -321,9 +560,24 @@ export async function searchDocumentation(root, request) {
             return false;
         return true;
     };
+    const wantedScope = (pathFromDocs) => {
+        // `docsIdentityOf` expects a file path. A synthetic leaf makes the current
+        // directory participate as a scope while still allowing an ancestor that
+        // has not reached its module/version segment yet.
+        const identity = docsIdentityOf(join(pathFromDocs, "__scope__"));
+        if (version !== "" &&
+            identity.version !== undefined &&
+            !versionMatches(identity, version)) {
+            return false;
+        }
+        if (module !== "" &&
+            identity.module !== undefined &&
+            !moduleMatches(identity, module)) {
+            return false;
+        }
+        return true;
+    };
     const visit = async (file, pathFromDocs, explicit) => {
-        if (!wanted(pathFromDocs))
-            return "continue";
         let lines;
         try {
             lines = await readDocLines(file);
@@ -356,7 +610,7 @@ export async function searchDocumentation(root, request) {
         }
         return "continue";
     };
-    const walk = await visitDocumentation(scope, visit);
+    const walk = await visitDocumentation(scope, wanted, wantedScope, visit);
     return {
         ...identityOf(version === "" ? undefined : version, module === "" ? undefined : module),
         query,
@@ -397,7 +651,12 @@ export async function readDocumentation(root, request) {
         text: lines.slice(from - 1, Math.max(to, from - 1)).join("\n"),
     };
 }
-function filtersOf(identity) {
+/**
+ * The facets an answer ran under, as one leading-space clause the callers
+ * interpolate. `note` rides beside them in a report's header — never on a hit's
+ * own label, where it would repeat on every line.
+ */
+function filtersOf(identity, note = "") {
     const parts = [];
     if (identity.version !== undefined && identity.version !== "") {
         parts.push(`version ${identity.version}`);
@@ -405,7 +664,9 @@ function filtersOf(identity) {
     if (identity.module !== undefined && identity.module !== "") {
         parts.push(`module ${identity.module}`);
     }
-    return parts.length === 0 ? "" : ` (${parts.join(", ")})`;
+    const facets = parts.join(", ");
+    const described = note === "" ? facets : facets === "" ? note : `${facets}, ${note}`;
+    return described === "" ? "" : ` (${described})`;
 }
 function identityLabel(identity) {
     return filtersOf(identity);
@@ -418,10 +679,10 @@ function identityLabel(identity) {
  * version/module facets exist so a model that has been told "3.8" stops
  * sweeping the whole tree.
  */
-export function createDocsSearchTool() {
+export function createDocsSearchTool(options = {}) {
     return defineTool({
         name: "docs_search",
-        description: `Search the stand's documentation, which lives in the ${QA_DOCS_DIRECTORY}/ directory of this chat's workspace. Use it — not memory and not a glob sweep over guessed paths — whenever a question is about the product, a version or a module. Hits are lines, tagged with the module and version parsed from the path (${QA_DOCS_DIRECTORY}/<module>/<version>/…); pass version and module to stay inside one edition, and path to stay inside one subtree. Output is bounded by limit and by a byte budget, and a truncated result says so.`,
+        description: `Search the stand's documentation, which lives ${docsLayout(options)}. Use it — not memory and not a glob sweep over guessed paths — whenever a question is about the product, a version or a module. Hits are lines, tagged with the module and version parsed from the path (${QA_DOCS_DIRECTORY}/<module>/<version>/…); pass version and module to stay inside one edition, and path to stay inside one subtree. Output is bounded by limit and by a byte budget, and a truncated result says so.${defaultVersionNote(options)}`,
         parameters: {
             query: {
                 type: "string",
@@ -470,11 +731,15 @@ export function createDocsSearchTool() {
                     truncated: { type: "boolean", required: true },
                     filesScanned: { type: "integer", required: true },
                     skipped: { type: "integer", required: true },
+                    // A search answers with the facets it ran under, so a filtered result
+                    // says which edition of which module it is speaking about.
+                    version: { type: "string" },
+                    module: { type: "string" },
                 },
             },
-            render: (_args, value) => {
+            render: (args, value) => {
                 const result = value;
-                const filters = filtersOf(result);
+                const filters = filtersOf(result, defaultedVersion(options, args) ? "the stand's default" : "");
                 if (result.hits.length === 0) {
                     return [
                         {
@@ -493,10 +758,10 @@ export function createDocsSearchTool() {
             },
         },
         execute: async (args, exec) => {
-            const root = await docsRootOf(exec);
+            const root = await docsRootOf(exec, options);
             return searchDocumentation(root, {
                 query: args.query,
-                version: args.version,
+                version: versionFor(options, args),
                 module: args.module,
                 path: args.path,
                 limit: args.limit,
@@ -504,11 +769,48 @@ export function createDocsSearchTool() {
         },
     });
 }
+/**
+ * Whether the version in an answer is the deployment's default rather than one
+ * the caller named — the difference between "I looked in 3.8" and "the stand
+ * looked in 3.8", which the report has to keep.
+ */
+function defaultedVersion(options, args) {
+    const request = (args ?? {});
+    const asked = request.version;
+    if (typeof asked === "string" && asked.trim() !== "")
+        return false;
+    if (typeof request.path === "string" && request.path.trim() !== "") {
+        return false;
+    }
+    return (options.defaultVersion ?? "").trim() !== "";
+}
+/**
+ * The sentence that tells the model which edition a search it did not scope
+ * itself will stay inside. Without it the model reads a filtered answer as the
+ * whole corpus and reports a missing document rather than a narrowed search.
+ */
+function defaultVersionNote(options) {
+    const version = (options.defaultVersion ?? "").trim();
+    return version === ""
+        ? ""
+        : ` This stand documents version ${version} by default: a search without version and without path stays inside that edition, and pass version or path to look at another one.`;
+}
+/**
+ * How the tool description names the tree: the model has to know where the
+ * documentation is before it decides to look, and a configured corpus is named
+ * by the stand rather than by the chat, so the sentence differs.
+ */
+function docsLayout(options) {
+    const root = (options.root ?? "").trim();
+    return root === ""
+        ? `in the ${QA_DOCS_DIRECTORY}/ directory of this chat's workspace`
+        : `in the ${QA_DOCS_DIRECTORY}/ tree this stand publishes (reported as ${QA_DOCS_DIRECTORY}/<module>/<version>/…)`;
+}
 /** `docs_read` — open one documentation file at a bounded window of lines. */
-export function createDocsReadTool() {
+export function createDocsReadTool(options = {}) {
     return defineTool({
         name: "docs_read",
-        description: `Read one documentation file of this chat's workspace, ${QA_DOCS_DIRECTORY}/, at a bounded window of lines. Use it after docs_search reports a path, to read the passage a hit belongs to. Only files inside ${QA_DOCS_DIRECTORY}/ can be read; directories, paths outside the tree and paths that leave it through a symbolic link are refused with the reason.`,
+        description: `Read one documentation file of the stand's documentation, which lives ${docsLayout(options)}, at a bounded window of lines. Use it after docs_search reports a path, to read the passage a hit belongs to. Only files inside ${QA_DOCS_DIRECTORY}/ can be read; directories, paths outside the tree and paths that leave it through a symbolic link are refused with the reason.`,
         parameters: {
             path: {
                 type: "string",
@@ -551,7 +853,7 @@ export function createDocsReadTool() {
             },
         },
         execute: async (args, exec) => {
-            const root = await docsRootOf(exec);
+            const root = await docsRootOf(exec, options);
             return readDocumentation(root, {
                 path: args.path,
                 from: args.from,