@c4a/context 0.6.1 → 0.6.3

package/README.md

@@ -44,8 +44,9 @@ 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 includes the skills and SDK manuals
-needed to maintain this configuration from a user's requirements.
+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.
 
 ## Public Surface
 
@@ -54,15 +55,17 @@ needed to maintain this configuration from a user's requirements.
 | `defineProject()` | Declares the complete project graph. |
 | `source()` and `allSources()` | References registered repo, file, or Lark source boundaries. |
 | `extractTs()` | Extracts TypeScript/TSX symbols and relationships into `codegraph` candidates. |
+| `extractCustom()` | Runs a project-owned code extractor while Context owns candidate, evidence, freshness, and Review state. |
 | `alignProse()` and `compileProse()` | Structures document evidence and compiles source-bound knowledge candidates. |
 | `reviewValidity()` | Declares the review gate for one collection or the project. |
 | `customPhase()` | Adds project-specific orchestration when built-in phase factories are not enough. |
 | `kbPackage()` | Builds an Agent knowledge-base package from approved knowledge and templates. |
 | `llmsPackage()` | Builds a single text bundle for model context or RAG import. |
 
-Use the built-in phase factories first. `customPhase()` is an escape hatch for
-project-specific orchestration, not a replacement for source, extraction,
-review, and package lifecycle rules.
+Use `extractCustom()` when a repository needs a non-TypeScript or aggregated
+code extractor. Use `customPhase()` only for orchestration that does not publish
+knowledge candidates; it is not a replacement for source, extraction, Review,
+and package lifecycle rules.
 
 ## Knowledge Collections
 
@@ -116,18 +119,33 @@ include `{{packageName}}`, `{{displayName}}`, `{{knowledgeCount}}`,
 `{{knowledgeGroups}}`, `{{knowledgeItems}}`, `{{knowledgeTree}}`, and
 `{{buildInventory}}`.
 
+Every KB package emits flat roots such as `wikis/`, `guides/`, `rules/`, and
+`feats/`. The package `name` defines only the `dist/<package-name>/` boundary;
+it is not repeated inside knowledge paths. Context still accepts
+`distribution.knowledgeNamespace` from older workspaces, but the legacy value
+no longer changes build output and new declarations do not need it. Skill names
+remain author-maintained and independent.
+
 For advanced routing and retrieval, a template may carry a local script such as
 `query.ts`, with a Skill describing when and how an Agent should call it. The
 Skill can also route the Agent to MCP servers, CLI commands, or other tools to
 form a package-specific Agentic Search workflow.
 
+Long-lived, multi-source production workspaces can copy
+`templates/project-skills/maintain-project-knowledge/SKILL.md` into their
+`.agents/skills/` directory and customize it with project ownership, source
+impact mappings, and readiness criteria. This project adapter is not included
+in knowledge packages; lifecycle authority remains with the installed Context
+Skill and current Route.
+
 ## State Boundary
 
 The SDK stays declarative. It may describe reads, writes, phases, review, and
 package selection, but the CLI owns source materialization, capture, extraction,
 review application, approved Markdown materialization, verification, and build.
 Do not replace CLI lifecycle operations with direct edits to `sources/`,
-`unapproved/`, `knowledge/`, or `dist/`.
+`knowledge/`, `dist/`, or the ignored `.tmp/context-runtime/lifecycle/` runtime
+state. The CLI owns that runtime state and removes it after a successful close.
 
 ## Documentation
 
@@ -136,5 +154,6 @@ Do not replace CLI lifecycle operations with direct edits to `sources/`,
 - [Agent Guide](./docs/guides/agent-guide.md)
 - [Project API](./docs/reference/project-api.md)
 - [Package Outputs](./docs/guides/package-outputs.md)
+- [Lark Resource Materialization](./docs/guides/lark-resources.md)
 - [Package Templates](./docs/reference/package-templates.md)
 - [Template Variables](./docs/reference/template-variables.md)

package/README.zh-CN.md

