@c4a/context 0.6.0-beta.8 → 0.6.1-beta.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 context4ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,32 +1,23 @@
-# @c4a/context
+# Context SDK
 
-`@c4a/context` is the project-local SDK for Context workspaces.
+[简体中文](./README.zh-CN.md)
 
-It provides the typed public surface used by `src/index.ts`: source references,
-phase declarations, review declarations, package declarations, and template
-metadata. `@c4a/context-cli` performs the filesystem side effects.
+`@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).
 
-## Install
+## Project Model
 
-Published users install through the workspace created by `context init`.
-
-For local SDK development:
-
-```bash
-./start.sh link
-context init context --dev
-cd context
-bun install
-```
-
-## Tiny Example
+A Context project follows a sources-to-phases-to-packages model:
 
 ```ts
 import {
   defineProject,
   extractTs,
-  reviewValidity,
   kbPackage,
+  reviewValidity,
   source,
 } from "@c4a/context";
 
@@ -51,50 +42,106 @@ export default defineProject({
 });
 ```
 
-## Read Next
+`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.
+
+## Public Surface
+
+| API | Purpose |
+|---|---|
+| `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. |
+| `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.
+
+## Knowledge Collections
+
+Approved Markdown is organized under `knowledge/<collection>/`:
+
+| Collection | What it contains | Typical sources |
+|---|---|---|
+| `codegraph` | Code symbols, modules, and relationships | Code repositories |
+| `business` | Business concepts, roles, and relationships | Business and Lark documents |
+| `product` | Product capabilities and behavior | Product and requirement documents |
+| `architecture` | System structure and design explanations | Architecture and design documents |
+| `sop` | Procedures, runbooks, and operational steps | Handbooks and operation documents |
+| `faq` | Common questions and troubleshooting | FAQs, support documents, experience notes |
+| `decision` | Decisions, alternatives, and trade-offs | Design reviews and decision records |
+| `incident` | Incident timelines, response, and follow-up | Incident reports and retrospectives |
+| `standards` | Normative rules and constraints | Engineering standards and business rules |
+| `test` | Validation rules, scenarios, and acceptance criteria | Test plans and acceptance documents |
+| `feats` | Capability records for a specific use case | Custom project workflows and approved knowledge |
+
+Collections are semantic classifications, not final package directories.
+Package build maps selected collections into OKF roots such as `wikis/`,
+`guides/`, `rules/`, and `feats/`. One source may contribute to several
+collections; classification should be based on evidence and user confirmation,
+not filenames.
+
+## Package Templates
+
+Package declarations point at editable templates under
+`src/package-templates/`. Installed examples are available at:
 
-These files ship inside the installed package at `node_modules/@c4a/context/`:
-
-- [Docs index](./docs/README.md)
-- [Getting Started](./docs/getting-started.md)
-- [Agent Guide](./docs/guides/agent-guide.md)
-- [Package Outputs](./docs/guides/package-outputs.md)
-- [Project API](./docs/reference/project-api.md)
-- [Package Templates](./docs/reference/package-templates.md)
+```text
+node_modules/@c4a/context/templates/package-templates/
+```
 
-Template examples ship in:
+The default KB template includes:
 
 ```text
-node_modules/@c4a/context/templates/package-templates/
+kb/
+|-- AGENTS.md
+|-- skills/
+|   `-- knowledge-query/SKILL.md
+`-- wikis/index.md
 ```
 
-Copy them into a workspace under `src/package-templates/` when declaring
-`kbPackage()` or `llmsPackage()`.
+The `knowledge-query` Skill teaches consuming Agents how to navigate indexes,
+inspect approved knowledge, and cite evidence. A project can add more Skills or
+template files under `wikis/`, `guides/`, `rules/`, and other package paths.
+
+Templates use Handlebars variables in file contents and paths. Common variables
+include `{{packageName}}`, `{{displayName}}`, `{{knowledgeCount}}`,
+`{{knowledgeGroups}}`, `{{knowledgeItems}}`, `{{knowledgeTree}}`, and
+`{{buildInventory}}`.
 
