@c4a/context 0.6.1-beta.6 → 0.6.2

package/docs/README.md

@@ -21,11 +21,12 @@ general reference; do not preload the whole manual set.
 - [Package Templates](./reference/package-templates.md) — `kbPackage`, `llmsPackage`, template variables, and examples.
 - [Template Variables](./reference/template-variables.md) — Handlebars variables, loops, comments, and default knowledge inventories.
 
-Approved Markdown and kb package OKF output follow the C4A OKF Profile:
-OKF fields and C4A extension fields live at the top level. Do not nest
-`sources`, `visibility`, or `code_symbols` under `context`, and do not add
-frontmatter `source_refs`. Section provenance lives in `context:section`
-source_ref span comments. The kb package root may contain agent files; the
+Approved Markdown follows the complete Context production profile. Package
+knowledge pages use a smaller consumer projection containing only reader-facing
+metadata and content. Node identity, provenance, section evidence, review
+fingerprints, symbol lists, generated-child records, and relationships remain in
+the production workspace or `context-build-inventory.json`. The inventory maps
+each distributed path back to its approved knowledge path. The kb package root may contain agent files; the
 OKF-compatible surface is its selected `wikis/`, `guides/`, `rules/`, and
 `feats/` subtrees.
 

package/docs/guides/package-outputs.md

@@ -78,7 +78,11 @@ carries the structure-first query discipline: start from OKF directory indexes,
 inspect page `sources` / `context:section` source_ref metadata, cite
 page/section evidence, and report explicit gaps when the package does not cover
 a requested fact. It does not treat direct grep over bundled OKF root
-directories as the primary discovery path. Its final template-author section
+directories as the primary discovery path. When indexes do not narrow the
+scope, or a candidate page is too large to read directly, its bundled
+`scripts/search.mjs` provides deterministic BM25 ranking over mechanically
+bounded Markdown chunks. Search results are leads; page bodies and typed edge
+records remain the evidence. Its final template-author section
 requires package authors to replace or edit the generic routing when the
 package needs project-specific terminology, entry points, known limits, or
 task workflows. Authors may explicitly accept the generic default when it is
@@ -96,10 +100,12 @@ as `wikis/`, `guides/`, `rules/`, or `feats/`; when selected, `context build`
 copies them into the package and generates root-aware directory indexes for them
 as needed. Selected OKF roots always have an index; smaller child directories
 are folded into their nearest generated ancestor index by default. These roots
-contain Markdown with OKF fields and C4A extension fields at the top level, plus
-`context:section` source_ref span comments. C4A extension fields such as `sources`,
-`visibility`, and `code_symbols` are not nested under `context`, and page
-frontmatter does not contain `source_refs`. The package root is an agent
+contain consumer-oriented Markdown with reader-facing frontmatter and no Context
+lifecycle comments. Node identity, source metadata, code symbol lists,
+relationship records, generated-child records, and candidate fingerprints are
+kept out of each page. `context-build-inventory.json` maps distributed paths to
+approved knowledge paths and exposes package-visible structure; exact Section
+evidence remains in the mapped `knowledge/` page. The package root is an agent
 package; the OKF-compatible interchange surface is the selected OKF root
 subtrees under `dist/<package-name>/`. The required template entry and final
 output path are both `wikis/index.md`.

package/docs/reference/package-templates.md

@@ -151,7 +151,9 @@ src/package-templates/
 │   │   └── index.md
 │   └── skills/
 │       └── knowledge-query/