@@ -0,0 +1,128 @@
+# Context SDK
+
+[English](./README.md)
+
+`@c4a/context` 是 Context workspace 使用的声明式 SDK。它为 `src/index.ts` 提供类型化 API，用来描述知识来源、处理阶段、审核门禁和知识包输出。SDK 本身不写入工作区，也不执行流程；这些操作由 [Context CLI](../context-cli/README.zh-CN.md) 负责。
+
+## 项目模型
+
+Context 项目使用“来源 → 阶段 → 知识包”的声明模型：
+
+```ts
+import {
+  defineProject,
+  extractTs,
+  kbPackage,
+  reviewValidity,
+  source,
+} from "@c4a/context";
+
+const sampleLib = source("20260712", "sample-lib");
+
+export default defineProject({
+  sources: [sampleLib],
+  phases: [
+    extractTs({ source: sampleLib, collection: "codegraph" }),
+    reviewValidity({ collection: "codegraph" }),
+  ],
+  packages: [
+    kbPackage({
+      name: "sample-lib-kb",
+      template: {
+        path: "src/package-templates/kb",
+        vars: { displayName: "Sample Library KB" },
+      },
+      select: { collections: ["codegraph"], okfRoots: ["wikis"] },
+    }),
+  ],
+});
+```
+
+`src/index.ts` 有点像知识项目的 Webpack 配置：它定义哪些内容进入项目、经过哪些转换和门禁，以及最终构建什么产物。安装好的 Agent 插件只提供薄入口，当前工作流路由会按需选择维护这份配置所需的流程资源和 SDK 文档。
+
+## 主要 API
+
+| API | 用途 |
+|---|---|
+| `defineProject()` | 声明完整的项目处理图。 |
+| `source()` 和 `allSources()` | 引用已经登记的代码仓库、本地文件或飞书来源边界。 |
+| `extractTs()` | 从 TypeScript/TSX 中提取符号和关系，生成 `codegraph` 候选。 |
+| `extractCustom()` | 运行项目自有代码提取器，同时由 Context 维护候选、证据、新鲜度和审核状态。 |
+| `alignProse()` 和 `compileProse()` | 整理文档证据，并生成与来源绑定的知识候选。 |
+| `reviewValidity()` | 声明单个知识类型或整个项目的审核门禁。 |
+| `customPhase()` | 在内置阶段无法覆盖时增加项目专用编排。 |
+| `kbPackage()` | 使用审核通过的知识和模板构建 Agent 知识库。 |
+| `llmsPackage()` | 构建供模型上下文或 RAG 导入使用的单文件文本包。 |
+
+非 TypeScript 或需要聚合代码事实时使用 `extractCustom()`。`customPhase()`
+只用于不发布知识候选的项目专用编排，不能绕开来源、提取、审核和打包生命周期。
+
+## 知识分类
+
+审核通过的 Markdown 会存放在 `knowledge/<collection>/`：
+
+| 知识类型 | 主要内容 | 常见来源 |
+|---|---|---|
+| `codegraph` | 代码符号、模块和调用关系 | 代码仓库 |
+| `business` | 业务概念、角色和业务关系 | 业务文档、飞书文档 |
+| `product` | 产品能力、功能行为和产品关系 | 产品文档、需求文档 |
+| `architecture` | 系统结构、模块职责和设计说明 | 架构文档、设计文档 |
+| `sop` | 操作流程、运行手册和处理步骤 | 操作手册、值班文档 |
+| `faq` | 常见问题、解释和排障方法 | FAQ、支持文档、经验记录 |
+| `decision` | 方案选择、取舍和决策背景 | 设计评审、决策记录 |
+| `incident` | 故障过程、处置方式和后续行动 | 故障复盘、事故报告 |
+| `standards` | 必须遵守的规范和约束 | 研发规范、业务规则 |
+| `test` | 验证规则、测试场景和验收标准 | 测试文档、验收说明 |
+| `feats` | 面向具体场景整理的能力记录 | 项目自定义处理和已确认知识 |
+
+知识类型是语义分类，不是最终知识包目录。构建时会把选中的类型映射到 `wikis/`、`guides/`、`rules/`、`feats/` 等 OKF 目录。同一份来源可能贡献多种知识，分类应该依据证据和用户确认，而不是文件名。
+
+## 知识包模板
+
+知识包声明会引用 `src/package-templates/` 下的可编辑模板。安装后的示例位于：
+
+```text
+node_modules/@c4a/context/templates/package-templates/
+```
+
+默认 KB 模板包含：
+
+```text
+kb/
+|-- AGENTS.md
+|-- skills/
+|   `-- knowledge-query/SKILL.md
+`-- wikis/index.md
+```
+
+`knowledge-query` Skill 会告诉消费知识包的 Agent 如何浏览索引、读取审核通过的知识并引用证据。项目还可以增加更多 Skills，或者在 `wikis/`、`guides/`、`rules/` 等目录中加入模板文件。
+
+模板使用 Handlebars 变量，可以作用于文件内容和路径。常用变量包括 `{{packageName}}`、`{{displayName}}`、`{{knowledgeCount}}`、`{{knowledgeGroups}}`、`{{knowledgeItems}}`、`{{knowledgeTree}}` 和 `{{buildInventory}}`。
+
+每个 KB 包直接输出扁平的 `wikis/`、`guides/`、`rules/`、`feats/` 等根目录；包 `name`
+只用于确定 `dist/<package-name>/` 边界，不会再次写入知识路径。旧工作区中的
+`distribution.knowledgeNamespace` 仍可被读取，但不再改变构建结果；新声明无需配置它。
+Skill 名称继续由作者独立维护。
+
+如果需要更强的路由和检索能力，模板可以携带 `query.ts` 一类本地脚本，再由 Skill 约定 Agent 何时、如何调用。Skill 也可以把 Agent 路由到 MCP、CLI 或其他工具，组成适合当前知识包的 Agentic Search 流程。
+
+长期维护、多来源的知识生产工作区可以从
+`templates/project-skills.zh-CN/maintain-project-knowledge/SKILL.md` 复制一份
+项目维护 Skill 到 `.agents/skills/`。它不进入知识包，而是补充项目专属的来源
+归属、仓库变化影响范围和准出标准；Context 生命周期仍由已安装的 Context Skill
+和当前 Route 负责。
+
+## 状态边界
+
+SDK 只负责声明。它可以描述读取、写入、阶段、审核和知识包选择，但来源物化、内容读取、代码提取、审核应用、正式知识写入、质量验证和构建都由 CLI 负责。不要通过直接编辑 `sources/`、`knowledge/`、`dist/` 或被忽略的 `.tmp/context-runtime/lifecycle/` 运行态来替代 CLI 生命周期操作；成功 close 后 CLI 会清理该运行态。
+
+## 参考文档
+
+- [文档索引](./docs/README.md)
+- [快速开始](./docs/getting-started.md)
+- [Agent 指南](./docs/guides/agent-guide.md)
+- [项目 API](./docs/reference/project-api.md)
+- [知识包输出](./docs/guides/package-outputs.md)
+- [飞书资源物化](./docs/guides/lark-resources.md)
+- [知识包模板](./docs/reference/package-templates.md)
+- [模板变量](./docs/reference/template-variables.md)

