@c4a/context-cli 0.5.29-alpha.2 → 0.5.29-beta.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c4a/context-cli",
-  "version": "0.5.29-alpha.2",
+  "version": "0.5.29-beta.17",
   "type": "module",
   "bin": {
     "context": "./cli.js"

package/plugin/.claude-plugin/plugin.json.template

@@ -1,6 +1,6 @@
 {
   "name": "context",
-  "description": "Context For AI — local knowledge workspace. Capture docs, extract code structure, compile into an interlinked wiki with source-traced facts. CLI does mechanical work; agent drives compile/drop via skill protocols.",
+  "description": "Turn project sources into a local, source-linked knowledge workspace your agent can maintain and query.",
   "version": "__VERSION__",
   "author": {
     "name": "c4a"

package/plugin/.codex-plugin/plugin.json.template

@@ -1,7 +1,7 @@
 {
   "name": "context",
   "version": "__VERSION__",
-  "description": "Context For AI — local knowledge workspace. Capture docs, extract code structure, compile into source-traced local knowledge, query with citations, and govern source updates.",
+  "description": "Turn project sources into a local, source-linked knowledge workspace your agent can maintain and query.",
   "author": {
     "name": "c4a"
   },
@@ -18,18 +18,21 @@
   "skills": "./skills/",
   "interface": {
     "displayName": "C4A Context",
-    "shortDescription": "Local knowledge workspace skills for C4A.",
-    "longDescription": "Use the context CLI and bundled skills to capture project sources, align them to a Node tree, compile source-traced local knowledge, query with citations, and govern source drop or refresh workflows.",
+    "shortDescription": "Build and query a local, source-linked project knowledge workspace.\nv__VERSION__",
+    "longDescription": "Keep project knowledge current inside your repo. Capture docs, code structure, notes, and source updates; organize them into readable local knowledge; ask questions with citations; and safely handle refresh, drop, restore, and cleanup without losing traceability.",
     "developerName": "c4a",
     "category": "Productivity",
+    "brandColor": "#ef6f2e",
+    "composerIcon": "./assets/icon.svg",
+    "logo": "./assets/logo.svg",
     "capabilities": [
       "Read",
       "Write"
     ],
     "websiteURL": "https://github.com/context4ai/c4a",
     "defaultPrompt": [
-      "Use C4A Context to answer from local knowledge with citations.",
-      "Use C4A Context to compile newly captured sources into local knowledge."
+      "Answer from my local project knowledge with citations.",
+      "Capture new project material and update the knowledge workspace."
     ]
   }
 }

package/plugin/.cursor-plugin/plugin.json.template

@@ -0,0 +1,29 @@
+{
+  "name": "context",
+  "displayName": "C4A Context",
+  "version": "__VERSION__",
+  "description": "Turn project sources into a local, source-linked knowledge workspace your agent can maintain and query.",
+  "author": {
+    "name": "Context4AI",
+    "email": "support@context4ai.dev"
+  },
+  "homepage": "https://github.com/context4ai/c4a",
+  "repository": "https://github.com/context4ai/c4a",
+  "license": "MIT",
+  "logo": "assets/logo.svg",
+  "keywords": [
+    "context",
+    "knowledge",
+    "citations",
+    "agent-skills"
+  ],
+  "category": "developer-tools",
+  "tags": [
+    "knowledge",
+    "documentation",
+    "agent-skills",
+    "citations"
+  ],
+  "commands": "./commands/",
+  "skills": "./skills/"
+}

package/plugin/README.md

@@ -0,0 +1,127 @@
+# Agentic Context System Over Compiled Knowledge
+
+> [中文版本](./README_CN.md)
+
+<p align="center"><img src="./assets/logo.svg" alt="C4A Context" width="180"/></p>
+
+An Agentic knowledge system built for AI Agents. It pre-compiles Feishu docs, local Markdown, code structure, and hand-curated business material into structured, traceable knowledge, so an agent can perform high-precision search over it through a dedicated CLI.
+
+This repository is the **local standalone build of C4A System**. The full C4A System will add online services with stronger multi-user collaboration support — releasing soon.
+
+## Why C4A Context
+
+When an AI agent looks up information in a project, it mostly relies on file search (e.g. `grep`) and full-text reading. As documents and codebases grow, two problems surface:
+
+- **Slow retrieval**: the whole repo has to be scanned to locate the relevant piece;
+- **Context bloat**: large amounts of raw text are pushed into the context window, dragging down downstream reasoning quality.
+
+Vanilla RAG handles basic retrieval, but relying on Embedding-based chunk recall has inherent flaws: **vector models lose key information and distort semantics at both the indexing and retrieval stages, which significantly amplifies LLM hallucination**; meanwhile, the downstream LLM is far better at intent recognition than vector similarity, yet the upstream RAG stage already caps recall quality before the LLM gets to see it — overall accuracy is bounded by the upstream pipeline rather than by the model.
+
+C4A Context takes a different path: **drop vector embeddings entirely, and let the LLM itself drive structured knowledge management and precise retrieval**. Each piece of raw material is pre-compiled into a typed structured knowledge unit (Section, classified as spec / example / warning / faq, etc.) carrying cross-references and traceable source quotes; the agent then queries that base through dedicated tools and lands on Node / Section-level content directly. Compilation runs through a harness-style loop — the CLI orchestrates small-window iterations of knowledge production, so the agent never has to ingest the whole corpus at once; at query time the CLI hits the Section index directly, with zero LLM calls on the runtime path. Backed by a standardized compile flow and a purpose-built query CLI, the knowledge base reaches a precision close to hand-curated material and **significantly outperforms** both file search and general-purpose RAG — benchmark scores approach 100%.
+
+## Where it fits
+
+**Producer side — long-term project knowledge maintenance**: compile material from different versions and sources into orthogonal structured content (each source non-redundant, with clear boundaries, independently maintainable), so the knowledge base doesn't bloat uncontrollably over time. Particularly suited to long-running large projects, multi-team collaboration, and complex business systems with many documentation sources.
+
+**Consumer side — high-reliability agent workflows**: coding, on-call operations, QA, and similar scenarios with zero tolerance for hallucination and a need for stable, high-quality recall — eliminates fabricated agent output.
+
+## Core capabilities
+
+C4A Context creates a `.context/` workspace under your project directory (the name is configurable) and provides a complete closed loop:
+
+- **Capture** — pull in Feishu docs, local Markdown, code structure, design specs, API specs, and other multi-source business material;
+- **Compile** — let the AI process raw material into structured knowledge under a single protocol — not a summary, but typed Sections (spec / example / warning, etc.) with cross-references and source traceability;
+- **Query & use** — query local structured knowledge directly from Claude / Cursor / Codex etc., landing on Node and Section precisely; or hand the whole knowledge base to another LLM;
+- **Knowledge governance** — drop deprecated material and reclaim its derived knowledge in one go; the knowledge base self-checks integrity and self-heals.
+
+Day to day, work loops through **capture → compile → query & use → governance**; you don't re-run everything from scratch — update incrementally on demand.
+
+<p align="center"><img src="./assets/workflow-en.png" alt="C4A Context workflow example: single-doc vs multi-doc batch" width="1280"/></p>
+
+## Install
+
+Every Agent needs the `context` CLI first:
+
+```bash
+npm i -g @c4a/context-cli
+# or
+bun add -g @c4a/context-cli
+```
+
+Then install the plugin matching the agent you use:
+
+| Agent | Install |
+|---|---|
+| Claude Code | `/plugin marketplace add context4ai/context`, then `/plugin install context@context` |
+| Cursor | Dashboard → Settings → Plugins → Import → `https://github.com/context4ai/context` |
+| Codex CLI | `codex marketplace add context4ai/context` |
+| Vercel-style skills (Windsurf / OpenCode / Cline / Copilot, etc.) | `npx skills add github:context4ai/context <skill-name>` |
+
+Once installed, the agent exposes entry points like `/context:*` (Claude) or `/context-*` (Cursor).
+
+> **Tip — updating the Claude Code plugin**: Claude Code caches the installed plugin locally. When upgrading to a new version, uninstall the old plugin first, run `context clean-cache`, then reinstall — this guarantees the new version takes effect immediately.
+
+## Manual workflow
+
+From your project directory:
+
+1. **Init** — `/context:init` creates the `.context/` workspace;
+2. **Capture** — `/context:capture <url-or-path>` pulls in Feishu docs, local Markdown, code snapshots, and so on;
+3. **Align** — `/context:align` places raw material onto the Node structure;
+4. **Compile** — `/context:compile` lets the AI turn raw material into structured Sections;
+5. **Query** — `/context:query <question>` answers from local knowledge, citing Node and Section;
+6. **Drop** — `/context:drop <source-id>` reclaims deprecated material and its derived Sections.
+
+Each step writes readable files and a changelog under `.context/`, so you can review or roll back at any time.
+
+## Automated workflow
+
+After completing the **Install** step above, you can hand this document to an AI Agent (or an automation harness such as OpenClaw), point it at the project workspace and any existing knowledge base, and let it run the entire flow autonomously — cutting most of the manual work.
+
+**Environment**: Claude Opus 4.6+ or Codex 5.5+ is recommended, so the agent can resolve instructions correctly and handle the decision/clarification steps during compile.
+
+**Core automation prompt** — paste directly to the Agent or automation tool:
+
+```
+Please initialize a project knowledge base in the current directory (choose Chinese as the language; keep all other parameters as defaults), and run the full knowledge-management flow through the context CLI.
+
+Knowledge sources (restrict to these):
+- Feishu docs: https://[URLS]
+- Local files: /local/path/*.md
+
+Work includes but is not limited to: workspace init, multi-source capture, alignment, AI compile, and query validation. For any clarification or decision (source priority, compile-rule tweaks, knowledge-unit classification, etc.), make the call on your own and log every operation, keeping the knowledge base structured and traceable.
+```
+
+> Knowledge building is a long iterative process: it involves many detail-level decisions and clarifications. Automation can take over most of the repetitive work, but cannot fully replace human judgment.
+> For engineering-critical knowledge (code structure, design specs, API details, etc.), prefer manual curation during the cold-start phase; once the base is stable, hand incremental updates and day-to-day governance to the Agent to avoid drift.
+
+## Export & publish
+
+The compiled knowledge base can be packaged for distribution:
+
+- export as a **Skills** package — `context build --format skills-pack`;
+- export as **LLMs.txt** — `context build --format llms`;
+- [TODO] publish to the **C4A platform** as an MCP service for other AIs to query live;
+- [TODO] publish as a standalone Plugin knowledge package, with retrieval quality on par with the MCP service and CLI.
+
+## Recommended environment
+
+Measured behavior of Agent + model combinations across instruction following, parameter hallucination, and extraction quality (scored 0–100):
+
+| Agent | Model | Instruction following | Parameter hallucination | Extraction quality |
+|---|---|---:|---|---:|
+| Claude | Opus 4.6 / 4.7 | 95 | Almost none | 95 |
+| Codex | GPT 5.5 | 95 | Almost none | 91 |
+| Cursor | Opus 4.6 / 4.7 | 92 | Almost none | 86 |
+| Claude | DeepSeek V4 | 80 | Frequent | 55 |
+| Claude | DeepSeek V4 Flash | 65 | Frequent | 50 |
+
+**Recommendation**: prefer Claude Opus or GPT for now. DeepSeek V4 still lags in instruction following and extraction quality and needs further CLI optimization; full DeepSeek V4 adaptation is planned for v0.5.40, targeting an overall score above 90.
+
+## About this repository
+
+The contents of this repository are auto-generated and published by the [c4a project](https://github.com/context4ai/c4a) — do not edit by hand.
+
+The c4a project provides end-to-end infrastructure for knowledge processing and hosting, covering the CLI, the knowledge-management Studio, and MCP services; open-source release is planned for late May 2026.
+
+License: MIT

package/plugin/README_CN.md

@@ -0,0 +1,125 @@
+# Agentic Context System Over Compiled Knowledge
+
+> [English](./README.md)
+
+<p align="center"><img src="./assets/logo.svg" alt="C4A Context" width="180"/></p>
+
+专为 AI Agent 打造的 Agentic 知识系统，将飞书文档、本地 Markdown、代码结构、人工整理的业务资料预编译为结构化、可溯源的知识，再让智能体通过专用命令行工具，在这套知识上完成高精度检索。
+
+本仓库是 **C4A System 的本地独立可运行版本**；完整的 C4A System 将支持在线服务、更适合多人协同，即将发布。
+
+## 为什么选择 C4A Context
+
+普通 AI 智能体在项目中查找资料，大多依赖文件检索（如 `grep`）和全文阅读。随着文档、代码体量变大，会暴露出两个核心问题：
+
+- **检索效率低下**：需要全盘扫描仓库内容才能定位关键信息；
+- **上下文冗余膨胀**：大量原始文本被注入上下文窗口，直接拉低后续推理质量。
+
+传统 RAG 虽能解决基础检索问题，但依赖 Embedding 向量分片召回存在天然缺陷：**无论在生产环节还是检索环节，向量模型都会造成关键信息丢失、语义失真，显著放大大模型幻觉问题**；同时，明明 LLM 本身的意图识别能力远强于向量相似度，前置 RAG 检索环节却先一步拉低召回质量，整体精度的上限被前置链路封顶。
+
+C4A Context 采用全新思路：**放弃向量嵌入依赖，直接基于大模型完成知识的结构化管理与精准检索**。将各类原始资料预编译为按类型分类、带交叉引用、能溯源到原文的结构化知识单元（Section），智能体通过查询工具精准命中 Node / Section 级内容。编译阶段通过类似 Harness 的机制，让 Agent 按 CLI 的意图在小上下文窗口内循环完成知识生产任务，绕开一次性塞入大段原文造成的上下文膨胀；查询阶段直接走 CLI 在 Section 索引上命中，运行时无需调用 LLM。依托标准化编译流程与专用查询能力，知识库精度接近人工梳理效果，综合表现**显著优于**传统文件检索与通用 RAG —— benchmark 得分接近 100%。
+
+## 适合场景
+
+**生产侧 — 项目知识的长期维护**：把不同版本、不同来源的资料编译为彼此正交的结构化内容（各来源知识互不冗余、边界清晰、可独立维护），避免知识库随时间膨胀失控。尤其适合长期迭代的大型项目、多团队协作、多文档来源的复杂业务系统。
+
+**消费侧 — Agent 协作的高可靠工作流**：编码、线上运维、质量保障等对幻觉零容忍、要求召回稳定的场景，杜绝 Agent 编造内容。
+
+## 核心能力
+
+C4A Context 在项目目录下创建 `.context/` 工作目录（目录名可自定义），提供完整闭环能力：
+
+- **采集**：拉取飞书文档、本地 Markdown、代码结构、设计规范、接口文档等多源业务资料；
+- **编译**：由 AI 按统一协议将原始素材加工为结构化知识 — 并非简单摘要，而是按类型分类（spec / example / warning 等）、附带交叉引用与原文溯源的标准化 Section；
+- **检索使用**：在 Claude / Cursor / Codex 等工具中直接查询本地结构化知识，精准定位 Node 与 Section；也可将完整知识库导入其他大模型使用；
+- **知识治理**：支持废弃资料撤回，连带派生知识同步回收；自动校验知识库完整性，实现问题自愈。
+
+日常使用围绕 **采集 → 编译 → 检索使用 → 知识治理** 形成闭环，无需全量重复执行，按需增量更新。
+
+<p align="center"><img src="./assets/workflow.png" alt="C4A Context 工作流示例：单文档 vs 多文档批量" width="1280"/></p>
+
+## 安装
+
+所有 Agent 均需先安装 `context` 命令行工具：
+
+```bash
+npm i -g @c4a/context-cli
+# 或
+bun add -g @c4a/context-cli
+```
+
+随后按所用 Agent 安装对应插件：
+
+| Agent | 安装方式 |
+|---|---|
+| Claude Code | `/plugin marketplace add context4ai/context`，再执行 `/plugin install context@context` |
+| Cursor | Dashboard → Settings → Plugins → Import → `https://github.com/context4ai/context` |
+| Codex CLI | `codex marketplace add context4ai/context` |
+| Vercel-style skills（Windsurf / OpenCode / Cline / Copilot 等） | `npx skills add github:context4ai/context <skill-name>` |
+
+安装完成后，在对应 Agent 中即可通过 `/context:*`（Claude）或 `/context-*`（Cursor）等入口调用。
+
+> **Tip — Claude Code 插件更新**：Claude Code 插件存在本地缓存，升级到新版本时建议先卸载旧插件，执行 `context clean-cache` 清理缓存，再重新安装，确保新版本立即生效。
+
+## 手动流程
+
+进入项目目录后：
+
+1. **初始化** — `/context:init` 创建 `.context/` 工作目录；
+2. **采集** — `/context:capture <url-or-path>` 拉取飞书文档、本地 Markdown、代码快照等原始资料；
+3. **对齐** — `/context:align` 将原料归位至 Node 结构；
+4. **编译** — `/context:compile` 由 AI 将原料加工为结构化 Section；
+5. **检索** — `/context:query <问题>` 在本地知识中查询答案，返回 Node 与 Section 级引用；
+6. **撤回** — `/context:drop <source-id>` 回收废弃资料及其派生 Section。
+
+每一步都会在 `.context/` 中留下可读文件与 changelog，支持随时回看与回滚。
+
+## 自动化流程
+
+完成前文「安装」步骤后，可直接让 AI Agent 或龙虾（OpenClaw）等自动化工具阅读本文档，指定项目工作区目录，引用存量知识目录自主开展全流程工作，大幅降低人工操作成本。
+
+**环境要求**: 建议使用 Claude Opus 4.6+ 或 Codex 5.5 及以上版本，确保 Agent 能精准解析指令、处理知识编译中的决策与澄清工作。
+**自动化核心指令**：可直接复制给 Agent/龙虾工具
+```
+请你在当前目录初始化项目知识库（配置选择中文，其余参数按默认设置），并通过 context 工具完成全流程知识管理工作。
+
+知识来源（仅限以下）：
+- 飞书文档：https://[URLS]
+- 本地文件：/local/path/*.md
+
+工作内容包括但不限于：工作区初始化、多源资料采集、知识对齐、AI 编译、检索校验。过程中所有需要澄清的细节、决策类事项（如资料优先级、编译规则微调、知识单元分类等），由你自主把控并记录操作日志，确保知识库结构化、可溯源。
+```
+> 知识建设是长期迭代的过程，涉及大量细节决策与需求澄清，自动化工具可承担大部分重复性工作，但无法完全替代人工判断；
+> 建议研发类核心知识（如代码结构、设计规范、接口细节等）在冷启阶段以人工维护为主，待知识库框架稳定后，再交由 Agent 负责增量更新与日常治理，避免核心知识偏差
+
+
+## 导出与发布
+
+完整知识库支持对外打包发布：
+
+- 导出为 **Skills** 包：`context build --format skills-pack`；
+- 导出为 **LLMs.txt**：`context build --format llms`；
+- [TODO] 发布至 **C4A 平台**，作为 MCP 服务供其他 AI 实时查询；
+- [TODO] 发布为独立 Plugin 知识包，具备与 MCP 及 CLI 同等精度的检索能力。
+
+## 环境推荐
+
+不同 Agent 与模型组合在指令遵循、参数幻觉、提取质量三项上的实测表现（0–100 分）：
+
+| Agent | 模型 | 指令遵循度 | 参数幻觉 | 提取质量 |
+|---|---|---:|---|---:|
+| Claude | Opus 4.6 / 4.7 | 95 | 几乎无 | 95 |
+| Codex | GPT 5.5 | 95 | 几乎无 | 91 |
+| Cursor | Opus 4.6 / 4.7 | 92 | 几乎无 | 86 |
+| Claude | DeepSeek V4 | 80 | 经常 | 55 |
+| Claude | DeepSeek V4 Flash | 65 | 经常 | 50 |
+
+**建议**：目前优先使用 Claude Opus 或 GPT；DeepSeek V4 在指令遵循与提取质量上仍有差距，需配合 CLI 进一步优化，预计 v0.5.40 完成 DeepSeek V4 适配并达到 90+ 综合得分。
+
+## 关于本仓库
+
+本仓库内容由 [c4a 项目](https://github.com/context4ai/c4a) 自动生成发布，请勿手动编辑。
+
+该项目提供端到端的知识处理与托管基础设施，涵盖 CLI 工具、知识管理 Studio、MCP 服务等，预计 2026 年 5 月底开源。
+
+License: MIT

package/plugin/assets/icon.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 758 296" fill="none">
+  <path fill-rule="evenodd" clip-rule="evenodd" d="M647.569 0.78043C613.4 3.48518 581.318 15.3269 533.021 43.0605C527.45 46.2597 498.781 61.8832 490.42 67.9156C464.4 83.1281 440.36 99.9754 407.462 125.999C399.965 131.93 392.626 137.658 391.153 138.729C389.68 139.8 382.798 145.128 375.858 150.569C368.919 156.01 358.504 163.98 352.714 168.281L343.516 175.006L348.516 179.006C351.553 181.229 358.164 187.09 362.516 190.006L370.516 196.006L379.016 190.006C384.498 185.597 392.279 178.726 395.782 175.811C399.285 172.896 411.776 162.857 414.201 160.847C416.626 158.838 420.318 155.949 427.144 150.29C445.631 134.963 481.502 112.007 494.26 102.533C581.313 47.1925 633.705 27.2029 682.312 46.6436C688.772 50.1275 692.158 52.8781 699.014 60.2106C706.594 68.3166 708.17 70.6632 712.305 79.9992C717.792 92.3865 720.263 102.609 721.288 117.182C723.104 142.96 716.794 171.243 703.236 198.108C693.06 218.269 684.3 229.708 671.088 242.211C628.153 272.315 597.665 274.481 543.801 261.017C510.873 246.43 487.481 230.006 448.016 193.506C444.204 190.241 440.144 186.014 439.516 186.006C438.281 185.991 399.991 214.634 399.516 216.006C399.235 216.815 404.057 219.412 409.016 222.506C410.702 223.559 412.975 225.335 416.516 227.006C433.391 238.059 468.991 255.632 482.516 262.006C485.929 263.614 490.402 264.707 492.545 265.749C509.884 274.195 533.276 282.099 555.644 287.07C564.55 289.049 601.674 289.814 609.103 288.171C612.031 287.523 616.387 286.554 618.782 286.017C633.747 282.66 656.745 272.897 670.289 264.153C708.746 239.325 740.493 194.104 753.016 146.317C764.533 102.359 755.681 60.2459 728.902 31.5909C712.119 13.6333 693.371 4.36271 667.389 1.17066C661.613 0.461953 656.637 -0.0628543 656.33 0.00607299C656.023 0.0750003 652.081 0.42386 647.569 0.78043ZM122.268 6.91848C100.692 8.62683 75.6783 17.7423 58.0176 30.3336C30.2119 50.158 12.2534 76.5887 3.92103 109.95C0.744084 122.668 -0.943192 149.281 0.550004 163.097C6.34545 216.709 38.9366 261.239 87.8925 282.436C108.528 291.37 128.098 295.45 152.658 295.937C173.489 296.35 191.779 294.037 213.531 288.238C254.082 277.427 282.658 266.098 328.68 231.976C341.818 222.235 344.259 221.314 342.05 219.506C337.696 215.941 316.951 199.525 316.016 199.506C315.451 199.495 312.641 202.192 307.128 205.872C245.084 247.275 198.239 258.453 151.476 252.979C138.261 251.432 123.184 247.836 114.645 244.194C82.5503 230.506 61.7452 207.016 52.8018 174.371C50.4952 165.952 50.3622 164.208 50.7059 146.886C51.0496 129.561 51.2517 127.827 53.8915 119.499C58.217 105.86 62.5516 96.3835 68.4271 87.7254C96.678 46.0924 144.857 34.898 199.322 57.3119C205.245 59.7489 221.144 67.3217 224.619 69.361C245.505 81.6138 248.559 83.5927 268.609 97.8683C286.178 110.375 299.632 125.4 316.016 139.031C330.379 150.982 332.229 144.373 335.6 144.44C337.306 142.561 337.353 141.225 335.571 139.031C334.554 137.779 334.892 138.21 331.041 133.458C307.893 104.899 285.92 82.0366 264.533 63.4627C232.185 35.3673 200.085 17.5822 168.343 10.1701C158.514 7.87465 132.964 6.07147 122.268 6.91848Z" fill="#ef6f2e"/>
+</svg>

package/plugin/assets/logo.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 758 296" fill="none">
+  <path fill-rule="evenodd" clip-rule="evenodd" d="M647.569 0.78043C613.4 3.48518 581.318 15.3269 533.021 43.0605C527.45 46.2597 498.781 61.8832 490.42 67.9156C464.4 83.1281 440.36 99.9754 407.462 125.999C399.965 131.93 392.626 137.658 391.153 138.729C389.68 139.8 382.798 145.128 375.858 150.569C368.919 156.01 358.504 163.98 352.714 168.281L343.516 175.006L348.516 179.006C351.553 181.229 358.164 187.09 362.516 190.006L370.516 196.006L379.016 190.006C384.498 185.597 392.279 178.726 395.782 175.811C399.285 172.896 411.776 162.857 414.201 160.847C416.626 158.838 420.318 155.949 427.144 150.29C445.631 134.963 481.502 112.007 494.26 102.533C581.313 47.1925 633.705 27.2029 682.312 46.6436C688.772 50.1275 692.158 52.8781 699.014 60.2106C706.594 68.3166 708.17 70.6632 712.305 79.9992C717.792 92.3865 720.263 102.609 721.288 117.182C723.104 142.96 716.794 171.243 703.236 198.108C693.06 218.269 684.3 229.708 671.088 242.211C628.153 272.315 597.665 274.481 543.801 261.017C510.873 246.43 487.481 230.006 448.016 193.506C444.204 190.241 440.144 186.014 439.516 186.006C438.281 185.991 399.991 214.634 399.516 216.006C399.235 216.815 404.057 219.412 409.016 222.506C410.702 223.559 412.975 225.335 416.516 227.006C433.391 238.059 468.991 255.632 482.516 262.006C485.929 263.614 490.402 264.707 492.545 265.749C509.884 274.195 533.276 282.099 555.644 287.07C564.55 289.049 601.674 289.814 609.103 288.171C612.031 287.523 616.387 286.554 618.782 286.017C633.747 282.66 656.745 272.897 670.289 264.153C708.746 239.325 740.493 194.104 753.016 146.317C764.533 102.359 755.681 60.2459 728.902 31.5909C712.119 13.6333 693.371 4.36271 667.389 1.17066C661.613 0.461953 656.637 -0.0628543 656.33 0.00607299C656.023 0.0750003 652.081 0.42386 647.569 0.78043ZM122.268 6.91848C100.692 8.62683 75.6783 17.7423 58.0176 30.3336C30.2119 50.158 12.2534 76.5887 3.92103 109.95C0.744084 122.668 -0.943192 149.281 0.550004 163.097C6.34545 216.709 38.9366 261.239 87.8925 282.436C108.528 291.37 128.098 295.45 152.658 295.937C173.489 296.35 191.779 294.037 213.531 288.238C254.082 277.427 282.658 266.098 328.68 231.976C341.818 222.235 344.259 221.314 342.05 219.506C337.696 215.941 316.951 199.525 316.016 199.506C315.451 199.495 312.641 202.192 307.128 205.872C245.084 247.275 198.239 258.453 151.476 252.979C138.261 251.432 123.184 247.836 114.645 244.194C82.5503 230.506 61.7452 207.016 52.8018 174.371C50.4952 165.952 50.3622 164.208 50.7059 146.886C51.0496 129.561 51.2517 127.827 53.8915 119.499C58.217 105.86 62.5516 96.3835 68.4271 87.7254C96.678 46.0924 144.857 34.898 199.322 57.3119C205.245 59.7489 221.144 67.3217 224.619 69.361C245.505 81.6138 248.559 83.5927 268.609 97.8683C286.178 110.375 299.632 125.4 316.016 139.031C330.379 150.982 332.229 144.373 335.6 144.44C337.306 142.561 337.353 141.225 335.571 139.031C334.554 137.779 334.892 138.21 331.041 133.458C307.893 104.899 285.92 82.0366 264.533 63.4627C232.185 35.3673 200.085 17.5822 168.343 10.1701C158.514 7.87465 132.964 6.07147 122.268 6.91848Z" fill="#ef6f2e"/>
+</svg>

package/plugin/commands/align.md

@@ -1,54 +1,62 @@
 ---
-description: "Align raw material into a candidate Node tree: scan → propose → user review → finalize. The CLI renders; the agent classifies."
+description: "Align raw material into a finalized Node structure and block ownership."
 argument-hint: ""
-allowed-tools: Read, Bash(context:*)
+allowed-tools: Bash(context:*)
 ---
 
-## Your task
+## Your Task
+
+Run the beta.8 align workflow. `/context:align` is the user entrypoint; internal stages are workflow payloads, not public slash commands.
+
+Keep the prompt shape stable: read fixed schema/protocol first, then existing knowledge lookup, then the current source-specific payload. Do not reorder CLI JSON, add timestamps, or invent scratch paths.
+
+1. Run `context align --scan --format json`. Use the returned workflow payload name, scope id, digest, and `next_command` / `show_command` fields as the continuation handles.
+   - If the align-segments payload includes `generation_policy`, use it as the language contract for generated Node titles, summaries, rationale prose, and planned Section wording. Preserve product names, code identifiers, slugs, flags, and citation tokens exactly when needed.
+2. Read schema and payloads through CLI only:
+   - `context schema align-segments`
+   - `context schema align-coarse-read`
+   - `context schema align-candidate-ops`
+   - `context schema align-candidate-ledger`
+   - `context schema align-candidate-aggregate`
+   - `context schema align-structure-decision`
+   - `context workflow show --payload align-segments --view segment --unwrap --format json`
+   - `context workflow show --payload align-segments --view blocks --unwrap --format json` (summary only)
+   - `context workflow show --payload align-segments --view windows --unwrap --format json`
+   - Drill into content only with semantic filters such as `--window <window-id>`, `--heading <prefix>`, `--range <start:end>`, or `--token-budget <n>`.
+   - `--unwrap` only removes the workflow metadata envelope. It does not turn a summary view into detail output.
+3. Reuse existing knowledge before inventing candidates. For named terms or entities, prefer `context mdrive glossary match <name>` and `context mdrive node list --format json` over direct file reads. Treat `match.kind`, `match.matched`, and `match.rank` as stable lookup hints: exact title/slug/alias hits should usually reuse the existing Node instead of creating another one.
+4. Submit generated workflow payloads directly through stdin, preferably as JSON. Use YAML schemas only for reading examples when helpful; generated artifacts should avoid YAML quoting/indentation failure loops. Do not create `/tmp` or workspace scratch files for align payloads. The CLI owns ids, reducer validation, workflow payload storage, and mechanical aggregate. You own semantic discovery, Node type/tag decisions, structure decisions, and user-facing questions.
+   - Save coarse-read with `context align --coarse-read - --format json`.
+     The latest `align-coarse-read` payload is only the most recent checkpoint; durable multi-source reading notes are stored under `align-candidate-ledger.source_readings`.
+     Submit coarse-read payloads serially within one workflow; workflow payload writes are not a parallel ingestion API.
+   - Submit each candidate batch with `context align --ops - --format json`.
+   - After the first batch, pass the current ledger digest as `--ledger-digest <digest>` so stale batches are rejected.
+   - Read the resulting payloads with `context workflow show --payload align-candidate-ledger --view ledger --unwrap --format json` and `context workflow show --payload align-candidate-aggregate --view aggregate --unwrap --format json`. To revisit one source's coarse-read notes, add `--source <source-id>` to the ledger view; candidates do not carry source ids, so add `--status` or `--candidate-id` only when you also need candidate rows.
+5. If any CLI command returns `agent_hints[]`, follow those hints before retrying. Legacy-protocol hints mean the submitted payload or schema name is retired; switch to the beta.8 schema named in the hint instead of adapting old fields.
+6. Finalize only with `align-structure-decision`:
 
-Orchestrate the three-skill align pipeline. Workspace reads go through `context workspace`; workflow writes go through `context align` domain commands. Every rendered markdown artifact under `output/` is rendered by the CLI; your outputs are the structured JSON / YAML each skill consumes.
+```bash
+context align --finalize - --digest <segments-digest>
+```
 
-First run `context workspace locate --format json` and use `ctxDir` from that JSON as `WORKSPACE_DIR`. In embedded layout it is the `.context/` directory; in root layout it is the current knowledge repo root. Use `WORKSPACE_DIR/output/...` below; do not assume `.context/output/...`.
+If `align-segments.incremental.mode` is `incremental`, the finalize step is a delta merge: submit only the Nodes and block ownership supported by the current scanned sources, and reference previous finalized Nodes when they are parents, dependencies, domain children, owners, or visibility targets. Absence of an old Node or edge is not a delete signal. Do not redeclare an old parent/domain just to attach a new child. `sections[].owner` must be a Node declared in the current payload; previous finalized Nodes can be referenced structurally but do not receive new section plans from this incremental payload. Existing or previously removed Node slugs cannot change `node_type`; `context align --scan --full` does not bypass that guard. Use a new slug for a different type, or retire the old slug through `context drop` or explicit structure correction before re-aligning.
 
-1. Run `context align --scan` to write `WORKSPACE_DIR/output/align.scan.yaml`. This is incremental by default: scan v2 separates `incremental.structure_changed[]` / `incremental.new_sources[]` from `incremental.content_changed_only[]`. Use `context align --scan --full` only when the user explicitly asks to rebuild the whole structure or when you are repairing a corrupted align artifact; it does not clean or reset the incremental cache.
-   - Read the scan with `context workspace read output/align.scan.yaml --format text`. If `incremental.unknown_sources[]` is non-empty, surface the reasons and ask the user whether to continue with a full scan or repair cache/source state first. Do not classify unknown input as unchanged.
-   - If `incremental.structure_changed.length + incremental.new_sources.length` is `0`, stop before align-scan / align-propose / align-finalize. Report `0 structural changes`; if `incremental.content_changed_only[]` is non-empty, tell the user those sources belong to `/context:compile`.
-2. Read `${CLAUDE_PLUGIN_ROOT}/skills/align-scan/SKILL.md` and follow its procedures. Use `context workspace read <path>` for evidence from the scan, then save the decisions with `context align --save-scan-decisions -`.
-3. Read `${CLAUDE_PLUGIN_ROOT}/skills/align-propose/SKILL.md` and follow its procedures. Pass the resulting YAML to `context align --propose - --save-input` so the CLI writes `WORKSPACE_DIR/output/align.propose.md` + `.yaml` and keeps the consumed input as an archived workflow artifact.
-4. Read `${CLAUDE_PLUGIN_ROOT}/skills/align-scan/references/user-question-contract.md`. Show `align.propose.md` to the user from `context workspace read output/align.propose.md --format text`, then gather only the decisions that affect business meaning, retrieval granularity, source validity, or user-visible organization. Use the host's multi-choice tool (Claude Code `AskUserQuestion`, Codex `ask_user_question`, Cursor Plan Mode `AskQuestion`); fall back to markdown A/B choices otherwise.
-   - Before asking, explain in 1-2 short sentences what you found and what the decision will affect.
-   - Ask in the user's language, but do not expose internal model terms such as Node, Section, Concept, Entity, Domain, contains, related_to, source_ref, raw, slug, or mount matrix.
-   - Do not ask implementation-only questions. Apply the safe default and mention it in the summary.
-   - Save the answers with `context align --save-user-decisions -` in the internal shape defined in the align-finalize reference.
-5. Read `${CLAUDE_PLUGIN_ROOT}/skills/align-finalize/SKILL.md` and follow its procedures. Pass the resulting YAML to `context align --finalize - --save-input` so the CLI writes `WORKSPACE_DIR/output/align.md` + `bind.yaml`.
-6. `context align --finalize` archives align intermediates under `WORKSPACE_DIR/output/archive/` and leaves only the current `align.md` + `bind.yaml` at the output root. Do not move, delete, or archive workspace `output/` files yourself; the CLI owns that lifecycle. Run `context doctor`; the output-align group must be green. On failure, fix the structured input and re-run step 5; never patch rendered files by hand.
+For large finalize decisions, use `block_ownership_defaults[]` instead of enumerating every block. Each default names a `source_id` plus the same ownership fields as a block-level entry except `block_id`; the CLI expands it across that source's coverable blocks. Put only exceptions in `block_ownership[]`, which override defaults for their `block_id`. Keep the payload on stdin; do not generate temp JSON files just to list hundreds of ownership rows.
 
-For large JSON / YAML payloads, use a direct heredoc into the `context` command:
+If a source is only navigation or placeholder context, keep the Node only when the graph/slug is still useful: set `planned_sections: []`, mark the navigation evidence `context_only` or `ignored` as appropriate, and do not promote relation lines to `owned` just to satisfy citations. Compile close will materialize an empty placeholder Node with no active Sections.
 
-```bash
-context align --save-scan-decisions - <<'JSON'
-{
-  "scan_version": 2,
-  "workspace": "example",
-  "existing_nodes": [],
-  "new_candidates": [],
-  "ambiguous": [],
-  "orphans": [],
-  "decisions": { "notes": "" }
-}
-JSON
-```
+Do not submit legacy candidate tables, old patch payloads, or full-tree proposal files. Do not write `knowledge/`; align finalize writes finalized workflow artifacts and source ownership only.
+
+## Constraints
 
-Do not pipe a heredoc through another command, and never redirect generated content into workspace files.
+- Node types are `domain`, `entity`, and `action`.
+- Document structure uses `nodes[].contains_parent` and `edges[].edge_type = "depends_on"` only.
+- Section-local references stay in `refers_to_nodes[]`; do not project them into Node edges.
+- Semantic boundary failures should become downgrade warnings or unresolved items. Do not retry the same semantic judgment in a loop.
+- Hard reference failures must be repaired at the exact op/path with a valid id/ref from the current payload. Use CLI `agent_hints[]` as the repair contract when present.
+- Do not read or modify source snapshots, caches, or rendered workflow artifacts with generic tools. Use `context workflow show`, schema commands, payload name, scope id, digest, and candidate ids as the workflow contract.
+- Do not pipe `context ... --format json` through `jq`, `head`, `tail`, `sed`, `cat`, `2>&1`, Python, Node.js, or shell scripts. Do not read host persisted output files such as Claude `tool-results/**`. Consume complete CLI stdout directly. Use compact views plus `--window` / `--heading` / `--range` / `--token-budget` when the full payload is too large.
 
-Final report contract:
+## Final Report
 
-- Report in the user's conversation language.
-- Keep a stable structure with these semantic sections; translate section headings into the user's conversation language instead of copying these English labels verbatim:
-  1. Completion headline.
-  2. A compact table with final Node count by type, deepest `contains` depth, and unmatched mention count.
-  3. If unmatched mention count is non-zero, list the mentions and state whether they are intentional demotions / rejected candidates or unresolved problems according to `context doctor` + `decisions.notes`; do not call intentional demotions a failed align when doctor is green.
-  4. Output files as clickable markdown links. Use absolute path targets without `file://`, for example `[align.md](/abs/path/.context/output/align.md)`. Always include `WORKSPACE_DIR/output/align.md` and `WORKSPACE_DIR/output/bind.yaml`; include the latest align archive directory if you mention archival.
-  5. Next step pointing at `/context:compile` to synthesise knowledge, or another `/context:align` pass to revise structure.
-- Do not expose internal model jargon beyond filenames, command names, and counts already printed by the CLI.
-- Never use Read / Glob / Grep / Write against `WORKSPACE_DIR`; use `context workspace` / `context mdrive` instead.
+Report in the user's language. Include final Node counts by type, unresolved ownership count, workflow payload identifiers, and the next step (`/context:compile` or another `/context:align` pass for unresolved structure).

package/plugin/commands/capture.md

@@ -1,6 +1,6 @@
 ---
-description: "Capture a URL / local .md file(s) / stdin path list / inbox / refresh all active remote sources into workspace raw/."
-argument-hint: "[url | ./path.md [./more.md...] | --stdin | --inbox | --refresh]"
+description: "Capture URLs, local Markdown, source code, stdin path lists, inbox/refresh sources, or conversation notes as Context sources."
+argument-hint: "[url | ./path.md [./more.md...] | --code [path] | --stdin | --inbox | --refresh | note]"
 allowed-tools: Bash(context:*, brew:*, curl:*, sh:*, scoop:*, choco:*, lark-cli:*), WebFetch
 ---
 
@@ -12,7 +12,7 @@ length exemption for self-contained slash commands.
 
 ## Your task
 
-Capture is entirely CLI-driven — your role is to route the right `context capture` invocation and relay its output. Never hand-write under workspace `raw/`: the CLI owns normalisation (NFC, BOM strip, line endings) and the `content_hash` contract, so any manual edit breaks idempotency.
+Capture is entirely CLI-driven — your role is to route the right `context capture` invocation and relay its output. Never hand-write captured source snapshots: the CLI owns normalisation (NFC, BOM strip, line endings) and the `content_hash` contract, so any manual edit breaks idempotency.
 
 ### Route by argument
 
@@ -21,7 +21,19 @@ Capture is entirely CLI-driven — your role is to route the right `context capt
 - User provides a long newline-separated path list → pass it to `context capture --stdin` with a direct heredoc.
 - `$ARGUMENTS` contains `--inbox` → `context capture --inbox`.
 - `$ARGUMENTS` contains `--refresh` → `context capture --refresh`.
-- User asks for `code` / `--type code` → redirect to `/context:capture-code`.
+- User asks for code capture with explicit `--module` flags → run `context capture --code $ARGUMENTS`, preserving code flags such as `--module`, `--version`, `--version-from`, and `--no-runner-cache`.
+- User asks to refresh/re-capture an already configured code source → run `context capture --code` unless the user explicitly wants to change package selection or version flags. The CLI reuses stored `capture_config`, appends a new snapshot only when code/version content changes, and never overwrites prior snapshots.
+- User asks for code capture without explicit `--module` flags → first run `context capture --code $ARGUMENTS --plan --format json`.
+  - Present only candidate package name, module path, and version. Do not show file counts or the derived path filter.
+  - Ask the user which package paths to capture. If the host interaction supports multi-select, allow multi-select; otherwise ask the user to reply with one or more package paths/names.
+  - Then run `context capture --code` with one repeated `--module <path>` for every selected package. The CLI derives and stores path filtering silently from that selection.
+- User asks to record conversation material, a decision, a revision intent, or a temporary observation → use note capture:
+  - Classify once as `revision`, `decision`, or `brainstorm`; temporary observations are `brainstorm`. If unclear, ask one clarification.
+  - For `revision` or `decision`, require an existing target. If missing, run `context query --intent node_search <user words>` and ask the user to confirm a Node or Section before writing.
+  - Write the body to `context capture --note --intent <intent> --anchor <node-slug>[#<section-id>] --input -` for anchored notes, or omit `--anchor` for brainstorm.
+  - For `revision`, organize the stdin Markdown with headings: `旧上下文`, `修改意图`, `新内容`, `验证条件`.
+  - For `decision`, organize the stdin Markdown with headings: `议题`, `选项`, `决议`, `理由`.
+  - After capture, run `context status --format json` and base the user-facing next step on `next_step.command` / `workflow.next_step`.
 
 For stdin batches, use this shape:
 
@@ -38,11 +50,12 @@ Do not pipe the heredoc through another command, and do not discover files with
 
 Report the CLI output verbatim. If the CLI reports `N sources changed`, suggest the right next step:
 
-- Run `context workspace locate --format json` and use `ctxDir` as `WORKSPACE_DIR`.
-- `WORKSPACE_DIR/output/align.md` does not exist (first-time path) → suggest `/context:align` (required before compile).
-- `WORKSPACE_DIR/output/align.md` exists → suggest `/context:compile`. Mention `/context:align` as an option if the user wants to revise the structure.
+- Run `context status --format json` and use its `next_step.command` / `workflow.next_step`.
+- If status says aligned knowledge is missing or alignment is required → suggest `/context:align`.
+- If status says compile work is pending for Markdown / evidence-backed knowledge → suggest `/context:compile`. Mention `/context:align` only if the user wants to revise the structure.
+- If the capture was code-only and status explains that code compile projection is not available yet, do not suggest `/context:compile`; report that the code-aspect source snapshot was captured and active knowledge generation is a later code projection capability.
 
-Never suggest `/context:compile` when no align plan exists — compile refuses to run without one.
+Never suggest `/context:compile` when no align plan exists or when the only active source is `aspect:code` raw snapshot data — compile refuses prose-less work and must not be used to hand-build code knowledge.
 
 ### Missing dependency recovery
 
@@ -60,8 +73,11 @@ Your prose to the user follows the user's conversation language. CLI commands, f
 
 ### Invariants
 
-- `raw/<type>/*.md` and `raw/aspect/**` are immutable post-write — the CLI only ever appends new snapshots.
-- `raw/_sources.yaml` is the authoritative source registry; `raw/<type>/_index.md` files are derived caches (prefer files-on-disk when they disagree).
+- Captured source snapshots are immutable post-write — the CLI only ever appends new snapshots.
+- The source registry is authoritative; derived index files are not Agent workflow inputs.
 - Local `.md` source identity follows the captured file's stable origin path, not its H1/title. If the user edits the title but captures the same path again, the CLI appends a new snapshot to the same `local:*` source.
-- `raw/aspect/code/latest` is a symlink to the most recent bucket — never hard-code a dated bucket name.
+- In `--format json`, code capture runner cache state is authoritative in `result.runner.cacheMode`: `prepared` means a workspace runner was prepared, `cached` means workspace cache hit, and `bypass` means `--no-runner-cache` used a temporary runner directory instead of the workspace runner cache.
+- Aspect snapshots default to `evidence.mode: none`. Prose-like custom aspects must opt in with `evidence: { mode: block }` in `aspects/<name>/aspect.yaml` before they generate evidence manifests. Invalid `evidence.mode` values are reported as `evidence-policy-invalid`; they are not silently treated as `none`.
+- Code aspect snapshots ship with `evidence.mode: none`; symbols/files/edges are indexed inside the code bucket. Do not ask users to inspect or repair a code `.evidence` manifest.
+- Code aspect capture does not currently generate active knowledge Nodes. Do not ask users to run `/context:compile` just because no code Nodes appear; that is the expected boundary.
 - On duplicate capture of the same URL: identical `content_hash` → CLI skips with `unchanged`; different hash → CLI appends a new snapshot.