-│           └── SKILL.md
+│           ├── SKILL.md
+│           └── scripts/
+│               └── search.mjs
 └── llms/
     └── llms.txt
 ```
@@ -175,6 +177,10 @@ The default kb template includes:
   default entry OKF root is `wikis/`; packages that select additional internal
   collections expose
   `guides/`, `rules/`, or `feats/` indexes when those roots are selected.
+- `skills/knowledge-query/scripts/search.mjs`, a dependency-free BM25 fallback
+  for exact terms, mixed keyword queries, and large Markdown indexes. It chunks
+  mechanically, returns inspectable paths and line ranges, and never replaces
+  source-backed relationship evidence.
 - `wikis/index.md`, the editable OKF bundle entry page for the generated
   `dist/<package-name>/wikis/` directory.
 
@@ -231,14 +237,15 @@ explicitly accept the unchanged default through the package-template Review
 Route. Do not add a package-name Skill by default; add one only when the user
 wants project-specific behavior beyond knowledge lookup.
 
-## C4A OKF Profile
+## Context OKF Profiles
 
-Approved Markdown and kb package OKF output are an OKF superset:
+Approved Markdown under `knowledge/` is the production source of truth:
 
 - top-level YAML frontmatter uses OKF fields such as `type`, `title`,
   `description`, `tags`, `timestamp`, and `resource`;
-- C4A extension metadata such as `sources`, `visibility`, and `code_symbols`
-  also lives at the top level;
+- Context production metadata such as `sources`, `node_type`, `visibility`,
+  `code_symbols`, relationship records, and `candidate_fingerprint` also lives
+  at the top level;
 - do not nest C4A extension metadata under `context`; fields such as
   `context.sources` and `context.code_symbols` are not part of the 0.6 profile;
 - section provenance lives in `<!-- context:section ... source_ref="..." -->`
@@ -247,6 +254,15 @@ Approved Markdown and kb package OKF output are an OKF superset:
   section source refs when needed;
 - do not add `context` or `schema` fields.
 
+Package knowledge pages under `dist/<package-name>/` use a consumer projection.
+They retain reader-facing fields such as `title`, `type`, `description`, `tags`,
+`timestamp`, and custom non-lifecycle fields. Node identity, `resource`,
+`sources`, Section evidence comments, and build-only fields are omitted from the
+page. `context-build-inventory.json` records the distributed path, approved
+knowledge path, node identity, source summary, and package-visible structure.
+Maintainers return to the mapped `knowledge/` page for exact `sources` and
+`source_ref` attribution. `knowledge/` is never rewritten by this projection.
+
 Accepted section `source_ref` forms:
 
 ```text
@@ -256,7 +272,7 @@ src-N#span:<heading-hint> L<start>-<end>@<span-hash>
 
 The code symbol form includes the source-relative file so same-name symbols in
 different files resolve to one exact symbol-index row. Consumers should still
-treat the complete `source_ref` as opaque. Codegraph pages keep
+treat the complete `source_ref` as opaque. Production codegraph pages keep
 `candidate_fingerprint` at the top level and do not duplicate this evidence in
 `code_origin`.
 
@@ -274,7 +290,7 @@ The OKF-compatible surface is the selected `wikis/`, `guides/`, `rules/`, and
 
 1. Selects approved Markdown from `knowledge/`.
 2. Renders all files from `template.path`.
-3. Copies selected approved Markdown into the package output.
+3. Projects selected approved Markdown into consumer-oriented package pages.
 4. For `llmsPackage`, appends selected knowledge to `llms.txt` when the template
    does not already use `{{knowledge}}` or `{{approvedKnowledge}}`.
 5. Writes deterministic package inventory such as
@@ -282,7 +298,9 @@ The OKF-compatible surface is the selected `wikis/`, `guides/`, `rules/`, and
 6. Writes output under `dist/<package-name>/`.
 
 `context-build-inventory.json` records what was selected and why. Each selected
-file includes `selected_by` entries such as `{ "kind": "collection" }`,
+file includes `selected_by` entries such as `{ "kind": "collection" }` and a
+`production_metadata` object for selected page-level production fields. Child
+and relationship records use the inventory's canonical structure projection,
 `{ "kind": "okf_root" }`, `{ "kind": "include" }`, or
 `{ "kind": "default" }`. The inventory also exposes package-visible typed
 edges under `structure.edge_records`; these records are filtered to edges whose

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c4a/context",
-  "version": "0.6.1-beta.6",
+  "version": "0.6.2",
   "type": "module",
   "description": "Context SDK — project-local configuration and workspace primitives",
   "license": "MIT",

package/templates/package-templates/kb/skills/knowledge-query/SKILL.md

@@ -56,7 +56,7 @@ Use each opened page or package artifact as an evidence card:
 | Evidence | Valid use |
 |---|---|
 | Page path | Page identity and citation handle. |
-| Frontmatter title, description, node type, and tags | Navigation and scope selection only. |
+| Frontmatter title, description, stable node identity, and tags | Navigation and scope selection only. |
 | `context:section` id, kind, and `source_ref` | Section identity, citation, and source boundary. |
 | Reader-visible section body | Primary support for factual claims. |
 | `context-build-inventory.json` edge records | Typed relationship evidence. |
