@c4a/context-cli 0.6.13 → 0.6.16

package/docs/document-optimization.md

@@ -0,0 +1,62 @@
+# Document revisions
+
+Document optimization is an optional build phase for source-backed prose. It
+repairs presentation-level Markdown without changing the approved knowledge
+page.
+
+Enable it during initialization:
+
+```bash
+context init context --optimize-docs
+```
+
+Or enable it in an existing workspace:
+
+```bash
+context optimize-docs enable
+context status --format json
+```
+
+When enabled, the workflow plans only new or changed fragments. The Agent may
+keep a fragment unchanged or apply a conservative replacement. Only changed
+pages receive a full revision beside their approved page:
+
+```text
+knowledge/guides/setup.md
+knowledge/guides/setup__revision.md
+```
+
+The `__revision.md` suffix is reserved. Default knowledge discovery, structure,
+search, and package selection exclude revision files. Validation and build
+associate a revision with its sibling base page and apply it under the original
+package path. A revision stores only the base digest that cannot be inferred;
+its path and revised fragments are derived. Unchanged fragments inside a full
+revision are inferred. A page with no changes stores only one derived negative
+cache key below `.tmp/context-runtime/document-optimization/`; replacement
+prose and fragment metadata are not duplicated there.
+
+After capture, review, or build, a user may ask conversationally to correct one
+existing knowledge page. Start the correction by title, approved path, or
+ViewRef:
+
+```bash
+context revise "<title, approved path, or ViewRef>" --format json
+```
+
+Context starts `route.document-revision.requested` only after resolving one
+page. Ambiguous requests return candidates instead of guessing. Edit
+reader-visible prose without changing provenance or `context:section`
+boundaries, then run `context optimize-docs validate`. A valid correction ends
+the request and the next Route offers a package build when output is stale. If
+broad document optimization was disabled, this entry activates only the target
+page and keeps every other eligible page out of the pending batch. If upstream
+content changes, the revision becomes a conflict and must be reviewed again.
+
+Disable and restore baseline output with:
+
+```bash
+context optimize-docs disable
+```
+
+Revision pages move to Context runtime recovery storage, and the next build
+uses approved knowledge directly.

package/docs/document-optimization.zh-CN.md

@@ -0,0 +1,54 @@
+# 文档修订页
+
+文档编译优化是面向来源可追溯正文的可选构建阶段。它只修复 Markdown
+排版和明显的局部问题，不修改正式知识页。
+
+初始化时开启：
+
+```bash
+context init context --optimize-docs
+```
+
+已有工作区可以运行：
+
+```bash
+context optimize-docs enable
+context status --format json
+```
+
+开启后，工作流只规划新增或发生变化的片段。Agent 可以保持片段不变，或提交
+保守的局部替换。只有实际改写的页面才在原文旁生成完整修订页：
+
+```text
+knowledge/guides/setup.md
+knowledge/guides/setup__revision.md
+```
+
+`__revision.md` 是保留后缀。默认知识发现、结构、检索和包选择都排除修订页；
+校验和构建根据文件名把它关联回同目录原文，并仍按原文件名输出。修订页只额外
+记录无法推导的原文摘要；原文路径和修订片段由文件名与正文差异推导。完整修订
+页中未变化的片段直接推导为 `keep`；整页都不修改时，运行时只保存一个页级负
+缓存键，不重复保存改写正文或片段元数据。
+
+工作区采集、审核或构建完成后，用户可以直接通过对话要求修正某篇知识。Agent
+先使用标题、正式知识路径或 ViewRef 启动修订：
+
+```bash
+context revise "<标题、正式知识路径或 ViewRef>" --format json
+```
+
+CLI 只在目标唯一时创建或复用该页修订，并由 Agent Graph 返回
+`route.document-revision.requested`。若有多个候选，Agent 必须依据当前对话选定，
+否则询问用户。Agent 只编辑面向读者的正文，不修改来源信息和
+`context:section` 边界，随后运行 `context optimize-docs validate`。校验成功后，
+请求自动结束；若产物因此过期，下一条 Route 会直接提示重新构建。即使工作区
+此前没有开启整库文档编译优化，这个入口也只激活目标页面，不会让其他页面进入
+待优化队列。上游内容变化后，旧修订页会成为冲突，不会被静默应用。
+
+关闭并恢复基础构建结果：
+
+```bash
+context optimize-docs disable
+```
+
+修订页会被移动到 Context 的运行时恢复目录，下一次构建直接使用正式知识。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c4a/context-cli",
-  "version": "0.6.13",
+  "version": "0.6.16",
   "type": "module",
   "description": "Local runtime and Agent integration for traceable knowledge production",
   "license": "MIT",