package/contracts.d.ts

@@ -19,6 +19,11 @@ export type PackageSelectDefinition = {
     include?: readonly string[];
     exclude?: readonly string[];
 };
+export type PackageNavigationDefinition = {
+    foldDirectoryIndexes: boolean;
+    maxInlineEntries: number;
+};
+export declare const DEFAULT_PACKAGE_NAVIGATION: Readonly<PackageNavigationDefinition>;
 export declare const DOC_MAINLINE_COLLECTIONS: readonly DocumentMainlineCollection[];
 export declare const MAINLINE_COLLECTIONS: readonly MainlineCollection[];
 export declare const TOP_LEVEL_NAMESPACES: readonly TopLevelNamespace[];

package/docs/README.md

@@ -6,24 +6,28 @@ These docs ship inside the installed SDK package at:
 node_modules/@c4a/context/docs/
 ```
 
-Agents should read these files before editing a Context workspace, especially
-before changing `src/index.ts` or package templates.
+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.
 
 ## Read First
 
 - [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.
-- [Agent Dialogue](./guides/agent-dialogue.md) — how agents should explain human gates without exposing internal API details first.
+- [Agent Dialogue](./guides/agent-dialogue.md) — stable dialogue principles and how route-selected gate resources are discovered.
 - [Package Outputs](./guides/package-outputs.md) — how to choose between an agent knowledge-base package, LLM text, or no package output.
+- [Lark Resource Materialization](./guides/lark-resources.md) — how embedded resources move from source evidence to approved knowledge and package assets.
 - [Project API](./reference/project-api.md) — `defineProject`, sources, phases, review, and packages.
 - [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.
 
@@ -37,3 +41,15 @@ node_modules/@c4a/context/templates/package-templates/
 
 Copy or mirror these into a workspace under `src/package-templates/` when the
 project needs package outputs.
+
+Long-lived multi-source production workspaces may also start from the optional
+project-maintenance Skill template at:
+
+```text
+node_modules/@c4a/context/templates/project-skills/maintain-project-knowledge/SKILL.md
+```
+
+Copy it into the project's `.agents/skills/`, rename it for the project, and
+replace its project-fact and impact-map sections. It is a project adapter; it is
+not included in a built knowledge package and does not replace the installed
+Context Skill.

package/docs/getting-started.md

@@ -7,17 +7,32 @@ source boundary, then declare the matching phases in `src/index.ts`.
 ## 1. Initialize
 
 ```bash