@@ -68,11 +68,26 @@ and do not expand beyond its visible content.
 
 ## Search Fallback
 
-Use text search only when indexes and page structure do not identify a useful
-scope. Search exact names, aliases, API names, configuration keys, flags,
-versions, or error strings from the request. Treat a hit as a lead: open its
-page and section before answering. Search cannot replace typed edge evidence
-for relationship claims.
+Search only when indexes and page structure do not identify a useful scope, or
+when a candidate page is too large to read in full. Use `rg` for an exact name,
+API, configuration key, path, or error string. For multiple terms, Chinese
+phrases, or several large indexes, run the bundled
+[`scripts/search.mjs`](scripts/search.mjs) BM25 ranker:
+
+```bash
+node <current knowledge-query Skill directory>/scripts/search.mjs --query '<terms>' --limit 8
+```
+
+The script locates `{{packageName}}` from a raw package or TTKB installation.
+If discovery is ambiguous, add `--root <package directory containing
+context-build-inventory.json>`. It chunks Markdown mechanically by headings and
+bounded line ranges, then returns paths, line ranges, headings, and previews; it
+does not interpret meaning.
+
+Treat every hit as a lead and open its page and section before answering. For
+relationship or impact claims, use typed edges from
+`context-build-inventory.json`; BM25 scores and text co-occurrence are not
+relationship evidence.
 
 ## Citations And Gaps
 