-Approved Markdown lives under internal `knowledge/<collection>/...` paths such
-as `knowledge/codegraph/...` or `knowledge/architecture/...`. During build, the
-CLI maps selected internal collections to OKF output roots such as `wikis/`,
-`guides/`, `rules/`, or `feats/`. OKF fields and Context 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 comments.
+Every KB package defaults `distribution.knowledgeNamespace` to its package
+`name`, producing a short single-level knowledge directory. Set the field
+explicitly when a multi-segment namespace such as
+`personal-user.123/package` is required. Context isolates OKF roots under the
+complete value; Skill names remain author-maintained and independent.
 
-## Boundary
+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.
 
-The SDK stays declarative:
+## State Boundary
 
-- `defineProject`
-- `source`, `allSources`
-- `extractTs`, `reviewValidity`, `customPhase`
-- `kbPackage`, `llmsPackage`
-- source registry reading and validation helpers
+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/`.
 
-The CLI owns:
+## Documentation
 
-- source materialization
-- extraction
-- review HTML and review apply
-- approved Markdown materialization
-- package build
-- verification
-- status and next-step guidance
+- [Documentation index](./docs/README.md)
+- [Getting Started](./docs/getting-started.md)
+- [Agent Guide](./docs/guides/agent-guide.md)
+- [Project API](./docs/reference/project-api.md)
+- [Package Outputs](./docs/guides/package-outputs.md)
+- [Package Templates](./docs/reference/package-templates.md)
+- [Template Variables](./docs/reference/template-variables.md)

package/README.zh-CN.md

@@ -0,0 +1,118 @@
+# 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` 候选。 |
+| `alignProse()` 和 `compileProse()` | 整理文档证据，并生成与来源绑定的知识候选。 |
+| `reviewValidity()` | 声明单个知识类型或整个项目的审核门禁。 |
+| `customPhase()` | 在内置阶段无法覆盖时增加项目专用编排。 |
+| `kbPackage()` | 使用审核通过的知识和模板构建 Agent 知识库。 |
+| `llmsPackage()` | 构建供模型上下文或 RAG 导入使用的单文件文本包。 |
+
+优先使用内置阶段。`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 包默认使用包 `name` 作为 `distribution.knowledgeNamespace`，生成简短的
+单级知识目录。需要 `personal-user.123/package` 这类多段目录时可以显式配置该字段。
+Context 会按照完整 namespace 隔离各个 OKF 根目录；Skill 名称仍由作者独立维护。
+
+如果需要更强的路由和检索能力，模板可以携带 `query.ts` 一类本地脚本，再由 Skill 约定 Agent 何时、如何调用。Skill 也可以把 Agent 路由到 MCP、CLI 或其他工具，组成适合当前知识包的 Agentic Search 流程。
+
+## 状态边界
+
+SDK 只负责声明。它可以描述读取、写入、阶段、审核和知识包选择，但来源物化、内容读取、代码提取、审核应用、正式知识写入、质量验证和构建都由 CLI 负责。不要通过直接编辑 `sources/`、`unapproved/`、`knowledge/` 或 `dist/` 来替代 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/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,14 +6,16 @@ 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.
 - [Project API](./reference/project-api.md) — `defineProject`, sources, phases, review, and packages.
 - [Package Templates](./reference/package-templates.md) — `kbPackage`, `llmsPackage`, template variables, and examples.

package/docs/getting-started.md

@@ -10,14 +10,18 @@ source boundary, then declare the matching phases in `src/index.ts`.
 context init context --dev
 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.
+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 +34,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 +103,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:
@@ -173,8 +184,8 @@ the wrong ref, ask the user before running repo operations outside the CLI.
 ### 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,7 +211,8 @@ 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;
@@ -242,8 +254,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:
@@ -311,6 +326,15 @@ 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 becomes its stable single-level knowledge namespace by
+default. Ask for a custom namespace only when the user needs another value. An
+explicit namespace may contain several concise lowercase path segments, such
+as `group/package` or `personal-user.123/package`; each segment may use letters
+and numbers joined by hyphens or dots. Do not infer custom values from
+downstream platform identifiers. 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