@c4a/context 0.6.8 → 0.6.9

package/README.md

@@ -2,11 +2,43 @@
 
 [简体中文](./README.zh-CN.md)
 
-`@c4a/context` is the declarative SDK for a Context workspace. It provides the
-typed API used by `src/index.ts` to describe sources, processing phases, review
-gates, and package outputs. It does not perform filesystem writes or run the
-workflow; those operations belong to the
-[Context CLI](../context-cli/README.md).
+`@c4a/context` is the declarative model behind a Context knowledge workspace.
+It lets the workspace describe which sources contribute knowledge, how evidence
+is processed, where human review applies, and which reusable outputs should be
+built.
+
+Most users do not install or operate this SDK directly. They start through the
+Context Agent entry, describe a knowledge goal, and let the selected workflow
+Route guide the Agent when `src/index.ts` needs configuration. This README is
+for knowledge-project authors, Agent maintainers, and developers who need to
+understand that project declaration.
+
+The SDK is intentionally declarative. It does not read sources, write workspace
+state, execute an Agent, or build packages by itself. Those operations belong
+to the [Context workflow runtime](../context-cli/README.md).
+
+## Place in the knowledge workflow
+
+```text
+User intent + source boundaries
+              ↓
+       src/index.ts declaration   ← this package
+              ↓
+  Context Route + Agent judgment
+              ↓
+ approved knowledge → package output
+```
+
+The declaration answers four stable questions:
+
+- Which registered source boundaries may contribute evidence?
+- Which capture, extraction, alignment, compilation, and review phases exist?
+- Which approved collections belong in each output?
+- Which templates and asset-delivery policies shape the built package?
+
+It does not encode current progress. Workspace facts and the bundled workflow
+Provider select the next Route at runtime, so `src/index.ts` remains a project
+contract rather than a second state machine.
 
 ## Project Model
 
@@ -42,11 +74,11 @@ export default defineProject({
 });
 ```
 
-`src/index.ts` is similar to a Webpack configuration for knowledge. It defines
-what enters the project, which transformations and gates run, and what is built
-at the end. The installed Agent plugin provides thin entries; the current
-workflow route selects the procedures and manuals needed to maintain this
-configuration from a user's requirements.
+`src/index.ts` is similar to a build configuration for knowledge. It defines
+what enters the project, which transformations and gates are available, and
+what can be built at the end. The installed Agent entry stays thin; the current
+workflow Route selects the exact procedures, schemas, and manuals needed to
+maintain this declaration from the user's requirements.
 
 ## Public Surface
 
@@ -181,3 +213,7 @@ state. The CLI owns that runtime state and removes it after a successful close.
 - [Lark Resource Materialization](./docs/guides/lark-resources.md)
 - [Package Templates](./docs/reference/package-templates.md)
 - [Template Variables](./docs/reference/template-variables.md)
+
+The [documentation index](./docs/README.md) explains which references should be
+read for each workflow decision. Agents should prefer Route-selected resources
+over preloading every manual.

package/README.zh-CN.md

@@ -2,7 +2,39 @@
 
 [English](./README.md)
 
-`@c4a/context` 是 Context workspace 使用的声明式 SDK。它为 `src/index.ts` 提供类型化 API，用来描述知识来源、处理阶段、审核门禁和知识包输出。SDK 本身不写入工作区，也不执行流程；这些操作由 [Context CLI](../context-cli/README.zh-CN.md) 负责。
+`@c4a/context` 是 Context 知识工作区背后的声明模型。它让工作区说明哪些来源会
+贡献知识、证据经过哪些处理、哪些地方需要人工审核，以及最终应该构建哪些可复用
+产物。
+
+多数用户不需要单独安装或直接操作这个 SDK。他们从 Context Agent 入口开始，说明
+知识目标；当 `src/index.ts` 需要配置时，当前工作流 Route 会引导 Agent 完成修改。
+这份 README 面向知识项目作者、Agent 维护者和需要理解项目声明的开发者。
+
+SDK 有意保持声明式：它本身不读取来源、不写入工作区状态、不运行 Agent，也不
+构建知识包。这些操作由 [Context 工作流运行时](../context-cli/README.zh-CN.md)
+负责。
+
+## 在知识生产工作流中的位置
+
+```text
+用户意图 + 来源边界
+         ↓
+  src/index.ts 项目声明   ← 本包
+         ↓
+Context Route + Agent 判断
+         ↓
+正式知识 → 知识包产物
+```
+
+项目声明回答四个长期稳定的问题：
+
+- 哪些已经登记的来源边界可以贡献证据？
+- 存在哪些采集、提取、对齐、编译和审核阶段？
+- 每种产物应该选择哪些正式知识分类？
+- 哪些模板和资源分发策略决定最终包的结构？
+
+它不记录当前进度。工作区事实和随包发布的 Workflow Provider 会在运行时选择下一
+条 Route，因此 `src/index.ts` 是项目契约，不是第二套状态机。
 
 ## 项目模型
 
@@ -38,7 +70,9 @@ export default defineProject({
 });
 ```
 
