@c4a/context-cli 0.7.26 → 0.7.29

package/indexers/release-manifest.json

@@ -1,7 +1,7 @@
 {
   "protocol": "context.indexer.cli-release-manifest/v1",
   "package": "@c4a/context-cli",
-  "version": "0.7.26",
+  "version": "0.7.29",
   "issuer": "context4ai/context",
   "bundles": [
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c4a/context-cli",
-  "version": "0.7.26",
+  "version": "0.7.29",
   "type": "module",
   "description": "Local runtime and Agent integration for traceable knowledge production",
   "license": "MIT",
@@ -24,17 +24,17 @@
   },
   "dependencies": {
     "@c4a/agent-graph": "0.3.0",
-    "@c4a/context": "0.7.26",
-    "@c4a/extract": "0.7.26",
-    "@c4a/extract-contract": "0.7.26",
-    "@c4a/extract-go": "0.7.26",
-    "@c4a/extract-mdx": "0.7.26",
-    "@c4a/extract-proto": "0.7.26",
-    "@c4a/extract-rush": "0.7.26",
-    "@c4a/extract-sql": "0.7.26",
-    "@c4a/extract-style": "0.7.26",
-    "@c4a/extract-thrift": "0.7.26",
-    "@c4a/extract-ts": "0.7.26",
+    "@c4a/context": "0.7.29",
+    "@c4a/extract": "0.7.29",
+    "@c4a/extract-contract": "0.7.29",
+    "@c4a/extract-go": "0.7.29",
+    "@c4a/extract-mdx": "0.7.29",
+    "@c4a/extract-proto": "0.7.29",
+    "@c4a/extract-rush": "0.7.29",
+    "@c4a/extract-sql": "0.7.29",
+    "@c4a/extract-style": "0.7.29",
+    "@c4a/extract-thrift": "0.7.29",
+    "@c4a/extract-ts": "0.7.29",
     "@mermaid-js/layout-elk": "0.2.0",
     "commander": "^11.0.0",
     "fast-xml-parser": "^5.10.1",

package/parserEntryWorker.js

@@ -20765,24 +20765,78 @@ var init_indexerSourceBoundary = __esm(() => {
   init_indexerReadScopeAuthorization();
 });
 
+// src/lib/errors.ts
+var ContextError;
+var init_errors2 = __esm(() => {
+  ContextError = class ContextError extends Error {
+    code;
+    detail;
+    constructor(code, message, detail) {
+      super(message);
+      this.name = "ContextError";
+      this.code = code;
+      this.detail = detail;
+    }
+  };
+});
+
+// src/types/exitCode.ts
+var ExitCode;
+var init_exitCode = __esm(() => {
+  ExitCode = {
+    Success: 0,
+    UserError: 1,
+    WorkspaceStateError: 2,
+    ExternalToolError: 3,
+    UserAbort: 4
+  };
+});
+
+// src/lib/cliFeedback.ts
+function formatFeedback(block) {
+  const subjectPart = block.subject ? ` ${block.subject}` : "";
+  const lines = [`${block.symbol} ${block.action}${subjectPart}: ${block.headline}`];
+  for (const item of block.body ?? []) {
+    if (item === false || item === null || item === undefined)
+      continue;
+    if (typeof item === "string") {
+      lines.push(item.length > 0 ? `  ${item}` : "");
+    }
+  }
+  if (block.next) {
+    lines.push(`  next: ${block.next}`);
+  }
+  return `${lines.join(`
+`)}
+`;
+}
+var ErrorCategory;
+var init_cliFeedback = __esm(() => {
+  ErrorCategory = {
+    WorkspaceNotFound: "workspace-not-found",
+    WorkspaceStateInvalid: "workspace-state-invalid",
+    WorkflowRevisionStale: "workflow-revision-stale",
+    SourceNotFound: "source-not-found",
+    MountMatrixViolation: "mount-matrix-violation",
+    SchemaInvalid: "schema-invalid",
+    ProviderUnavailable: "provider-unavailable",
+    ExternalToolFailed: "external-tool-failed",
+    PartialFailure: "partial-failure",
+    UserInputInvalid: "user-input-invalid",
+    Unknown: "unknown"
+  };
+});
+
 // src/project/indexerParserSourceMaterialization.ts
 import { execFile } from "node:child_process";
-import { lstat as lstat2, readFile as readFile6 } from "node:fs/promises";
+import { lstat as lstat2, readFile as readFile6, stat as stat2 } from "node:fs/promises";
 import { promisify } from "node:util";
 import { basename, extname, join as join4 } from "node:path";
 function sourceRefName(sourceRef) {
   return sourceRef.startsWith("repo:") ? sourceRef.slice("repo:".length) : null;
 }
 async function trackedPaths(root, ref) {
-  try {
-    await execFileAsync("git", ["diff", "--quiet", ref, "--", "."], { cwd: root });
-  } catch (error) {
-    const exitCode = error !== null && typeof error === "object" && "code" in error ? error.code : null;
-    if (exitCode === 1) {
-      throw new TypeError(`materialized repository source differs from its pinned ref: ${root}`);
-    }
-    throw error;
-  }
+  await assertPinnedSource(root, ref);
   const { stdout } = await execFileAsync("git", ["ls-files", "-z", "--", "."], {
     cwd: root,
     encoding: "buffer",
@@ -20791,6 +20845,20 @@ async function trackedPaths(root, ref) {
   return Buffer.from(stdout).toString("utf8").split("\x00").filter(Boolean).sort();
 }
 async function assertPinnedSource(root, ref) {
+  const sourceStat = await stat2(root).catch((error) => {
+    if (error.code === "ENOENT" || error.code === "ENOTDIR")
+      return;
+    throw error;
+  });
+  if (!sourceStat?.isDirectory()) {
+    throw new ContextError(ExitCode.WorkspaceStateError, `Repository source directory is unavailable: ${root}. Inspect recovery with context source recovery-plan --format json.`, {
+      category: ErrorCategory.WorkspaceStateInvalid,
+      reason_code: "repository-source-directory-unavailable",
+      cwd: root,
+      next_action: { command: "context source recovery-plan --format json" },
+      input_schema: { type: "object", properties: {}, additionalProperties: false }
+    });
+  }
   try {
     await execFileAsync("git", ["diff", "--quiet", ref, "--", "."], { cwd: root });
   } catch (error) {
@@ -20798,6 +20866,15 @@ async function assertPinnedSource(root, ref) {
     if (exitCode === 1) {
       throw new TypeError(`materialized repository source differs from its pinned ref: ${root}`);
     }
+    if (exitCode === "ENOENT") {
+      throw new ContextError(ExitCode.ExternalToolError, `Git could not start for repository source ${root}. Check git --version and the source directory in the same host environment.`, {
+        category: ErrorCategory.ExternalToolFailed,
+        reason_code: "repository-git-spawn-unavailable",
+        cwd: root,
+        next_action: { command: "git --version" },
+        input_schema: { type: "object", properties: {}, additionalProperties: false }
+      });
+    }
     throw error;
   }
 }
@@ -20861,6 +20938,9 @@ var init_indexerParserSourceMaterialization = __esm(() => {
   init_src();
   init_indexerReadScopeAuthorization();
   init_indexerSourceBoundary();
+  init_errors2();
+  init_exitCode();
+  init_cliFeedback();
   execFileAsync = promisify(execFile);
 });
 

package/plugins/README.md

@@ -31,7 +31,7 @@ Context workflow and Indexer Provider lifecycle.
 ## Query and attribute workspace knowledge
 
 Explicitly invoke `/c4a:context-inspect-search` (Cursor: `/c4a-context-inspect-search`),
-or let a host configuration route knowledge questions to the `context-inspect-search` Skill. It can start from a readable local, global or host-provided knowledge package and its query Skill without a local workspace. Without output, it
+or let a host configuration route knowledge questions to the `context-inspect-search` Skill. `CONTEXT_QUERY_SOURCE_MODE` selects `repo-first` (the default), `package-first`, or `dual` retrieval. It can start from a readable local, global or host-provided knowledge package and its query Skill without a local workspace. Without output, it
 queries approved `knowledge` directly; a package build requires prior authorization for that workspace write.
 Read-only investigation and bounded non-destructive checks need no further approval. For code attribution, it
 retrieves the registered revision and checks relevant differences against current code without asking the user to select a version.

package/plugins/README_CN.md

@@ -27,7 +27,7 @@ Skills 只能通过完成校验的 Context Indexer Provider 生命周期激活
 ## 查询知识与来源归因
 
 主动调用 `/c4a:context-inspect-search`（Cursor：`/c4a-context-inspect-search`），
-或由宿主配置将知识问答路由到 `context-inspect-search` 技能。无需本地工作区即可检索本地、全局或宿主提供的知识包，优先使用包内查询技能；没有产物但有工作区时，
+或由宿主配置将知识问答路由到 `context-inspect-search` 技能。`CONTEXT_QUERY_SOURCE_MODE` 可选择默认的 `repo-first`、`package-first` 或 `dual` 检索。无需本地工作区也可检索本地、全局或宿主提供的知识包；没有产物但有工作区时，
 直接查询已批准的 `knowledge`，构建产物需事先获得写入工作区的授权。只读探索及有边界的
 非破坏性检查无需再次确认。代码归因自动取得登记版本，并核对相关文件与当前代码的差异，
 无需用户选择版本。通过构建清单关联批准原稿

package/plugins/VERSION

@@ -1 +1 @@
-0.7.26
+0.7.29

package/plugins/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "c4a",
   "description": "Start or continue a project-local knowledge workspace through one graph-routed entry.",
-  "version": "0.7.26",
+  "version": "0.7.29",
   "author": {
     "name": "c4a"
   },

package/plugins/claude/commands/context-inspect-search.md

@@ -26,14 +26,35 @@ Do not execute returned production actions, initialize a replacement workspace,
 or install tools without existing authorization. Querying must not alter source
 registrations, snapshots, tasks, approvals or user checkouts.
 
-## Search available material concurrently
-
-Check relevant knowledge packages, the workspace and reusable source checkouts
-in parallel. Search each as soon as it is readable; tool checks and authorized
-upgrades must not block independent reading. If a missing configured workspace
-is needed for further attribution, recover it into an isolated directory while
-package retrieval continues. Without a configured workspace, investigate the
-available packages directly; do not request or create one merely to start.
+Resolve `CONTEXT_QUERY_SOURCE_MODE` from the host or Bot instance configuration
+before choosing the first retrieval path. Supported values are:
+
+- `repo-first` (default): inspect the configured knowledge workspace and
+  authorized repository sources first. Use an available package only when the
+  repository path is unavailable or leaves a material gap.
+- `package-first`: inspect the selected package first, then use its recorded
+  workspace or repository sources for missing, stale or disputed evidence.
+- `dual`: inspect the package and repository paths concurrently, then reconcile
+  relevant differences before answering.
+
+An unknown or empty value is `repo-first`; do not invent a fourth mode. The
+mode changes retrieval order, not authorization or evidence standards. It does
+not make a missing secondary source mandatory: continue with readable configured
+sources and identify only gaps that affect the answer.
+
+## Search available material according to the configured mode
+
+Apply `CONTEXT_QUERY_SOURCE_MODE` before starting retrieval. In `repo-first`,
+start with the configured workspace and reusable source checkouts; do not fetch
+or install a package merely to begin the query. In `package-first`, start with
+the selected readable package. In `dual`, start both paths concurrently. Search
+each selected path as soon as it is readable; tool checks and authorized
+upgrades must not block independent reading. If a configured primary path is
+missing, continue with the readable fallback instead of stopping. If a missing
+configured workspace is needed for further attribution, recover it into an
+isolated directory while other selected retrieval continues. Without a
+configured workspace, investigate available packages directly; do not request
+or create one merely to start.
 
 A knowledge package may be workspace build output (usually `dist/`), a global
 installation, or an equivalent host-provided directory. Locate it from available
@@ -119,7 +140,21 @@ not prove a historical snapshot.
 
 ## Answer with evidence and hand off updates
 
-Lead with the conclusion and a concise evidence chain. Distinguish implementation,
+Answer the user's question directly, keeping conditions that change the conclusion
+beside it. For complex questions, explain the mechanism that determines the result,
+not just the verdict and source links. Explain its practical meaning before using
+a short code excerpt or concrete rule when that helps the reader verify or act.
+Keep decisive evidence beside the claim it supports; separate supplementary facts
+from the proof. State where a local rule applies rather than generalizing it to
+the whole system, and do not infer presentation or behavior from data retrieval
+alone without checking the controlling logic.
+
+Adapt depth and structure to the question: keep simple answers short; use short
+headings and, where supported, separators between major semantic sections in
+longer answers. Do not impose a fixed outline, separate every paragraph, repeat
+the conclusion, or remove necessary explanation just to shorten the answer.
+Keep conditions affecting the answer prominent and supplementary reading secondary.
+Distinguish implementation,
 declared contracts, test assertions, runtime observations and inferences. Perform
 bounded non-destructive validation only when useful; inspect its effects first
 and do not run unrelated scripts, builds or tests.

package/plugins/claude/skills/context-inspect-search/SKILL.md

@@ -25,14 +25,35 @@ Do not execute returned production actions, initialize a replacement workspace,
 or install tools without existing authorization. Querying must not alter source
 registrations, snapshots, tasks, approvals or user checkouts.
 
-## Search available material concurrently
-
-Check relevant knowledge packages, the workspace and reusable source checkouts
-in parallel. Search each as soon as it is readable; tool checks and authorized
-upgrades must not block independent reading. If a missing configured workspace
-is needed for further attribution, recover it into an isolated directory while
-package retrieval continues. Without a configured workspace, investigate the
-available packages directly; do not request or create one merely to start.
+Resolve `CONTEXT_QUERY_SOURCE_MODE` from the host or Bot instance configuration
+before choosing the first retrieval path. Supported values are:
+
+- `repo-first` (default): inspect the configured knowledge workspace and
+  authorized repository sources first. Use an available package only when the
+  repository path is unavailable or leaves a material gap.
+- `package-first`: inspect the selected package first, then use its recorded
+  workspace or repository sources for missing, stale or disputed evidence.
+- `dual`: inspect the package and repository paths concurrently, then reconcile
+  relevant differences before answering.
+
+An unknown or empty value is `repo-first`; do not invent a fourth mode. The
+mode changes retrieval order, not authorization or evidence standards. It does
+not make a missing secondary source mandatory: continue with readable configured
+sources and identify only gaps that affect the answer.
+
+## Search available material according to the configured mode
+
+Apply `CONTEXT_QUERY_SOURCE_MODE` before starting retrieval. In `repo-first`,
+start with the configured workspace and reusable source checkouts; do not fetch
+or install a package merely to begin the query. In `package-first`, start with
+the selected readable package. In `dual`, start both paths concurrently. Search
+each selected path as soon as it is readable; tool checks and authorized
+upgrades must not block independent reading. If a configured primary path is
+missing, continue with the readable fallback instead of stopping. If a missing
+configured workspace is needed for further attribution, recover it into an
+isolated directory while other selected retrieval continues. Without a
+configured workspace, investigate available packages directly; do not request
+or create one merely to start.
 
 A knowledge package may be workspace build output (usually `dist/`), a global
 installation, or an equivalent host-provided directory. Locate it from available
@@ -118,7 +139,21 @@ not prove a historical snapshot.
 
 ## Answer with evidence and hand off updates
 
-Lead with the conclusion and a concise evidence chain. Distinguish implementation,
+Answer the user's question directly, keeping conditions that change the conclusion
+beside it. For complex questions, explain the mechanism that determines the result,
+not just the verdict and source links. Explain its practical meaning before using
+a short code excerpt or concrete rule when that helps the reader verify or act.
+Keep decisive evidence beside the claim it supports; separate supplementary facts
+from the proof. State where a local rule applies rather than generalizing it to
+the whole system, and do not infer presentation or behavior from data retrieval
+alone without checking the controlling logic.
+
+Adapt depth and structure to the question: keep simple answers short; use short
+headings and, where supported, separators between major semantic sections in
+longer answers. Do not impose a fixed outline, separate every paragraph, repeat
+the conclusion, or remove necessary explanation just to shorten the answer.
+Keep conditions affecting the answer prominent and supplementary reading secondary.
+Distinguish implementation,
 declared contracts, test assertions, runtime observations and inferences. Perform
 bounded non-destructive validation only when useful; inspect its effects first
 and do not run unrelated scripts, builds or tests.

package/plugins/codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "c4a",
-  "version": "0.7.26",
+  "version": "0.7.29",
   "description": "Start or continue a project-local knowledge workspace through one graph-routed entry.",
   "author": { "name": "c4a" },
   "homepage": "https://github.com/context4ai/c4a",
@@ -10,7 +10,7 @@
   "skills": "./skills/",
   "interface": {
     "displayName": "C4A Context",
-    "shortDescription": "Initialize and advance a local, source-linked project knowledge workspace.\nv0.7.26",
+    "shortDescription": "Initialize and advance a local, source-linked project knowledge workspace.\nv0.7.29",
     "longDescription": "Create a Context workspace and use agent-guided next steps to register sources, run extraction, review candidates, build package outputs, and verify health without silently mutating source repositories.",
     "developerName": "c4a",
     "category": "Productivity",

package/plugins/codex/skills/context-inspect-search/SKILL.md

@@ -25,14 +25,35 @@ Do not execute returned production actions, initialize a replacement workspace,
 or install tools without existing authorization. Querying must not alter source
 registrations, snapshots, tasks, approvals or user checkouts.
 
-## Search available material concurrently
-
-Check relevant knowledge packages, the workspace and reusable source checkouts
-in parallel. Search each as soon as it is readable; tool checks and authorized
-upgrades must not block independent reading. If a missing configured workspace
-is needed for further attribution, recover it into an isolated directory while
-package retrieval continues. Without a configured workspace, investigate the
-available packages directly; do not request or create one merely to start.
+Resolve `CONTEXT_QUERY_SOURCE_MODE` from the host or Bot instance configuration
+before choosing the first retrieval path. Supported values are:
+
+- `repo-first` (default): inspect the configured knowledge workspace and
+  authorized repository sources first. Use an available package only when the
+  repository path is unavailable or leaves a material gap.
+- `package-first`: inspect the selected package first, then use its recorded
+  workspace or repository sources for missing, stale or disputed evidence.
+- `dual`: inspect the package and repository paths concurrently, then reconcile
+  relevant differences before answering.
+
+An unknown or empty value is `repo-first`; do not invent a fourth mode. The
+mode changes retrieval order, not authorization or evidence standards. It does
+not make a missing secondary source mandatory: continue with readable configured
+sources and identify only gaps that affect the answer.
+
+## Search available material according to the configured mode
+
+Apply `CONTEXT_QUERY_SOURCE_MODE` before starting retrieval. In `repo-first`,
+start with the configured workspace and reusable source checkouts; do not fetch
+or install a package merely to begin the query. In `package-first`, start with
+the selected readable package. In `dual`, start both paths concurrently. Search
+each selected path as soon as it is readable; tool checks and authorized
+upgrades must not block independent reading. If a configured primary path is
+missing, continue with the readable fallback instead of stopping. If a missing
+configured workspace is needed for further attribution, recover it into an
+isolated directory while other selected retrieval continues. Without a
+configured workspace, investigate available packages directly; do not request
+or create one merely to start.
 
 A knowledge package may be workspace build output (usually `dist/`), a global
 installation, or an equivalent host-provided directory. Locate it from available
@@ -118,7 +139,21 @@ not prove a historical snapshot.
 
 ## Answer with evidence and hand off updates
 
-Lead with the conclusion and a concise evidence chain. Distinguish implementation,
+Answer the user's question directly, keeping conditions that change the conclusion
+beside it. For complex questions, explain the mechanism that determines the result,
+not just the verdict and source links. Explain its practical meaning before using
+a short code excerpt or concrete rule when that helps the reader verify or act.
+Keep decisive evidence beside the claim it supports; separate supplementary facts
+from the proof. State where a local rule applies rather than generalizing it to
+the whole system, and do not infer presentation or behavior from data retrieval
+alone without checking the controlling logic.
+
+Adapt depth and structure to the question: keep simple answers short; use short
+headings and, where supported, separators between major semantic sections in
+longer answers. Do not impose a fixed outline, separate every paragraph, repeat
+the conclusion, or remove necessary explanation just to shorten the answer.
+Keep conditions affecting the answer prominent and supplementary reading secondary.
+Distinguish implementation,
 declared contracts, test assertions, runtime observations and inferences. Perform
 bounded non-destructive validation only when useful; inspect its effects first
 and do not run unrelated scripts, builds or tests.

package/plugins/cursor/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "c4a",
   "displayName": "C4A Context",
-  "version": "0.7.26",
+  "version": "0.7.29",
   "description": "Start or continue a project-local knowledge workspace through one graph-routed entry.",
   "author": {
     "name": "Context4AI",

package/plugins/cursor/commands/c4a-context-inspect-search.md

@@ -24,14 +24,35 @@ Do not execute returned production actions, initialize a replacement workspace,
 or install tools without existing authorization. Querying must not alter source
 registrations, snapshots, tasks, approvals or user checkouts.
 
-## Search available material concurrently
-
-Check relevant knowledge packages, the workspace and reusable source checkouts
-in parallel. Search each as soon as it is readable; tool checks and authorized
-upgrades must not block independent reading. If a missing configured workspace
-is needed for further attribution, recover it into an isolated directory while
-package retrieval continues. Without a configured workspace, investigate the
-available packages directly; do not request or create one merely to start.
+Resolve `CONTEXT_QUERY_SOURCE_MODE` from the host or Bot instance configuration
+before choosing the first retrieval path. Supported values are:
+
+- `repo-first` (default): inspect the configured knowledge workspace and
+  authorized repository sources first. Use an available package only when the
+  repository path is unavailable or leaves a material gap.
+- `package-first`: inspect the selected package first, then use its recorded
+  workspace or repository sources for missing, stale or disputed evidence.
+- `dual`: inspect the package and repository paths concurrently, then reconcile
+  relevant differences before answering.
+
+An unknown or empty value is `repo-first`; do not invent a fourth mode. The
+mode changes retrieval order, not authorization or evidence standards. It does
+not make a missing secondary source mandatory: continue with readable configured
+sources and identify only gaps that affect the answer.
+
+## Search available material according to the configured mode
+
+Apply `CONTEXT_QUERY_SOURCE_MODE` before starting retrieval. In `repo-first`,
+start with the configured workspace and reusable source checkouts; do not fetch
+or install a package merely to begin the query. In `package-first`, start with
+the selected readable package. In `dual`, start both paths concurrently. Search
+each selected path as soon as it is readable; tool checks and authorized
+upgrades must not block independent reading. If a configured primary path is
+missing, continue with the readable fallback instead of stopping. If a missing
+configured workspace is needed for further attribution, recover it into an
+isolated directory while other selected retrieval continues. Without a
+configured workspace, investigate available packages directly; do not request
+or create one merely to start.
 
 A knowledge package may be workspace build output (usually `dist/`), a global
 installation, or an equivalent host-provided directory. Locate it from available
@@ -117,7 +138,21 @@ not prove a historical snapshot.
 
 ## Answer with evidence and hand off updates
 
-Lead with the conclusion and a concise evidence chain. Distinguish implementation,
+Answer the user's question directly, keeping conditions that change the conclusion
+beside it. For complex questions, explain the mechanism that determines the result,
+not just the verdict and source links. Explain its practical meaning before using
+a short code excerpt or concrete rule when that helps the reader verify or act.
+Keep decisive evidence beside the claim it supports; separate supplementary facts
+from the proof. State where a local rule applies rather than generalizing it to
+the whole system, and do not infer presentation or behavior from data retrieval
+alone without checking the controlling logic.
+
+Adapt depth and structure to the question: keep simple answers short; use short
+headings and, where supported, separators between major semantic sections in
+longer answers. Do not impose a fixed outline, separate every paragraph, repeat
+the conclusion, or remove necessary explanation just to shorten the answer.
+Keep conditions affecting the answer prominent and supplementary reading secondary.
+Distinguish implementation,
 declared contracts, test assertions, runtime observations and inferences. Perform
 bounded non-destructive validation only when useful; inspect its effects first
 and do not run unrelated scripts, builds or tests.

package/plugins/cursor/skills/context-inspect-search/SKILL.md

@@ -25,14 +25,35 @@ Do not execute returned production actions, initialize a replacement workspace,
 or install tools without existing authorization. Querying must not alter source
 registrations, snapshots, tasks, approvals or user checkouts.
 
-## Search available material concurrently
-
-Check relevant knowledge packages, the workspace and reusable source checkouts
-in parallel. Search each as soon as it is readable; tool checks and authorized
-upgrades must not block independent reading. If a missing configured workspace
-is needed for further attribution, recover it into an isolated directory while
-package retrieval continues. Without a configured workspace, investigate the
-available packages directly; do not request or create one merely to start.
+Resolve `CONTEXT_QUERY_SOURCE_MODE` from the host or Bot instance configuration
+before choosing the first retrieval path. Supported values are:
+
+- `repo-first` (default): inspect the configured knowledge workspace and
+  authorized repository sources first. Use an available package only when the
+  repository path is unavailable or leaves a material gap.
+- `package-first`: inspect the selected package first, then use its recorded
+  workspace or repository sources for missing, stale or disputed evidence.
+- `dual`: inspect the package and repository paths concurrently, then reconcile
+  relevant differences before answering.
+
+An unknown or empty value is `repo-first`; do not invent a fourth mode. The
+mode changes retrieval order, not authorization or evidence standards. It does
+not make a missing secondary source mandatory: continue with readable configured
+sources and identify only gaps that affect the answer.
+
+## Search available material according to the configured mode
+
+Apply `CONTEXT_QUERY_SOURCE_MODE` before starting retrieval. In `repo-first`,
+start with the configured workspace and reusable source checkouts; do not fetch
+or install a package merely to begin the query. In `package-first`, start with
+the selected readable package. In `dual`, start both paths concurrently. Search
+each selected path as soon as it is readable; tool checks and authorized
+upgrades must not block independent reading. If a configured primary path is
+missing, continue with the readable fallback instead of stopping. If a missing
+configured workspace is needed for further attribution, recover it into an
+isolated directory while other selected retrieval continues. Without a
+configured workspace, investigate available packages directly; do not request
+or create one merely to start.
 
 A knowledge package may be workspace build output (usually `dist/`), a global
 installation, or an equivalent host-provided directory. Locate it from available
@@ -118,7 +139,21 @@ not prove a historical snapshot.
 
 ## Answer with evidence and hand off updates
 
-Lead with the conclusion and a concise evidence chain. Distinguish implementation,
+Answer the user's question directly, keeping conditions that change the conclusion
+beside it. For complex questions, explain the mechanism that determines the result,
+not just the verdict and source links. Explain its practical meaning before using
+a short code excerpt or concrete rule when that helps the reader verify or act.
+Keep decisive evidence beside the claim it supports; separate supplementary facts
+from the proof. State where a local rule applies rather than generalizing it to
+the whole system, and do not infer presentation or behavior from data retrieval
+alone without checking the controlling logic.
+
+Adapt depth and structure to the question: keep simple answers short; use short
+headings and, where supported, separators between major semantic sections in
+longer answers. Do not impose a fixed outline, separate every paragraph, repeat
+the conclusion, or remove necessary explanation just to shorten the answer.
+Keep conditions affecting the answer prominent and supplementary reading secondary.
+Distinguish implementation,
 declared contracts, test assertions, runtime observations and inferences. Perform
 bounded non-destructive validation only when useful; inspect its effects first
 and do not run unrelated scripts, builds or tests.