@c4a/context 0.6.1 → 0.6.2

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

@@ -1,208 +1,132 @@
 ---
-name: knowledge-query
-description: Query the approved knowledge bundled with {{displayName}}.
+name: {{skillName}}
+description: Query the approved, source-linked knowledge bundled with {{displayName}}. Use for questions about included entities, APIs, behavior, procedures, constraints, decisions, troubleshooting, relationships, and package coverage.
 ---
 
 # Knowledge Query
 
-Use this starter skill when the user asks about APIs, components, usage patterns,
-migration details, relationships, or source-linked facts covered by this
-package. Customize it before build if the package needs project-specific
-routing, terminology, or task workflows.
+Answer from the approved knowledge bundled with this package. Navigate through
+its indexes before opening individual pages, and treat the visible section body
+as evidence rather than relying on memory or frontmatter summaries.
+
+## Query Procedure
+
+1. Classify the request as entity lookup, explanation, procedure, rule,
+   relationship, detail, or coverage audit.
+2. Open the most relevant root index, such as `{{wikisRoot}}/index.md`, then
+   follow its links to a likely page.
+3. Read only the sections needed for the question. Use frontmatter to select
+   scope, not to support factual claims.
+4. For relationship or impact questions, inspect
+   `context-build-inventory.json` `structure.edge_records` before reading the
+   endpoint pages.
+5. Answer only from reader-visible section content and source-backed edge
+   records. Cite the supporting page or section.
+6. If the package lacks evidence, report the gap and what was checked instead
+   of inferring from nearby content.
+
+## Package Roots
+
+| Root | Use |
+|---|---|
+| `{{wikisRoot}}/` | Structured entities and relationships from codegraph, business, and product knowledge. |
+| `{{guidesRoot}}/` | Architecture, procedures, FAQs, decisions, incidents, and troubleshooting. |
+| `{{rulesRoot}}/` | Standards, constraints, acceptance criteria, and test scenarios. |
+| `{{featsRoot}}/` | Feature knowledge when selected into the package. |
 
-## Non-negotiables
+Start from the root that matches the request. A missing root means that category
+was not selected into this package.
 
-- Structure first: start from OKF indexes and package structure before opening
-  individual pages.
-- Bundled knowledge pages are evidence cards. Do not answer from memory when a
-  copied page exists.
-- Cite every substantive claim with a page path and, when available, a
-  `context:section` id/source_ref.
-- Frontmatter summaries help route the query; reader-visible section content is
-  the evidence for factual answers.
-- If the package does not contain evidence for the requested fact, report a gap
-  instead of inferring from adjacent pages.
-- Do not treat direct grep over bundled OKF root directories as the primary
-  discovery path. Use it only as a fallback after indexes and page structure do
-  not identify a scope.
+## Route By Intent
 
-## Evidence Shape
+| Intent | First move |
+|---|---|
+| Vague topic or unknown name | Open the likely root index and choose a page from its grouping. |
+| Named entity, API, domain, or action | Open the matching page or nearest group index. Show candidates if names are ambiguous. |
+| Architecture, procedure, FAQ, decision, or incident | Start from `{{guidesRoot}}/index.md`. |
+| Standard, constraint, acceptance, or test question | Start from `{{rulesRoot}}/index.md`. |
+| Relationship or impact | Inspect typed edges, then read both endpoint pages. |
+| Detail inside a known page | Read the relevant `context:section` block. |
+| Coverage, gap, or inventory | Inspect the root indexes and `context-build-inventory.json`. |
 
-Treat each opened knowledge page or package artifact as an evidence card:
+## Evidence Contract
 
-| Evidence field | Use |
-|---|---|
-| Page path | Citation handle and package-local identity. |
-| Frontmatter `title` / `description` / `node_type` / `tags` | Navigation and scope selection; not enough by itself for factual claims. |
-| `context:section` id / kind / source_ref metadata | Section citation handle and evidence boundary. |
-| Reader-visible section body | Primary evidence for factual answers. |
-| `context-build-inventory.json` `structure.edge_records` | Package-visible relationship evidence when typed edges are selected into this package. |
-| `context-build-inventory.json` | Package scope, counts, selected-by reasons, edge records, and build-time visibility evidence. |
-
-Frontmatter and indexes orient the search; reader-visible section content and
-source-backed edge records support claims. If a source_ref points to evidence
-that is not bundled, cite the approved knowledge section that reviewed it and avoid expanding
-beyond the packaged content.
+Use each opened page or package artifact as an evidence card:
 
-## Route By Intent
+| Evidence | Valid use |
+|---|---|
+| Page path | Page identity and citation handle. |
+| 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. |
+| Root indexes and build inventory | Package scope and coverage evidence. |
 