-`src/index.ts` 有点像知识项目的 Webpack 配置：它定义哪些内容进入项目、经过哪些转换和门禁，以及最终构建什么产物。安装好的 Agent 插件只提供薄入口，当前工作流路由会按需选择维护这份配置所需的流程资源和 SDK 文档。
+`src/index.ts` 类似知识项目的构建配置：它定义哪些内容进入项目、可以经过哪些转换
+和门禁，以及最终能够构建什么产物。安装好的 Agent 入口保持精简，当前工作流
+Route 会按需选择维护这份声明所需的操作说明、Schema 和手册。
 
 ## 主要 API
 
@@ -145,3 +179,6 @@ SDK 只负责声明。它可以描述读取、写入、阶段、审核和知识
 - [飞书资源物化](./docs/guides/lark-resources.md)
 - [知识包模板](./docs/reference/package-templates.md)
 - [模板变量](./docs/reference/template-variables.md)
+
+[文档索引](./docs/README.zh-CN.md)说明每类工作流决策应该查看哪些参考资料。Agent
+应优先读取 Route 选择的资源，不要预加载整套手册。

package/docs/README.md

@@ -1,17 +1,36 @@
 # Context SDK Docs
 
+[简体中文](./README.zh-CN.md)
+
 These docs ship inside the installed SDK package at:
 
 ```text
 node_modules/@c4a/context/docs/
 ```
 
-For lifecycle work, Agents should first consume the resources selected by
-`context status --format json` `workflow.current`. Read these SDK manuals when
-the selected route requires project configuration, package templates, or
-general reference; do not preload the whole manual set.
+These manuals explain how a knowledge project declares sources, processing,
+review, and package output. They are references inside the larger Agent-driven
+workflow, not a second set of lifecycle instructions.
+
+For active knowledge production, start through the installed Context Agent
+entry. Agents should first consume the resources selected by
+`workflow.current`, then read an SDK manual only when that Route requires
+project configuration, package-template work, or a stable API reference. Do not
+preload the whole manual set.
+
+## Find the right document
+
+| Current need | Read |
+|---|---|
+| Understand the whole knowledge-project shape | [Getting Started](./getting-started.md) |
+| Know what the Agent may decide or change | [Agent Guide](./guides/agent-guide.md) and [Agent Dialogue](./guides/agent-dialogue.md) |
+| Configure sources, phases, review, or packages | [Project API](./reference/project-api.md) |
+| Choose a code extraction path | [Code Extractor Selection](./reference/code-extractors.md) |
+| Choose an Agent package or LLM document | [Package Outputs](./guides/package-outputs.md) |
+| Customize package files and indexes | [Package Templates](./reference/package-templates.md) and [Template Variables](./reference/template-variables.md) |
+| Preserve Lark images and embedded resources | [Lark Resource Materialization](./guides/lark-resources.md) |
 
-## Read First
+## Complete reference
 
 - [Getting Started](./getting-started.md) — end-to-end component-library flow.
 - [Agent Guide](./guides/agent-guide.md) — what an agent should do, and what it should not inspect manually.

package/docs/README.zh-CN.md