-context init context --dev
+context init context
 cd context
 bun install
-context status
+context status --format json
 ```
 
-Use `--dev` when testing a local link or prepared pack before the matching SDK
-version is published. It writes a `file:` dependency to the SDK resolved beside
-the active CLI. Published users can omit it and install the versioned SDK from
-the registry.
-When operating through an Agent plugin, use the installed Context continuation entry from the project root after initialization; it reads `context status` and then calls the lower-level CLI primitives as needed. The exact slash command or skill name is host-specific.
+Use `--language zh-CN` (or `--language en`) during initialization when the
+generated README, AGENTS contract, and package starter templates should use a
+specific language. Context stores this choice in `package.json`; it does not
+guess from the shell locale or Agent conversation.
+
+Use `--dev` only when testing a locally linked CLI or a prepared package before
+the matching SDK version is published. It writes a `file:` dependency to the SDK
+resolved beside the active CLI. Registry installs should use the default command
+above so the workspace receives the matching versioned SDK dependency.
+
+Without `project-dir`, init uses the dedicated `context/` directory. Initializing
+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.
 
 ## 2. Choose And Register A Source Boundary
 
@@ -30,7 +45,8 @@ suffixes from prose or content. ViewRef/NodeRef are identity fields, not path
 strings:
 
 ```text
-knowledge/<collection>/<containment>/<slug>.md
+knowledge/<collection>/<slug>.md
+knowledge/<collection>/<containment>/<slug>.md  # intentional hierarchy only
 repo:<date>/<module>#symbol:...
 file:<source-name>/<document>#span:...
 lark:<source-name>/<document>#span:...
@@ -98,21 +114,27 @@ module first. An explicit request to capture/read those exact paths or URLs is
 the read confirmation for that requested batch; do not ask again after
 registration. Merely mentioning a possible source is not permission.
 `context status --format json` returns all remaining capture phases in
-`routing.command_plan`. Every item is marked `after-human-confirmation`, so one
-explicit confirmation can authorize the complete requested batch without
-pausing for another date name or collection choice between modules. If any
-module lacks a declaration, status returns `needs-capture-phase` and a precise
-`routing.configuration` action instead of an unexecutable command.
-
-After capture, status returns `captured-ready-to-classify` for document modules
-without an align declaration. Run the returned collection-neutral evidence
-views first; only then propose a mainline collection and ask for confirmation.
-The batch read permission does not itself choose a collection.
+`workflow.current.commands`. Every item requiring the confirmed read scope is
+marked `after-human-confirmation`, so one explicit confirmation can authorize
+the complete requested batch without pausing for another date name or
+collection choice between modules. If any module lacks a declaration,
+`workflow.current.configuration` identifies the precise project change instead
+of returning an unexecutable command. Read every
+`workflow.current.resources.required` item before acting; long procedures and
+semantic rules remain available as files and are loaded only for the route that
+needs them.
+
+After capture, status selects `route.document.classification-required` for
+document modules without an align declaration. Run the Gate's returned
+collection-neutral inspection commands first; only then propose a mainline
+collection and ask for confirmation. Batch read permission does not choose a
+collection.
 
 When the workspace also contains repo sources, Context prioritizes untouched
-code after all document captures finish: status returns `ready-to-extract`
-until the code extraction round is current, then returns to document
-investigation. An existing document structure/compile gate is never interrupted.
+code after all document captures finish: the current reason is
+`route.extract.pending-target` until the code extraction round is current,
+then routing returns to document investigation. An existing document
+structure/compile gate is never interrupted.
 
 For a single component package, use the package directory as the repo source
 boundary:
@@ -165,16 +187,27 @@ and suggested `context source add` commands.
 
 Remote Git sources need the same boundary decision. Ask for the remote URL, the
 pinned commit/ref, and whether the user approves cloning. The CLI does not
