@yadsh/dsh-qa-surface 0.11.2 → 0.12.0

package/lib/types/config-resolvers/tools.d.ts

@@ -2,5 +2,14 @@ import type { QaSurfaceConfig, ResolvedQaSurfaceConfig } from "../types.js";
 type ToolsSlice = ResolvedQaSurfaceConfig["tools"];
 /** Resolve the QA tool delivery domain: activation trigger, policy, and scope. */
 export declare function resolveTools(input: QaSurfaceConfig): ToolsSlice;
+/**
+ * The version one search runs under, or `""` when the deployment's default is
+ * off, unset, or not what the call is about.
+ *
+ * The readers take a single fallback, and a switch that is off must not fall
+ * back at all — the value stays configured for the day it is turned on, and an
+ * enabled-but-empty pair is simply no default.
+ */
+export declare function docsDefaultVersionOf(tools: ResolvedQaSurfaceConfig["tools"]): string;
 export {};
 //# sourceMappingURL=tools.d.ts.map

package/lib/types/qa-tools/catalog.d.ts

@@ -23,7 +23,12 @@ export interface QaToolsSelfcheckDeps {
      * Documentation root the two readers use, or `""` for the `docs/` directory
      * inside each chat's own workspace.
      */
-    readonly docsRoot?: string;
+    readonly docsRoot?: string | (() => string);
+    /**
+     * Version a search without `version` and without `path` stays inside, or `""`
+     * for a search across every edition the corpus carries.
+     */
+    readonly docsDefaultVersion?: string | (() => string);
 }
 /**
  * Build the shipped QA tool catalog.

package/lib/types/qa-tools/docs-tools.d.ts

@@ -19,6 +19,14 @@ import type { ToolDefinition } from "@deepseek-ai/dsh-tools";
  * 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.
@@ -67,6 +75,13 @@ interface QaDocsExecution {
 export interface QaDocsOptions {
     /** Absolute documentation root, or `""` for `<chat workspace>/docs`. */
     readonly root?: string;
+    /**
+     * Documentation version a search stays inside when the caller named neither
+     * `version` nor `path`; `""` (the default) leaves every edition in scope. The
+     * deployment sets it so a chat's questions do not have to carry the stand's
+     * edition, and an explicit `version` or `path` still decides for itself.
+     */
+    readonly defaultVersion?: string;
 }
 /** The resolved documentation root of one call. */
 export interface QaDocsRoot {

package/lib/types/qa-tools/index.d.ts

@@ -9,7 +9,12 @@ export interface QaToolsOptions {
     readonly activationMode: string;
     readonly activationPresets: readonly string[];
     /** Documentation root the readers use; `""` reads each chat's own `docs/`. */
-    readonly docsRoot: string;
+    readonly docsRoot: string | (() => string);
+    /**
+     * Version a search falls back to when the model named neither `version` nor
+     * `path`; `""` searches every edition the corpus carries.
+     */
+    readonly docsDefaultVersion: string | (() => string);
 }
 /**
  * The QA tool subsystem: one catalog, one per-agent activation manager, and the

package/lib/types/shared/docs-version.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The documentation version grammar, shared by the Host and the browser half.
+ *
+ * This module must stay dependency-free: the settings card bundle inlines the
+ * resolver that validates a configured default version, and a browser build
+ * must not pull the QA tool runtime — or the Node builtins it reads files with
+ * — into the page just to learn what a version looks like.
+ */
+/**
+ * Whether a path segment — or a configured default version — is a documentation
+ * version. A default the corpus can never match is refused where it is written
+ * rather than answered with an empty search.
+ */
+export declare function isDocumentationVersion(value: string): boolean;
+//# sourceMappingURL=docs-version.d.ts.map

package/lib/types/types.d.ts

@@ -721,6 +721,21 @@ export interface QaSurfaceConfig {
          * per-user directory, which is otherwise unreadable to those tools.
          */
         readonly docsRoot?: string;
+        /**
+         * Documentation version `docs_search` stays inside when the model named
+         * neither `version` nor `path`. A corpus carries several editions of the
+         * same module, and a chat asked about "the product" answers out of whichever
+         * edition it happened to read first; naming the stand's edition here lets a
+         * search default to it, and an explicit `version` or `path` still decides
+         * for itself.
+         */
+        readonly docsDefaultVersion?: string;
+        /**
+         * Whether `docsDefaultVersion` is applied. The value stays configured while
+         * the switch is off, so a stand can turn the default back on without
+         * retyping it.
+         */
+        readonly docsDefaultVersionEnabled?: boolean;
     };
     readonly lockdown?: {
         readonly enabled?: boolean;
@@ -1002,6 +1017,13 @@ export interface ResolvedQaSurfaceConfig {
          * `docs/` directory inside each chat's own workspace.
          */
         readonly docsRoot: string;
+        /**
+         * Version a search without `version` and without `path` stays inside, or
+         * `""` for a search across every edition the corpus carries.
+         */
+        readonly docsDefaultVersion: string;
+        /** Whether the deployment's default version is in force. */
+        readonly docsDefaultVersionEnabled: boolean;
     };
     readonly sources: {
         readonly enabled: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yadsh/dsh-qa-surface",
-  "version": "0.11.2",
+  "version": "0.12.0",
   "description": "A focused end-user QA surface backed by native DeepSeek Harness sessions",
   "repository": {
     "type": "git",
@@ -133,10 +133,10 @@
   "dependencies": {
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
-    "@yadsh/dsh-audit-core": "^0.1.0",
     "@yadsh/dsh-documents": "^0.5.1",
-    "@yadsh/dsh-plugin-log": "^0.4.0",
+    "@yadsh/dsh-audit-core": "^0.1.0",
     "@yadsh/dsh-audit-ui": "^0.1.1",
+    "@yadsh/dsh-plugin-log": "^0.4.0",
     "@yadsh/dsh-plugin-kit": "^0.3.0"
   },
   "devDependencies": {