@@ -0,0 +1,60 @@
+# Context SDK 文档
+
+[English](./README.md)
+
+这些手册说明知识项目如何声明来源、处理过程、审核和知识包产物。它们是 Agent
+驱动工作流中的参考资料，不是另一套生命周期指令。
+
+进行知识生产时，应先从已安装的 Context Agent 入口开始。Agent 优先消费
+`workflow.current` 选择的资源；只有当前 Route 要求编辑项目配置、维护知识包模板
+或查询稳定 API 时，才读取对应 SDK 手册，不要预加载整套文档。
+
+## 按当前需要选择文档
+
+| 当前需要 | 阅读内容 |
+|---|---|
+| 理解完整知识项目的形态 | [Getting Started](./getting-started.md) |
+| 判断 Agent 可以决定或修改什么 | [Agent Guide](./guides/agent-guide.md) 和 [Agent Dialogue](./guides/agent-dialogue.md) |
+| 配置来源、阶段、审核或产物 | [Project API](./reference/project-api.md) |
+| 选择代码提取方式 | [Code Extractor Selection](./reference/code-extractors.md) |
+| 选择 Agent 知识包或 LLM 文档 | [Package Outputs](./guides/package-outputs.md) |
+| 自定义包文件和索引 | [Package Templates](./reference/package-templates.md) 和 [Template Variables](./reference/template-variables.md) |
+| 保留飞书图片和内嵌资源 | [Lark Resource Materialization](./guides/lark-resources.md) |
+
+## 完整参考
+
+- [Getting Started](./getting-started.md)：从来源到知识包的端到端组件库示例。
+- [Agent Guide](./guides/agent-guide.md)：Agent 应该执行什么，以及哪些状态不能手工探查或修改。
+- [Agent Dialogue](./guides/agent-dialogue.md)：稳定的对话原则和 Route-selected Gate 资源发现方式。
+- [Package Outputs](./guides/package-outputs.md)：如何选择 Agent 知识包、LLM 文本或不构建产物。
+- [Lark Resource Materialization](./guides/lark-resources.md)：内嵌资源如何从来源证据进入正式知识和知识包。
+- [Project API](./reference/project-api.md)：`defineProject`、来源、阶段、审核和知识包声明。
+- [Code Extractor Selection](./reference/code-extractors.md)：如何根据技术信号选择内建提取器、结构库或项目适配器。
+- [Package Templates](./reference/package-templates.md)：`kbPackage`、`llmsPackage`、模板变量和示例。
+- [Template Variables](./reference/template-variables.md)：Handlebars 变量、循环、注释和默认知识清单。
+
+正式 Markdown 使用完整的 Context production profile。知识包内的知识页只保留
+面向读者的元数据和正文；Node 身份、来源、Section 证据、审核指纹、符号清单、
+生成子项和关系继续留在生产工作区或 `context-build-inventory.json` 中。构建清单
+将每个分发路径映射回正式知识路径。知识包根目录可以包含 Agent 文件；可交换知识
+位于所选的 `wikis/`、`guides/`、`rules/` 和 `feats/` 子树。
+
+## 已安装模板
+
+知识包模板示例随 SDK 安装在：
+
+```text
+node_modules/@c4a/context/templates/package-templates/
+```
+
+需要构建产物时，将合适的模板复制或映射到工作区的
+`src/package-templates/`。
+
+长期维护、多来源的生产工作区还可以使用可选的项目维护 Skill 模板：
+
+```text
+node_modules/@c4a/context/templates/project-skills/maintain-project-knowledge/SKILL.md
+```
+
+将它复制到项目 `.agents/skills/`，按项目重命名并填写来源归属与影响映射。它是
+项目适配器，不会进入最终知识包，也不替代已安装的 Context Agent 入口。

package/docs/getting-started.md

@@ -1,10 +1,27 @@
-# Getting Started
+# Knowledge Project Walkthrough
 
 This guide shows the common Context workspace shape. The same workspace can
 ingest source documents, code repositories, or both. Start with the user's
 source boundary, then declare the matching phases in `src/index.ts`.
 