package/templates/package-templates/kb/skills/knowledge-query/scripts/search.mjs

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PACKAGE_NAME = "{{packageName}}";
+const STANDARD_ROOTS = ["wikis", "guides", "rules", "feats"];
+const MAX_CHUNK_LINES = 80;
+const CHUNK_OVERLAP = 5;
+
+function usage() {
+  return [
+    "Search an approved knowledge package with deterministic BM25 ranking.",
+    "",
+    "Usage:",
+    "  node search.mjs --query <text> [--root <package-root>] [--limit <n>] [--json]",
+    "  node search.mjs <text> [--root <package-root>] [--limit <n>] [--json]",
+    "",
+    "The package root is detected from context-build-inventory.json when possible.",
+  ].join("\n");
+}
+
+function parseArgs(argv) {
+  const positional = [];
+  const options = { root: undefined, query: undefined, limit: 8, json: false };
+  for (let index = 0; index < argv.length; index++) {
+    const arg = argv[index];
+    if (arg === "--help" || arg === "-h") return { help: true };
+    if (arg === "--json") {
+      options.json = true;
+      continue;
+    }
+    if (arg === "--root" || arg === "--query" || arg === "--limit") {
+      const value = argv[++index];
+      if (value === undefined) throw new Error(`missing value for ${arg}`);
+      if (arg === "--root") options.root = value;
+      else if (arg === "--query") options.query = value;
+      else options.limit = Number(value);
+      continue;
+    }
+    positional.push(arg);
+  }
+  if (!Number.isInteger(options.limit) || options.limit < 1 || options.limit > 50) {
+    throw new Error("--limit must be an integer between 1 and 50");
+  }
+  options.query ??= positional.join(" ");
+  if (options.query.trim().length === 0) throw new Error("query must not be empty");
+  return options;
+}
+
+function isPackageRoot(directory) {
+  return existsSync(join(directory, "context-build-inventory.json"));
+}
+
+function ancestorPackageRoot(start) {
+  let current = resolve(start);
+  while (true) {
+    if (isPackageRoot(current)) return current;
+    const parent = dirname(current);
+    if (parent === current) return undefined;
+    current = parent;
+  }
+}
+
+function findInventories(directory, depth = 0) {
+  if (!existsSync(directory) || depth > 5) return [];
+  const inventory = join(directory, "context-build-inventory.json");
+  if (existsSync(inventory)) return [inventory];
+  const matches = [];
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    matches.push(...findInventories(join(directory, entry.name), depth + 1));
+  }
+  return matches;
+}
+
+function inventoryPackageName(inventoryPath) {
+  try {
+    return JSON.parse(readFileSync(inventoryPath, "utf8"))?.package?.name;
+  } catch {
+    return undefined;
+  }
+}
+
+function resolvePackageRoot(explicitRoot) {
+  if (explicitRoot !== undefined) {
+    const root = resolve(explicitRoot);
+    if (!isPackageRoot(root)) throw new Error(`package root has no context-build-inventory.json: ${root}`);
+    return root;
+  }
+  const scriptRoot = ancestorPackageRoot(dirname(fileURLToPath(import.meta.url)));
+  if (scriptRoot !== undefined) return scriptRoot;
+  const cwdRoot = ancestorPackageRoot(process.cwd());
+  if (cwdRoot !== undefined) return cwdRoot;
+  const inventories = findInventories(join(process.cwd(), ".ttkb", "packages"));
+  const matching = inventories.filter((path) => inventoryPackageName(path) === PACKAGE_NAME);
+  if (matching.length === 1) return dirname(matching[0]);
+  if (matching.length > 1) {
+    throw new Error(`multiple installed packages named ${PACKAGE_NAME}; pass --root explicitly`);
+  }
+  throw new Error("cannot locate the knowledge package; pass --root <package-root>");
+}
+
+function knowledgeRoots(packageRoot) {
+  const inventoryPath = join(packageRoot, "context-build-inventory.json");
+  let declared = [];
+  try {
+    const inventory = JSON.parse(readFileSync(inventoryPath, "utf8"));
+    declared = Object.values(inventory?.package?.distribution?.roots ?? {})
+      .filter((value) => typeof value === "string");
+  } catch {
+    declared = [];
+  }
+  return [...new Set([...declared, ...STANDARD_ROOTS])]
+    .map((root) => join(packageRoot, root))
+    .filter((root) => existsSync(root) && statSync(root).isDirectory());
+}
+
+function markdownFiles(directory) {
+  const files = [];
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    const path = join(directory, entry.name);
+    if (entry.isDirectory()) files.push(...markdownFiles(path));
+    else if (entry.isFile() && entry.name.endsWith(".md")) files.push(path);
+  }
+  return files;
+}
+
+function headingChunks(content) {
+  const lines = content.split(/\r?\n/u);
+  const starts = [];
+  for (let index = 0; index < lines.length; index++) {
+    if (/^#{1,6}\s+\S/u.test(lines[index] ?? "")) starts.push(index);
+  }
+  if (starts.length === 0) starts.push(0);
+  const chunks = [];
+  for (let headingIndex = 0; headingIndex < starts.length; headingIndex++) {
+    const start = starts[headingIndex] ?? 0;
+    const end = starts[headingIndex + 1] ?? lines.length;
+    const heading = (lines[start] ?? "").replace(/^#{1,6}\s+/u, "").trim() || "Document";
+    for (let offset = start; offset < end; offset += MAX_CHUNK_LINES - CHUNK_OVERLAP) {
+      const chunkEnd = Math.min(end, offset + MAX_CHUNK_LINES);
+      chunks.push({
+        heading,
+        startLine: offset + 1,
+        endLine: chunkEnd,
+        text: lines.slice(offset, chunkEnd).join("\n"),
+      });
+      if (chunkEnd === end) break;
+    }
+  }
+  return chunks;
+}
+
+function tokens(text) {
+  const normalized = text.toLocaleLowerCase();
+  const result = normalized.match(/[a-z0-9@._:/-]+|\p{Script=Han}+/gu) ?? [];
+  const expanded = [];
+  for (const token of result) {
+    expanded.push(token);
+    if (/^\p{Script=Han}+$/u.test(token)) {
+      for (let index = 0; index < token.length - 1; index++) expanded.push(token.slice(index, index + 2));
+    } else {
+      expanded.push(...token.split(/[^a-z0-9]+/u).filter((part) => part.length > 1));
+    }
+  }
+  return expanded.filter((token) => token.length > 0);
+}
+
+function termFrequency(items) {
+  const counts = new Map();
+  for (const item of items) counts.set(item, (counts.get(item) ?? 0) + 1);
+  return counts;
+}
+
+function preview(text, queryTerms, query) {
+  const lines = text.split(/\r?\n/u).map((line) => line.trim()).filter(Boolean);
+  const loweredQuery = query.toLocaleLowerCase().trim();
+  const matching = [...lines].sort((left, right) => {
+    const leftText = left.toLocaleLowerCase();
+    const rightText = right.toLocaleLowerCase();
+    const lineScore = (value) =>
+      (value.includes(loweredQuery) ? queryTerms.length + 2 : 0)
+      + queryTerms.filter((term) => value.includes(term)).length;
+    return lineScore(rightText) - lineScore(leftText);
+  })[0];
+  return (matching ?? lines[0] ?? "").replace(/\s+/gu, " ").slice(0, 240);
+}
+
+function search(packageRoot, query, limit) {
+  const documents = [];
+  for (const root of knowledgeRoots(packageRoot)) {
+    for (const file of markdownFiles(root)) {
+      const path = relative(packageRoot, file).split("\\").join("/");
+      const content = readFileSync(file, "utf8");
+      for (const chunk of headingChunks(content)) {
+        const weightedText = `${path} ${chunk.heading} ${chunk.heading} ${chunk.text}`;
+        const chunkTokens = tokens(weightedText);
+        documents.push({ ...chunk, path, tokens: chunkTokens, tf: termFrequency(chunkTokens) });
+      }
+    }
+  }
+  const queryTerms = [...new Set(tokens(query))];
+  const documentFrequency = new Map();
+  for (const term of queryTerms) {
+    documentFrequency.set(term, documents.filter((document) => document.tf.has(term)).length);
+  }
+  const averageLength = documents.reduce((sum, document) => sum + document.tokens.length, 0)
+    / Math.max(documents.length, 1);
+  const loweredQuery = query.toLocaleLowerCase().trim();
+  const scored = documents.map((document) => {
+    let score = 0;
+    for (const term of queryTerms) {
+      const frequency = document.tf.get(term) ?? 0;
+      if (frequency === 0) continue;
+      const matches = documentFrequency.get(term) ?? 0;
+      const idf = Math.log(1 + (documents.length - matches + 0.5) / (matches + 0.5));
+      const denominator = frequency + 1.2 * (0.25 + 0.75 * document.tokens.length / Math.max(averageLength, 1));
+      score += idf * frequency * 2.2 / denominator;
+    }
+    const searchable = `${document.path}\n${document.heading}\n${document.text}`.toLocaleLowerCase();
+    if (searchable.includes(loweredQuery)) score += 4;
+    if (`${document.path} ${document.heading}`.toLocaleLowerCase().includes(loweredQuery)) score += 2;
+    return { ...document, score };
+  }).filter((document) => document.score > 0);
+  scored.sort((left, right) =>
+    right.score - left.score
+    || left.path.localeCompare(right.path)
+    || left.startLine - right.startLine
+  );
+  return scored.slice(0, limit).map((document) => ({
+    score: Number(document.score.toFixed(4)),
+    path: document.path,
+    heading: document.heading,
+    start_line: document.startLine,
+    end_line: document.endLine,
+    preview: preview(document.text, queryTerms, query),
+  }));
+}
+
+try {
+  const options = parseArgs(process.argv.slice(2));
+  if (options.help) {
+    process.stdout.write(`${usage()}\n`);
+    process.exit(0);
+  }
+  const root = resolvePackageRoot(options.root);
+  const results = search(root, options.query, options.limit);
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify({ package: PACKAGE_NAME, root, query: options.query, results }, null, 2)}\n`);
+  } else if (results.length === 0) {
+    process.stdout.write(`No matching knowledge found for: ${options.query}\n`);
+  } else {
+    for (const [index, result] of results.entries()) {
+      process.stdout.write(`${index + 1}. ${result.path}:${result.start_line}-${result.end_line} [${result.score}] ${result.heading}\n`);
+      process.stdout.write(`   ${result.preview}\n`);
+    }
+  }
+} catch (error) {
+  process.stderr.write(`knowledge-search: ${error instanceof Error ? error.message : String(error)}\n`);
+  process.stderr.write(`${usage()}\n`);
+  process.exit(2);
+}

package/templates/package-templates.zh-CN/kb/skills/knowledge-query/SKILL.md

@@ -44,7 +44,7 @@ description: 查询 {{displayName}} 中经过审核、可追溯来源的知识
 | 证据 | 可支持的内容 |
 |---|---|
 | 页面路径 | 页面身份和引用位置。 |
-| frontmatter 的标题、描述、节点类型和标签 | 导航和范围选择。 |
+| frontmatter 的标题、描述、稳定节点标识和标签 | 导航和范围选择。 |
 | `context:section` 的 id、kind、`source_ref` | 章节身份、引用位置和来源边界。 |
 | 读者可见的章节正文 | 事实结论的主要依据。 |
 | `context-build-inventory.json` 的边记录 | 类型化关系证据。 |
@@ -54,7 +54,15 @@ description: 查询 {{displayName}} 中经过审核、可追溯来源的知识
 
 ## 搜索兜底
 
-只有索引和页面结构无法确定范围时才使用文本搜索。优先搜索请求中的精确名称、别名、API、配置键、参数、版本或错误字符串。搜索命中只是线索，回答前仍需打开对应页面和章节。文本搜索不能代替关系边证据。
+只有索引和页面结构无法确定范围，或候选页面过大不适合整页读取时才搜索。精确名称、API、配置键、路径或错误字符串可先用 `rg`；包含多个关键词、中文短语或多个大型索引时，执行本 Skill 随附的 [`scripts/search.mjs`](scripts/search.mjs) 做 BM25 排序：
+
+```bash
+node <当前 knowledge-query Skill 目录>/scripts/search.mjs --query '<关键词>' --limit 8
+```
+
+脚本会从原始包或 TTKB 安装目录定位 `{{packageName}}`；无法唯一定位时，增加 `--root <包含 context-build-inventory.json 的包目录>`。它按 Markdown 标题和固定行块机械切分，返回路径、行号、标题和短预览，不判断内容语义。
+
+搜索命中只是线索。回答前必须打开命中的页面和章节；关系或影响范围仍以 `context-build-inventory.json` 的类型化边为准，不能用 BM25 分数或文本共现替代关系证据。
 
 ## 引用与缺口
 

package/templates/package-templates.zh-CN/kb/skills/knowledge-query/scripts/search.mjs

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PACKAGE_NAME = "{{packageName}}";
+const STANDARD_ROOTS = ["wikis", "guides", "rules", "feats"];
+const MAX_CHUNK_LINES = 80;
+const CHUNK_OVERLAP = 5;
+
+function usage() {
+  return [
+    "Search an approved knowledge package with deterministic BM25 ranking.",
+    "",
+    "Usage:",
+    "  node search.mjs --query <text> [--root <package-root>] [--limit <n>] [--json]",
+    "  node search.mjs <text> [--root <package-root>] [--limit <n>] [--json]",
+    "",
+    "The package root is detected from context-build-inventory.json when possible.",
+  ].join("\n");
+}
+
+function parseArgs(argv) {
+  const positional = [];
+  const options = { root: undefined, query: undefined, limit: 8, json: false };
+  for (let index = 0; index < argv.length; index++) {
+    const arg = argv[index];
+    if (arg === "--help" || arg === "-h") return { help: true };
+    if (arg === "--json") {
+      options.json = true;
+      continue;
+    }
+    if (arg === "--root" || arg === "--query" || arg === "--limit") {
+      const value = argv[++index];
+      if (value === undefined) throw new Error(`missing value for ${arg}`);
+      if (arg === "--root") options.root = value;
+      else if (arg === "--query") options.query = value;
+      else options.limit = Number(value);
+      continue;
+    }
+    positional.push(arg);
+  }
+  if (!Number.isInteger(options.limit) || options.limit < 1 || options.limit > 50) {
+    throw new Error("--limit must be an integer between 1 and 50");
+  }
+  options.query ??= positional.join(" ");
+  if (options.query.trim().length === 0) throw new Error("query must not be empty");
+  return options;
+}
+
+function isPackageRoot(directory) {
+  return existsSync(join(directory, "context-build-inventory.json"));
+}
+
+function ancestorPackageRoot(start) {
+  let current = resolve(start);
+  while (true) {
+    if (isPackageRoot(current)) return current;
+    const parent = dirname(current);
+    if (parent === current) return undefined;
+    current = parent;
+  }
+}
+
+function findInventories(directory, depth = 0) {
+  if (!existsSync(directory) || depth > 5) return [];
+  const inventory = join(directory, "context-build-inventory.json");
+  if (existsSync(inventory)) return [inventory];
+  const matches = [];
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    matches.push(...findInventories(join(directory, entry.name), depth + 1));
+  }
+  return matches;
+}
+
+function inventoryPackageName(inventoryPath) {
+  try {
+    return JSON.parse(readFileSync(inventoryPath, "utf8"))?.package?.name;
+  } catch {
+    return undefined;
+  }
+}
+
+function resolvePackageRoot(explicitRoot) {
+  if (explicitRoot !== undefined) {
+    const root = resolve(explicitRoot);
+    if (!isPackageRoot(root)) throw new Error(`package root has no context-build-inventory.json: ${root}`);
+    return root;
+  }
+  const scriptRoot = ancestorPackageRoot(dirname(fileURLToPath(import.meta.url)));
+  if (scriptRoot !== undefined) return scriptRoot;
+  const cwdRoot = ancestorPackageRoot(process.cwd());
+  if (cwdRoot !== undefined) return cwdRoot;
+  const inventories = findInventories(join(process.cwd(), ".ttkb", "packages"));
+  const matching = inventories.filter((path) => inventoryPackageName(path) === PACKAGE_NAME);
+  if (matching.length === 1) return dirname(matching[0]);
+  if (matching.length > 1) {
+    throw new Error(`multiple installed packages named ${PACKAGE_NAME}; pass --root explicitly`);
+  }
+  throw new Error("cannot locate the knowledge package; pass --root <package-root>");
+}
+
+function knowledgeRoots(packageRoot) {
+  const inventoryPath = join(packageRoot, "context-build-inventory.json");
+  let declared = [];
+  try {
+    const inventory = JSON.parse(readFileSync(inventoryPath, "utf8"));
+    declared = Object.values(inventory?.package?.distribution?.roots ?? {})
+      .filter((value) => typeof value === "string");
+  } catch {
+    declared = [];
+  }
+  return [...new Set([...declared, ...STANDARD_ROOTS])]
+    .map((root) => join(packageRoot, root))
+    .filter((root) => existsSync(root) && statSync(root).isDirectory());
+}
+
+function markdownFiles(directory) {
+  const files = [];
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    const path = join(directory, entry.name);
+    if (entry.isDirectory()) files.push(...markdownFiles(path));
+    else if (entry.isFile() && entry.name.endsWith(".md")) files.push(path);
+  }
+  return files;
+}
+
+function headingChunks(content) {
+  const lines = content.split(/\r?\n/u);
+  const starts = [];
+  for (let index = 0; index < lines.length; index++) {
+    if (/^#{1,6}\s+\S/u.test(lines[index] ?? "")) starts.push(index);
+  }
+  if (starts.length === 0) starts.push(0);
+  const chunks = [];
+  for (let headingIndex = 0; headingIndex < starts.length; headingIndex++) {
+    const start = starts[headingIndex] ?? 0;
+    const end = starts[headingIndex + 1] ?? lines.length;
+    const heading = (lines[start] ?? "").replace(/^#{1,6}\s+/u, "").trim() || "Document";
+    for (let offset = start; offset < end; offset += MAX_CHUNK_LINES - CHUNK_OVERLAP) {
+      const chunkEnd = Math.min(end, offset + MAX_CHUNK_LINES);
+      chunks.push({
+        heading,
+        startLine: offset + 1,
+        endLine: chunkEnd,
+        text: lines.slice(offset, chunkEnd).join("\n"),
+      });
+      if (chunkEnd === end) break;
+    }
+  }
+  return chunks;
+}
+
+function tokens(text) {
+  const normalized = text.toLocaleLowerCase();
+  const result = normalized.match(/[a-z0-9@._:/-]+|\p{Script=Han}+/gu) ?? [];
+  const expanded = [];
+  for (const token of result) {
+    expanded.push(token);
+    if (/^\p{Script=Han}+$/u.test(token)) {
+      for (let index = 0; index < token.length - 1; index++) expanded.push(token.slice(index, index + 2));
+    } else {
+      expanded.push(...token.split(/[^a-z0-9]+/u).filter((part) => part.length > 1));
+    }
+  }
+  return expanded.filter((token) => token.length > 0);
+}
+
+function termFrequency(items) {
+  const counts = new Map();
+  for (const item of items) counts.set(item, (counts.get(item) ?? 0) + 1);
+  return counts;
+}
+
+function preview(text, queryTerms, query) {
+  const lines = text.split(/\r?\n/u).map((line) => line.trim()).filter(Boolean);
+  const loweredQuery = query.toLocaleLowerCase().trim();
+  const matching = [...lines].sort((left, right) => {
+    const leftText = left.toLocaleLowerCase();
+    const rightText = right.toLocaleLowerCase();
+    const lineScore = (value) =>
+      (value.includes(loweredQuery) ? queryTerms.length + 2 : 0)
+      + queryTerms.filter((term) => value.includes(term)).length;
+    return lineScore(rightText) - lineScore(leftText);
+  })[0];
+  return (matching ?? lines[0] ?? "").replace(/\s+/gu, " ").slice(0, 240);
+}
+
+function search(packageRoot, query, limit) {
+  const documents = [];
+  for (const root of knowledgeRoots(packageRoot)) {
+    for (const file of markdownFiles(root)) {
+      const path = relative(packageRoot, file).split("\\").join("/");
+      const content = readFileSync(file, "utf8");
+      for (const chunk of headingChunks(content)) {
+        const weightedText = `${path} ${chunk.heading} ${chunk.heading} ${chunk.text}`;
+        const chunkTokens = tokens(weightedText);
+        documents.push({ ...chunk, path, tokens: chunkTokens, tf: termFrequency(chunkTokens) });
+      }
+    }
+  }
+  const queryTerms = [...new Set(tokens(query))];
+  const documentFrequency = new Map();
+  for (const term of queryTerms) {
+    documentFrequency.set(term, documents.filter((document) => document.tf.has(term)).length);
+  }
+  const averageLength = documents.reduce((sum, document) => sum + document.tokens.length, 0)
+    / Math.max(documents.length, 1);
+  const loweredQuery = query.toLocaleLowerCase().trim();
+  const scored = documents.map((document) => {
+    let score = 0;
+    for (const term of queryTerms) {
+      const frequency = document.tf.get(term) ?? 0;
+      if (frequency === 0) continue;
+      const matches = documentFrequency.get(term) ?? 0;
+      const idf = Math.log(1 + (documents.length - matches + 0.5) / (matches + 0.5));
+      const denominator = frequency + 1.2 * (0.25 + 0.75 * document.tokens.length / Math.max(averageLength, 1));
+      score += idf * frequency * 2.2 / denominator;
+    }
+    const searchable = `${document.path}\n${document.heading}\n${document.text}`.toLocaleLowerCase();
+    if (searchable.includes(loweredQuery)) score += 4;
+    if (`${document.path} ${document.heading}`.toLocaleLowerCase().includes(loweredQuery)) score += 2;
+    return { ...document, score };
+  }).filter((document) => document.score > 0);
+  scored.sort((left, right) =>
+    right.score - left.score
+    || left.path.localeCompare(right.path)
+    || left.startLine - right.startLine
+  );
+  return scored.slice(0, limit).map((document) => ({
+    score: Number(document.score.toFixed(4)),
+    path: document.path,
+    heading: document.heading,
+    start_line: document.startLine,
+    end_line: document.endLine,
+    preview: preview(document.text, queryTerms, query),
+  }));
+}
+
+try {
+  const options = parseArgs(process.argv.slice(2));
+  if (options.help) {
+    process.stdout.write(`${usage()}\n`);
+    process.exit(0);
+  }
+  const root = resolvePackageRoot(options.root);
+  const results = search(root, options.query, options.limit);
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify({ package: PACKAGE_NAME, root, query: options.query, results }, null, 2)}\n`);
+  } else if (results.length === 0) {
+    process.stdout.write(`No matching knowledge found for: ${options.query}\n`);
+  } else {
+    for (const [index, result] of results.entries()) {
+      process.stdout.write(`${index + 1}. ${result.path}:${result.start_line}-${result.end_line} [${result.score}] ${result.heading}\n`);
+      process.stdout.write(`   ${result.preview}\n`);
+    }
+  }
+} catch (error) {
+  process.stderr.write(`knowledge-search: ${error instanceof Error ? error.message : String(error)}\n`);
+  process.stderr.write(`${usage()}\n`);
+  process.exit(2);
+}