@c4a/context-cli 0.5.41-beta.6 → 0.6.0-alpha.1

package/docs/quickstart.md

@@ -0,0 +1,85 @@
+# CLI Quickstart
+
+This file is shipped with the installed CLI at `dist/docs/quickstart.md`.
+It is for users who have installed the `context` executable and need the next
+step before an agent plugin or project workspace is ready.
+
+## 1. Install Agent Plugin Entry Points
+
+Install the bundled agent plugin first:
+
+```bash
+context plugin install
+```
+
+The plugin adds the user-facing agent entries for workspace initialization and
+continuation. Exact command names depend on the host agent, but the intended
+flow is:
+
+- initialize a Context workspace through the plugin entry when available;
+- continue work through the plugin entry after a workspace exists;
+- let the agent follow `context status`, CLI diagnostics, and human gates.
+
+If the host agent has not loaded the plugin yet, restart or refresh that agent
+after installation.
+
+## 2. Create a Project Workspace
+
+Create a standalone workspace:
+
+```bash
+context init context
+```
+
+Then enter it and install dependencies:
+
+```bash
+cd context
+bun install
+```
+
+After initialization, read the workspace guidance:
+
+```text
+AGENTS.md
+```
+
+`AGENTS.md` explains the current project, SDK references, plugin Skills, and
+the safe workflow for agents. It is the project-local starting point after
+`context init`.
+
+## 3. Work Through an Agent
+
+Inside the workspace, ask the installed agent plugin to continue the workflow.
+The agent should:
+
+1. read `AGENTS.md`;
+2. run `context status`;
+3. follow the status `next` hint and CLI diagnostics;
+4. stop at human gates such as source scope, structure confirmation, review,
+   and package decisions.
+
+The CLI performs mechanical work such as source registration, capture,
+validation, review application, verify, close, and build. The agent performs
+semantic judgment only when the workflow asks for it.
+
+## 4. Manual Orientation
+
+When operating without an agent plugin, start with:
+
+```bash
+context status
+```
+
+If the command reports that no workspace exists, run `context init` first. If a
+workspace exists, prefer the next action reported by `context status` instead of
+guessing lower-level phase commands.
+
+Project-local SDK documentation is installed under:
+
+```text
+node_modules/@c4a/context/docs/README.md
+```
+
+Use those SDK docs when editing `src/index.ts` or package templates. For normal
+workflow operation, prefer the agent plugin and the workspace `AGENTS.md`.

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@c4a/context-cli",
-  "version": "0.5.41-beta.6",
+  "version": "0.6.0-alpha.1",
   "type": "module",
   "bin": {
     "context": "./cli.js"
   },
   "dependencies": {
     "commander": "^11.0.0",
+    "handlebars": "^4.7.8",
     "ink": "^5.0.0",
+    "jiti": "^2.7.0",
     "mdast-util-to-string": "^4.0.0",
     "react": "^18.3.1",
     "remark-gfm": "^4.0.1",

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

@@ -1,6 +1,6 @@
 {
   "name": "context",
-  "description": "Turn project sources into a local, source-linked knowledge workspace your agent can maintain and query.",
+  "description": "Maintain a project-local knowledge workspace through init and next-step agent guidance.",
   "version": "__VERSION__",
   "author": {
     "name": "c4a"

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

@@ -1,7 +1,7 @@
 {
   "name": "context",
   "version": "__VERSION__",
-  "description": "Turn project sources into a local, source-linked knowledge workspace your agent can maintain and query.",
+  "description": "Maintain a project-local knowledge workspace through init and next-step agent guidance.",
   "author": {
     "name": "c4a"
   },
@@ -18,8 +18,8 @@
   "skills": "./skills/",
   "interface": {
     "displayName": "C4A Context",
-    "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.",
+    "shortDescription": "Initialize and advance a local, source-linked project knowledge workspace.\nv__VERSION__",
+    "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",
     "brandColor": "#ef6f2e",
@@ -31,8 +31,8 @@
     ],
     "websiteURL": "https://github.com/context4ai/c4a",
     "defaultPrompt": [
-      "Answer from my local project knowledge with citations.",
-      "Capture new project material and update the knowledge workspace."
+      "Continue my Context workspace with the next useful step.",
+      "Inspect my Context workspace and proceed safely."
     ]
   }
 }

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

@@ -2,7 +2,7 @@
   "name": "context",
   "displayName": "C4A Context",
   "version": "__VERSION__",
-  "description": "Turn project sources into a local, source-linked knowledge workspace your agent can maintain and query.",
+  "description": "Maintain a project-local knowledge workspace through init and next-step agent guidance.",
   "author": {
     "name": "Context4AI",
     "email": "support@context4ai.dev"

package/plugin/README.md

@@ -1,130 +1,150 @@
-# Context: Build Agent-Facing Knowledge
+# Context Plugin
 
 > [中文版本](./README_CN.md)
 
 <p align="center"><img src="./assets/logo.svg" alt="C4A Context" width="180"/></p>
 
-A knowledge workflow built for small and mid-sized teams working with Agents. It compiles Feishu docs, local Markdown, code, and hand-curated business material into structured, traceable knowledge, then guides the Agent — through optimal reasoning patterns and targeted exploration of that knowledge — to deliver high-quality retrieval. Runs inside any Agent environment that supports Plugins (Skill + Command).
+Context provides agent commands for maintaining a project-local knowledge workspace. The plugin is installed globally for the agent, while each workspace keeps its own sources, pending review state, approved knowledge, and build output. Public agent entrypoints are intentionally small: initialize once, then use next-step guidance.
 
-## Why C4A Context
+Agent dialogue should follow the user's current conversation language. CLI
+commands, flags, ids, status values, JSONL keys, and `source_ref` tokens are
+protocol text and stay unchanged.
 
-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%.
+## Install
 
-## Where it fits
+Install the CLI first:
 
-**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.
+```bash
+npm i -g @c4a/context-cli
+# or
+bun add -g @c4a/context-cli
+```
 
-**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.
+Then install the bundled plugin marketplace globally:
 
-## Core capabilities
+```bash
+context plugin install
+```
 
-C4A Context creates a `.context/` workspace under your project directory (the name is configurable) and provides a complete closed loop:
+The installer resolves the plugin marketplace from the installed CLI package. Published packages use `dist/plugins`; source checkouts use the same generated tree after `bun run --filter @c4a/context-cli build`. For Codex, it materializes the bundled plugin into `~/.codex/plugins/cache/c4a/context/local/`, matching Codex's local-plugin cache convention.
 
-- **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.
+For a dry run:
 
-Day to day, work loops through **capture → compile → query & use → governance**; you don't re-run everything from scratch — update incrementally on demand.
+```bash
+context plugin install --dry-run
+context plugin path
+```
 
-<p align="center"><img src="./assets/workflow-en.png" alt="C4A Context workflow example: single-doc vs multi-doc batch" width="1280"/></p>
+## Workflow
 
-## Install
+Run commands from the context project root.
 
-Every Agent needs the `context` CLI first:
+1. Initialize a workspace:
 
-```bash
-npm i -g @c4a/context-cli
-# or
-bun add -g @c4a/context-cli
-```
+   ```bash
+   context init context
+   cd context
+   bun install
+   ```
 
-Then install the plugin matching the agent you use:
+2. Continue through the installed agent entry:
 
-| Agent | Install |
-|---|---|
-| Claude Code | `/plugin marketplace add context4ai/context`, then `/plugin install context@c4a` |
-| 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>` |
+   ```bash
+   <host-specific Context continuation command or skill>
+   ```
 
-Once installed, the agent exposes entry points like `/context:*` (Claude) or `/context-*` (Cursor).
+The continuation entry first runs `context status`, then follows CLI diagnostics. It
+executes safe mechanical `next:` steps instead of only reporting them, and stops
+at `Human gate:` / placeholder next steps, source registration, source scope
+selection, review, package output choice, or source-repo operations that require
+user approval. It must not infer repo sources or extraction scope from the
+surrounding monorepo.
+It uses lower-level CLI primitives only when the workspace state requires them:
 
-> **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.
+- `context source ...`
+- `context run ...`
+- `context review ...`
+- `context close`
+- `context build`
+- `context verify`
 
-## Manual workflow
+## SDK Manual For Agents
 
-From your project directory:
+After `bun install`, the project has a local SDK manual under:
 
-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. **Code projection** — for code snapshots, `/context:compile --aspect code <source-slug>` materializes package/category/symbol Nodes such as `pkg`, `pkg/components`, and `pkg/symbol/button`;
-4. **Align** — `/context:align` places prose material onto the Node structure, including docs or examples that should attach to existing code symbol Nodes;
-5. **Compile** — `/context:compile` lets the AI turn prose material into structured Sections;
-6. **Query** — `/context:query <question>` answers from local knowledge, citing Node and Section; code workspaces can filter mixed evidence with `--evidence code|prose|all`;
-7. **Drop** — `/context:drop <source-id>` reclaims deprecated material and its derived Sections.
+```text
+node_modules/@c4a/context/docs/
+```
 
-Each step writes readable files and a changelog under `.context/`, so you can review or roll back at any time.
+Recommended files:
 
-## Automated workflow
+- `node_modules/@c4a/context/docs/guides/agent-dialogue.md`
+- `node_modules/@c4a/context/docs/guides/agent-guide.md`
+- `node_modules/@c4a/context/docs/reference/project-api.md`
+- `node_modules/@c4a/context/docs/reference/package-templates.md`
 
-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.
+Template examples are installed at:
 
-**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.
+```text
+node_modules/@c4a/context/templates/package-templates/
+```
 
-**Core automation prompt** — paste directly to the Agent or automation tool:
+Agents should read these files instead of probing `node_modules/@c4a/context/dist`
+with ad-hoc scripts.
 
-```
-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.
+## Workspace Shape
 
-Knowledge sources (restrict to these):
-- Feishu docs: https://[URLS]
-- Local files: /local/path/*.md
+Committed project state lives in:
 
-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.
-```
+- `src/` — project flow and custom code;
+- `sources/repo/index.yaml`, `sources/file/index.yaml`, and
+  `sources/lark/index.yaml` — source registries;
+- `unapproved/entities.jsonl` — draft/rejected/deprecated metadata;
+- `unapproved/structure.yaml` — unconfirmed or confirmed prose structure draft;
+- `knowledge/` — approved Markdown;
+- `knowledge/structure.yaml` — closed structure/edge projection derived from
+  approved knowledge;
+- `dist/` — built packages;
+- `README.md`, `AGENTS.md`, `package.json`.
 
-> 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.
+Runtime scratch lives in `.tmp/context-runtime/` and is ignored.
 
-## Export & publish
+## Agent Entry Points
 
-The compiled knowledge base can be packaged for distribution:
+The global plugin exposes only the user-facing Context commands for the current workspace:
 
-- 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.
+- `init`
+- `continue`
 
-## Recommended environment
+The CLI still provides lower-level primitives, but they are not public slash
+commands. The continuation entry chooses them based on CLI output and user intent.
 
-The numbers below come from a parallel benchmark: each model runs the full c4a flow (capture → align → compile) end-to-end over the same 10-document business corpus, with no manual intervention. Quality is scored across 7 dimensions (totaling 100) based on the resulting knowledge base; duration covers the full flow from `context init` to `compile close`.
+Current source registration, document capture discipline, structure planning,
+node classification, reading density, candidate resolution, edge gates,
+source-bound section drafting, refresh/update judgment, semantic conflict
+judgment, and close guidance live in internal procedures under
+`skill-source-scope`, `skill-prose-align`, and `skill-prose-compile`.
 
-| Dimension | GPT 5.5 xh fast | GPT 5.5 m fast | Opus 4.8 | Sonnet 4.6 | DeepSeek V4 Pro | V4 Flash |
-|---|---:|---:|---:|---:|---:|---:|
-| Fact coverage | 24 | 24 | 24 | 23 | 24 | 23 |
-| Fact fidelity | 25 | 25 | 25 | 25 | 25 | 25 |
-| Structure | 15 | 15 | 15 | 14 | 15 | 14 |
-| URL | 5 | 5 | 5 | 5 | 5 | 5 |
-| Evidence link | 10 | 10 | 10 | 10 | 10 | 7 |
-| Section boundary | 9 | 9 | 8 | 9 | 9 | 3 |
-| Modeling | 9 | 9 | 8 | 8 | 7 | 6 |
-| **Total** | **97** | **97** | **95** | **94** | **95** | **83** |
-| Duration | 5m44s | 4m34s | 20m27s | 20m20s | ~9m28s | 2m37s |
+Package-time querying is generated into each built package as the
+`knowledge-query` skill. Package output decisions live in `skill-package-output`.
+The current workflow does not expose source deletion, purge, or retraction
+commands. If a user asks for that kind of lifecycle change, stop and explain
+that the current plugin has no approved gate for it; do not recreate
+file-mutating operations outside the current workflow.
 
-> GPT 5.5 xh fast / GPT 5.5 m fast run on Codex; Opus 4.8 / Sonnet 4.6 / DeepSeek V4 Pro / V4 Flash run on Claude.
+Agents should follow the current status route and internal procedures. Do not
+call or reconstruct command shapes or payload protocols that are absent from the
+current CLI/schema views.
 
-## About this repository
+The CLI performs mechanical work only. It does not clone, checkout, reset, fetch, or call an LLM silently. When source repos are missing or at the wrong commit, it reports diagnostics and expects the agent to ask the user before running external repo operations.
 
-The contents of this repository are auto-generated and published by the [c4a project](https://github.com/context4ai/c4a) — do not edit by hand.
+## Current Workflow Surface
 
-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.
+This plugin exposes the current workflow through `init` and `continue`.
+`continue` starts from `context status`, follows the status route, and delegates
+to current source/capture phases, prose align evidence views, source-bound prose
+compile, review, close, verify/build/status guidance, OKF indexes, generated
+knowledge-query skills, and declared project phase previews.
 
-License: MIT
+Agents must not simulate lifecycle or retraction work by deleting workspace
+files. Source deletion, purge, and retraction are not current plugin operations.

package/plugin/README_CN.md

@@ -1,128 +1,136 @@
-# Context: Build Agent-Facing Knowledge
+# Context Plugin
 
-> [English](./README.md)
+> [English version](./README.md)
 
 <p align="center"><img src="./assets/logo.svg" alt="C4A Context" width="180"/></p>
 
-专为 Agent 打造的中小团队知识工作流，将飞书文档、本地 Markdown、代码、人工整理的业务资料编译为结构化、可溯源的知识，再指导 Agent 通过最佳的推理模式和探查知识完成高质量检索。本工具运行在支持 Plugin （Skill + Command） 的 Agent 环境中。
+Context 提供面向 Agent 的知识工作区命令。Plugin 安装到全局 Agent 环境;每个知识工作区只保存自己的源声明、待审状态、已批准知识和构建产物。公开入口刻意收口:初始化一次,之后通过 next-step guidance 推进。
 
-## 为什么选择 C4A Context
+Agent 与用户对话时应使用当前对话语言;CLI 命令、参数、id、状态枚举、JSONL key 和 `source_ref` 属于协议文本,保持英文或原样。
 
-普通 AI 智能体在项目中查找资料，大多依赖文件检索（如 `grep`）和全文阅读。随着文档、代码体量变大，会暴露出两个核心问题：
+## 安装
 
-- **检索效率低下**：需要全盘扫描仓库内容才能定位关键信息；
-- **上下文冗余膨胀**：大量原始文本被注入上下文窗口，直接拉低后续推理质量。
+先安装 CLI:
 
-传统 RAG 虽能解决基础检索问题，但依赖 Embedding 向量分片召回存在天然缺陷：**无论在生产环节还是检索环节，向量模型都会造成关键信息丢失、语义失真，显著放大大模型幻觉问题**；同时，明明 LLM 本身的意图识别能力远强于向量相似度，前置 RAG 检索环节却先一步拉低召回质量，整体精度的上限被前置链路封顶。
+```bash
+npm i -g @c4a/context-cli
+# 或
+bun add -g @c4a/context-cli
+```
 
-C4A Context 采用全新思路：**放弃向量嵌入依赖，直接基于大模型完成知识的结构化管理与精准检索**。将各类原始资料预编译为按类型分类、带交叉引用、能溯源到原文的结构化知识单元（Section），智能体通过查询工具精准命中 Node / Section 级内容。编译阶段通过类似 Harness 的机制，让 Agent 按 CLI 的意图在小上下文窗口内循环完成知识生产任务，绕开一次性塞入大段原文造成的上下文膨胀；查询阶段直接走 CLI 在 Section 索引上命中，运行时无需调用 LLM。依托标准化编译流程与专用查询能力，知识库精度接近人工梳理效果，综合表现**显著优于**传统文件检索与通用 RAG —— benchmark 得分接近 100%。
+再把随 CLI 包发布的 plugin marketplace 安装到全局:
 
-## 适合场景
+```bash
+context plugin install
+```
 
-**生产侧 — 项目知识的长期维护**：把不同版本、不同来源的资料编译为彼此正交的结构化内容（各来源知识互不冗余、边界清晰、可独立维护），避免知识库随时间膨胀失控。尤其适合长期迭代的大型项目、多团队协作、多文档来源的复杂业务系统。
+安装器会从当前 CLI 包动态解析 marketplace 目录。发布包使用 `dist/plugins`;源码 checkout 在执行 `bun run --filter @c4a/context-cli build` 后也使用同样的生成目录。对 Codex,安装器会把随包生成的插件复制到 `~/.codex/plugins/cache/c4a/context/local/`,符合 Codex 本地插件的 cache 约定。
 
-**消费侧 — Agent 协作的高可靠工作流**：编码、线上运维、质量保障等对幻觉零容忍、要求召回稳定的场景，杜绝 Agent 编造内容。
+只查看将执行的操作:
 
-## 核心能力
+```bash
+context plugin install --dry-run
+context plugin path
+```
 
-C4A Context 在项目目录下创建 `.context/` 工作目录（目录名可自定义），提供完整闭环能力：
+## 工作流
 
-- **采集**：拉取飞书文档、本地 Markdown、代码结构、设计规范、接口文档等多源业务资料；
-- **编译**：由 AI 按统一协议将原始素材加工为结构化知识 — 并非简单摘要，而是按类型分类（spec / example / warning 等）、附带交叉引用与原文溯源的标准化 Section；
-- **检索使用**：在 Claude / Cursor / Codex 等工具中直接查询本地结构化知识，精准定位 Node 与 Section；也可将完整知识库导入其他大模型使用；
-- **知识治理**：支持废弃资料撤回，连带派生知识同步回收；自动校验知识库完整性，实现问题自愈。
+在 context 项目根目录执行命令。
 
-日常使用围绕 **采集 → 编译 → 检索使用 → 知识治理** 形成闭环，无需全量重复执行，按需增量更新。
+1. 初始化工作区:
 
-<p align="center"><img src="./assets/workflow.png" alt="C4A Context 工作流示例：单文档 vs 多文档批量" width="1280"/></p>
+   ```bash
+   context init context
+   cd context
+   bun install
+   ```
 
-## 安装
+2. 通过已安装的 Agent 入口继续推进:
 
-所有 Agent 均需先安装 `context` 命令行工具：
+   ```bash
+   <当前宿主暴露的 Context continuation command 或 skill>
+   ```
 
-```bash
-npm i -g @c4a/context-cli
-# 或
-bun add -g @c4a/context-cli
-```
+Continuation 入口会先运行 `context status`,然后跟随 CLI 诊断。安全的机械 `next:` 步骤会直接执行,不会只把命令复述给用户;遇到 `Human gate:`、带占位符的 next、source 注册、source 范围选择、审阅、package 输出选择或需要用户授权的 source repo 操作才会停下来确认。它不能根据周边 monorepo 自行推断 repo source 或提取范围,只在工作区状态需要时调用底层 CLI 能力:
 
-随后按所用 Agent 安装对应插件：
+- `context source ...`
+- `context run ...`
+- `context review ...`
+- `context close`
+- `context build`
+- `context verify`
 
-| Agent | 安装方式 |
-|---|---|
-| Claude Code | `/plugin marketplace add context4ai/context`，再执行 `/plugin install context@c4a` |
-| 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 可读的 SDK 手册
 
-安装完成后，在对应 Agent 中即可通过 `/context:*`（Claude）或 `/context-*`（Cursor）等入口调用。
+执行 `bun install` 后,项目内会有 SDK 手册:
 
-> **Tip — Claude Code 插件更新**：Claude Code 插件存在本地缓存，升级到新版本时建议先卸载旧插件，执行 `context clean-cache` 清理缓存，再重新安装，确保新版本立即生效。
+```text
+node_modules/@c4a/context/docs/
+```
 
-## 手动流程
+推荐先读:
 
-进入项目目录后：
+- `node_modules/@c4a/context/docs/guides/agent-dialogue.md`
+- `node_modules/@c4a/context/docs/guides/agent-guide.md`
+- `node_modules/@c4a/context/docs/reference/project-api.md`
+- `node_modules/@c4a/context/docs/reference/package-templates.md`
 
-1. **初始化** — `/context:init` 创建 `.context/` 工作目录；
-2. **采集** — `/context:capture <url-or-path>` 拉取飞书文档、本地 Markdown、代码快照等原始资料；
-3. **代码投影** — 对代码快照执行 `/context:compile --aspect code <source-slug>`，生成 `pkg`、`pkg/components`、`pkg/symbol/button` 这类 package/category/symbol Node；
-4. **对齐** — `/context:align` 将文档原料归位至 Node 结构，包括挂靠到已有 code symbol Node 的手册、示例和经验；
-5. **编译** — `/context:compile` 由 AI 将文档原料加工为结构化 Section；
-6. **检索** — `/context:query <问题>` 在本地知识中查询答案，返回 Node 与 Section 级引用；代码工作区可用 `--evidence code|prose|all` 区分代码证据和文档证据；
-7. **撤回** — `/context:drop <source-id>` 回收废弃资料及其派生 Section。
+模板示例在:
 
-每一步都会在 `.context/` 中留下可读文件与 changelog，支持随时回看与回滚。
+```text
+node_modules/@c4a/context/templates/package-templates/
+```
 
-## 自动化流程
+Agent 应读取这些文件,不要通过临时脚本反查 `node_modules/@c4a/context/dist`
+来猜 SDK API。
 
-完成前文「安装」步骤后，可直接让 AI Agent 或龙虾（OpenClaw）等自动化工具阅读本文档，指定项目工作区目录，引用存量知识目录自主开展全流程工作，大幅降低人工操作成本。
+## 工作区形态
 
-**环境要求**: 建议使用 Claude Opus 4.6+ 或 Codex 5.5 及以上版本，确保 Agent 能精准解析指令、处理知识编译中的决策与澄清工作。
-**自动化核心指令**：可直接复制给 Agent/龙虾工具
-```
-请你在当前目录初始化项目知识库（配置选择中文，其余参数按默认设置），并通过 context 工具完成全流程知识管理工作。
+需要提交的项目状态在:
 
-知识来源（仅限以下）：
-- 飞书文档：https://[URLS]
-- 本地文件：/local/path/*.md
-
-工作内容包括但不限于：工作区初始化、多源资料采集、知识对齐、AI 编译、检索校验。过程中所有需要澄清的细节、决策类事项（如资料优先级、编译规则微调、知识单元分类等），由你自主把控并记录操作日志，确保知识库结构化、可溯源。
-```
-> 知识建设是长期迭代的过程，涉及大量细节决策与需求澄清，自动化工具可承担大部分重复性工作，但无法完全替代人工判断；
-> 建议研发类核心知识（如代码结构、设计规范、接口细节等）在冷启阶段以人工维护为主，待知识库框架稳定后，再交由 Agent 负责增量更新与日常治理，避免核心知识偏差
+- `src/`:项目流程和定制代码;
+- `sources/repo/index.yaml`、`sources/file/index.yaml`、`sources/lark/index.yaml`:源 registry;
+- `unapproved/entities.jsonl`:draft/rejected/deprecated 元信息;
+- `unapproved/structure.yaml`:未确认或已确认的文档结构草稿;
+- `knowledge/`:approved Markdown;
+- `knowledge/structure.yaml`:由 approved knowledge 派生的结构与关系投影;
+- `dist/`:构建产物;
+- `README.md`、`AGENTS.md`、`package.json`。
 
+运行缓存放在 `.tmp/context-runtime/`,并被忽略。
 
-## 导出与发布
+## Agent 入口
 
-完整知识库支持对外打包发布：
+全局 plugin 只暴露面向用户的 Context 命令:
 
-- 导出为 **Skills** 包：`context build --format skills-pack`；
-- 导出为 **LLMs.txt**：`context build --format llms`；
-- [TODO] 发布至 **C4A 平台**，作为 MCP 服务供其他 AI 实时查询；
-- [TODO] 发布为独立 Plugin 知识包，具备与 MCP 及 CLI 同等精度的检索能力。
+- `init`
+- `continue`
 
-## 环境推荐
+CLI 仍保留底层能力,但它们不是公开 slash command。Continuation 入口根据 CLI 输出和用户意图选择要调用的底层命令。
 
-下方数据来自一次并发基准测试：每个模型在同一份 10 篇业务文档语料上端到端跑完 c4a 全流程（capture → align → compile），无人工介入。质量按 7 个维度评分（总分 100）反映产物知识库；耗时覆盖 `context init` 到 `compile close` 的全流程。
+当前 source 注册、文档 capture 纪律、structure planning、Node 分类、阅读密度、
+候选处理、edge gates、source-bound section drafting、refresh/update 判断、
+语义冲突判断和 close 指引都在 `skill-source-scope`、`skill-prose-align`、
+`skill-prose-compile` 下面的内部 procedure。
 
-| 维度 | GPT 5.5 xh fast | GPT 5.5 m fast | Opus 4.8 | Sonnet 4.6 | DeepSeek V4 Pro | V4 Flash |
-|---|---:|---:|---:|---:|---:|---:|
-| 事实覆盖 | 24 | 24 | 24 | 23 | 24 | 23 |
-| 事实忠实 | 25 | 25 | 25 | 25 | 25 | 25 |
-| 结构语义 | 15 | 15 | 15 | 14 | 15 | 14 |
-| URL | 5 | 5 | 5 | 5 | 5 | 5 |
-| 证据链 | 10 | 10 | 10 | 10 | 10 | 7 |
-| Section 边界 | 9 | 9 | 8 | 9 | 9 | 3 |
-| 建模 | 9 | 9 | 8 | 8 | 7 | 6 |
-| **总分** | **97** | **97** | **95** | **94** | **95** | **83** |
-| 总耗时 | 5m44s | 4m34s | 20m27s | 20m20s | ~9m28s | 2m37s |
+包内查询能力在构建包时生成到 `knowledge-query` skill。package 输出决策在
+`skill-package-output`。当前工作流不暴露 source 删除、purge 或撤回命令。
+如果用户要求这类生命周期变更,先停下来说明当前 plugin 没有已批准门禁;
+Agent 不得在当前工作流之外重建文件变更类操作。
 
-> GPT 5.5 xh fast / GPT 5.5 m fast 运行于 Codex；Opus 4.8 / Sonnet 4.6 / DeepSeek V4 Pro / V4 Flash 运行于 Claude。
+Agent 应按当前 status route 和内部 procedure 推进。不要调用或重建当前
+CLI/schema views 没有暴露的命令形态或 payload 协议。
 
-## 关于本仓库
+CLI 只做机械操作。它不会静默 clone、checkout、reset、fetch,也不会调用 LLM。源仓库缺失或 commit 不匹配时,CLI 只返回诊断;Agent 需要先征询用户,再决定是否执行外部 repo 操作。
 
-本仓库内容由 [c4a 项目](https://github.com/context4ai/c4a) 自动生成发布，请勿手动编辑。
+## 当前工作流入口
 
-该项目提供端到端的知识处理与托管基础设施，涵盖 CLI 工具、知识管理 Studio、MCP 服务等，预计 2026 年 5 月底开源。
+本 plugin 只暴露当前工作流入口: `init` 和 `continue`。`continue` 从
+`context status` 开始,按 status route 分发到 source/capture phase、prose
+align evidence views、source-bound prose compile、review、close、
+verify/build/status guidance、OKF indexes、生成包里的 knowledge-query skill,
+以及已声明 project phase 的只读预览。
 
-License: MIT
+Agent 不得通过直接删除 `sources/`、`knowledge/`、`unapproved/`、`dist/`
+或 `.tmp` 来模拟生命周期或撤回操作。source 删除、purge 和撤回不是当前
+plugin 操作。