@c4a/context 0.6.1-beta.2 → 0.6.1-beta.4

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

@@ -1,209 +1,117 @@
 ---
 name: {{skillName}}
-description: Query the approved knowledge bundled with {{displayName}}.
+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.
-
-## Non-negotiables
-
-- 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.
-
-## Evidence Shape
-
-Treat each opened knowledge page or package artifact as an evidence card:
-
-| Evidence field | Use |
+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 |
 |---|---|
-| 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.
+| `{{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. |
+
+Start from the root that matches the request. A missing root means that category
+was not selected into this package.
 
 ## Route By Intent
 
-| User intent | First move | Evidence move |
-|---|---|---|
-| Vague topic or unknown name | Open the package's OKF root index, usually `{{wikisRoot}}/index.md`, then its child indexes. If the package includes other selected OKF roots such as `{{guidesRoot}}/` or `{{rulesRoot}}/`, use their indexes too. | Choose candidate pages by title, path, frontmatter, and index grouping. |
-| Architecture, procedure, FAQ, decision, incident, or troubleshooting question | Start from `{{guidesRoot}}/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 `{{wikisRoot}}/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 `{{rulesRoot}}/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 `{{wikisRoot}}/index.md`, to
-   understand the package scope.
-2. Follow the links exposed by that index. Small directories may link directly
-   to pages; larger directories may expose their own `index.md`. If the package
-   includes other selected OKF roots, inspect their root 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.
+| 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`. |
 
-## Search Fallback
+## Evidence Contract
 
-Use text search only after the structure path above fails to identify a scope.
+Use each opened page or package artifact as an evidence card:
 
-- 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.
+| Evidence | Valid use |
+|---|---|
+| Page path | Page identity and citation handle. |
+| Frontmatter title, description, node type, 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. |
 
-Search is keyword-literal, so use deliberate terms:
+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.
 
-- 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.
+## Search Fallback
 
-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.
+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.
 
-## 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.
-
-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.
+When evidence is missing, return:
 
-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 `{{wikisRoot}}/`, are the source
-  of truth for this skill.
-- OKF root mapping: `{{wikisRoot}}/` maps from the structured `codegraph`,
-  `business`, and `product` collections; `{{guidesRoot}}/` maps from
-  `architecture`, `sop`, `faq`, `decision`, and `incident`;
-  `{{rulesRoot}}/` maps from `standards` and `test`; `{{featsRoot}}/` maps from
-  `feats`.
-- Treat `{{wikisRoot}}/` 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/wikis/index.md

@@ -40,4 +40,4 @@ Use this index as the entry point, then open the linked knowledge pages for sour
 
 - 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.
-- Customize `src/package-templates/kb/wikis/index.md` before build to add bundle scope, known gaps, project-specific reading paths, or task entry points.
+- 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 中明确接受未修改模板。

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

@@ -0,0 +1,91 @@
+---
+name: {{skillName}}
+description: 查询 {{displayName}} 中经过审核、可追溯来源的知识。用于查找包内实体、API、行为、流程、约束、决策、排障信息、关系和覆盖范围。
+---
+
+# 知识查询
+
+只根据本包包含的已批准知识回答。先通过索引缩小范围，再打开具体页面；正文是事实证据，frontmatter 摘要只用于导航。
+
+## 查询步骤
+
+1. 判断请求属于实体查找、解释、流程、规则、关系、细节还是覆盖检查。
+2. 从最相关的根索引开始，例如 `{{wikisRoot}}/index.md`，再沿链接进入具体页面。
+3. 只读取回答所需的章节；frontmatter 用来选择范围，不作为事实依据。
+4. 查询关系或影响范围时，先检查 `context-build-inventory.json` 中的 `structure.edge_records`，再读取两端页面。
+5. 结论只能来自可见章节正文和来源支持的边记录，并引用对应页面或章节。
+6. 如果包内没有证据，明确报告缺口和已经检查的范围，不要根据邻近内容推断。
+
+## 知识根目录
+
+| 根目录 | 用途 |
+|---|---|
+| `{{wikisRoot}}/` | 来自 codegraph、business、product 的结构化实体和关系。 |
+| `{{guidesRoot}}/` | 架构、流程、FAQ、决策、故障和排障说明。 |
+| `{{rulesRoot}}/` | 标准、约束、验收条件和测试场景。 |
+| `{{featsRoot}}/` | 被选择进入包内的功能知识。 |
+
+缺少某个根目录表示当前知识包没有选择该类别。
+
+## 按意图导航
+
+| 意图 | 第一步 |
+|---|---|
+| 模糊主题或未知名称 | 打开可能相关的根索引，从分组中选择候选页面。 |
+| 指定实体、API、领域或动作 | 打开匹配页面或最近的分组索引；有歧义时列出候选。 |
+| 架构、流程、FAQ、决策或故障 | 从 `{{guidesRoot}}/index.md` 开始。 |
+| 标准、约束、验收或测试 | 从 `{{rulesRoot}}/index.md` 开始。 |
+| 关系或影响范围 | 检查类型化边，再读取两端页面。 |
+| 已知页面中的细节 | 读取对应 `context:section`。 |
+| 覆盖范围或缺口 | 检查根索引和 `context-build-inventory.json`。 |
+
+## 证据契约
+
+| 证据 | 可支持的内容 |
+|---|---|
+| 页面路径 | 页面身份和引用位置。 |
+| frontmatter 的标题、描述、节点类型和标签 | 导航和范围选择。 |
+| `context:section` 的 id、kind、`source_ref` | 章节身份、引用位置和来源边界。 |
+| 读者可见的章节正文 | 事实结论的主要依据。 |
+| `context-build-inventory.json` 的边记录 | 类型化关系证据。 |
+| 根索引和构建清单 | 包的范围和覆盖情况。 |
+
+不要根据页面同时出现来推断关系。如果 `source_ref` 指向未随包分发的来源，只能引用已经过审核的可见章节，不能扩展到正文没有表达的内容。
+
+## 搜索兜底
+
+只有索引和页面结构无法确定范围时才使用文本搜索。优先搜索请求中的精确名称、别名、API、配置键、参数、版本或错误字符串。搜索命中只是线索，回答前仍需打开对应页面和章节。文本搜索不能代替关系边证据。
+
+## 引用与缺口
+
+引用应紧跟结论：
+
+```text
+页面：     <结论> [<root>/path/page.md]
+章节：     <结论> [<root>/path/page.md#section-id]
+来源绑定： <结论> [<root>/path/page.md#section-id, source_ref]
+关系：     <结论> [context-build-inventory.json#structure.edge_records edge:<type>]
+覆盖：     <结论> [context-build-inventory.json]
+```
+
+没有证据时返回：
+
+```text
+缺口：本知识包没有包含 <缺失点> 的证据。
+已检查：<索引、页面或构建产物>。
+下一步来源：<已知时填写来源、页面或 source_ref>。
+```
+
+“本包没有证据”不等于“事实不成立”。禁止使用模型记忆、旧对话或包外源码填补缺口。
+
+## 包边界
+
+- 包内兼容 OKF 的根目录是本 Skill 的事实来源。
+- 本包只包含 Context 工作区选择并批准的知识，不声明完整覆盖底层产品或代码库。
+- 已有更窄索引范围可以回答时，不要扫描所有页面或关系边。
+
+已批准知识文件：`{{knowledgeCount}}`
+
+## 模板作者建议
+
+这是可直接工作的通用查询 Skill。正式发布前，如果知识包存在专用术语、常见用户意图、推荐入口、已知边界或固定任务流程，作者应修改 description、路由表和包边界说明；如果通用行为已经足够，应在 Context 的包模板 Review 中明确接受未修改模板。

package/templates/package-templates.zh-CN/kb/wikis/index.md

@@ -0,0 +1,39 @@
+---
+type: Knowledge Bundle
+title: "{{displayName}}"
+description: "由 Context 工作区生成的已批准知识包。"
+tags:
+  - context
+  - knowledge-base
+timestamp: "{{knowledgeTimestamp}}"
+resource: "context://package/{{packageName}}/{{wikisRoot}}"
+package: "{{packageName}}"
+package_kind: "{{packageKind}}"
+knowledge_count: {{knowledgeCount}}
+---
+
+<!-- context:template
+这是一个起始模板。`context build` 渲染后会将其复制到
+`dist/<package-name>/{{wikisRoot}}/index.md`。
+
+以 context:template 开头的模板注释不会进入构建产物。
+修改前请阅读模板变量手册：
+node_modules/@c4a/context/docs/reference/template-variables.md
+
+正式发布前，应补充知识包范围、目标读者、推荐阅读顺序、已知缺口、使用场景或任务入口。
+小目录会直接列出内容，超过导航阈值时会链接到子目录 index.md。
+-->
+
+# {{displayName}}
+
+本知识包包含 `{{knowledgeCount}}` 个已批准知识页面。请先使用本索引定位范围，再打开具体知识页获取可追溯来源的细节。
+
+## 内容
+
+{{knowledgeGroupsMarkdown}}
+
+## 使用方式
+
+- 从上方导航开始，再进入知识页或子目录索引。
+- 安装为 Agent 知识包后，可以使用随包提供的 knowledge-query Skill。
+- 如果包需要专用范围、已知缺口、阅读路径或任务入口，作者应替换或编辑本通用索引；否则应在 Context 包模板 Review 中明确接受未修改模板。

package/templates/package-templates.zh-CN/llms/llms.txt

@@ -0,0 +1,8 @@
+# {{packageName}}
+
+由 Context 生成。
+
+包类型：{{packageKind}}
+已批准知识文件：{{knowledgeCount}}
+
+{{knowledge}}