-## 1. Initialize
+For normal use, start from the installed Context Agent entry and describe the
+knowledge goal. The entry resolves whether it should initialize a workspace,
+enter an existing workspace, or continue the current production round:
+
+```text
+/c4a:context Build a traceable knowledge package from this repository and the
+documents I provide. Explain each source and structure decision before asking
+for confirmation.
+```
+
+The remainder of this guide explains the project model behind that
+conversation. Command examples are maintainer orientation; an Agent should
+prefer the exact command and resources returned by `workflow.current`.
+
+## 1. Establish the workspace
+
+When initialization is required, the Agent runs the exact action returned by
+`context entry`. A manual equivalent for automation or source development is:
 
 ```bash
 context init context
@@ -28,11 +45,10 @@ inside a non-empty directory that is not already a Context workspace is blocked
 before any files are written; use the returned `--allow-nonempty` command only
 after confirming that the existing files should share the workspace root.
 
-When operating through an Agent plugin, use the installed Context continuation
-entry from the project root after initialization. It consumes
-`workflow.current`, loads only the selected resources, and calls lower-level
-CLI primitives as needed. The exact slash command or skill name is
-host-specific.
+After initialization, return to the single installed Context Agent entry from
+the project root. It consumes `workflow.current`, loads only the selected
+resources, and calls lower-level CLI primitives as needed. Do not introduce a
+separate continuation entry.
 
 ## 2. Choose And Register A Source Boundary
 
@@ -233,9 +249,9 @@ export default defineProject({
 });
 ```
 
-Then start from `context status` or the installed host-specific Context
-continuation entry. The
-normal sequence is:
+Then return to the installed Context Agent entry. For maintainer inspection,
+`context status --format json` exposes the same current Route. The normal
+sequence is:
 
 1. capture the source into committed snapshots;
 2. investigate evidence and confirm the CLI-managed lifecycle structure;

package/docs/guides/agent-dialogue.md

@@ -21,6 +21,13 @@ not duplicated in this SDK manual.
 This keeps a new Agent from loading every possible conversation script before
 it knows which decision is current.
 
+The ordinary path also selects short mode guidance after workspace creation
+and source capture. Explain that ordinary review is the default, provides HTML
+reports at review decisions, and is currently estimated to take about 40%
+longer overall depending on scope and response time. Offer fully managed mode
+for the current conversation while explaining that it gives the user fewer
+opportunities to adjust intermediate content.
+
 ## Stable Principles
 
 - Use the user's conversation language for explanations and questions.
@@ -47,7 +54,10 @@ context status --managed --format json
 ```
 
 The returned route decides which delegatable gates may proceed without another
-question. This authority is not project configuration and must not be persisted
-or reused in another conversation. It cannot choose source boundaries,
+question. A Gate may keep its ordinary inspection Action and dialogue resources
+while replacing them with a direct revision-bound resolution path only for a
+session-authority Route. Necessary evidence inspection remains selected for
+semantic scope or classification work. This authority is not project
+configuration and must not be persisted or reused in another conversation. It cannot choose source boundaries,
 authorize unread external sources or external operations, or bypass validation
 and verification.

package/docs/guides/agent-guide.md

@@ -30,6 +30,13 @@ without another question. Review uses the CLI's atomic `context review
 approve-all ... --managed` route; valid structure staging records
 `confirmed_by: managed-session`.
 
+The Provider may omit an ordinary Gate's HTML inspection Action and
+user-dialogue resources only on its session-authority Route, then expose the
+authority-selected revision-bound resolution Action directly. The ordinary
+inspection and resolution capabilities remain available in ordinary mode.
+Evidence reads needed to choose an extraction scope or classify a captured
+document are not removed.
+
 After the first managed status evaluation, use
 `context run --managed --until blocked-or-complete --format json` when the
 current work can advance through consecutive mechanical routes. The CLI

package/docs/guides/package-outputs.md

@@ -116,7 +116,7 @@ metadata, how many codegraph views were selected, and how many package-visible
 edges were emitted. An empty edge list is therefore explicit evidence of a
 coverage state, not permission to invent a dependency.
 
-The generated `wikis/` directory is the default OKF root and follows the C4A OKF
+The generated `wikis/` directory is the default OKF root and follows the Context OKF
 Profile. Internal production collections are mapped into package OKF roots such
 as `wikis/`, `guides/`, `rules/`, or `feats/`; when selected, `context build`
 copies them into the package and generates root-aware directory indexes for them

package/docs/reference/package-templates.md

@@ -321,7 +321,7 @@ Approved Markdown under `knowledge/` is the production source of truth:
 - 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
+- do not nest Context production 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="..." -->`
   comments;

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@c4a/context",
-  "version": "0.6.8",
+  "version": "0.6.9",
   "type": "module",
-  "description": "Context SDK — project-local configuration and workspace primitives",
+  "description": "Declarative SDK for Context knowledge sources, workflows, review, and package outputs",
   "license": "MIT",
   "repository": {
     "type": "git",