@c4a/extract-go 0.6.8 → 0.6.9

package/README.md

@@ -1,18 +1,58 @@
-# @c4a/extract-go
+# Go Structure Extraction for Context
 
-Go extraction plugin for Context's `ExtractionResult v2` protocol. It extracts
-declarations, signatures, documentation, imports, calls, and common HTTP route
-registrations without applying product-specific classifications.
+[简体中文](./README.zh-CN.md)
+
+`@c4a/extract-go` provides deterministic Go structure facts for Context
+knowledge projects. It extracts declarations, signatures, documentation,
+imports, calls, and common HTTP route registrations without assigning
+product-specific meaning.
+
+This is an optional structural package. The Context runtime does not bundle it
+or add a Go lifecycle phase automatically. A knowledge project opts in through
+its own `extractCustom()` adapter, maps the returned facts to project-owned
+candidates, and keeps review, evidence, freshness, close, and build under the
+normal Context workflow.
+
+## Place in the knowledge workflow
+
+```text
+confirmed Go repository boundary
+             ↓
+Go structural index
+             ↓
+project-owned extractCustom() mapping
+             ↓
+Context candidates → review → approved knowledge
+```
+
+## Public APIs
 
 ```ts
 import { GoPlugin, indexGoRepository, indexGoSource } from "@c4a/extract-go";
 ```
 
-Use `GoPlugin` with `@c4a/extract`, or use `indexGoSource()` when a project-owned
-extractor needs detailed Go facts before building its own candidates.
-`indexGoRepository()` provides the same structural facts for a repository tree,
-with deterministic controls for include roots, tests, generated files, and
-excluded directories.
+- `GoPlugin` implements the standard `@c4a/extract` plugin protocol.
+- `indexGoSource()` parses one source unit when an adapter needs detailed facts
+  before producing candidates.
+- `indexGoRepository()` indexes a repository tree with deterministic controls
+  for include roots, tests, generated files, and excluded directories.
 
-This package is optional. Context CLI does not bundle it or add a Go lifecycle
-phase. A knowledge project opts in from its own `extractCustom()` callback.
+The output remains code-grounded. Package naming, business categories,
+knowledge paths, candidate summaries, and approval decisions belong to the
+knowledge project and its Agent workflow.
+
+## When to use it
+
+Use this package when a Context workspace needs Go symbols or relationships and
+the project can define how those structures should become knowledge. Do not add
+a generic Go phase solely to avoid writing the project mapping: a language
+parser cannot know the audience, product boundaries, or useful knowledge shape.
+
+## Development
+
+```bash
+bun run --filter @c4a/extract-go build
+bun run --filter @c4a/extract-go typecheck
+bun run --filter @c4a/extract-go test
+bun run --filter @c4a/extract-go lint
+```

package/README.zh-CN.md

@@ -1,15 +1,51 @@
-# @c4a/extract-go
+# Context Go 结构提取
 
-面向 Context `ExtractionResult v2` 协议的 Go 提取插件。它提取声明、签名、
-文档、导入、调用关系和常见 HTTP 路由注册，不加入任何业务分类。
+[English](./README.md)
+
+`@c4a/extract-go` 为 Context 知识项目提供确定性的 Go 结构事实。它提取声明、签名、
+源码文档、导入、调用关系和常见 HTTP 路由注册，但不赋予产品专属含义。
+
+这是可选结构包。Context 运行时不会内置它，也不会自动增加 Go 生命周期阶段。知识
+项目通过自己的 `extractCustom()` Adapter 显式使用，把结构事实映射成项目候选；
+审核、证据、新鲜度、close 和构建继续由标准 Context 工作流负责。
+
+## 在知识生产链中的位置
+
+```text
+已确认的 Go 仓库边界
+          ↓
+Go 结构索引
+          ↓
+项目自有 extractCustom() 映射
+          ↓
+Context 候选 → 审核 → 正式知识
+```
+
+## 公开 API
 
 ```ts
 import { GoPlugin, indexGoRepository, indexGoSource } from "@c4a/extract-go";
 ```
 
-标准代码图谱使用 `GoPlugin`；项目自有提取器需要先读取细粒度 Go 事实时，
-可以直接使用 `indexGoSource()`。`indexGoRepository()` 提供仓库级结构事实，
-并通过确定性参数控制扫描根目录、测试文件、生成文件和排除目录。
+- `GoPlugin` 实现标准 `@c4a/extract` 插件协议；
+- `indexGoSource()` 解析一个源码单元，供 Adapter 在生成候选前读取细粒度事实；
+- `indexGoRepository()` 索引仓库树，并通过确定性参数控制 include root、测试文件、
+  生成文件和排除目录。
 
-这是可选包。Context CLI 不会内置它，也不会新增 Go 生命周期阶段；知识项目
-需要在自己的 `extractCustom()` 回调中显式使用。
+输出始终由代码事实支撑。package 命名、业务分类、知识路径、候选摘要和审核决定属于
+知识项目及其 Agent 工作流。
+
+## 适用场景
+
+当 Context 工作区需要 Go 符号或关系，并且项目能够说明这些结构应该如何转化为知识
+时使用本包。不要仅为了省去项目映射就添加通用 Go phase：语言解析器无法知道目标
+读者、产品边界或有价值的知识形态。
+
+## 开发
+
+```bash
+bun run --filter @c4a/extract-go build
+bun run --filter @c4a/extract-go typecheck
+bun run --filter @c4a/extract-go test
+bun run --filter @c4a/extract-go lint
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c4a/extract-go",
-  "version": "0.6.8",
+  "version": "0.6.9",
   "type": "module",
   "description": "Go extraction plugin and structural index for Context",
   "license": "MIT",