@@ -24,7 +24,7 @@
   },
   "dependencies": {
     "@c4a/agent-graph": "0.2.6",
-    "@c4a/context": "0.6.13",
+    "@c4a/context": "0.6.16",
     "commander": "^11.0.0",
     "fast-xml-parser": "^5.10.1",
     "handlebars": "^4.7.8",
@@ -36,6 +36,7 @@
     "remark-mdx": "^3.1.1",
     "remark-parse": "^11.0.0",
     "remark-stringify": "^11.0.0",
+    "sharp": "^0.35.3",
     "typescript": "^5.5.4",
     "unified": "^11.0.5",
     "web-tree-sitter": "^0.20.8",

package/plugins/VERSION

@@ -1 +1 @@
-0.6.13
+0.6.16

package/plugins/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "c4a",
   "description": "Start or continue a project-local knowledge workspace through one graph-routed entry.",
-  "version": "0.6.13",
+  "version": "0.6.16",
   "author": {
     "name": "c4a"
   },

package/plugins/claude/commands/context.md

@@ -28,8 +28,11 @@ context entry [project-dir] --language <language> --format json
 
 Use the user's explicit language choice when present; otherwise pass `zh-CN`
 for a Chinese conversation and `en` for an English conversation. Pass
-`project-dir`, `--name`, `--dev`, or `--debug` only when the user explicitly
-requested that initialization choice. Pass `--managed` only after the user
+`project-dir`, `--name`, `--dev`, `--debug`, or `--optimize-docs` only when the
+user explicitly requested that initialization choice. Treat requests to enable
+document compilation optimization, document formatting optimization, or
+equivalent conservative build-time cleanup as `--optimize-docs`. Pass
+`--managed` only after the user
 explicitly authorizes fully managed operation in this conversation.
 
 If the `context` process itself cannot start because the command is missing
@@ -59,6 +62,24 @@ Execute only `next_action.command` returned by `context entry`:
   init`, enter the project root, read the generated `AGENTS.md`, and run this
   entry again.
 
+If the user explicitly asks to correct or revise an existing approved or built
+knowledge page, first let `context entry` relocate into the existing workspace
+and evaluate its current Route once. Resolve a blocking workspace diagnostic,
+evidence-maintenance action, or already-pending Review batch first; these may
+change the approved baseline. Before continuing unrelated capture, extraction,
+package configuration, or build work, start the correction with:
+
+```bash
+context revise "<the user's page title, approved path, ViewRef, or wording>" --format json
+```
+
+When the target is unique, run the returned status command and follow
+`route.document-revision.requested`. When candidates are returned, select one
+only if the conversation identifies it uniquely; otherwise ask which page the
+user means. Never edit the approved base page or `dist/` for this operation.
+After the Route validates the revision, continue normally: Context will offer
+the package build when the correction makes its output stale.
+
 ### Conversation modes
 
 Enable debugging only when the user explicitly requests it. If initialization
@@ -69,6 +90,16 @@ before workflow evaluation. Debugging records traces below
 `.tmp/context-runtime/debug/` but does not grant workflow authority or provide
 source evidence.
 
+Enable document optimization only when the user explicitly requests it. If
+initialization is required, pass `--optimize-docs` through `context entry`; for
+an existing workspace, run `context optimize-docs enable` before workflow
+evaluation. The feature keeps approved pages source-faithful and stores only
+changed full-page revisions beside them as `knowledge/**/*__revision.md`.
+Default knowledge discovery excludes those reserved sidecars; validation and
+package compilation apply them to the matching base page.
+Follow the resulting Route instead of editing approved knowledge or package
+output by hand.
+
 For explicitly authorized fully managed operation, use:
 
 ```bash
@@ -109,6 +140,10 @@ Treat `workflow.current` as the current-step authority:
    not inside a restricted child sandbox. Follow the Route-selected procedure
    for its audit and approval contract; never invent a payload, destination, or
    substitute command.
+   Treat a code-extraction batch preview as one Route action. Read its complete
+   index-unit report and keep same-kind capability or scale decisions in the
+   single returned Gate; do not ask about modules one by one. A non-delegatable
+   extraction Gate must stop even in fully managed mode.
 4. If `configuration` is present, edit only the named project file and use the
    selected resources as its contract.
 5. After every action or configuration change, run status again. The managed

package/plugins/codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "c4a",
-  "version": "0.6.13",
+  "version": "0.6.16",
   "description": "Start or continue a project-local knowledge workspace through one graph-routed entry.",
   "author": {
     "name": "c4a"
@@ -18,7 +18,7 @@
   "skills": "./skills/",
   "interface": {
     "displayName": "C4A Context",
-    "shortDescription": "Initialize and advance a local, source-linked project knowledge workspace.\nv0.6.13",
+    "shortDescription": "Initialize and advance a local, source-linked project knowledge workspace.\nv0.6.16",
     "longDescription": "Create a Context workspace and use agent-guided next steps to register sources, run extraction, review candidates, build package outputs, and verify health without silently mutating source repositories.",
     "developerName": "c4a",
     "category": "Productivity",

package/plugins/codex/skills/context/SKILL.md

@@ -40,8 +40,11 @@ context entry [project-dir] --language <language> --format json
 
 Use the user's explicit language choice when present; otherwise pass `zh-CN`
 for a Chinese conversation and `en` for an English conversation. Pass
-`project-dir`, `--name`, `--dev`, or `--debug` only when the user explicitly
-requested that initialization choice. Pass `--managed` only after the user
+`project-dir`, `--name`, `--dev`, `--debug`, or `--optimize-docs` only when the
+user explicitly requested that initialization choice. Treat requests to enable
+document compilation optimization, document formatting optimization, or
+equivalent conservative build-time cleanup as `--optimize-docs`. Pass
+`--managed` only after the user
 explicitly authorizes fully managed operation in this conversation.
 
 If the `context` process itself cannot start because the command is missing
@@ -71,6 +74,24 @@ Execute only `next_action.command` returned by `context entry`:
   init`, enter the project root, read the generated `AGENTS.md`, and run this
   entry again.
 
+If the user explicitly asks to correct or revise an existing approved or built
+knowledge page, first let `context entry` relocate into the existing workspace
+and evaluate its current Route once. Resolve a blocking workspace diagnostic,
+evidence-maintenance action, or already-pending Review batch first; these may
+change the approved baseline. Before continuing unrelated capture, extraction,
+package configuration, or build work, start the correction with:
+
+```bash
+context revise "<the user's page title, approved path, ViewRef, or wording>" --format json
+```
+
+When the target is unique, run the returned status command and follow
+`route.document-revision.requested`. When candidates are returned, select one
+only if the conversation identifies it uniquely; otherwise ask which page the
+user means. Never edit the approved base page or `dist/` for this operation.
+After the Route validates the revision, continue normally: Context will offer
+the package build when the correction makes its output stale.
+
 ### Conversation modes
 
 Enable debugging only when the user explicitly requests it. If initialization
@@ -81,6 +102,16 @@ before workflow evaluation. Debugging records traces below
 `.tmp/context-runtime/debug/` but does not grant workflow authority or provide
 source evidence.
 
+Enable document optimization only when the user explicitly requests it. If
+initialization is required, pass `--optimize-docs` through `context entry`; for
+an existing workspace, run `context optimize-docs enable` before workflow
+evaluation. The feature keeps approved pages source-faithful and stores only
+changed full-page revisions beside them as `knowledge/**/*__revision.md`.
+Default knowledge discovery excludes those reserved sidecars; validation and
+package compilation apply them to the matching base page.
+Follow the resulting Route instead of editing approved knowledge or package
+output by hand.
+
 For explicitly authorized fully managed operation, use:
 
 ```bash
@@ -121,6 +152,10 @@ Treat `workflow.current` as the current-step authority:
    not inside a restricted child sandbox. Follow the Route-selected procedure
    for its audit and approval contract; never invent a payload, destination, or
    substitute command.
+   Treat a code-extraction batch preview as one Route action. Read its complete
+   index-unit report and keep same-kind capability or scale decisions in the
+   single returned Gate; do not ask about modules one by one. A non-delegatable
+   extraction Gate must stop even in fully managed mode.
 4. If `configuration` is present, edit only the named project file and use the
    selected resources as its contract.
 5. After every action or configuration change, run status again. The managed

package/plugins/cursor/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "c4a",
   "displayName": "C4A Context",
-  "version": "0.6.13",
+  "version": "0.6.16",
   "description": "Start or continue a project-local knowledge workspace through one graph-routed entry.",
   "author": {
     "name": "Context4AI",

package/plugins/cursor/commands/c4a-context.md

@@ -32,8 +32,11 @@ context entry [project-dir] --language <language> --format json
 
 Use the user's explicit language choice when present; otherwise pass `zh-CN`
 for a Chinese conversation and `en` for an English conversation. Pass
-`project-dir`, `--name`, `--dev`, or `--debug` only when the user explicitly
-requested that initialization choice. Pass `--managed` only after the user
+`project-dir`, `--name`, `--dev`, `--debug`, or `--optimize-docs` only when the
+user explicitly requested that initialization choice. Treat requests to enable
+document compilation optimization, document formatting optimization, or
+equivalent conservative build-time cleanup as `--optimize-docs`. Pass
+`--managed` only after the user
 explicitly authorizes fully managed operation in this conversation.
 
 If the `context` process itself cannot start because the command is missing
@@ -63,6 +66,24 @@ Execute only `next_action.command` returned by `context entry`:
   init`, enter the project root, read the generated `AGENTS.md`, and run this
   entry again.
 
+If the user explicitly asks to correct or revise an existing approved or built
+knowledge page, first let `context entry` relocate into the existing workspace
+and evaluate its current Route once. Resolve a blocking workspace diagnostic,
+evidence-maintenance action, or already-pending Review batch first; these may
+change the approved baseline. Before continuing unrelated capture, extraction,
+package configuration, or build work, start the correction with:
+
+```bash
+context revise "<the user's page title, approved path, ViewRef, or wording>" --format json
+```
+
+When the target is unique, run the returned status command and follow
+`route.document-revision.requested`. When candidates are returned, select one
+only if the conversation identifies it uniquely; otherwise ask which page the
+user means. Never edit the approved base page or `dist/` for this operation.
+After the Route validates the revision, continue normally: Context will offer
+the package build when the correction makes its output stale.
+
 ### Conversation modes
 
 Enable debugging only when the user explicitly requests it. If initialization
@@ -73,6 +94,16 @@ before workflow evaluation. Debugging records traces below
 `.tmp/context-runtime/debug/` but does not grant workflow authority or provide
 source evidence.
 
+Enable document optimization only when the user explicitly requests it. If
+initialization is required, pass `--optimize-docs` through `context entry`; for
+an existing workspace, run `context optimize-docs enable` before workflow
+evaluation. The feature keeps approved pages source-faithful and stores only
+changed full-page revisions beside them as `knowledge/**/*__revision.md`.
+Default knowledge discovery excludes those reserved sidecars; validation and
+package compilation apply them to the matching base page.
+Follow the resulting Route instead of editing approved knowledge or package
+output by hand.
+
 For explicitly authorized fully managed operation, use:
 
 ```bash
@@ -113,6 +144,10 @@ Treat `workflow.current` as the current-step authority:
    not inside a restricted child sandbox. Follow the Route-selected procedure
    for its audit and approval contract; never invent a payload, destination, or
    substitute command.
+   Treat a code-extraction batch preview as one Route action. Read its complete
+   index-unit report and keep same-kind capability or scale decisions in the
+   single returned Gate; do not ask about modules one by one. A non-delegatable
+   extraction Gate must stop even in fully managed mode.
 4. If `configuration` is present, edit only the named project file and use the
    selected resources as its contract.
 5. After every action or configuration change, run status again. The managed

package/plugins/skills/c4a-context/SKILL.md

@@ -40,8 +40,11 @@ context entry [project-dir] --language <language> --format json
 
 Use the user's explicit language choice when present; otherwise pass `zh-CN`
 for a Chinese conversation and `en` for an English conversation. Pass
-`project-dir`, `--name`, `--dev`, or `--debug` only when the user explicitly
-requested that initialization choice. Pass `--managed` only after the user
+`project-dir`, `--name`, `--dev`, `--debug`, or `--optimize-docs` only when the
+user explicitly requested that initialization choice. Treat requests to enable
+document compilation optimization, document formatting optimization, or
+equivalent conservative build-time cleanup as `--optimize-docs`. Pass
+`--managed` only after the user
 explicitly authorizes fully managed operation in this conversation.
 
 If the `context` process itself cannot start because the command is missing
@@ -71,6 +74,24 @@ Execute only `next_action.command` returned by `context entry`:
   init`, enter the project root, read the generated `AGENTS.md`, and run this
   entry again.
 
+If the user explicitly asks to correct or revise an existing approved or built
+knowledge page, first let `context entry` relocate into the existing workspace
+and evaluate its current Route once. Resolve a blocking workspace diagnostic,
+evidence-maintenance action, or already-pending Review batch first; these may
+change the approved baseline. Before continuing unrelated capture, extraction,
+package configuration, or build work, start the correction with:
+
+```bash
+context revise "<the user's page title, approved path, ViewRef, or wording>" --format json
+```
+
+When the target is unique, run the returned status command and follow
+`route.document-revision.requested`. When candidates are returned, select one
+only if the conversation identifies it uniquely; otherwise ask which page the
+user means. Never edit the approved base page or `dist/` for this operation.
+After the Route validates the revision, continue normally: Context will offer
+the package build when the correction makes its output stale.
+
 ### Conversation modes
 
 Enable debugging only when the user explicitly requests it. If initialization
@@ -81,6 +102,16 @@ before workflow evaluation. Debugging records traces below
 `.tmp/context-runtime/debug/` but does not grant workflow authority or provide
 source evidence.
 
+Enable document optimization only when the user explicitly requests it. If
+initialization is required, pass `--optimize-docs` through `context entry`; for
+an existing workspace, run `context optimize-docs enable` before workflow
+evaluation. The feature keeps approved pages source-faithful and stores only
+changed full-page revisions beside them as `knowledge/**/*__revision.md`.
+Default knowledge discovery excludes those reserved sidecars; validation and
+package compilation apply them to the matching base page.
+Follow the resulting Route instead of editing approved knowledge or package
+output by hand.
+
 For explicitly authorized fully managed operation, use:
 
 ```bash
@@ -121,6 +152,10 @@ Treat `workflow.current` as the current-step authority:
    not inside a restricted child sandbox. Follow the Route-selected procedure
    for its audit and approval contract; never invent a payload, destination, or
    substitute command.
+   Treat a code-extraction batch preview as one Route action. Read its complete
+   index-unit report and keep same-kind capability or scale decisions in the
+   single returned Gate; do not ask about modules one by one. A non-delegatable
+   extraction Gate must stop even in fully managed mode.
 4. If `configuration` is present, edit only the named project file and use the
    selected resources as its contract.
 5. After every action or configuration change, run status again. The managed

package/providers/context/actions/optimize-documents.yaml

@@ -0,0 +1,6 @@
+schema: agent-graph.action.v1
+id: optimize-documents
+runner: host
+effect: write
+handler: context.document-optimization.next
+inputSchema: schemas/document-optimization-decisions.schema.json

package/providers/context/actions/preview-extraction-batch.yaml

@@ -0,0 +1,5 @@
+schema: agent-graph.action.v1
+id: preview-extraction-batch
+runner: host
+effect: write
+handler: context.extract.preview-batch

package/providers/context/actions/revise-document.yaml

@@ -0,0 +1,5 @@
+schema: agent-graph.action.v1
+id: revise-document
+runner: host
+effect: read
+handler: context.document-revision.next

package/providers/context/codes.yaml

@@ -24,6 +24,10 @@ codes:
   - { code: route.capture.pending-target, kind: route-reason, summary: Capture the next declared document target., document: resources/procedures/document-capture.md }
   - { code: route.extract.scope-required, kind: route-reason, summary: Code extraction scope has not been confirmed., document: resources/procedures/code-extraction.md }
   - { code: route.extract.configuration-required, kind: route-reason, summary: Registered repository sources are missing extraction declarations., document: resources/procedures/project-configuration.md }
+  - { code: route.extract.capability-required, kind: route-reason, summary: One or more code index units require missing material or a narrower plan., document: resources/procedures/code-extraction.md }
+  - { code: route.extract.preview-required, kind: route-reason, summary: Preview all pending code index units before candidate writes., document: resources/procedures/code-extraction.md }
+  - { code: route.extract.ownership-required, kind: route-reason, summary: Revise the index plan so every projected page has one output owner., document: resources/procedures/code-extraction.md }
+  - { code: route.extract.scale-limit-exceeded, kind: route-reason, summary: At least one index unit exceeds the supported page limit., document: resources/procedures/code-extraction.md }
   - { code: route.extract.pending-target, kind: route-reason, summary: Extract the next pending code target before another workflow family., document: resources/procedures/code-extraction.md }
   - { code: route.document.classification-required, kind: route-reason, summary: A captured document needs an evidence-backed collection decision., document: resources/procedures/document-classification.md }
   - { code: route.prose.configuration-required, kind: route-reason, summary: A document target is missing a complete prose lifecycle declaration., document: resources/procedures/project-configuration.md }
@@ -38,5 +42,7 @@ codes:
   - { code: route.package.output-required, kind: route-reason, summary: Approved knowledge has no confirmed package output., document: resources/procedures/package-output.md }
   - { code: route.package.configuration-required, kind: route-reason, summary: Declare the confirmed package output in the Context project., document: resources/procedures/package-output.md }
   - { code: route.package.template-review-required, kind: route-reason, summary: "Replace or edit package templates, or explicitly accept the generic defaults.", document: resources/procedures/package-output.md }
+  - { code: route.document-revision.requested, kind: route-reason, summary: Apply and validate the user's requested correction on one approved knowledge page., document: resources/procedures/document-revision.md }
+  - { code: route.document-optimization.pending, kind: route-reason, summary: Resolve the current source-faithful document revision batch before building packages., document: resources/procedures/document-optimization.md }
   - { code: route.build.package-stale, kind: route-reason, summary: Build the declared package outputs from current approved knowledge., document: resources/procedures/close-and-build.md }
   - { code: route.logs.delivery-pending, kind: route-reason, summary: Send locally queued runtime logs through the configured generic sink., document: resources/procedures/close-and-build.md }