-| User intent | First move | Evidence move |
-|---|---|---|
-| Vague topic or unknown name | Open the package's OKF root index, usually `wikis/index.md`, then child indexes such as `wikis/<group>/index.md`. If the package includes other selected OKF roots such as `guides/` or `rules/`, use their indexes too. | Choose candidate pages by title, path, frontmatter, and index grouping. |
-| Architecture, procedure, FAQ, decision, incident, or troubleshooting question | Start from `guides/index.md` when present. These pages are mapped from internal `architecture`, `sop`, `faq`, `decision`, and `incident` collections. | Use guide pages for explanations, design narratives, decisions, steps, operational context, and troubleshooting; cite the relevant sections. |
-| Structured product or business question | Start from `wikis/index.md`, then the `product` or `business` group index. | Use entity pages and typed relationships to establish scope before reading supporting narratives. |
-| Standard, constraint, acceptance, or test scenario question | Start from `rules/index.md` when present. These pages are mapped from internal `standards` and `test` collections. | Use rule pages for normative constraints, acceptance criteria, and validation scenarios. |
-| Specific entity/domain/action named | Open the matching page or nearest group index. | Read the page sections and source metadata. |
-| Relationship or impact question | Check `context-build-inventory.json` `structure.edge_records`, then related endpoint pages. | Cite typed edge evidence if available; otherwise cite page sections and mark relation gaps. |
-| Detail within a known page | Read that page's relevant `context:section` block. | Cite the section id/source_ref and quote or summarize only supported text. |
-| Coverage, gaps, or package scope | Check indexes and `context-build-inventory.json`. | Cite those package artifacts plus relevant pages. |
-
-Classify the user's question before opening pages. Structure queries take
-priority over keyword search:
-
-- Vague problem: show the relevant package structure first, then choose or ask
-  for a page/group scope. Do not answer from a package-wide text hit before
-  choosing the likely Node/page.
-- Explicit Node/page name: open the matching page or nearest group index. If
-  several pages normalize to the same name, show the candidates instead of
-  guessing.
-- Relationship/impact: inspect typed edges first, then read both endpoint
-  pages. If an edge is absent, page co-occurrence is not relationship evidence.
-- Detail inside a chosen scope: open only the relevant page sections. Use
-  search only to locate the section inside that page or group.
-- Coverage/gap/audit: use package artifacts first, then supporting pages.
-
-If the package structure returns multiple plausible pages, ask the user to pick
-or state the selection basis before answering. If no page or edge supports the
-requested fact, report a gap; do not broaden search until something vaguely
-matches.
-
-## Workflow
-
-1. Start with the relevant OKF root index, usually `wikis/index.md`, to
-   understand the package scope.
-2. Follow OKF directory indexes such as `wikis/<group>/index.md` before opening
-   pages. If the package includes other selected OKF roots, inspect their
-   indexes the same way.
-3. Open only the candidate pages needed for the question; avoid workspace-wide
-   reading unless the user asks for an inventory.
-4. Inspect frontmatter `node_type`, `sources`, and `context:section` comments to
-   confirm evidence boundaries.
-5. Answer from reader-visible section content. Use source_ref metadata as
-   citation and freshness context, not as a license to invent missing facts.
-6. Cite source-linked facts from the knowledge page when the answer depends on
-   code or reviewed knowledge.
-7. If the indexes and matching pages do not cover the request, return a
-   structured gap: requested topic, indexes/pages checked, and missing source
-   span or source_ref.
-
-For follow-up exploration, stay within the package boundary:
-
-- User asks about dependencies or impact: inspect `context-build-inventory.json`
-  `structure.edge_records` and the endpoint pages.
-- User asks for full detail after a partial answer: continue within the same
-  page or its child index before expanding outward.
-- User asks for a specific feature or behavior: use exact terminology,
-  bilingual terms, product aliases, API names, flags, and error strings from the
-  question to locate a section, then answer from the section body.
-- User mentions another page through a referenced edge or section link: open it
-  only if the relationship question requires it or the user asks to drill down.
-- Do not auto-open every related page, edge endpoint, or search hit just because
-  it is present.
+Do not infer a relationship from page co-occurrence. If a `source_ref` points to
+source material that is not bundled, cite the approved section that reviewed it
+and do not expand beyond its visible content.
 
 ## Search Fallback
 
-Use text search only after the structure path above fails to identify a scope.
+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:
 
-- Search with exact product names, API names, bilingual terms, aliases, and
-  error strings from the user's question.
-- Prefer scoped search under a likely group/page over a package-wide scan.
-- A search hit is only a lead. Open the containing page/section and answer from
-  the section body, not from the hit line alone.
-- If search returns only unrelated pages, report the gap instead of broadening
-  until something vaguely matches.
-
-Search is keyword-literal, so use deliberate terms:
+```bash
+node <current knowledge-query Skill directory>/scripts/search.mjs --query '<terms>' --limit 8
+```
 
