diff --git a/CHANGELOG.md b/CHANGELOG.md
index 744bdaac..9421d81f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,16 @@ All notable changes to Context are documented here.
## Unreleased
+## 0.7.30 - 2026-09-21
+
+- Add explicit User/Bot identity selection for Lark reads, retaining User as
+ the default and allowing bounded authorization fallback from Bot to User.
+- Let capture instructions limit task-wide document image collection with
+ ON/OFF/count policies, defaulting to ten documents and Agent self-checks.
+- Search approved knowledge before preparing original sources, reuse query
+ checks and batch evidence reads and citations. Compare versions only when
+ the question or evidence warrants it, retaining source and freshness limits.
+
## 0.7.29 - 2026-09-21
- Explain decisive mechanisms and scoped evidence in complex query answers,
diff --git a/bun.lock b/bun.lock
index 23e21a7b..df4cd287 100644
--- a/bun.lock
+++ b/bun.lock
@@ -18,7 +18,7 @@
},
"packages/context": {
"name": "@c4a/context",
- "version": "0.7.29",
+ "version": "0.7.30",
"dependencies": {
"yaml": "^2.5.1",
"zod": "^3.23.8",
@@ -26,7 +26,7 @@
},
"packages/context-cli": {
"name": "@c4a/context-cli",
- "version": "0.7.29",
+ "version": "0.7.30",
"bin": {
"context": "dist/cli.js",
},
@@ -73,7 +73,7 @@
},
"packages/core": {
"name": "@c4a/core",
- "version": "0.7.29",
+ "version": "0.7.30",
"dependencies": {
"picomatch": "^4.0.4",
"yaml": "^2.4.5",
@@ -85,7 +85,7 @@
},
"packages/dev-cli": {
"name": "@c4a/dev-cli",
- "version": "0.7.29",
+ "version": "0.7.30",
"dependencies": {
"@c4a/context": "workspace:*",
"@c4a/core": "workspace:*",
@@ -97,7 +97,7 @@
},
"packages/extract": {
"name": "@c4a/extract",
- "version": "0.7.29",
+ "version": "0.7.30",
"bin": {
"c4a-extract-code": "./dist/bin/c4a-extract-code.js",
},
@@ -112,7 +112,7 @@
},
"packages/extract-contract": {
"name": "@c4a/extract-contract",
- "version": "0.7.29",
+ "version": "0.7.30",
"dependencies": {
"@c4a/core": "workspace:*",
"graphql": "^16.14.2",
@@ -122,7 +122,7 @@
},
"packages/extract-go": {
"name": "@c4a/extract-go",
- "version": "0.7.29",
+ "version": "0.7.30",
"dependencies": {
"@c4a/core": "workspace:*",
"@c4a/extract": "workspace:*",
@@ -132,7 +132,7 @@
},
"packages/extract-mdx": {
"name": "@c4a/extract-mdx",
- "version": "0.7.29",
+ "version": "0.7.30",
"dependencies": {
"@c4a/core": "workspace:*",
"remark-mdx": "^3.1.1",
@@ -144,7 +144,7 @@
},
"packages/extract-proto": {
"name": "@c4a/extract-proto",
- "version": "0.7.29",
+ "version": "0.7.30",
"dependencies": {
"@c4a/core": "workspace:*",
"zod": "^3.23.8",
@@ -152,7 +152,7 @@
},
"packages/extract-rush": {
"name": "@c4a/extract-rush",
- "version": "0.7.29",
+ "version": "0.7.30",
"dependencies": {
"@c4a/core": "workspace:*",
"typescript": "^5.5.4",
@@ -162,7 +162,7 @@
},
"packages/extract-sql": {
"name": "@c4a/extract-sql",
- "version": "0.7.29",
+ "version": "0.7.30",
"dependencies": {
"@c4a/core": "workspace:*",
"node-sql-parser": "^5.4.0",
@@ -171,7 +171,7 @@
},
"packages/extract-style": {
"name": "@c4a/extract-style",
- "version": "0.7.29",
+ "version": "0.7.30",
"dependencies": {
"@c4a/core": "workspace:*",
"postcss": "^8.5.26",
@@ -183,7 +183,7 @@
},
"packages/extract-thrift": {
"name": "@c4a/extract-thrift",
- "version": "0.7.29",
+ "version": "0.7.30",
"dependencies": {
"@c4a/core": "workspace:*",
"zod": "^3.23.8",
@@ -191,7 +191,7 @@
},
"packages/extract-ts": {
"name": "@c4a/extract-ts",
- "version": "0.7.29",
+ "version": "0.7.30",
"dependencies": {
"@c4a/core": "workspace:*",
"@c4a/extract": "workspace:*",
@@ -202,7 +202,7 @@
},
"packages/tui": {
"name": "@c4a/tui",
- "version": "0.7.29",
+ "version": "0.7.30",
"dependencies": {
"ink": "^5.0.0",
"react": "^18.3.1",
diff --git a/package.json b/package.json
index 5d18af54..1d0982b8 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "context",
- "version": "0.7.29",
+ "version": "0.7.30",
"packageManager": "bun@1.3.9",
"repository": {
"type": "git",
diff --git a/packages/context-cli/README.md b/packages/context-cli/README.md
index 6d812b50..e2f1f09f 100644
--- a/packages/context-cli/README.md
+++ b/packages/context-cli/README.md
@@ -283,6 +283,18 @@ MIT.
## Updating an existing workspace
+### Lark read identity
+
+`CONTEXT_LARK_IDENTITY=user|bot` selects the identity for Lark acquisition
+(default: `user`). Export it in each shell executing Context commands. In Bot
+mode, a credential/scope/access failure retries once as the current user; the
+rest of that capture keeps the fallback identity for pagination and resources.
+Network, rate-limit and parsing errors do not trigger a user authorization
+attempt. This does not change source-read consent or the audience of published
+knowledge. Host-managed OAuth must use the host's authorization flow.
+
+### Workspace updates
+
Start with `context entry --format json` and read the returned update guide when
adding material or changing published knowledge. Entry and status only observe;
they do not resume an earlier managed task before the new request is understood.
diff --git a/packages/context-cli/README.zh-CN.md b/packages/context-cli/README.zh-CN.md
index 483e3f18..d6c11517 100644
--- a/packages/context-cli/README.zh-CN.md
+++ b/packages/context-cli/README.zh-CN.md
@@ -47,6 +47,14 @@ Provider Skill 投影到 Claude、Codex 和 Cursor 的用户技能目录。
方法并停止。它不会为每次调用增加安装预检，也不会把普通工作流中的 `not found`
诊断误判成可执行文件缺失。
+## 飞书读取身份
+
+`CONTEXT_LARK_IDENTITY=user|bot` 控制飞书来源采集，默认 `user`。每次执行 Context
+命令的 shell 都需传入该环境变量；仅在提示词中写配置并不会自动导出环境变量。
+`bot` 模式先使用应用身份，遇到凭证、scope 或访问权限错误时回退当前用户一次，
+本次采集后续分页、引用与资源下载沿用回退身份。网络、限流和解析错误不切换身份。
+该配置不扩大来源授权或知识产物可见范围；托管运行时的用户授权遵循宿主流程。
+
## 一个 Agent 入口如何驱动整套工作流
```text
diff --git a/packages/context-cli/context-workflow/provider.yaml b/packages/context-cli/context-workflow/provider.yaml
index 9fecf3a6..0347799f 100644
--- a/packages/context-cli/context-workflow/provider.yaml
+++ b/packages/context-cli/context-workflow/provider.yaml
@@ -1,6 +1,6 @@
schema: agent-graph.provider.v1
id: c4a/context
-version: 0.7.29
+version: 0.7.30
name: Context workflow
description: Internal work contract for Context knowledge workspaces.
graphs:
diff --git a/packages/context-cli/context-workflow/resources/dialogue/document-capture.md b/packages/context-cli/context-workflow/resources/dialogue/document-capture.md
index 1abbe15f..bf0f6536 100644
--- a/packages/context-cli/context-workflow/resources/dialogue/document-capture.md
+++ b/packages/context-cli/context-workflow/resources/dialogue/document-capture.md
@@ -23,6 +23,14 @@ refresh, or capture preview before permission is clear. A request that
explicitly says to ingest, fetch, capture, or read the named documents grants
that scope; merely mentioning a possible source does not.
+The image preflight in the document-capture procedure is an Agent self-check,
+not an additional user question. Before capture, briefly report the task-wide
+document count and applied policy. Reference-only images keep source references
+but are not downloaded or interpreted. Do not wait for confirmation or infer an
+all-image override from managed execution. Unknown scope requires authorized
+metadata or body-and-reference-only discovery first. Existing source-read
+permission requirements remain unchanged.
+
If deterministic inspection detects `.mdx`, route metadata, sidebars, or a docs
configuration, explain that the boundary looks like a documentation site and
ask whether to use the Context document-site processor. Do not infer that
diff --git a/packages/context-cli/context-workflow/resources/manuals/guides/lark-resources.md b/packages/context-cli/context-workflow/resources/manuals/guides/lark-resources.md
index 76753b23..ca82e7a0 100644
--- a/packages/context-cli/context-workflow/resources/manuals/guides/lark-resources.md
+++ b/packages/context-cli/context-workflow/resources/manuals/guides/lark-resources.md
@@ -133,8 +133,24 @@ assess the page with its non-text evidence.
## Image choices for a production task
+Before capture, the Agent follows the document-capture Route procedure's task-wide
+document threshold and image self-check, without asking for user confirmation.
+Set `DOCUMENT_IMAGE_CAPTURE` in task instructions or workspace guidance to `ON`
+(include images), `OFF` (references only), or a positive integer document threshold.
+Omitting it uses `10`; exactly the threshold remains within normal acquisition.
+Current-conversation instructions override workspace guidance for that task only.
+For example, `DOCUMENT_IMAGE_CAPTURE: 20` skips image downloads when the task
+contains more than 20 distinct documents. This is an Agent instruction, not an
+environment variable, CLI flag or SDK field; no Bot configuration is required.
+Above a numeric threshold, the default is body capture with image references,
+unless the effective setting is overridden to `ON`. This workflow
+choice uses the existing resource fields; it does not change SDK defaults or add
+a CLI hard gate. Apply it before bulk capture or host prefetch, not after images
+have already been downloaded.
+
The work-start report asks once when a task contains more than 30 distinct images
-and has no explicit image policy. The choices are intelligent conversion and
+that will be acquired and has no explicit image handling policy. Reuse the
+current-conversation image instruction when it already settles this choice. The choices are intelligent conversion and
inclusion (recommended), include all as images with compression, or include none
with placeholders. Count the whole task, not each capture or writing batch.
Review reports show the resulting image handling and any fallbacks.
diff --git a/packages/context-cli/context-workflow/resources/procedures/document-capture.md b/packages/context-cli/context-workflow/resources/procedures/document-capture.md
index 442e50f4..e354e8a6 100644
--- a/packages/context-cli/context-workflow/resources/procedures/document-capture.md
+++ b/packages/context-cli/context-workflow/resources/procedures/document-capture.md
@@ -13,14 +13,16 @@ Before capture:
1. every registered document module must have a matching capture declaration;
2. the user must have allowed the external read in the current conversation;
-3. execute only the current route command.
+3. perform the Agent's task-wide image acquisition preflight below before capture;
+4. execute only the current route command.
An explicit request to capture, ingest, fetch, or read named file/remote
documents grants source-read permission for those named modules. A mention,
possible-source discussion, or register-only request does not. An explicit
refusal always wins.
-When that permission is already present in the conversation, execute the
+When that permission is already present and the Agent's image acquisition
+preflight is complete, execute the
Gate's returned authority-carrying command. In managed mode it runs the
deterministic capture batch until the next real blocker; in ordinary mode it
reevaluates status with `context.source-read`. The authority remains in the
@@ -48,12 +50,26 @@ boundary is a documentation site rather than plain Markdown, use the
Context-provided processor/configuration diagnostic; do not invent rendered
text or scan outside the confirmed boundary.
-For Lark reads, Context prefers the authenticated user identity. If that
-identity is unavailable because its credential is missing, expired, or cannot
-be refreshed, Context may retry the same registered source with the bot
-identity. It does not switch identity after a permission or missing-scope
-response. Once selected, the same identity is used for the document body and
-all embedded resources. If `docs +fetch` lacks the required `--doc-format`
+For Lark reads, set `CONTEXT_LARK_IDENTITY=user|bot` in the environment of every
+Context invocation that may read Lark; the default is `user`. A host/Bot prompt
+setting alone is not an exported environment variable. User mode reads only
+as the current user. Bot mode reads as the configured application, then retries
+once as the current user on a credential, scope or access denial. Subsequent
+reads in that capture use the fallback identity, including pagination, synced
+references, media, Sheets, Base and whiteboards. Network, rate-limit and format
+errors do not switch identity. The diagnostic records any fallback.
+
+This setting does not grant source access or change the intended audience of
+the resulting knowledge. Do not use another person's credentials. For direct
+host `lark-cli` reads, explicitly pass the selected `--as bot` or `--as user`
+on every business read, including Wiki resolution/listing and asset reads.
+If Bot access fails for the reasons above, retry that read once as user; stop
+and report a pending source if user authorization is required. In a managed
+runtime, use its authorization flow rather than repeatedly running `auth login`.
+Local help and embedded skill discovery require no document authorization;
+do not request user OAuth just to read a CLI guide.
+
+If `docs +fetch` lacks the required `--doc-format`
capability, follow the returned `lark-cli update` recovery and rerun the same
Route command; do not replace the capture with a hand-written export.
@@ -63,9 +79,67 @@ are available while another capture remains pending. Keep unresolved sources in
pending capture after the active production/review work, before delivery completes.
This does not mark failed captures as complete or waive source-read authorization.
-For image-heavy tasks, reuse the image choice in the work-start report. When
-source descriptors already show more than 30 distinct images across the task,
-resolve that question before bulk media acquisition. If counts emerge only from
-capture, stop further image processing to confirm the choice during planning.
-Use explicit image/GIF reference-only policies for exclusions; never substitute
-temporary signed media URLs as permanent public image links.
+## Image acquisition before capture
+
+The workflow instruction setting `DOCUMENT_IMAGE_CAPTURE` accepts `ON`, `OFF`,
+or a positive integer document threshold; when absent it defaults to **10**.
+Read it from the current task instructions or workspace guidance; a current
+conversation instruction takes precedence. This is an Agent-interpreted setting,
+not a CLI flag, environment variable, or SDK field. Hosts need not add a setting.
+
+| Setting | Acquisition policy |
+| --- | --- |
+| `ON` | Include images without a document-count cutoff, subject to existing resource limits and explicit exclusions. |
+| `OFF` | Capture bodies and image references only, regardless of document count. |
+| positive integer `N` | Include images under the existing policy for at most `N` documents; above `N`, use references only. |
+| absent | Use `10`. |
+
+For an invalid value, report it and use `10` rather than silently enabling all
+images or blocking the task. An explicit current-conversation request to include
+all images selects `ON` for this task; an explicit request to skip images selects
+`OFF`. If neither is present, use the configured setting. Do not write a temporary
+conversation override back into permanent workspace guidance.
+
+Count distinct documents
+selected for this task, including Wiki descendants and in-scope linked documents,
+not all historical workspace sources, API pages, retries, or output articles.
+Deduplicate shortcuts and repeated links. Splitting the task into batches or
+resuming it does not reset the count. Exactly 10 documents is within the default.
+
+Before starting capture, the Agent separately checks the document count (or known
+lower bound), setting, and effective image policy. This is an Agent self-check,
+not a user confirmation gate: do not ask a question or wait for a reply. Above the
+numeric threshold, automatically capture bodies with image references only; at or
+below it, retain the existing image policy. `ON` and `OFF` apply regardless of count.
+A generic
+"capture everything", source-read permission, managed mode, or an old bundle setting
+does not. Briefly report the count and applied policy in the work-start update and
+retain the decision in task notes; do not repeat the update for every document.
+
+If the count is unknown, first perform only authorized directory/metadata discovery
+without image downloads. If body reads are needed to discover linked documents,
+use a body-and-reference-only discovery pass within existing read authorization.
+With a numeric setting, unknown totals do not authorize image acquisition; `ON`
+does not require counting to enable images, and `OFF` never enables them.
+Recalculate the task total before enabling images under a numeric setting.
+If later expansion crosses the numeric threshold, apply the
+reference-only policy before further acquisition and report the change without
+waiting for a reply; retain any explicit all-image override and existing evidence.
+
+For `OFF` or above-threshold tasks without an `ON` override, apply
+`resources: { images: "reference-only", gifs: "reference-only" }` to the selected
+Lark capture declarations before executing the Route. Preserve unrelated sources,
+resource settings and existing stricter exclusions; inspect generated/dynamic
+configuration rather than assuming registration applied the policy. Host prefetch
+and import paths must honor the same choice, not download images before import.
+Other resource types retain their existing policies. Do not edit snapshots or
+invent unsupported flags; when a capture adapter cannot exclude images, explain
+that limitation and resolve the acquisition method before downloading.
+
+Preserve source links/placeholders and report skipped images as not acquired or
+interpreted. This is a workflow instruction using existing resource policies, not
+a new CLI hard gate or automatic document counter. For tasks that still include
+images, retain the existing handling workflow for more than 30 distinct images
+and reuse an explicit choice; do not invoke it for images skipped by this
+preflight. Never substitute temporary signed media URLs as permanent
+public image links.
diff --git a/packages/context-cli/context-workflow/resources/procedures/source-capture-detailed.md b/packages/context-cli/context-workflow/resources/procedures/source-capture-detailed.md
index aae9cabc..ac809e98 100644
--- a/packages/context-cli/context-workflow/resources/procedures/source-capture-detailed.md
+++ b/packages/context-cli/context-workflow/resources/procedures/source-capture-detailed.md
@@ -71,6 +71,12 @@ settled scope, not a new confirmation step.
## Workflow
+Before any capture or host prefetch, follow the task-wide image threshold and
+Agent self-check in [Document capture](document-capture.md#image-acquisition-before-capture).
+Do not ask the user to confirm this default or infer an all-image override from
+source-read permission. Apply the effective resource policy before a managed batch;
+registration defaults must not silently re-enable excluded images.
+
Capture is entirely CLI-driven — your role is to register the right source,
declare the matching capture phase, run the current `context run capture:*`
command, and preserve its machine fields while summarizing the outcome in the
diff --git a/packages/context-cli/package.json b/packages/context-cli/package.json
index 6e73a24d..92749e65 100644
--- a/packages/context-cli/package.json
+++ b/packages/context-cli/package.json
@@ -1,7 +1,7 @@
{
"name": "@c4a/context-cli",
"description": "Local runtime and Agent integration for traceable knowledge production",
- "version": "0.7.29",
+ "version": "0.7.30",
"type": "module",
"license": "MIT",
"engines": {
diff --git a/packages/context-cli/src/__tests__/documentLarkIdentityV062.test.ts b/packages/context-cli/src/__tests__/documentLarkIdentityV062.test.ts
index 8591f8b2..5f5fcc53 100644
--- a/packages/context-cli/src/__tests__/documentLarkIdentityV062.test.ts
+++ b/packages/context-cli/src/__tests__/documentLarkIdentityV062.test.ts
@@ -61,7 +61,7 @@ describe("Lark capture identity selection", () => {
throw new Error(`unexpected command: ${args.join(" ")}`);
};
- const result = await fetchFeishuDocSnapshot({ url: "https://example.test/wiki/shared" }, runner);
+ const result = await fetchFeishuDocSnapshot({ url: "https://example.test/wiki/shared", identity: "auto" }, runner);
expect(result.accessIdentity).toBe("bot");
expect(result.identityFallback).toBe(true);
diff --git a/packages/context-cli/src/__tests__/larkReadIdentity.test.ts b/packages/context-cli/src/__tests__/larkReadIdentity.test.ts
new file mode 100644
index 00000000..84b546d8
--- /dev/null
+++ b/packages/context-cli/src/__tests__/larkReadIdentity.test.ts
@@ -0,0 +1,133 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { writeFile } from "node:fs/promises";
+import { rmSync } from "node:fs";
+import { resolve } from "node:path";
+import { checkLarkCli, fetchFeishuDocSnapshot, type LarkRunner } from "../lib/feishu.js";
+import { createLarkReadSession, resolveLarkReadIdentity } from "../lib/larkReadIdentity.js";
+import { createLarkCaptureProject, makeLarkCaptureTmp, runLarkCapturePhase } from "./projectCaptureLarkV062.fixtures.js";
+
+const previous = process.env.CONTEXT_LARK_IDENTITY;
+afterEach(() => {
+ if (previous === undefined) delete process.env.CONTEXT_LARK_IDENTITY;
+ else process.env.CONTEXT_LARK_IDENTITY = previous;
+});
+const denied = {
+ exitCode: 3, stderr: "", stdout: JSON.stringify({ ok: false,
+ error: { type: "authorization", subtype: "missing_scope" } }),
+};
+const success = { exitCode: 0, stderr: "", stdout: JSON.stringify({ ok: true }) };
+const as = (args: string[]) => args[args.indexOf("--as") + 1];
+
+describe("configured Lark read identity", () => {
+ test("defaults to user and rejects an invalid mode with recovery", () => {
+ delete process.env.CONTEXT_LARK_IDENTITY;
+ expect(resolveLarkReadIdentity()).toBe("user");
+ process.env.CONTEXT_LARK_IDENTITY = "auto";
+ expect(resolveLarkReadIdentity).toThrow("must be user or bot");
+ });
+
+ test("user mode does not retry a denied request with bot", async () => {
+ const seen: string[] = [];
+ const session = createLarkReadSession(async args => { seen.push(as(args)!); return denied; }, "user");
+ expect(await session.run(["docs", "+fetch"])).toEqual(denied);
+ expect(seen).toEqual(["user"]);
+ });
+
+ test("bot falls back once and keeps user for subsequent pages/resources", async () => {
+ const seen: string[] = [];
+ const session = createLarkReadSession(async args => {
+ seen.push(as(args)!);
+ return as(args) === "bot" ? denied : success;
+ }, "bot");
+ await session.run(["docs", "+fetch", "--as", "bot"]);
+ await session.run(["docs", "+fetch", "--offset", "1", "--as", "bot"]);
+ await session.run(["docs", "+media-download", "--as", "bot"]);
+ expect(seen).toEqual(["bot", "user", "user", "user"]);
+ expect(session.usedFallback).toBe(true);
+ });
+
+ test.each(["rate_limit", "network", "validation", "parse"])("does not switch on %s errors", async type => {
+ const seen: string[] = [];
+ const session = createLarkReadSession(async args => {
+ seen.push(as(args)!);
+ return { exitCode: 1, stdout: JSON.stringify({ ok: false, error: { type } }), stderr: "" };
+ }, "bot");
+ await session.run(["docs", "+fetch"]);
+ expect(seen).toEqual(["bot"]);
+ });
+
+ test("does not request user credentials for local help failures", async () => {
+ const seen: string[] = [];
+ const session = createLarkReadSession(async args => { seen.push(as(args)!); return denied; }, "bot");
+ await session.run(["docs", "+fetch", "--help"]);
+ expect(seen).toEqual(["bot"]);
+ });
+
+ test("capture uses the configured identity for discovery, body and media fallback", async () => {
+ process.env.CONTEXT_LARK_IDENTITY = "bot";
+ const seen: string[] = [];
+ const runner: LarkRunner = async (args, options) => {
+ seen.push(`${args[0]}:${args[1]}:${as(args)}`);
+ if (args.includes("--version")) return { ...success, stdout: "1.0.0" };
+ if (args.includes("--help")) return { ...success, stdout: "Flags:\n --doc-format string\n --api-version string\n" };
+ if (args[1] === "+fetch") return { ...success, stdout: JSON.stringify({ ok: true, identity: as(args), data: {
+ document: { content: 'HandbookBody
![]()
' },
+ } }) };
+ if (args[1] === "+media-download" && as(args) === "bot") return denied;
+ if (args[1] === "+media-download") {
+ await writeFile(resolve(options!.cwd!, `${args[args.indexOf("--output") + 1]}.png`), "image");
+ return success;
+ }
+ throw new Error(`unexpected command ${args}`);
+ };
+ await checkLarkCli(runner);
+ const result = await fetchFeishuDocSnapshot({ url: "https://example.test/wiki/handbook" }, runner);
+ expect(result.accessIdentity).toBe("bot");
+ expect(result.identityFallback).toBe(true);
+ expect(result.resourceMaterialization.status).toBe("complete");
+ expect(seen).toEqual(["--version:--as:bot", "docs:+fetch:bot", "docs:+fetch:bot",
+ "docs:+media-download:bot", "docs:+media-download:user"]);
+ });
+
+ test("body fallback records user identity", async () => {
+ const runner: LarkRunner = async args => as(args) === "bot" ? denied : {
+ ...success, stdout: JSON.stringify({ ok: true, identity: "user", data: { document: { content: "Body
" } } }),
+ };
+ const result = await fetchFeishuDocSnapshot({ url: "https://example.test/docx/shared", identity: "bot", docsApiVersion: "v2" }, runner);
+ expect(result.accessIdentity).toBe("user");
+ expect(result.identityFallback).toBe(true);
+ });
+
+ test("the official capture phase honors the environment without an identity argument", async () => {
+ process.env.CONTEXT_LARK_IDENTITY = "bot";
+ const root = makeLarkCaptureTmp();
+ const identities: string[] = [];
+ try {
+ const cwd = await createLarkCaptureProject(root);
+ const output = await runLarkCapturePhase({ cwd, phaseId: "capture:lark:handbook", format: "json",
+ larkRunner: async args => {
+ identities.push(as(args)!);
+ if (args.includes("--help")) return { ...success, stdout: "Flags:\n --doc-format string\n --api-version string\n" };
+ return { ...success, stdout: JSON.stringify({ ok: true, identity: "bot", data: {
+ document: { content: "HandbookBody
" },
+ } }) };
+ },
+ });
+ expect(JSON.parse(output).result.snapshot.changed).toBe(true);
+ expect(identities).toEqual(["bot", "bot"]);
+ } finally {
+ rmSync(root, { recursive: true, force: true });
+ }
+ });
+
+ test("returns user error if both identities fail", async () => {
+ const seen: string[] = [];
+ const runner: LarkRunner = async args => {
+ seen.push(as(args)!);
+ return denied;
+ };
+ await expect(fetchFeishuDocSnapshot({ url: "https://example.test/docx/private", identity: "bot", docsApiVersion: "v2" }, runner))
+ .rejects.toThrow();
+ expect(seen).toEqual(["bot", "user"]);
+ });
+});
diff --git a/packages/context-cli/src/lib/feishu.ts b/packages/context-cli/src/lib/feishu.ts
index 4a93abae..6ac13623 100644
--- a/packages/context-cli/src/lib/feishu.ts
+++ b/packages/context-cli/src/lib/feishu.ts
@@ -17,6 +17,7 @@ import {
} from "./larkResourceMaterialization.js";
import { createLarkCaptureReport } from "./larkCaptureReport.js";
import { larkMarkdownImageResources, replaceLarkMarkdownImages } from "./larkMarkdownImages.js";
+import { createLarkReadSession, resolveLarkReadIdentity } from "./larkReadIdentity.js";
/**
* Name of the binary we spawn. Matches the `bin` field of the official npm
@@ -92,7 +93,7 @@ const defaultRunner: LarkRunner = (args, options) =>
});
export async function checkLarkCli(runner: LarkRunner = defaultRunner): Promise {
- const result = await runner(["--version"]);
+ const result = await runner(["--version", "--as", resolveLarkReadIdentity()]);
if (result.exitCode !== 0) {
throw new LarkCliError(`${LARK_BIN} --version failed`, result.exitCode, result.stderr);
}
@@ -117,7 +118,9 @@ export interface FetchFeishuDocInput {
url: string;
docsApiVersion?: DocsFetchApiVersion | "auto";
/**
- * Identity used to read the document. `auto` prefers the user identity and
+ * Defaults to CONTEXT_LARK_IDENTITY (user). Bot mode permits one credential/
+ * permission fallback to user for this capture, including embedded resources.
+ * Explicit legacy `auto` prefers the user identity and
* falls back to the bot only when user credentials themselves are absent or
* cannot be refreshed. It never changes identity after a permission error.
*/
@@ -160,7 +163,7 @@ interface DocsFetchPlan {
docFormat?: "xml";
}
-const docsFetchCapabilitiesCache = new WeakMap>();
+const docsFetchCapabilitiesCache = new WeakMap>>();
async function detectDocsFetchCapabilities(runner: LarkRunner): Promise {
const result = await runner(["docs", "+fetch", "--help"]).catch((): RunLarkResult => ({
@@ -179,14 +182,21 @@ async function detectDocsFetchCapabilities(runner: LarkRunner): Promise {
if (requested === "v1" || requested === "v2") {
return Promise.resolve({ apiVersion: requested, docFormat: "xml" });
}
- let capabilitiesPromise = docsFetchCapabilitiesCache.get(runner);
+ let cached = docsFetchCapabilitiesCache.get(cacheKey);
+ if (!cached) {
+ cached = new Map();
+ docsFetchCapabilitiesCache.set(cacheKey, cached);
+ }
+ let capabilitiesPromise = cached.get(identity);
if (capabilitiesPromise === undefined) {
capabilitiesPromise = detectDocsFetchCapabilities(runner);
- docsFetchCapabilitiesCache.set(runner, capabilitiesPromise);
+ cached.set(identity, capabilitiesPromise);
}
return capabilitiesPromise.then((capabilities) => {
if (!capabilities.supportsDocFormat) {
@@ -630,20 +640,26 @@ export async function fetchFeishuDocSnapshot(
input: FetchFeishuDocInput,
runner: LarkRunner = defaultRunner,
): Promise {
+ const preference = input.prefetched?.identity ?? input.identity ?? resolveLarkReadIdentity();
+ const cacheKey = runner;
+ const session = createLarkReadSession(runner, input.prefetched?.identity ?? (preference === "bot" ? "bot" : "user"),
+ !input.prefetched && preference === "bot");
+ runner = session.run;
const docsFetchPlan: DocsFetchPlan = input.prefetched
? { apiVersion: "v2", docFormat: "xml" }
- : await resolveDocsFetchPlan(input.docsApiVersion ?? "auto", runner);
+ : await resolveDocsFetchPlan(input.docsApiVersion ?? "auto", runner, cacheKey, preference);
const identityFetch = input.prefetched
? { fetched: await fetchDocsResponse(input, docsFetchPlan, runner, input.prefetched.identity),
identity: input.prefetched.identity, fallback: false }
- : await fetchWithIdentity(input, docsFetchPlan, runner);
+ : await fetchWithIdentity({ ...input, identity: preference }, docsFetchPlan, runner);
let fetched = identityFetch.fetched;
- const accessIdentity = identityFetch.identity;
+ let accessIdentity = input.prefetched?.identity ?? session.identity;
let projection: LarkDocxProjection | undefined;
for (let attempt = 0; attempt < MAX_STRUCTURAL_FETCH_ATTEMPTS && fetched.contentFormat === "xml"; attempt++) {
projection = projectLarkDocxXml({ xml: fetched.body, sourceUrl: input.url });
if (input.prefetched || !hasEmptySubPageList(projection) || attempt === MAX_STRUCTURAL_FETCH_ATTEMPTS - 1) break;
fetched = await fetchDocsResponse(input, docsFetchPlan, runner, accessIdentity);
+ accessIdentity = session.identity;
}
let body = fetched.body;
@@ -733,7 +749,7 @@ export async function fetchFeishuDocSnapshot(
fidelity,
resourceMaterialization,
accessIdentity,
- identityFallback: identityFetch.fallback,
+ identityFallback: identityFetch.fallback || session.usedFallback,
};
}
return {
@@ -744,7 +760,7 @@ export async function fetchFeishuDocSnapshot(
fidelity,
resourceMaterialization,
accessIdentity,
- identityFallback: identityFetch.fallback,
+ identityFallback: identityFetch.fallback || session.usedFallback,
};
}
diff --git a/packages/context-cli/src/lib/larkReadIdentity.ts b/packages/context-cli/src/lib/larkReadIdentity.ts
new file mode 100644
index 00000000..a9f23e12
--- /dev/null
+++ b/packages/context-cli/src/lib/larkReadIdentity.ts
@@ -0,0 +1,59 @@
+import { ContextError } from "./errors.js";
+import { ExitCode } from "../types/exitCode.js";
+import type { LarkRunner, RunLarkResult } from "./feishu.js";
+
+export type LarkReadIdentity = "user" | "bot";
+
+export function resolveLarkReadIdentity(): LarkReadIdentity {
+ const value = process.env.CONTEXT_LARK_IDENTITY?.trim() || "user";
+ if (value === "user" || value === "bot") return value;
+ throw new ContextError(ExitCode.UserError, "CONTEXT_LARK_IDENTITY must be user or bot", {
+ reason_code: "lark.invalid-read-identity",
+ valid_values: ["user", "bot"],
+ next: "Set CONTEXT_LARK_IDENTITY to user or bot and rerun the same command",
+ });
+}
+
+function credentialFailure(result: RunLarkResult): boolean {
+ for (const output of [result.stdout, result.stderr]) {
+ const start = output.indexOf("{");
+ if (start < 0) continue;
+ try {
+ const parsed: unknown = JSON.parse(output.slice(start));
+ if (!parsed || typeof parsed !== "object" || !("error" in parsed)) continue;
+ if (result.exitCode === 0 && (!("ok" in parsed) || parsed.ok !== false)) continue;
+ const error = parsed.error;
+ if (!error || typeof error !== "object") continue;
+ const type = "type" in error ? error.type : undefined;
+ const subtype = "subtype" in error ? error.subtype : undefined;
+ if (type === "authorization" || type === "authentication" ||
+ ["missing_scope", "permission_denied", "access_denied", "need_user_authorization"].includes(String(subtype))) {
+ return true;
+ }
+ } catch { /* Plain host credential diagnostics are checked below. */ }
+ }
+ return result.exitCode !== 0 && /reason=(?:bot_unavailable|not_authorized)\b|\b(?:missing_scope|permission_denied|access_denied)\b/iu.test(result.stderr);
+}
+
+/** One capture owns one identity session; a fallback is sticky, not per image. */
+export function createLarkReadSession(runner: LarkRunner, initial: LarkReadIdentity, fallback = initial === "bot") {
+ let identity = initial;
+ let usedFallback = false;
+ const run: LarkRunner = async (args, options) => {
+ const explicit = args.indexOf("--as");
+ const requested = explicit >= 0 ? args[explicit + 1] : identity;
+ const selected = usedFallback ? "user" : requested === "bot" ? "bot" : "user";
+ const withIdentity = [...args];
+ if (explicit >= 0) withIdentity[explicit + 1] = selected;
+ else withIdentity.push("--as", selected);
+ const result = await runner(withIdentity, options);
+ identity = selected;
+ // Help is local discovery, not a reason to request the user's OAuth grant.
+ if (identity !== "bot" || !fallback || usedFallback || args.includes("--help") || !credentialFailure(result)) return result;
+ usedFallback = true;
+ identity = "user";
+ withIdentity[withIdentity.indexOf("--as") + 1] = "user";
+ return runner(withIdentity, options);
+ };
+ return { run, get identity() { return identity; }, get usedFallback() { return usedFallback; } };
+}
diff --git a/packages/context-cli/src/project/documentCaptureLark.ts b/packages/context-cli/src/project/documentCaptureLark.ts
index 6c5ec2af..d25bbd4f 100644
--- a/packages/context-cli/src/project/documentCaptureLark.ts
+++ b/packages/context-cli/src/project/documentCaptureLark.ts
@@ -187,7 +187,7 @@ function larkErrorRecovery(error: unknown, sourceName: string): {
if (/auth|login|permission|forbidden|unauthori[sz]ed|scope/iu.test(message)) {
return {
reasonCode: "external.authorization-required",
- next: "Run lark-cli auth login with an account that can read the document, then rerun capture",
+ next: "Check the selected Lark identity and document access. For host-managed credentials use the host authorization flow; use lark-cli auth login only for a locally managed user login, then rerun capture",
};
}
return {
@@ -378,6 +378,7 @@ async function runCaptureLarkPhaseUnlocked(input: {
...(input.prefetched === undefined ? {} : { prefetched: input.prefetched }),
}, input.larkRunner);
} catch (error) {
+ if (error instanceof ContextError) throw error;
const failure = normalizeLarkError(error, resolved.sourceName);
if (failure.detail?.reason_code === "external.authorization-required" ||
failure.detail?.reason_code === "external.tool-failed" && error instanceof LarkCliError && error.exitCode !== 0) {
@@ -566,7 +567,7 @@ async function runCaptureLarkPhaseUnlocked(input: {
diagnostics: [
...(recovery === undefined ? [] : [recovery.diagnostic]),
...(fetched.identityFallback
- ? [`info: lark.capture.identity-fallback: user credentials unavailable; captured with ${fetched.accessIdentity} identity`]
+ ? [`info: lark.capture.identity-fallback: capture used an identity fallback; document identity: ${fetched.accessIdentity}; embedded reads may use the fallback identity`]
: []),
...fetched.fidelity.issues.map((issue) =>
`${issue.severity}: ${issue.code}: ${issue.block_type} × ${issue.count}: ${issue.reason}`
diff --git a/packages/context-cli/src/project/indexerBaseContracts.ts b/packages/context-cli/src/project/indexerBaseContracts.ts
index 277e79a6..71c63b49 100644
--- a/packages/context-cli/src/project/indexerBaseContracts.ts
+++ b/packages/context-cli/src/project/indexerBaseContracts.ts
@@ -21,7 +21,7 @@ import { bundledMarkdownReaderQuestionContracts } from
"./indexerBaseMarkdownAuthoringCatalog.js";
const BASE_CONTRACT_VERSION = "1.1.0";
-export const BUNDLED_INDEXER_PARSER_PACKAGE_VERSION = "0.7.29";
+export const BUNDLED_INDEXER_PARSER_PACKAGE_VERSION = "0.7.30";
const BUNDLED_PARSER_REQUIREMENTS = buildIndexerParserCapabilityRequirements(
BUNDLED_INDEXER_PARSER_PACKAGE_VERSION,
);
diff --git a/packages/context/docs/guides/lark-resources.md b/packages/context/docs/guides/lark-resources.md
index 5d24263c..3b4afa51 100644
--- a/packages/context/docs/guides/lark-resources.md
+++ b/packages/context/docs/guides/lark-resources.md
@@ -127,8 +127,24 @@ assess the page with its non-text evidence.
## Image choices for a production task
+Before capture, the Agent follows the document-capture Route procedure's task-wide
+document threshold and image self-check, without asking for user confirmation.
+Set `DOCUMENT_IMAGE_CAPTURE` in task instructions or workspace guidance to `ON`
+(include images), `OFF` (references only), or a positive integer document threshold.
+Omitting it uses `10`; exactly the threshold remains within normal acquisition.
+Current-conversation instructions override workspace guidance for that task only.
+For example, `DOCUMENT_IMAGE_CAPTURE: 20` skips image downloads when the task
+contains more than 20 distinct documents. This is an Agent instruction, not an
+environment variable, CLI flag or SDK field; no Bot configuration is required.
+Above a numeric threshold, the default is body capture with image references,
+unless the effective setting is overridden to `ON`. This workflow
+choice uses the existing resource fields; it does not change SDK defaults or add
+a CLI hard gate. Apply it before bulk capture or host prefetch, not after images
+have already been downloaded.
+
The work-start report asks once when a task contains more than 30 distinct images
-and has no explicit image policy. The choices are intelligent conversion and
+that will be acquired and has no explicit image handling policy. Reuse the
+current-conversation image instruction when it already settles this choice. The choices are intelligent conversion and
inclusion (recommended), include all as images with compression, or include none
with placeholders. Count the whole task, not each capture or writing batch.
Review reports show the resulting image handling and any fallbacks.
diff --git a/packages/context/package.json b/packages/context/package.json
index 442acd12..9e9e713f 100644
--- a/packages/context/package.json
+++ b/packages/context/package.json
@@ -1,7 +1,7 @@
{
"name": "@c4a/context",
"description": "Declarative SDK for Context knowledge sources, workflows, review, and package outputs",
- "version": "0.7.29",
+ "version": "0.7.30",
"type": "module",
"license": "MIT",
"engines": {
diff --git a/packages/core/package.json b/packages/core/package.json
index b30b0382..1eb622c6 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -1,7 +1,7 @@
{
"name": "@c4a/core",
"description": "Shared extraction types, schemas, and utilities for Context",
- "version": "0.7.29",
+ "version": "0.7.30",
"type": "module",
"license": "MIT",
"engines": {
diff --git a/packages/dev-cli/package.json b/packages/dev-cli/package.json
index 773a8148..9b75bb52 100644
--- a/packages/dev-cli/package.json
+++ b/packages/dev-cli/package.json
@@ -1,7 +1,7 @@
{
"name": "@c4a/dev-cli",
"description": "Developer menu for Context build, verification, link, and release preparation",
- "version": "0.7.29",
+ "version": "0.7.30",
"private": true,
"type": "module",
"license": "MIT",
diff --git a/packages/extract-contract/package.json b/packages/extract-contract/package.json
index e47fa407..950147e9 100644
--- a/packages/extract-contract/package.json
+++ b/packages/extract-contract/package.json
@@ -1,7 +1,7 @@
{
"name": "@c4a/extract-contract",
"description": "OpenAPI and GraphQL contract catalog adapter for Context",
- "version": "0.7.29",
+ "version": "0.7.30",
"type": "module",
"license": "MIT",
"engines": {
diff --git a/packages/extract-go/package.json b/packages/extract-go/package.json
index 20133a12..1e7a3fad 100644
--- a/packages/extract-go/package.json
+++ b/packages/extract-go/package.json
@@ -1,7 +1,7 @@
{
"name": "@c4a/extract-go",
"description": "Go extraction plugin and structural index for Context",
- "version": "0.7.29",
+ "version": "0.7.30",
"type": "module",
"license": "MIT",
"engines": {
diff --git a/packages/extract-mdx/package.json b/packages/extract-mdx/package.json
index abd218cc..300e7730 100644
--- a/packages/extract-mdx/package.json
+++ b/packages/extract-mdx/package.json
@@ -1,7 +1,7 @@
{
"name": "@c4a/extract-mdx",
"description": "MDX component and example catalog bridge for Context",
- "version": "0.7.29",
+ "version": "0.7.30",
"type": "module",
"license": "MIT",
"engines": {
diff --git a/packages/extract-proto/package.json b/packages/extract-proto/package.json
index a2b72f2e..4a0c7d46 100644
--- a/packages/extract-proto/package.json
+++ b/packages/extract-proto/package.json
@@ -1,7 +1,7 @@
{
"name": "@c4a/extract-proto",
"description": "Protocol Buffers IDL catalog parser for Context",
- "version": "0.7.29",
+ "version": "0.7.30",
"type": "module",
"license": "MIT",
"engines": {
diff --git a/packages/extract-rush/package.json b/packages/extract-rush/package.json
index 9e6aefb9..02bab91f 100644
--- a/packages/extract-rush/package.json
+++ b/packages/extract-rush/package.json
@@ -1,7 +1,7 @@
{
"name": "@c4a/extract-rush",
"description": "Rush workspace structural index for Context",
- "version": "0.7.29",
+ "version": "0.7.30",
"type": "module",
"license": "MIT",
"engines": {
diff --git a/packages/extract-sql/package.json b/packages/extract-sql/package.json
index 2770a5f5..89856b11 100644
--- a/packages/extract-sql/package.json
+++ b/packages/extract-sql/package.json
@@ -1,7 +1,7 @@
{
"name": "@c4a/extract-sql",
"description": "Dialect-bound lightweight SQL evidence adapter for Context",
- "version": "0.7.29",
+ "version": "0.7.30",
"type": "module",
"license": "MIT",
"engines": {
diff --git a/packages/extract-style/package.json b/packages/extract-style/package.json
index 537293c2..f94456a2 100644
--- a/packages/extract-style/package.json
+++ b/packages/extract-style/package.json
@@ -1,7 +1,7 @@
{
"name": "@c4a/extract-style",
"description": "Lightweight CSS and SCSS evidence adapter for Context",
- "version": "0.7.29",
+ "version": "0.7.30",
"type": "module",
"license": "MIT",
"engines": {
diff --git a/packages/extract-thrift/package.json b/packages/extract-thrift/package.json
index 8d0b1aa1..bbc6bb06 100644
--- a/packages/extract-thrift/package.json
+++ b/packages/extract-thrift/package.json
@@ -1,7 +1,7 @@
{
"name": "@c4a/extract-thrift",
"description": "Apache Thrift IDL catalog parser for Context",
- "version": "0.7.29",
+ "version": "0.7.30",
"type": "module",
"license": "MIT",
"engines": {
diff --git a/packages/extract-ts/package.json b/packages/extract-ts/package.json
index 6bc1ac68..65733fb3 100644
--- a/packages/extract-ts/package.json
+++ b/packages/extract-ts/package.json
@@ -1,7 +1,7 @@
{
"name": "@c4a/extract-ts",
"description": "TypeScript and JavaScript extraction plugin for the Context ExtractionResult v2 contract",
- "version": "0.7.29",
+ "version": "0.7.30",
"type": "module",
"license": "MIT",
"engines": {
diff --git a/packages/extract/package.json b/packages/extract/package.json
index 1f589316..a21ace49 100644
--- a/packages/extract/package.json
+++ b/packages/extract/package.json
@@ -1,7 +1,7 @@
{
"name": "@c4a/extract",
"description": "Language-plugin framework and repository runner for Context code evidence",
- "version": "0.7.29",
+ "version": "0.7.30",
"type": "module",
"license": "MIT",
"engines": {
diff --git a/packages/tui/package.json b/packages/tui/package.json
index fb7428d8..33c04fd9 100644
--- a/packages/tui/package.json
+++ b/packages/tui/package.json
@@ -1,7 +1,7 @@
{
"name": "@c4a/tui",
"description": "Shared terminal UI components (Ink + React) for Context development tools",
- "version": "0.7.29",
+ "version": "0.7.30",
"private": true,
"type": "module",
"license": "MIT",
diff --git a/plugins/context/repo-install/claude/.claude-plugin/plugin.json b/plugins/context/repo-install/claude/.claude-plugin/plugin.json
index 0f6b1774..5343e29d 100644
--- a/plugins/context/repo-install/claude/.claude-plugin/plugin.json
+++ b/plugins/context/repo-install/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.29",
+ "version": "0.7.30",
"author": {
"name": "c4a"
},
diff --git a/plugins/context/repo-install/claude/commands/context-inspect-search.md b/plugins/context/repo-install/claude/commands/context-inspect-search.md
index e922ffea..160add6b 100644
--- a/plugins/context/repo-install/claude/commands/context-inspect-search.md
+++ b/plugins/context/repo-install/claude/commands/context-inspect-search.md
@@ -29,9 +29,9 @@ registrations, snapshots, tasks, approvals or user checkouts.
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.
+- `repo-first` (default): search approved `knowledge/` in the configured knowledge
+ workspace first; trace authorized original sources only for material gaps.
+ Use an available package when approved knowledge is unavailable.
- `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
@@ -45,8 +45,10 @@ 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
+start with approved knowledge, not original-code checkout preparation. With
+readable `knowledge/`, do not probe `dist/`, build inventories or installed
+packages: distribution output is not a query prerequisite. An explicit request
+to investigate delivered content is an exception. 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
@@ -66,9 +68,11 @@ missing, use the host's configured, authorized package retrieval mechanism while
other reading continues. Only check or prepare tools needed for the next actual
operation; installation failure does not block independent local retrieval.
-For gaps or latest-content questions, also search approved knowledge when a workspace is available:
-use `knowledge/structure.yaml` and relevant `knowledge/` paths, trying business
-terms, symbols and synonyms, then read matching sections in context. Delivered
+Search relevant `knowledge/` paths using business terms, symbols and synonyms,
+then read matching sections in context; use `knowledge/structure.yaml` when
+navigation or associations are needed, not as an exhaustive preflight. In
+package-first or dual mode, approved knowledge can resolve gaps or freshness
+questions in delivered material. Delivered
content may lag approved knowledge; they are not independent corroboration.
Candidates and temporary reports are not approved pages. A search miss does not
prove a capability is absent. Do not build merely to answer a query; a separately
@@ -78,8 +82,11 @@ When package or approved knowledge leaves a gap, directly trace relevant sources
without asking whether to deepen the query. Use available document, code-search
or extraction tools within the authorized scope, recording source identity and
version. Prepare sources while continuing other reading.
-One failed source blocks only dependent claims. Answer when evidence is
-sufficient, without completing unnecessary preparation.
+One failed source blocks only dependent claims. If the read knowledge supports
+the requested conclusion, its conditions and scope, answer without restoring
+code or checking every associated source. Missing mechanisms, conflicting facts
+or unsupported current-behavior claims still require targeted investigation;
+an article title, search snippet or unread citation is not sufficient evidence.
## Trace and retrieve only relevant sources
@@ -90,18 +97,23 @@ registry is not a mandatory intermediate step. If the source identity or version
cannot be established, retain package-grounded findings and qualify attribution;
do not invent a repository or equate current source with the package's baseline.
-When a workspace and `context-build-inventory.json` are available, map a delivered page's
+Only when tracing a delivered page and a build inventory is already available, map its
`dist_path` through `approved_knowledge.files` to its `approved_path`, relative
-to the workspace's `knowledge/` root. Follow the approved page's associations in
-`knowledge/structure.yaml` and `sources/*/index.yaml`. Without a reliable mapping,
+to the workspace's `knowledge/` root. For directly read approved pages, skip this
+mapping entirely. Follow relevant associations in `knowledge/structure.yaml`
+and `sources/*/index.yaml` only when source tracing is needed. Without a reliable mapping,
continue package retrieval and follow explicit source references where available.
Do not guess originals from similar filenames or claim attribution without
checking the referenced material.
Use the repository and recorded commit identified by the package or workspace
as the source baseline.
-Reuse existing checkouts only after checking remote, commit, module coverage
-and local changes; do not reset them or change their sparse configuration.
+Before reusing a checkout for source reads, group checks of remote, commit,
+module coverage and local changes. Reuse those findings within this response
+instead of checking again before each search or file read. Recheck affected
+facts if the checkout/ref changes, sparse scope expands or there is evidence of
+concurrent edits; do not treat a previous response's checks as current. Do not
+reset user checkouts or change their sparse configuration.
Missing code goes into a reusable query-owned path such as
`.tmp/context-inspect////`, separate from user
checkouts and production-managed sources. Use safe, credential-free path
@@ -130,10 +142,24 @@ capture/recovery actions. Production recovery gates do not block this independen
inspection. Preserve unavailable-evidence gaps rather than changing production
state to get past them.
-Compare relevant baseline files with current code when accessible, including
-relevant local changes. Use actual diffs to assess impact; current code is not a
-substitute for the baseline. Mention a missing comparison only when it limits
-the answer. For documents, notes and sessions, read saved bodies and necessary
+Batch independent searches and related file reads once paths are known, such as
+the entrypoint, state update and controlling render logic for one mechanism.
+Read enough surrounding context and follow unresolved imports or calls; batching
+must not truncate decisive evidence or turn a partial read into a complete audit.
+Reuse already read evidence rather than rereading it to prepare each tool call.
+
+Let evidence sufficiency determine whether a version comparison is needed.
+When the available knowledge or identified baseline code resolves the question,
+answer without fetching the default branch, recovering a second checkout or
+reading history merely to confirm freshness. Compare narrowly when uncertainty,
+conflicting evidence, suspected changes or an explicit version-comparison request
+makes it useful. A question about current behavior requires judging whether the
+available evidence supports that claim, not automatically comparing every branch.
+Retain necessary source reads; do not equate a recorded baseline or branch HEAD
+with a verified live deployment. When comparing, use actual relevant diffs,
+including relevant local changes; current code is not a substitute for the baseline.
+Mention a missing comparison only when it limits the answer.
+For documents, notes and sessions, read saved bodies and necessary
attachments; fetch missing accessible material within scope. A summary is not a
full transcript, an unread link is not evidence, and current remote content does
not prove a historical snapshot.
@@ -166,13 +192,25 @@ limitation. Do not dump internal reasoning, runtime identifiers or routine
version comparisons. Explain only differences affecting the answer; hashes may
appear in source URLs without requiring a separate version audit in the prose.
-For website links, use `context-site-map.json` from the selected package or
-sibling website output. Match `pages[].package_path` or `approved_path`, and
+Collect citation targets after the relevant evidence is established and resolve
+them in one batch using the host's existing link resolver when available. Reuse
+known workspace, repository and site parameters; do not rediscover them per link.
+If later evidence adds targets, resolve only those missing from the results.
+Without a host resolver, use an already available `context-site-map.json` from
+the selected package or website output. Do not search for `dist/` merely to
+obtain links for readable approved knowledge. Match `pages[].package_path` or `approved_path`, and
resolve `site_path` against `site_url` without prepending `base` again. Cite only
matched pages, deduplicate links and do not invent anchors. If mapping is absent
or invalid, retain local citations. Do not build, publish or probe remote sites
just to format citations; a local map is not proof of the current online content.
+Once the requested questions are supported or genuinely unavailable evidence is
+clearly bounded, synthesize the final answer directly. Do not add another planning,
+freshness-audit or summary round just to prepare it. Preserve necessary mechanisms,
+exceptions, citations and verification limits; fewer preparation steps must not
+mean weaker evidence or omitted questions. Host delivery and receipt requirements
+still apply, without repeating the completed investigation.
+
Suggest a knowledge update only with supporting evidence: identify the affected
page or gap, proposed change and bounded source scope. Check neighboring content
before proposing a new page. Only after user acceptance, hand the evidence and
diff --git a/plugins/context/repo-install/claude/skills/context-inspect-search/SKILL.md b/plugins/context/repo-install/claude/skills/context-inspect-search/SKILL.md
index 5c777958..8d80bd49 100644
--- a/plugins/context/repo-install/claude/skills/context-inspect-search/SKILL.md
+++ b/plugins/context/repo-install/claude/skills/context-inspect-search/SKILL.md
@@ -28,9 +28,9 @@ registrations, snapshots, tasks, approvals or user checkouts.
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.
+- `repo-first` (default): search approved `knowledge/` in the configured knowledge
+ workspace first; trace authorized original sources only for material gaps.
+ Use an available package when approved knowledge is unavailable.
- `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
@@ -44,8 +44,10 @@ 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
+start with approved knowledge, not original-code checkout preparation. With
+readable `knowledge/`, do not probe `dist/`, build inventories or installed
+packages: distribution output is not a query prerequisite. An explicit request
+to investigate delivered content is an exception. 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
@@ -65,9 +67,11 @@ missing, use the host's configured, authorized package retrieval mechanism while
other reading continues. Only check or prepare tools needed for the next actual
operation; installation failure does not block independent local retrieval.
-For gaps or latest-content questions, also search approved knowledge when a workspace is available:
-use `knowledge/structure.yaml` and relevant `knowledge/` paths, trying business
-terms, symbols and synonyms, then read matching sections in context. Delivered
+Search relevant `knowledge/` paths using business terms, symbols and synonyms,
+then read matching sections in context; use `knowledge/structure.yaml` when
+navigation or associations are needed, not as an exhaustive preflight. In
+package-first or dual mode, approved knowledge can resolve gaps or freshness
+questions in delivered material. Delivered
content may lag approved knowledge; they are not independent corroboration.
Candidates and temporary reports are not approved pages. A search miss does not
prove a capability is absent. Do not build merely to answer a query; a separately
@@ -77,8 +81,11 @@ When package or approved knowledge leaves a gap, directly trace relevant sources
without asking whether to deepen the query. Use available document, code-search
or extraction tools within the authorized scope, recording source identity and
version. Prepare sources while continuing other reading.
-One failed source blocks only dependent claims. Answer when evidence is
-sufficient, without completing unnecessary preparation.
+One failed source blocks only dependent claims. If the read knowledge supports
+the requested conclusion, its conditions and scope, answer without restoring
+code or checking every associated source. Missing mechanisms, conflicting facts
+or unsupported current-behavior claims still require targeted investigation;
+an article title, search snippet or unread citation is not sufficient evidence.
## Trace and retrieve only relevant sources
@@ -89,18 +96,23 @@ registry is not a mandatory intermediate step. If the source identity or version
cannot be established, retain package-grounded findings and qualify attribution;
do not invent a repository or equate current source with the package's baseline.
-When a workspace and `context-build-inventory.json` are available, map a delivered page's
+Only when tracing a delivered page and a build inventory is already available, map its
`dist_path` through `approved_knowledge.files` to its `approved_path`, relative
-to the workspace's `knowledge/` root. Follow the approved page's associations in
-`knowledge/structure.yaml` and `sources/*/index.yaml`. Without a reliable mapping,
+to the workspace's `knowledge/` root. For directly read approved pages, skip this
+mapping entirely. Follow relevant associations in `knowledge/structure.yaml`
+and `sources/*/index.yaml` only when source tracing is needed. Without a reliable mapping,
continue package retrieval and follow explicit source references where available.
Do not guess originals from similar filenames or claim attribution without
checking the referenced material.
Use the repository and recorded commit identified by the package or workspace
as the source baseline.
-Reuse existing checkouts only after checking remote, commit, module coverage
-and local changes; do not reset them or change their sparse configuration.
+Before reusing a checkout for source reads, group checks of remote, commit,
+module coverage and local changes. Reuse those findings within this response
+instead of checking again before each search or file read. Recheck affected
+facts if the checkout/ref changes, sparse scope expands or there is evidence of
+concurrent edits; do not treat a previous response's checks as current. Do not
+reset user checkouts or change their sparse configuration.
Missing code goes into a reusable query-owned path such as
`.tmp/context-inspect////`, separate from user
checkouts and production-managed sources. Use safe, credential-free path
@@ -129,10 +141,24 @@ capture/recovery actions. Production recovery gates do not block this independen
inspection. Preserve unavailable-evidence gaps rather than changing production
state to get past them.
-Compare relevant baseline files with current code when accessible, including
-relevant local changes. Use actual diffs to assess impact; current code is not a
-substitute for the baseline. Mention a missing comparison only when it limits
-the answer. For documents, notes and sessions, read saved bodies and necessary
+Batch independent searches and related file reads once paths are known, such as
+the entrypoint, state update and controlling render logic for one mechanism.
+Read enough surrounding context and follow unresolved imports or calls; batching
+must not truncate decisive evidence or turn a partial read into a complete audit.
+Reuse already read evidence rather than rereading it to prepare each tool call.
+
+Let evidence sufficiency determine whether a version comparison is needed.
+When the available knowledge or identified baseline code resolves the question,
+answer without fetching the default branch, recovering a second checkout or
+reading history merely to confirm freshness. Compare narrowly when uncertainty,
+conflicting evidence, suspected changes or an explicit version-comparison request
+makes it useful. A question about current behavior requires judging whether the
+available evidence supports that claim, not automatically comparing every branch.
+Retain necessary source reads; do not equate a recorded baseline or branch HEAD
+with a verified live deployment. When comparing, use actual relevant diffs,
+including relevant local changes; current code is not a substitute for the baseline.
+Mention a missing comparison only when it limits the answer.
+For documents, notes and sessions, read saved bodies and necessary
attachments; fetch missing accessible material within scope. A summary is not a
full transcript, an unread link is not evidence, and current remote content does
not prove a historical snapshot.
@@ -165,13 +191,25 @@ limitation. Do not dump internal reasoning, runtime identifiers or routine
version comparisons. Explain only differences affecting the answer; hashes may
appear in source URLs without requiring a separate version audit in the prose.
-For website links, use `context-site-map.json` from the selected package or
-sibling website output. Match `pages[].package_path` or `approved_path`, and
+Collect citation targets after the relevant evidence is established and resolve
+them in one batch using the host's existing link resolver when available. Reuse
+known workspace, repository and site parameters; do not rediscover them per link.
+If later evidence adds targets, resolve only those missing from the results.
+Without a host resolver, use an already available `context-site-map.json` from
+the selected package or website output. Do not search for `dist/` merely to
+obtain links for readable approved knowledge. Match `pages[].package_path` or `approved_path`, and
resolve `site_path` against `site_url` without prepending `base` again. Cite only
matched pages, deduplicate links and do not invent anchors. If mapping is absent
or invalid, retain local citations. Do not build, publish or probe remote sites
just to format citations; a local map is not proof of the current online content.
+Once the requested questions are supported or genuinely unavailable evidence is
+clearly bounded, synthesize the final answer directly. Do not add another planning,
+freshness-audit or summary round just to prepare it. Preserve necessary mechanisms,
+exceptions, citations and verification limits; fewer preparation steps must not
+mean weaker evidence or omitted questions. Host delivery and receipt requirements
+still apply, without repeating the completed investigation.
+
Suggest a knowledge update only with supporting evidence: identify the affected
page or gap, proposed change and bounded source scope. Check neighboring content
before proposing a new page. Only after user acceptance, hand the evidence and
diff --git a/plugins/context/repo-install/codex/.codex-plugin/plugin.json b/plugins/context/repo-install/codex/.codex-plugin/plugin.json
index c3187064..75ee6382 100644
--- a/plugins/context/repo-install/codex/.codex-plugin/plugin.json
+++ b/plugins/context/repo-install/codex/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "c4a",
- "version": "0.7.29",
+ "version": "0.7.30",
"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.29",
+ "shortDescription": "Initialize and advance a local, source-linked project knowledge workspace.\nv0.7.30",
"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",
diff --git a/plugins/context/repo-install/codex/skills/context-inspect-search/SKILL.md b/plugins/context/repo-install/codex/skills/context-inspect-search/SKILL.md
index 5c777958..8d80bd49 100644
--- a/plugins/context/repo-install/codex/skills/context-inspect-search/SKILL.md
+++ b/plugins/context/repo-install/codex/skills/context-inspect-search/SKILL.md
@@ -28,9 +28,9 @@ registrations, snapshots, tasks, approvals or user checkouts.
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.
+- `repo-first` (default): search approved `knowledge/` in the configured knowledge
+ workspace first; trace authorized original sources only for material gaps.
+ Use an available package when approved knowledge is unavailable.
- `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
@@ -44,8 +44,10 @@ 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
+start with approved knowledge, not original-code checkout preparation. With
+readable `knowledge/`, do not probe `dist/`, build inventories or installed
+packages: distribution output is not a query prerequisite. An explicit request
+to investigate delivered content is an exception. 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
@@ -65,9 +67,11 @@ missing, use the host's configured, authorized package retrieval mechanism while
other reading continues. Only check or prepare tools needed for the next actual
operation; installation failure does not block independent local retrieval.
-For gaps or latest-content questions, also search approved knowledge when a workspace is available:
-use `knowledge/structure.yaml` and relevant `knowledge/` paths, trying business
-terms, symbols and synonyms, then read matching sections in context. Delivered
+Search relevant `knowledge/` paths using business terms, symbols and synonyms,
+then read matching sections in context; use `knowledge/structure.yaml` when
+navigation or associations are needed, not as an exhaustive preflight. In
+package-first or dual mode, approved knowledge can resolve gaps or freshness
+questions in delivered material. Delivered
content may lag approved knowledge; they are not independent corroboration.
Candidates and temporary reports are not approved pages. A search miss does not
prove a capability is absent. Do not build merely to answer a query; a separately
@@ -77,8 +81,11 @@ When package or approved knowledge leaves a gap, directly trace relevant sources
without asking whether to deepen the query. Use available document, code-search
or extraction tools within the authorized scope, recording source identity and
version. Prepare sources while continuing other reading.
-One failed source blocks only dependent claims. Answer when evidence is
-sufficient, without completing unnecessary preparation.
+One failed source blocks only dependent claims. If the read knowledge supports
+the requested conclusion, its conditions and scope, answer without restoring
+code or checking every associated source. Missing mechanisms, conflicting facts
+or unsupported current-behavior claims still require targeted investigation;
+an article title, search snippet or unread citation is not sufficient evidence.
## Trace and retrieve only relevant sources
@@ -89,18 +96,23 @@ registry is not a mandatory intermediate step. If the source identity or version
cannot be established, retain package-grounded findings and qualify attribution;
do not invent a repository or equate current source with the package's baseline.
-When a workspace and `context-build-inventory.json` are available, map a delivered page's
+Only when tracing a delivered page and a build inventory is already available, map its
`dist_path` through `approved_knowledge.files` to its `approved_path`, relative
-to the workspace's `knowledge/` root. Follow the approved page's associations in
-`knowledge/structure.yaml` and `sources/*/index.yaml`. Without a reliable mapping,
+to the workspace's `knowledge/` root. For directly read approved pages, skip this
+mapping entirely. Follow relevant associations in `knowledge/structure.yaml`
+and `sources/*/index.yaml` only when source tracing is needed. Without a reliable mapping,
continue package retrieval and follow explicit source references where available.
Do not guess originals from similar filenames or claim attribution without
checking the referenced material.
Use the repository and recorded commit identified by the package or workspace
as the source baseline.
-Reuse existing checkouts only after checking remote, commit, module coverage
-and local changes; do not reset them or change their sparse configuration.
+Before reusing a checkout for source reads, group checks of remote, commit,
+module coverage and local changes. Reuse those findings within this response
+instead of checking again before each search or file read. Recheck affected
+facts if the checkout/ref changes, sparse scope expands or there is evidence of
+concurrent edits; do not treat a previous response's checks as current. Do not
+reset user checkouts or change their sparse configuration.
Missing code goes into a reusable query-owned path such as
`.tmp/context-inspect////`, separate from user
checkouts and production-managed sources. Use safe, credential-free path
@@ -129,10 +141,24 @@ capture/recovery actions. Production recovery gates do not block this independen
inspection. Preserve unavailable-evidence gaps rather than changing production
state to get past them.
-Compare relevant baseline files with current code when accessible, including
-relevant local changes. Use actual diffs to assess impact; current code is not a
-substitute for the baseline. Mention a missing comparison only when it limits
-the answer. For documents, notes and sessions, read saved bodies and necessary
+Batch independent searches and related file reads once paths are known, such as
+the entrypoint, state update and controlling render logic for one mechanism.
+Read enough surrounding context and follow unresolved imports or calls; batching
+must not truncate decisive evidence or turn a partial read into a complete audit.
+Reuse already read evidence rather than rereading it to prepare each tool call.
+
+Let evidence sufficiency determine whether a version comparison is needed.
+When the available knowledge or identified baseline code resolves the question,
+answer without fetching the default branch, recovering a second checkout or
+reading history merely to confirm freshness. Compare narrowly when uncertainty,
+conflicting evidence, suspected changes or an explicit version-comparison request
+makes it useful. A question about current behavior requires judging whether the
+available evidence supports that claim, not automatically comparing every branch.
+Retain necessary source reads; do not equate a recorded baseline or branch HEAD
+with a verified live deployment. When comparing, use actual relevant diffs,
+including relevant local changes; current code is not a substitute for the baseline.
+Mention a missing comparison only when it limits the answer.
+For documents, notes and sessions, read saved bodies and necessary
attachments; fetch missing accessible material within scope. A summary is not a
full transcript, an unread link is not evidence, and current remote content does
not prove a historical snapshot.
@@ -165,13 +191,25 @@ limitation. Do not dump internal reasoning, runtime identifiers or routine
version comparisons. Explain only differences affecting the answer; hashes may
appear in source URLs without requiring a separate version audit in the prose.
-For website links, use `context-site-map.json` from the selected package or
-sibling website output. Match `pages[].package_path` or `approved_path`, and
+Collect citation targets after the relevant evidence is established and resolve
+them in one batch using the host's existing link resolver when available. Reuse
+known workspace, repository and site parameters; do not rediscover them per link.
+If later evidence adds targets, resolve only those missing from the results.
+Without a host resolver, use an already available `context-site-map.json` from
+the selected package or website output. Do not search for `dist/` merely to
+obtain links for readable approved knowledge. Match `pages[].package_path` or `approved_path`, and
resolve `site_path` against `site_url` without prepending `base` again. Cite only
matched pages, deduplicate links and do not invent anchors. If mapping is absent
or invalid, retain local citations. Do not build, publish or probe remote sites
just to format citations; a local map is not proof of the current online content.
+Once the requested questions are supported or genuinely unavailable evidence is
+clearly bounded, synthesize the final answer directly. Do not add another planning,
+freshness-audit or summary round just to prepare it. Preserve necessary mechanisms,
+exceptions, citations and verification limits; fewer preparation steps must not
+mean weaker evidence or omitted questions. Host delivery and receipt requirements
+still apply, without repeating the completed investigation.
+
Suggest a knowledge update only with supporting evidence: identify the affected
page or gap, proposed change and bounded source scope. Check neighboring content
before proposing a new page. Only after user acceptance, hand the evidence and
diff --git a/plugins/context/repo-install/cursor/.cursor-plugin/plugin.json b/plugins/context/repo-install/cursor/.cursor-plugin/plugin.json
index 5a17a98b..3775b0c6 100644
--- a/plugins/context/repo-install/cursor/.cursor-plugin/plugin.json
+++ b/plugins/context/repo-install/cursor/.cursor-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "c4a",
"displayName": "C4A Context",
- "version": "0.7.29",
+ "version": "0.7.30",
"description": "Start or continue a project-local knowledge workspace through one graph-routed entry.",
"author": {
"name": "Context4AI",
diff --git a/plugins/context/repo-install/cursor/commands/c4a-context-inspect-search.md b/plugins/context/repo-install/cursor/commands/c4a-context-inspect-search.md
index 55b23598..b952e06c 100644
--- a/plugins/context/repo-install/cursor/commands/c4a-context-inspect-search.md
+++ b/plugins/context/repo-install/cursor/commands/c4a-context-inspect-search.md
@@ -27,9 +27,9 @@ registrations, snapshots, tasks, approvals or user checkouts.
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.
+- `repo-first` (default): search approved `knowledge/` in the configured knowledge
+ workspace first; trace authorized original sources only for material gaps.
+ Use an available package when approved knowledge is unavailable.
- `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
@@ -43,8 +43,10 @@ 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
+start with approved knowledge, not original-code checkout preparation. With
+readable `knowledge/`, do not probe `dist/`, build inventories or installed
+packages: distribution output is not a query prerequisite. An explicit request
+to investigate delivered content is an exception. 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
@@ -64,9 +66,11 @@ missing, use the host's configured, authorized package retrieval mechanism while
other reading continues. Only check or prepare tools needed for the next actual
operation; installation failure does not block independent local retrieval.
-For gaps or latest-content questions, also search approved knowledge when a workspace is available:
-use `knowledge/structure.yaml` and relevant `knowledge/` paths, trying business
-terms, symbols and synonyms, then read matching sections in context. Delivered
+Search relevant `knowledge/` paths using business terms, symbols and synonyms,
+then read matching sections in context; use `knowledge/structure.yaml` when
+navigation or associations are needed, not as an exhaustive preflight. In
+package-first or dual mode, approved knowledge can resolve gaps or freshness
+questions in delivered material. Delivered
content may lag approved knowledge; they are not independent corroboration.
Candidates and temporary reports are not approved pages. A search miss does not
prove a capability is absent. Do not build merely to answer a query; a separately
@@ -76,8 +80,11 @@ When package or approved knowledge leaves a gap, directly trace relevant sources
without asking whether to deepen the query. Use available document, code-search
or extraction tools within the authorized scope, recording source identity and
version. Prepare sources while continuing other reading.
-One failed source blocks only dependent claims. Answer when evidence is
-sufficient, without completing unnecessary preparation.
+One failed source blocks only dependent claims. If the read knowledge supports
+the requested conclusion, its conditions and scope, answer without restoring
+code or checking every associated source. Missing mechanisms, conflicting facts
+or unsupported current-behavior claims still require targeted investigation;
+an article title, search snippet or unread citation is not sufficient evidence.
## Trace and retrieve only relevant sources
@@ -88,18 +95,23 @@ registry is not a mandatory intermediate step. If the source identity or version
cannot be established, retain package-grounded findings and qualify attribution;
do not invent a repository or equate current source with the package's baseline.
-When a workspace and `context-build-inventory.json` are available, map a delivered page's
+Only when tracing a delivered page and a build inventory is already available, map its
`dist_path` through `approved_knowledge.files` to its `approved_path`, relative
-to the workspace's `knowledge/` root. Follow the approved page's associations in
-`knowledge/structure.yaml` and `sources/*/index.yaml`. Without a reliable mapping,
+to the workspace's `knowledge/` root. For directly read approved pages, skip this
+mapping entirely. Follow relevant associations in `knowledge/structure.yaml`
+and `sources/*/index.yaml` only when source tracing is needed. Without a reliable mapping,
continue package retrieval and follow explicit source references where available.
Do not guess originals from similar filenames or claim attribution without
checking the referenced material.
Use the repository and recorded commit identified by the package or workspace
as the source baseline.
-Reuse existing checkouts only after checking remote, commit, module coverage
-and local changes; do not reset them or change their sparse configuration.
+Before reusing a checkout for source reads, group checks of remote, commit,
+module coverage and local changes. Reuse those findings within this response
+instead of checking again before each search or file read. Recheck affected
+facts if the checkout/ref changes, sparse scope expands or there is evidence of
+concurrent edits; do not treat a previous response's checks as current. Do not
+reset user checkouts or change their sparse configuration.
Missing code goes into a reusable query-owned path such as
`.tmp/context-inspect////`, separate from user
checkouts and production-managed sources. Use safe, credential-free path
@@ -128,10 +140,24 @@ capture/recovery actions. Production recovery gates do not block this independen
inspection. Preserve unavailable-evidence gaps rather than changing production
state to get past them.
-Compare relevant baseline files with current code when accessible, including
-relevant local changes. Use actual diffs to assess impact; current code is not a
-substitute for the baseline. Mention a missing comparison only when it limits
-the answer. For documents, notes and sessions, read saved bodies and necessary
+Batch independent searches and related file reads once paths are known, such as
+the entrypoint, state update and controlling render logic for one mechanism.
+Read enough surrounding context and follow unresolved imports or calls; batching
+must not truncate decisive evidence or turn a partial read into a complete audit.
+Reuse already read evidence rather than rereading it to prepare each tool call.
+
+Let evidence sufficiency determine whether a version comparison is needed.
+When the available knowledge or identified baseline code resolves the question,
+answer without fetching the default branch, recovering a second checkout or
+reading history merely to confirm freshness. Compare narrowly when uncertainty,
+conflicting evidence, suspected changes or an explicit version-comparison request
+makes it useful. A question about current behavior requires judging whether the
+available evidence supports that claim, not automatically comparing every branch.
+Retain necessary source reads; do not equate a recorded baseline or branch HEAD
+with a verified live deployment. When comparing, use actual relevant diffs,
+including relevant local changes; current code is not a substitute for the baseline.
+Mention a missing comparison only when it limits the answer.
+For documents, notes and sessions, read saved bodies and necessary
attachments; fetch missing accessible material within scope. A summary is not a
full transcript, an unread link is not evidence, and current remote content does
not prove a historical snapshot.
@@ -164,13 +190,25 @@ limitation. Do not dump internal reasoning, runtime identifiers or routine
version comparisons. Explain only differences affecting the answer; hashes may
appear in source URLs without requiring a separate version audit in the prose.
-For website links, use `context-site-map.json` from the selected package or
-sibling website output. Match `pages[].package_path` or `approved_path`, and
+Collect citation targets after the relevant evidence is established and resolve
+them in one batch using the host's existing link resolver when available. Reuse
+known workspace, repository and site parameters; do not rediscover them per link.
+If later evidence adds targets, resolve only those missing from the results.
+Without a host resolver, use an already available `context-site-map.json` from
+the selected package or website output. Do not search for `dist/` merely to
+obtain links for readable approved knowledge. Match `pages[].package_path` or `approved_path`, and
resolve `site_path` against `site_url` without prepending `base` again. Cite only
matched pages, deduplicate links and do not invent anchors. If mapping is absent
or invalid, retain local citations. Do not build, publish or probe remote sites
just to format citations; a local map is not proof of the current online content.
+Once the requested questions are supported or genuinely unavailable evidence is
+clearly bounded, synthesize the final answer directly. Do not add another planning,
+freshness-audit or summary round just to prepare it. Preserve necessary mechanisms,
+exceptions, citations and verification limits; fewer preparation steps must not
+mean weaker evidence or omitted questions. Host delivery and receipt requirements
+still apply, without repeating the completed investigation.
+
Suggest a knowledge update only with supporting evidence: identify the affected
page or gap, proposed change and bounded source scope. Check neighboring content
before proposing a new page. Only after user acceptance, hand the evidence and
diff --git a/plugins/context/repo-install/cursor/skills/context-inspect-search/SKILL.md b/plugins/context/repo-install/cursor/skills/context-inspect-search/SKILL.md
index 5c777958..8d80bd49 100644
--- a/plugins/context/repo-install/cursor/skills/context-inspect-search/SKILL.md
+++ b/plugins/context/repo-install/cursor/skills/context-inspect-search/SKILL.md
@@ -28,9 +28,9 @@ registrations, snapshots, tasks, approvals or user checkouts.
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.
+- `repo-first` (default): search approved `knowledge/` in the configured knowledge
+ workspace first; trace authorized original sources only for material gaps.
+ Use an available package when approved knowledge is unavailable.
- `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
@@ -44,8 +44,10 @@ 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
+start with approved knowledge, not original-code checkout preparation. With
+readable `knowledge/`, do not probe `dist/`, build inventories or installed
+packages: distribution output is not a query prerequisite. An explicit request
+to investigate delivered content is an exception. 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
@@ -65,9 +67,11 @@ missing, use the host's configured, authorized package retrieval mechanism while
other reading continues. Only check or prepare tools needed for the next actual
operation; installation failure does not block independent local retrieval.
-For gaps or latest-content questions, also search approved knowledge when a workspace is available:
-use `knowledge/structure.yaml` and relevant `knowledge/` paths, trying business
-terms, symbols and synonyms, then read matching sections in context. Delivered
+Search relevant `knowledge/` paths using business terms, symbols and synonyms,
+then read matching sections in context; use `knowledge/structure.yaml` when
+navigation or associations are needed, not as an exhaustive preflight. In
+package-first or dual mode, approved knowledge can resolve gaps or freshness
+questions in delivered material. Delivered
content may lag approved knowledge; they are not independent corroboration.
Candidates and temporary reports are not approved pages. A search miss does not
prove a capability is absent. Do not build merely to answer a query; a separately
@@ -77,8 +81,11 @@ When package or approved knowledge leaves a gap, directly trace relevant sources
without asking whether to deepen the query. Use available document, code-search
or extraction tools within the authorized scope, recording source identity and
version. Prepare sources while continuing other reading.
-One failed source blocks only dependent claims. Answer when evidence is
-sufficient, without completing unnecessary preparation.
+One failed source blocks only dependent claims. If the read knowledge supports
+the requested conclusion, its conditions and scope, answer without restoring
+code or checking every associated source. Missing mechanisms, conflicting facts
+or unsupported current-behavior claims still require targeted investigation;
+an article title, search snippet or unread citation is not sufficient evidence.
## Trace and retrieve only relevant sources
@@ -89,18 +96,23 @@ registry is not a mandatory intermediate step. If the source identity or version
cannot be established, retain package-grounded findings and qualify attribution;
do not invent a repository or equate current source with the package's baseline.
-When a workspace and `context-build-inventory.json` are available, map a delivered page's
+Only when tracing a delivered page and a build inventory is already available, map its
`dist_path` through `approved_knowledge.files` to its `approved_path`, relative
-to the workspace's `knowledge/` root. Follow the approved page's associations in
-`knowledge/structure.yaml` and `sources/*/index.yaml`. Without a reliable mapping,
+to the workspace's `knowledge/` root. For directly read approved pages, skip this
+mapping entirely. Follow relevant associations in `knowledge/structure.yaml`
+and `sources/*/index.yaml` only when source tracing is needed. Without a reliable mapping,
continue package retrieval and follow explicit source references where available.
Do not guess originals from similar filenames or claim attribution without
checking the referenced material.
Use the repository and recorded commit identified by the package or workspace
as the source baseline.
-Reuse existing checkouts only after checking remote, commit, module coverage
-and local changes; do not reset them or change their sparse configuration.
+Before reusing a checkout for source reads, group checks of remote, commit,
+module coverage and local changes. Reuse those findings within this response
+instead of checking again before each search or file read. Recheck affected
+facts if the checkout/ref changes, sparse scope expands or there is evidence of
+concurrent edits; do not treat a previous response's checks as current. Do not
+reset user checkouts or change their sparse configuration.
Missing code goes into a reusable query-owned path such as
`.tmp/context-inspect////`, separate from user
checkouts and production-managed sources. Use safe, credential-free path
@@ -129,10 +141,24 @@ capture/recovery actions. Production recovery gates do not block this independen
inspection. Preserve unavailable-evidence gaps rather than changing production
state to get past them.
-Compare relevant baseline files with current code when accessible, including
-relevant local changes. Use actual diffs to assess impact; current code is not a
-substitute for the baseline. Mention a missing comparison only when it limits
-the answer. For documents, notes and sessions, read saved bodies and necessary
+Batch independent searches and related file reads once paths are known, such as
+the entrypoint, state update and controlling render logic for one mechanism.
+Read enough surrounding context and follow unresolved imports or calls; batching
+must not truncate decisive evidence or turn a partial read into a complete audit.
+Reuse already read evidence rather than rereading it to prepare each tool call.
+
+Let evidence sufficiency determine whether a version comparison is needed.
+When the available knowledge or identified baseline code resolves the question,
+answer without fetching the default branch, recovering a second checkout or
+reading history merely to confirm freshness. Compare narrowly when uncertainty,
+conflicting evidence, suspected changes or an explicit version-comparison request
+makes it useful. A question about current behavior requires judging whether the
+available evidence supports that claim, not automatically comparing every branch.
+Retain necessary source reads; do not equate a recorded baseline or branch HEAD
+with a verified live deployment. When comparing, use actual relevant diffs,
+including relevant local changes; current code is not a substitute for the baseline.
+Mention a missing comparison only when it limits the answer.
+For documents, notes and sessions, read saved bodies and necessary
attachments; fetch missing accessible material within scope. A summary is not a
full transcript, an unread link is not evidence, and current remote content does
not prove a historical snapshot.
@@ -165,13 +191,25 @@ limitation. Do not dump internal reasoning, runtime identifiers or routine
version comparisons. Explain only differences affecting the answer; hashes may
appear in source URLs without requiring a separate version audit in the prose.
-For website links, use `context-site-map.json` from the selected package or
-sibling website output. Match `pages[].package_path` or `approved_path`, and
+Collect citation targets after the relevant evidence is established and resolve
+them in one batch using the host's existing link resolver when available. Reuse
+known workspace, repository and site parameters; do not rediscover them per link.
+If later evidence adds targets, resolve only those missing from the results.
+Without a host resolver, use an already available `context-site-map.json` from
+the selected package or website output. Do not search for `dist/` merely to
+obtain links for readable approved knowledge. Match `pages[].package_path` or `approved_path`, and
resolve `site_path` against `site_url` without prepending `base` again. Cite only
matched pages, deduplicate links and do not invent anchors. If mapping is absent
or invalid, retain local citations. Do not build, publish or probe remote sites
just to format citations; a local map is not proof of the current online content.
+Once the requested questions are supported or genuinely unavailable evidence is
+clearly bounded, synthesize the final answer directly. Do not add another planning,
+freshness-audit or summary round just to prepare it. Preserve necessary mechanisms,
+exceptions, citations and verification limits; fewer preparation steps must not
+mean weaker evidence or omitted questions. Host delivery and receipt requirements
+still apply, without repeating the completed investigation.
+
Suggest a knowledge update only with supporting evidence: identify the affected
page or gap, proposed change and bounded source scope. Check neighboring content
before proposing a new page. Only after user acceptance, hand the evidence and
diff --git a/plugins/context/repo-install/skills/context-inspect-search/SKILL.md b/plugins/context/repo-install/skills/context-inspect-search/SKILL.md
index 5c777958..8d80bd49 100644
--- a/plugins/context/repo-install/skills/context-inspect-search/SKILL.md
+++ b/plugins/context/repo-install/skills/context-inspect-search/SKILL.md
@@ -28,9 +28,9 @@ registrations, snapshots, tasks, approvals or user checkouts.
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.
+- `repo-first` (default): search approved `knowledge/` in the configured knowledge
+ workspace first; trace authorized original sources only for material gaps.
+ Use an available package when approved knowledge is unavailable.
- `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
@@ -44,8 +44,10 @@ 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
+start with approved knowledge, not original-code checkout preparation. With
+readable `knowledge/`, do not probe `dist/`, build inventories or installed
+packages: distribution output is not a query prerequisite. An explicit request
+to investigate delivered content is an exception. 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
@@ -65,9 +67,11 @@ missing, use the host's configured, authorized package retrieval mechanism while
other reading continues. Only check or prepare tools needed for the next actual
operation; installation failure does not block independent local retrieval.
-For gaps or latest-content questions, also search approved knowledge when a workspace is available:
-use `knowledge/structure.yaml` and relevant `knowledge/` paths, trying business
-terms, symbols and synonyms, then read matching sections in context. Delivered
+Search relevant `knowledge/` paths using business terms, symbols and synonyms,
+then read matching sections in context; use `knowledge/structure.yaml` when
+navigation or associations are needed, not as an exhaustive preflight. In
+package-first or dual mode, approved knowledge can resolve gaps or freshness
+questions in delivered material. Delivered
content may lag approved knowledge; they are not independent corroboration.
Candidates and temporary reports are not approved pages. A search miss does not
prove a capability is absent. Do not build merely to answer a query; a separately
@@ -77,8 +81,11 @@ When package or approved knowledge leaves a gap, directly trace relevant sources
without asking whether to deepen the query. Use available document, code-search
or extraction tools within the authorized scope, recording source identity and
version. Prepare sources while continuing other reading.
-One failed source blocks only dependent claims. Answer when evidence is
-sufficient, without completing unnecessary preparation.
+One failed source blocks only dependent claims. If the read knowledge supports
+the requested conclusion, its conditions and scope, answer without restoring
+code or checking every associated source. Missing mechanisms, conflicting facts
+or unsupported current-behavior claims still require targeted investigation;
+an article title, search snippet or unread citation is not sufficient evidence.
## Trace and retrieve only relevant sources
@@ -89,18 +96,23 @@ registry is not a mandatory intermediate step. If the source identity or version
cannot be established, retain package-grounded findings and qualify attribution;
do not invent a repository or equate current source with the package's baseline.
-When a workspace and `context-build-inventory.json` are available, map a delivered page's
+Only when tracing a delivered page and a build inventory is already available, map its
`dist_path` through `approved_knowledge.files` to its `approved_path`, relative
-to the workspace's `knowledge/` root. Follow the approved page's associations in
-`knowledge/structure.yaml` and `sources/*/index.yaml`. Without a reliable mapping,
+to the workspace's `knowledge/` root. For directly read approved pages, skip this
+mapping entirely. Follow relevant associations in `knowledge/structure.yaml`
+and `sources/*/index.yaml` only when source tracing is needed. Without a reliable mapping,
continue package retrieval and follow explicit source references where available.
Do not guess originals from similar filenames or claim attribution without
checking the referenced material.
Use the repository and recorded commit identified by the package or workspace
as the source baseline.
-Reuse existing checkouts only after checking remote, commit, module coverage
-and local changes; do not reset them or change their sparse configuration.
+Before reusing a checkout for source reads, group checks of remote, commit,
+module coverage and local changes. Reuse those findings within this response
+instead of checking again before each search or file read. Recheck affected
+facts if the checkout/ref changes, sparse scope expands or there is evidence of
+concurrent edits; do not treat a previous response's checks as current. Do not
+reset user checkouts or change their sparse configuration.
Missing code goes into a reusable query-owned path such as
`.tmp/context-inspect////`, separate from user
checkouts and production-managed sources. Use safe, credential-free path
@@ -129,10 +141,24 @@ capture/recovery actions. Production recovery gates do not block this independen
inspection. Preserve unavailable-evidence gaps rather than changing production
state to get past them.
-Compare relevant baseline files with current code when accessible, including
-relevant local changes. Use actual diffs to assess impact; current code is not a
-substitute for the baseline. Mention a missing comparison only when it limits
-the answer. For documents, notes and sessions, read saved bodies and necessary
+Batch independent searches and related file reads once paths are known, such as
+the entrypoint, state update and controlling render logic for one mechanism.
+Read enough surrounding context and follow unresolved imports or calls; batching
+must not truncate decisive evidence or turn a partial read into a complete audit.
+Reuse already read evidence rather than rereading it to prepare each tool call.
+
+Let evidence sufficiency determine whether a version comparison is needed.
+When the available knowledge or identified baseline code resolves the question,
+answer without fetching the default branch, recovering a second checkout or
+reading history merely to confirm freshness. Compare narrowly when uncertainty,
+conflicting evidence, suspected changes or an explicit version-comparison request
+makes it useful. A question about current behavior requires judging whether the
+available evidence supports that claim, not automatically comparing every branch.
+Retain necessary source reads; do not equate a recorded baseline or branch HEAD
+with a verified live deployment. When comparing, use actual relevant diffs,
+including relevant local changes; current code is not a substitute for the baseline.
+Mention a missing comparison only when it limits the answer.
+For documents, notes and sessions, read saved bodies and necessary
attachments; fetch missing accessible material within scope. A summary is not a
full transcript, an unread link is not evidence, and current remote content does
not prove a historical snapshot.
@@ -165,13 +191,25 @@ limitation. Do not dump internal reasoning, runtime identifiers or routine
version comparisons. Explain only differences affecting the answer; hashes may
appear in source URLs without requiring a separate version audit in the prose.
-For website links, use `context-site-map.json` from the selected package or
-sibling website output. Match `pages[].package_path` or `approved_path`, and
+Collect citation targets after the relevant evidence is established and resolve
+them in one batch using the host's existing link resolver when available. Reuse
+known workspace, repository and site parameters; do not rediscover them per link.
+If later evidence adds targets, resolve only those missing from the results.
+Without a host resolver, use an already available `context-site-map.json` from
+the selected package or website output. Do not search for `dist/` merely to
+obtain links for readable approved knowledge. Match `pages[].package_path` or `approved_path`, and
resolve `site_path` against `site_url` without prepending `base` again. Cite only
matched pages, deduplicate links and do not invent anchors. If mapping is absent
or invalid, retain local citations. Do not build, publish or probe remote sites
just to format citations; a local map is not proof of the current online content.
+Once the requested questions are supported or genuinely unavailable evidence is
+clearly bounded, synthesize the final answer directly. Do not add another planning,
+freshness-audit or summary round just to prepare it. Preserve necessary mechanisms,
+exceptions, citations and verification limits; fewer preparation steps must not
+mean weaker evidence or omitted questions. Host delivery and receipt requirements
+still apply, without repeating the completed investigation.
+
Suggest a knowledge update only with supporting evidence: identify the affected
page or gap, proposed change and bounded source scope. Check neighboring content
before proposing a new page. Only after user acceptance, hand the evidence and
diff --git a/plugins/context/skills/context-inspect-search/SKILL.md b/plugins/context/skills/context-inspect-search/SKILL.md
index 5c777958..8d80bd49 100644
--- a/plugins/context/skills/context-inspect-search/SKILL.md
+++ b/plugins/context/skills/context-inspect-search/SKILL.md
@@ -28,9 +28,9 @@ registrations, snapshots, tasks, approvals or user checkouts.
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.
+- `repo-first` (default): search approved `knowledge/` in the configured knowledge
+ workspace first; trace authorized original sources only for material gaps.
+ Use an available package when approved knowledge is unavailable.
- `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
@@ -44,8 +44,10 @@ 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
+start with approved knowledge, not original-code checkout preparation. With
+readable `knowledge/`, do not probe `dist/`, build inventories or installed
+packages: distribution output is not a query prerequisite. An explicit request
+to investigate delivered content is an exception. 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
@@ -65,9 +67,11 @@ missing, use the host's configured, authorized package retrieval mechanism while
other reading continues. Only check or prepare tools needed for the next actual
operation; installation failure does not block independent local retrieval.
-For gaps or latest-content questions, also search approved knowledge when a workspace is available:
-use `knowledge/structure.yaml` and relevant `knowledge/` paths, trying business
-terms, symbols and synonyms, then read matching sections in context. Delivered
+Search relevant `knowledge/` paths using business terms, symbols and synonyms,
+then read matching sections in context; use `knowledge/structure.yaml` when
+navigation or associations are needed, not as an exhaustive preflight. In
+package-first or dual mode, approved knowledge can resolve gaps or freshness
+questions in delivered material. Delivered
content may lag approved knowledge; they are not independent corroboration.
Candidates and temporary reports are not approved pages. A search miss does not
prove a capability is absent. Do not build merely to answer a query; a separately
@@ -77,8 +81,11 @@ When package or approved knowledge leaves a gap, directly trace relevant sources
without asking whether to deepen the query. Use available document, code-search
or extraction tools within the authorized scope, recording source identity and
version. Prepare sources while continuing other reading.
-One failed source blocks only dependent claims. Answer when evidence is
-sufficient, without completing unnecessary preparation.
+One failed source blocks only dependent claims. If the read knowledge supports
+the requested conclusion, its conditions and scope, answer without restoring
+code or checking every associated source. Missing mechanisms, conflicting facts
+or unsupported current-behavior claims still require targeted investigation;
+an article title, search snippet or unread citation is not sufficient evidence.
## Trace and retrieve only relevant sources
@@ -89,18 +96,23 @@ registry is not a mandatory intermediate step. If the source identity or version
cannot be established, retain package-grounded findings and qualify attribution;
do not invent a repository or equate current source with the package's baseline.
-When a workspace and `context-build-inventory.json` are available, map a delivered page's
+Only when tracing a delivered page and a build inventory is already available, map its
`dist_path` through `approved_knowledge.files` to its `approved_path`, relative
-to the workspace's `knowledge/` root. Follow the approved page's associations in
-`knowledge/structure.yaml` and `sources/*/index.yaml`. Without a reliable mapping,
+to the workspace's `knowledge/` root. For directly read approved pages, skip this
+mapping entirely. Follow relevant associations in `knowledge/structure.yaml`
+and `sources/*/index.yaml` only when source tracing is needed. Without a reliable mapping,
continue package retrieval and follow explicit source references where available.
Do not guess originals from similar filenames or claim attribution without
checking the referenced material.
Use the repository and recorded commit identified by the package or workspace
as the source baseline.
-Reuse existing checkouts only after checking remote, commit, module coverage
-and local changes; do not reset them or change their sparse configuration.
+Before reusing a checkout for source reads, group checks of remote, commit,
+module coverage and local changes. Reuse those findings within this response
+instead of checking again before each search or file read. Recheck affected
+facts if the checkout/ref changes, sparse scope expands or there is evidence of
+concurrent edits; do not treat a previous response's checks as current. Do not
+reset user checkouts or change their sparse configuration.
Missing code goes into a reusable query-owned path such as
`.tmp/context-inspect////`, separate from user
checkouts and production-managed sources. Use safe, credential-free path
@@ -129,10 +141,24 @@ capture/recovery actions. Production recovery gates do not block this independen
inspection. Preserve unavailable-evidence gaps rather than changing production
state to get past them.
-Compare relevant baseline files with current code when accessible, including
-relevant local changes. Use actual diffs to assess impact; current code is not a
-substitute for the baseline. Mention a missing comparison only when it limits
-the answer. For documents, notes and sessions, read saved bodies and necessary
+Batch independent searches and related file reads once paths are known, such as
+the entrypoint, state update and controlling render logic for one mechanism.
+Read enough surrounding context and follow unresolved imports or calls; batching
+must not truncate decisive evidence or turn a partial read into a complete audit.
+Reuse already read evidence rather than rereading it to prepare each tool call.
+
+Let evidence sufficiency determine whether a version comparison is needed.
+When the available knowledge or identified baseline code resolves the question,
+answer without fetching the default branch, recovering a second checkout or
+reading history merely to confirm freshness. Compare narrowly when uncertainty,
+conflicting evidence, suspected changes or an explicit version-comparison request
+makes it useful. A question about current behavior requires judging whether the
+available evidence supports that claim, not automatically comparing every branch.
+Retain necessary source reads; do not equate a recorded baseline or branch HEAD
+with a verified live deployment. When comparing, use actual relevant diffs,
+including relevant local changes; current code is not a substitute for the baseline.
+Mention a missing comparison only when it limits the answer.
+For documents, notes and sessions, read saved bodies and necessary
attachments; fetch missing accessible material within scope. A summary is not a
full transcript, an unread link is not evidence, and current remote content does
not prove a historical snapshot.
@@ -165,13 +191,25 @@ limitation. Do not dump internal reasoning, runtime identifiers or routine
version comparisons. Explain only differences affecting the answer; hashes may
appear in source URLs without requiring a separate version audit in the prose.
-For website links, use `context-site-map.json` from the selected package or
-sibling website output. Match `pages[].package_path` or `approved_path`, and
+Collect citation targets after the relevant evidence is established and resolve
+them in one batch using the host's existing link resolver when available. Reuse
+known workspace, repository and site parameters; do not rediscover them per link.
+If later evidence adds targets, resolve only those missing from the results.
+Without a host resolver, use an already available `context-site-map.json` from
+the selected package or website output. Do not search for `dist/` merely to
+obtain links for readable approved knowledge. Match `pages[].package_path` or `approved_path`, and
resolve `site_path` against `site_url` without prepending `base` again. Cite only
matched pages, deduplicate links and do not invent anchors. If mapping is absent
or invalid, retain local citations. Do not build, publish or probe remote sites
just to format citations; a local map is not proof of the current online content.
+Once the requested questions are supported or genuinely unavailable evidence is
+clearly bounded, synthesize the final answer directly. Do not add another planning,
+freshness-audit or summary round just to prepare it. Preserve necessary mechanisms,
+exceptions, citations and verification limits; fewer preparation steps must not
+mean weaker evidence or omitted questions. Host delivery and receipt requirements
+still apply, without repeating the completed investigation.
+
Suggest a knowledge update only with supporting evidence: identify the affected
page or gap, proposed change and bounded source scope. Check neighboring content
before proposing a new page. Only after user acceptance, hand the evidence and