-clone, checkout, reset, or fetch silently. If source material is missing or at
-the wrong ref, ask the user before running repo operations outside the CLI.
+clone, checkout, reset, or fetch silently. If registered source material is
+missing, the current Route exposes a repository recovery plan. The user chooses
+an existing checkout, a bounded local scan, or an explicit shallow/partial clone
+of the registered pinned commit. Context validates the remote, commit, and
+subpaths, restores local aliases, and materializes module links. Advancing to a
+new upstream commit remains a separate source-update decision.
+
+For a long-lived production workspace with project-specific source ownership or
+impact rules, copy the optional maintenance Skill template from
+`templates/project-skills/maintain-project-knowledge/SKILL.md` into the
+project's `.agents/skills/`, rename it for the project, and edit its project
+facts. Keep Context lifecycle commands in the installed Context Skill and
+current Route rather than duplicating them in the project Skill.
 
 ## 3. Declare The Flow
 
 ### Document Source Flow
 
 For source documents, keep the project declaration small and let the CLI guide
-the evidence views, structure confirmation, compile action schema, review, and
-close steps:
+the evidence views, structure confirmation, deterministic compile projection,
+review, and close steps:
 
 ```ts
 import {
@@ -200,11 +233,12 @@ export default defineProject({
 });
 ```
 
-Then start from `context status` or the installed Context continue Skill. The
+Then start from `context status` or the installed host-specific Context
+continuation entry. The
 normal sequence is:
 
 1. capture the source into committed snapshots;
-2. investigate evidence and confirm `unapproved/structure.yaml`;
+2. investigate evidence and confirm the CLI-managed lifecycle structure;
 3. compile every source-bound View from confirmed structure;
 4. review/apply the complete candidate batch once;
 5. run close once, then verify and build when packages are declared.
@@ -242,8 +276,11 @@ context run extract:20260712/component-lib:codegraph
 When operating through an Agent, use `--dry-run --format json` as the CLI
 implementation for a no-write preview. For extract phases it returns a
 `preview` block with resolved sources, modules, file counts, symbol counts,
-candidate estimates, `knowledgeTree`, `knowledgePathExamples`, and module-level
-hints. Treat that preview as the scope check before producing draft candidates.
+resolved entry files, exported/internal counts, symbol-kind counts, candidate
+estimates, `knowledgeTree`, `knowledgePathExamples`, and module-level hints.
+Treat that preview as a structural scope check before producing draft
+candidates; the CLI does not decide which symbols are important to a business
+or audience.
 
 The codegraph path keeps the stable module identity. The date stays in the repo
 source ref and phase id, not in the knowledge path:
@@ -272,18 +309,21 @@ context review html architecture --open
 Use the generated HTML page to approve or reject candidates. If the browser does
 not open automatically, use the emitted `file://` URL. When
 finished, open `Payload` and copy the review decision Payload into the agent chat.
-Uniform decisions use one JSON line; exceptions add JSONL lines. The
-agent writes that pasted payload to a normal temporary file under the workspace
-`.tmp/` directory and runs:
+Uniform decisions use one JSON line; exceptions add JSONL lines. The agent
+writes that pasted payload to the recommended workspace scratch area,
+`.tmp/agent-payloads/`, and runs:
 
 ```bash
 context review apply <payload-file>
 ```
 
 Do not hand-write approved Markdown. `context review apply` owns materialization
-from `unapproved/entities.jsonl` into `knowledge/`.
-Do not store review payloads through scratch files outside `.tmp/` or by
-editing workspace config.
+from the CLI-managed lifecycle candidate ledger into `knowledge/`. The runtime
+ledger is ignored and is removed after a successful close; durable rejected
+candidate fingerprints, when any, are kept in `knowledge/decisions.json`.
+The location is a recommendation rather than a CLI restriction. Do not create a
+top-level scratch directory or edit workspace config merely to retain a review
+payload.
 
 ## 5. Build Packages
 
@@ -311,6 +351,12 @@ Choose an agent knowledge-base package when agents should consume the reviewed
 knowledge as a reusable package. After the user chooses this output shape,
 declare it with `kbPackage()`.
 
+The package name already identifies the surrounding `dist/` directory. The OKF
+roots inside it stay flat (`wikis/`, `guides/`, `rules/`, and `feats/`), so do
+not ask for a second distribution namespace. Ask separately whether the author
+wants a short Skill prefix, then maintain the complete final Skill directory
+name in the template.
+
 The default `knowledge-query` skill teaches agents how to query copied OKF root
 directories structure-first, starting with `wikis/`, cite
 page/section evidence, inspect structure/build metadata when present, and report