-- mix Chinese and English names when both may appear in the package;
-- include version numbers, API names, config keys, command flags, and exact
-  error strings when the user provides them;
-- try aliases and synonyms only to locate a candidate page, not to justify a
-  claim;
-- after a search hit, return to structure: identify the page, section, and
-  evidence boundary before answering.
+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.
 
-Do not use search for relationship or impact claims when a typed edge is
-available. Relationship answers should cite the edge first; search can only
-find endpoint details.
+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.
 
-## Citation Shape
+## Citations And Gaps
 
-Use compact citations keyed to package artifacts:
+Use compact citations tied to claims:
 
 ```text
-Page identity/title:      <claim> [<okf-root>/path/page.md]
-Section claim:            <claim> [<okf-root>/path/page.md#section-id]
-Source-backed detail:     <claim> [<okf-root>/path/page.md#section-id, source_ref]
-Relationship/edge:        <claim> [context-build-inventory.json#structure.edge_records edge:<type>]
-Package coverage/gap:     <claim> [context-build-inventory.json]
+Page:         <claim> [<root>/path/page.md]
+Section:      <claim> [<root>/path/page.md#section-id]
+Source-bound: <claim> [<root>/path/page.md#section-id, source_ref]
+Relationship: <claim> [context-build-inventory.json#structure.edge_records edge:<type>]
+Coverage:     <claim> [context-build-inventory.json]
 ```
 
-If several sections support the same claim, cite the strongest one or two and
-explain what each supports. Do not list citations without tying them to claims.
+When evidence is missing, return:
 
-For relationship answers, cite the typed edge when present and then cite endpoint
-sections for the facts about each endpoint. If no edge exists, do not infer a relationship from co-occurrence; say that the package lacks a source-backed relationship edge and cite any weaker page-level evidence separately.
-
-Use citation scope conservatively:
+```text
+Gap: this package does not contain evidence for <missing point>.
+Checked: <indexes, pages, or artifacts>.
+Next useful source: <source, page, or source_ref if known>.
+```
 
-- Page identity/title claims can cite the page path.
-- Factual behavior, constraints, examples, warnings, and usage claims need a
-  `context:section` citation when available.
-- Package coverage or known-limit claims need `context-build-inventory.json`
-  and/or the checked indexes/pages.
-- `source_ref` metadata names the reviewed evidence boundary, but the source
-  body may not be bundled. Do not invent source text that is not present in the
-  packaged knowledge page.
+Distinguish “not evidenced by this package” from “not true.” Do not fill gaps
+from memory, previous conversations, or source files outside the package.
 
-## Gap Shape
+## Package Boundary
 
-When the package lacks evidence, say so explicitly:
+- The bundled OKF-compatible roots are the source of truth for this Skill.
+- The package contains approved knowledge selected by its Context workspace; it
+  does not claim complete coverage of the underlying product or codebase.
+- Do not scan every page or edge when a narrower indexed scope answers the
+  request.
 
-```text
-Gap: this package did not return evidence for <missing point>.
-Checked: <indexes/pages/artifacts>.
-Next useful source need: <source, page, or source_ref if known>.
-```
+Approved knowledge files: `{{knowledgeCount}}`
 
-Do not fill the gap from general product knowledge, previous conversations, or
-raw source files outside this package.
-
-If the likely cause is that source material was captured but not approved into
-this package, say that the packaged knowledge does not include it. Do not tell
-the user it is false; distinguish "not evidenced here" from "not true."
-
-## Knowledge Boundary
-
-- The bundled OKF root directories, usually including `wikis/`, are the source
-  of truth for this skill.
-- OKF root mapping: `wikis/` maps from the structured `codegraph`, `business`,
-  and `product` collections; `guides/` maps from `architecture`, `sop`, `faq`,
-  `decision`, and `incident`; `rules/` maps from `standards` and `test`;
-  `feats/` maps from `feats`.
-- Treat `wikis/` as the primary entity-and-relationship layer. Guides and rules
-  may explain, operationalize, or constrain that structured knowledge, but
-  directory co-location alone is not relationship evidence.
-- Bundled OKF root directories follow the C4A OKF Profile.
-- Prefer OKF indexes, `context-build-inventory.json`, package manifests when
-  present, build inventory, and page source span metadata over raw text search.
-- Do not rely on memory when a knowledge page exists.
-- Do not claim the package is complete; it only contains approved knowledge that
-  was selected by the Context workspace.
-- If the package lacks project-specific instructions, state that the default
-  skill is a generic query entry and report gaps instead of inventing workflow
-  guidance.
-
-## Included Knowledge
+## Template Author Recommendation
 
-Approved knowledge files: `{{knowledgeCount}}`
+This is a complete generic query Skill, but package authors should replace or
+edit it before publishing when the package has project-specific terminology,
+common user intents, preferred entry pages, known limits, or task workflows.
+Update the description, routing table, and package-boundary guidance to match
+the actual package. If the generic behavior is intentionally sufficient,
+explicitly accept the unchanged default during Context package-template review.

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/kb/wikis/index.md

@@ -6,7 +6,7 @@ tags:
   - context
   - knowledge-base
 timestamp: "{{knowledgeTimestamp}}"
-resource: "context://package/{{packageName}}/wikis"
+resource: "context://package/{{packageName}}/{{wikisRoot}}"
 package: "{{packageName}}"
 package_kind: "{{packageKind}}"
 knowledge_count: {{knowledgeCount}}
@@ -14,7 +14,7 @@ knowledge_count: {{knowledgeCount}}
 
 <!-- context:template
 This file is a starter template. It is rendered by `context build` and copied to
-`dist/<package-name>/wikis/index.md`.
+`dist/<package-name>/{{wikisRoot}}/index.md`.
 
 Template comments that start with `context:template` are removed from build output.
 Read the template variable guide before customizing:
@@ -22,9 +22,9 @@ node_modules/@c4a/context/docs/reference/template-variables.md
 
 Customize this file before calling the package usable. Add the bundle scope,
 intended readers, recommended reading order, known gaps, product scenarios,
-or task-focused entry sections. The default root index lists only the
-next-level directories; context build generates directory-level index.md
-files below it.
+or task-focused entry sections. The default root index links small directory
+contents directly and links to child index.md files when a directory exceeds
+the package navigation threshold.
 -->
 
 # {{displayName}}
@@ -38,6 +38,6 @@ Use this index as the entry point, then open the linked knowledge pages for sour
 
 ## How To Use
 
-- Start from the directory list above, then open child indexes and linked knowledge pages for source-linked details.
-- Use `skills/knowledge-query/SKILL.md` when this bundle is installed as an agent knowledge package.
-- Customize `src/package-templates/kb/wikis/index.md` before build to add bundle scope, known gaps, project-specific reading paths, or task entry points.
+- Start from the navigation above, then open linked pages or child indexes for source-linked details.
+- Use the bundled knowledge-query Skill when this bundle is installed as an agent knowledge package.
+- Package authors should replace or edit this generic index before publishing when the package needs bundle scope, known gaps, project-specific reading paths, or task entry points; otherwise explicitly accept the unchanged default during Context package-template review.

package/templates/package-templates.zh-CN/kb/AGENTS.md

@@ -0,0 +1,30 @@
+# {{displayName}}
+
+本知识包由 Context 工作区生成。
+
+- 包名：`{{packageName}}`
+- 类型：`{{packageKind}}`
+- 已批准知识文件：`{{knowledgeCount}}`
+
+## 使用方式
+
+将包内 Markdown 作为经过审核、可追溯来源的产品与代码知识。回答问题时优先使用知识页中的可见正文，不要依赖记忆补全。
+
+随包提供的 knowledge-query Skill 会指导 Agent 从 `{{wikisRoot}}/` 等 OKF 索引开始导航，并引用实际读取的知识页。
+
+包内可能包含以下 OKF 根目录：
+
+- `{{wikisRoot}}/`：结构化实体和关系，对应 codegraph、business、product。
+- `{{guidesRoot}}/`：架构、流程、FAQ、决策和故障记录。
+- `{{rulesRoot}}/`：标准、约束、验收条件和测试场景。
+- `{{featsRoot}}/`：被选择进入包内的功能知识。
+
+这些目录使用兼容 OKF 的 Context profile：OKF 字段和 Context 扩展字段保持在顶层，不生成额外的 `context` 或 `schema` 包装字段。`{{wikisRoot}}/` 是实体与关系层，guides 和 rules 可以围绕其中内容进行解释或约束。
+
+## 包含的知识
+
+`context build` 会把已批准且被当前包选择的 Markdown 复制到这里。目录索引和 `context-build-inventory.json` 用于导航、覆盖检查与关系查询。
+
+## 模板作者建议
+
+这是可直接工作的通用模板。正式发布前，如果知识包存在专用术语、常见用户意图、推荐入口、已知边界或固定任务流程，作者应替换或编辑本文件及 knowledge-query Skill；如果通用行为已经足够，应在 Context 的包模板 Review 中明确接受未修改模板。