fluffy-context 0.6.0 → 0.7.6

package/README.md

@@ -1,225 +1,517 @@
-# Context Runtime
+# fluffy-context
 
-`fluffy-context` 正在从面向 AI 编程会话的本地 Context Runtime CLI，演进为 **Agent 无关的本地 Knowledge Runtime**。它负责自动捕获开发过程中产生的事件、候选共识、问题、不可达路径和分支工作状态，并向任意 Agent 注入有界、可验证的业务认知。
+本地优先、Agent 无关的 Context 与 Knowledge Runtime，帮助 AI 编程 Agent 保存任务状态、恢复工作上下文、复用已验证共识，并生成有界且可追溯的上下文输入。
 
-Git 仍然负责代码和真实文件变更，Issue 系统仍然负责任务，项目文档仍然负责设计；`fluffy-context` 补齐的是持续演进的项目认知层。最终架构是 `project → knowledge runtime → LLM`：CLI、MCP、Claude Hook 和未来 IDE/Agent 集成只是事件入口与信息注入适配器，而不是认知本体。
+**当前版本：0.7.6**
 
-0.6.0 在 branch-aware 注入闭环上补齐了可治理的确定性检索：迁移并启用 Runtime 后，Orient 从 v2 journal 的可重建索引检索已验证、适用的 Knowledge 与 Deadend，并返回有界的选择、排除与截断说明。v1 的 checkpoint、Note、Knowledge 与 Deadend 写入仍会最佳努力镜像为 v2 事件；Runtime 也会协调检测到的外部 v1 变更。自动产物默认仍仅进入 Candidate，Verified Knowledge 仍需治理确认。
+```text
+checkpoint → orient → compile → expand → feedback → Agent continues
+```
+
+`compile` 先返回有界的 summary 候选；Agent 只对需要的候选调用 `expand` 获取 structured 或 evidence 层。`feedback` 仍必须由调用方显式记录。
+
+`fluffy-context` 保存的是任务认知，不是项目代码备份。Git 仍是代码和文件变更的权威；Issue 系统、项目文档、`CLAUDE.md`、`AGENTS.md`、Skills 和 MCP 仍由各自系统维护。
 
-## 版本演进
+## 30 秒了解
 
-| 版本 | 主要能力 | 关键特点 |
-| --- | --- | --- |
-| 0.1.0 | 本地 Context CLI、baseline/patch Snapshot、resume、Note、Candidate Knowledge/Deadend | Git 继续作为代码权威；Context 只保存有界任务状态，不复制项目文件；checkpoint 显式触发且支持 no-op、限流与敏感路径过滤。 |
-| 0.2.0 | 确定性 Knowledge Discovery、Agent TypeScript API、可安装 Skill | Candidate 与 Verified 分离；默认只注入已验证共识；不依赖向量库、模型或远端服务。 |
-| 0.3.x | MCP `context_orient`、Claude Code Hook 与集成配置生成 | 通过 stdio MCP 和 fail-open Hook 降低 Agent 主动调用成本；集成安装仅在 `--apply` 时写入项目配置。 |
-| 0.4.0 | v2 事件 journal、v1 显式迁移、可重建投影、本地 Runtime、Git 观察 | v2 与 v1 并存；NDJSON hash chain 是 v2 权威；Runtime 仅监听 loopback 并记录分支、ref 与 HEAD 元数据。 |
-| 0.5.0 | branch-aware Orient、v1 写入镜像、Runtime 协调、宿主事件捕获 | Context 按当前 worktree/ref 选择，避免跨分支任务状态泄漏；稳定宿主 ID 才会写入限长、脱敏后的 session/prompt intent。 |
-| 0.6.0 | journal 派生的确定性检索、治理终态、可解释 Orient、显式使用反馈 | 启用 v2 后直接从可重建索引检索已验证且适用的共识；使用反馈只影响稳定排序，绝不自动验证或提升 Candidate。 |
+最常用的四类操作：
 
-所有版本均保持本地优先、显式治理与 fail-open 集成原则。v1 数据不会在迁移过程中被重写；当 v2 未启用、不可用、损坏或尚未同步时，读取接口会回退到兼容的 v1 行为。
+- `ctx checkpoint`：保存进度、完成项、待办、决策、风险和关联文件。
+- `ctx orient`：只读恢复当前任务，并检索匹配的已验证 Knowledge、Deadend 和 open Note。
+- `ctx compile`：生成带预算、来源和排除原因的 provider-neutral Context Manifest。
+- `ctx learn` / `ctx deadend`：记录可复用结论和失败方案，之后显式验证再用于普通检索。
 
-## 适用场景
+## 0.7.6 当前能力与边界
 
-- 下班前保存当前任务状态，下一次会话继续工作。
-- 以有界摘要恢复进行中的任务，降低重复阅读和 Token 消耗。
-- 让 Agent 在开始任务时获得已验证 Knowledge、匹配 Deadend 与未吸收 Note。
-- 通过 MCP 或 Claude Code Hooks 降低 Agent 主动调用 Context 工具的决策成本。
-- 记录完成项、待办、阻塞、决策、风险与已验证不可行的方案。
+| 能力 | 当前支持 |
+| --- | --- |
+| Context | 初始化、结构化 checkpoint、baseline/patch Snapshot、resume |
+| 检索 | `orient`、已验证 Knowledge/Deadend 检索、当前 Context 的 open Note |
+| Compiler | 确定性排序、字符预算、截断信息、provenance、纳入/排除原因 |
+| Manifest identity | `level`、`itemHash`、`manifestHash`、estimated token |
+| 文件活动 | 可选记录经过过滤的文件 metadata，并编译为 `activity` section |
+| Runtime | 本地 v2 Runtime、Git 观察、可选文件观察、自动唤醒和 fail-open 集成 |
+| 治理 | Knowledge/Deadend 的 candidate、verify、deprecate/obsolete、reject |
+| 集成 | Claude Code Hook、Claude Code 配置集成、MCP `context_orient`/`context_expand`、TypeScript Agent API |
 
-## 环境要求
+以下能力**不属于 0.7.6**：
 
-- Node.js `>=20.19.0`
-- Git 可选。项目在 Git 仓库内时，CLI 会记录分支与 commit。
+- 没有 `ctx clean` 或 `ctx report`。
+- 不自动创建 checkpoint、Note、Knowledge 或 Deadend。
+- 不自动把 Candidate 提升为 Verified。
+- 不提供模型总结、Embedding/向量检索、远程同步、多人协作或 Context merge。
+
+0.7.6 已支持 `context_expand`，用于按需取得已选候选的 `structured` 或 `evidence` 层；它是无状态、只读操作，不读取项目文件内容，也不自动记录 feedback。
+
+## 快速开始
 
-## 安装
+### 1. 安装
+
+要求 Node.js `>=20.19.0`。Git 可选；在 Git 项目中，Runtime 会记录当前 branch、ref 和 commit 等 metadata。
 
 ```bash
 npm install --global fluffy-context
-ctx --help
+ctx --version
 ```
 
-也可以在项目目录中使用：
+在源码工作树中开发时：
 
 ```bash
-npx fluffy-context --help
+npm install
+npm run build
+npm install --global .
 ```
 
-## 快速开始
+### 2. 初始化项目
 
-在项目根目录初始化：
+在项目根目录运行：
 
 ```bash
 ctx init
 ```
 
-这会创建本地 `.context/` 存储和 `.contextignored` 规则文件。保存阶段性工作：
+也可以显式指定路径：
+
+```bash
+ctx init --path path/to/project
+```
+
+初始化会创建本地 `.context/` 存储和 `.contextignored` 规则文件。重复执行是幂等的，不会覆盖已有 Context 或忽略规则。
+
+### 3. 保存第一个工作状态
 
 ```bash
 ctx checkpoint \
-  --title "订单状态机重构" \
-  --progress "完成状态流转梳理，正在补充异常路径测试" \
-  --completed "梳理状态转移,确认幂等策略" \
-  --pending "补充异常路径测试,运行集成测试" \
-  --decisions "订单状态由服务端状态机统一维护" \
+  --title "支付回调修复" \
+  --progress "已定位签名校验失败原因" \
+  --completed "复现问题,确认失败边界" \
+  --pending "补充回归测试,运行集成测试" \
+  --decisions "在回调入口统一执行签名校验" \
   --risks "第三方回调可能重复到达" \
-  --files "src/order/state-machine.ts,src/order-state-machine.test.ts"
+  --files "src/payment/callback.ts,test/payment/callback.test.ts"
 ```
 
-新会话中，Agent 或宿主优先使用：
+第一次包含实际结构化内容的 checkpoint 会创建 baseline Snapshot；后续变化会创建 patch Snapshot。
+
+- 内容没有变化时返回 `status: "no_change"`。
+- 默认两次实际写入之间至少间隔约 10 秒；变化过快时返回 `status: "rate_limited"` 和 `retryAt`。
+- 只有标题、没有实际结构化内容的 checkpoint 不会创建无意义 Snapshot。
+- `--last-error ""`、空列表等显式输入可以清理已有字段。
+
+查看当前状态：
 
 ```bash
-ctx orient "订单状态机异常路径" --max-chars 4000
+ctx status
+ctx resume --max-chars 2000
 ```
 
-`ctx orient` 只读地聚合当前 Context 摘要、与查询匹配的**已验证** Knowledge 和 Deadend，以及当前 Context 尚未吸收的 Note。它不更新 `lastUsedAt`、不创建 Snapshot，也不会记录 usage 噪声。省略查询时可只恢复当前任务和 open Notes：
+### 4. 在下一次会话开始时恢复
 
 ```bash
-ctx orient
-ctx orient --context <context-id> --note-limit 10
+ctx orient "支付回调签名校验" --max-chars 4000
 ```
 
-## Agent 工作流
+不带查询时只恢复当前任务和 open Note：
+
+```bash
+ctx orient
+```
 
-推荐阶段：
+## 推荐工作流
 
 ```text
 Orient → Plan → Implement → Verify → Handoff
 ```
 
-1. **Orient**：调用 `ctx orient` 或 MCP `context_orient`，读取有界任务上下文。
-2. **Plan**：在广泛改动前先形成可执行计划。
-3. **Implement**：用 `ctx note add` 记录有价值的观察、决策、阻塞或行动；不要为每条记录创建 Snapshot。
-4. **Verify**：执行适用的构建和测试，并把有意义的失败记录为 Note。
-5. **Handoff**：任务阶段结束时显式运行一次 `ctx checkpoint`，记录完成项、待办、决策和风险；Hook 不会自动 checkpoint。
+1. **Orient**：开始任务时读取当前 Context 和已验证共识。
+2. **Plan**：先形成可执行的实现计划。
+3. **Implement**：遇到重要观察、阻塞或临时决策时记录 Note。
+4. **Verify**：运行适用的测试、构建或其他检查。
+5. **Handoff**：阶段结束时显式执行一次 checkpoint，记录完成项、待办、决策和风险。
+
+Hook 只提供有界、只读的阶段提示，不会自动创建 Note 或 checkpoint。Runtime 捕获文件和 Git metadata，也不能替代 Agent 主动记录任务认知。
 
-## 常用命令
+## 核心命令
 
-业务命令默认输出格式化 JSON；帮助输出为纯文本。错误写入标准错误并返回非零退出码。`ctx --version` 输出一个 JSON 字符串。
+### `ctx orient`
+
+`orient` 是新会话和新任务的快速恢复入口：
+
+```bash
+ctx orient "身份认证回调" \
+  --scope project \
+  --max-chars 4000 \
+  --knowledge-limit 5 \
+  --deadend-limit 5 \
+  --note-limit 10
+```
+
+它返回：
+
+- 当前 Context 和 Snapshot 的有限 metadata；
+- 受字符预算限制的进度、错误、完成项、待办、决策、风险和关联文件；
+- 匹配且适用的已验证 Knowledge 和 Deadend；
+- 当前 Context 尚未吸收的 open Note；
+- v1/v2 选择方式、排除计数和截断说明。
+
+`orient` 是只读操作：不会创建 Snapshot、不会写入 Context、不会更新 `lastUsedAt`，也不会隐式记录 usage feedback。
+
+返回 `status: "no_context"` 表示项目已初始化，但还没有可恢复的有效 Context；这不是系统错误。
+
+### `ctx compile`
+
+`compile` 面向需要结构化输入的 Agent、适配器和集成方，返回 provider-neutral JSON Manifest：
+
+```bash
+ctx compile "修复支付回调" --max-chars 4000
+ctx compile "验证签名逻辑" --scenario verification --paths src/payment/callback.ts
+ctx compile "查看最近修改" --activity-limit 10 --max-chars 4000
+```
+
+Manifest 主要包含：
+
+- `intent`：规范化后的任务意图、场景、scope、paths 和预算；
+- `selected`：最终纳入的候选项；
+- `sections`：按 Context、Snapshot、Note、Knowledge、Deadend、Activity 等来源分组；
+- `excluded`：未纳入项目及其原因；
+- `provenance`：来源 Context、Snapshot、journal event 和读取状态；
+- `budget`：请求、使用、剩余字符和 section 统计；
+- `truncation`：预算或候选限制造成的截断说明；
+- `identity`：Manifest hash、选中 item hash 和 estimated token；
+- `text`：最终有界文本。
+
+0.7.6 的候选项提供：
+
+```text
+level: signal | summary | structured | evidence
+itemHash
+ tokenEstimate
+expandable
+```
+
+当前实际生成的候选项默认是 `summary` 层。`itemHash`、`manifestHash` 和 estimated token 可用于缓存、去重、审计和结果校验；token 是按字符估算的 provider-neutral 数值，不是真实 Provider 计费结果。
+
+### `ctx expand`
+
+`expand` 只接受本次 `compile` 返回的 selected candidate，并重新使用原始编译参数校验 `manifestHash`。调用方至少提供 `--candidate-id` 或 `--item-hash`，并选择 `--level structured|evidence`：
+
+```bash
+ctx compile "修复支付回调" --max-chars 4000 > manifest.json
+ctx expand --manifest-hash <manifestHash> --candidate-id <candidateId> \
+  --level structured --compile-max-chars 4000 --query "修复支付回调"
+```
+
+`--compile-max-chars` 必须与原始 compile 的预算一致；`--max-chars` 是独立的展开输出预算。展开返回 `complete` 时包含完整 structured content，超过预算则返回有界文本、`content: null` 和 `status: partial`。它不缓存 Manifest、不写入 Context/journal/projection、不执行 usage feedback，也不读取文件正文、diff、命令或 stdout/stderr。
+
+Compiler 具有以下边界：
+
+- 相同输入得到确定性的排序、截断和 hash；
+- `maxChars` 使用 JavaScript UTF-16 字符串长度；
+- 不调用模型；
+- 不写入 Context 或 journal；
+- 普通查询默认只纳入适用且已验证的 Knowledge 和 Deadend；
+- `context_expand` 只读取已选候选的安全 metadata，不读取任意项目文件内容。
+
+## Knowledge、Deadend 和 Note
+
+### Knowledge：记录可复用认知
+
+```bash
+ctx learn "支付回调必须验证网关签名" \
+  --scope project \
+  --evidence "src/payment/callback.ts,回归测试"
+```
+
+新记录默认是 `candidate`，不会进入普通检索。确认后才会进入默认发现：
 
 ```bash
-ctx init
-ctx checkpoint --title "修复支付回调" --progress "已定位签名校验失败原因"
-ctx resume --max-chars 2000
-ctx orient "支付回调" --knowledge-limit 5 --deadend-limit 3
-ctx note add "测试环境缺少回调凭据" --kind problem --context <context-id>
-ctx activity --context <context-id> --open
-ctx knowledge discover "支付回调"
 ctx knowledge verify <knowledge-id>
-ctx knowledge deprecate <knowledge-id> --reason "已被新的结论取代"
+ctx knowledge discover "支付回调"
+```
+
+治理已有记录：
+
+```bash
+ctx knowledge deprecate <knowledge-id> --reason "已被新的签名校验流程取代"
+ctx knowledge reject <knowledge-id> --reason "证据不足"
+```
+
+普通 `orient` 和 `discover` 默认只使用 `verified` 且适用的 Knowledge。需要审查候选或其他状态时，使用 `--all` 或显式 `--status`。
+
+### Deadend：记录已验证不可行方案
+
+```bash
+ctx deadend \
+  --attempt "绕过回调签名验证" \
+  --reason "回归测试失败且会引入安全风险" \
+  --scope project \
+  --evidence "test/payment/callback.test.ts"
+```
+
+确认和治理：
+
+```bash
 ctx deadend verify <deadend-id>
 ctx deadend obsolete <deadend-id> --reason "当前架构已不再适用"
-ctx feedback use knowledge <knowledge-id> --event-id <stable-id>
-ctx journal verify
-ctx migrate v1 --dry-run
-ctx migrate v1 --apply
-ctx migrate verify
-ctx runtime enable
-ctx runtime start
-ctx runtime status
-ctx runtime stop
-ctx status
-ctx doctor
+ctx deadend reject <deadend-id> --reason "失败证据不足"
 ```
 
-### v2 迁移与本地 Runtime
+Deadend 默认也是 `candidate`；只有 `verified` Deadend 才会进入普通检索。终态记录会保留治理原因，但不会默认注入。
+
+### Note：低成本记录过程信息
 
-v2 与既有 `.context/` 数据并存，迁移绝不会重写或修复 v1 文件。先执行只读检查，再显式导入并验证投影一致性：
+Note 不创建 Snapshot，适合开发过程中记录短期观察、问题、行动和决策：
 
 ```bash
-ctx migrate v1 --dry-run
-ctx migrate v1 --apply
-ctx migrate verify
+ctx note add "测试环境缺少回调凭据" \
+  --kind problem \
+  --context <context-id>
+
+ctx note add "保留原始请求体后再执行验签" \
+  --kind decision \
+  --status resolved \
+  --context <context-id>
 ```
 
-只有完成迁移后才可启用 Runtime：
+查看 Note 和只读 Activity：
 
 ```bash
-ctx runtime enable
-ctx runtime start
-ctx runtime status
-ctx runtime stop
-ctx runtime disable
+ctx note list --context <context-id> --open
+ctx activity --context <context-id> --open
+```
+
+阶段性 checkpoint 可以显式吸收当前 Context 的 open Note：
+
+```bash
+ctx checkpoint \
+  --context <context-id> \
+  --progress "完成阶段排查" \
+  --absorb-notes
 ```
 
-Runtime 是单项目、按需启动的本地守护进程。它只绑定 `127.0.0.1` 的动态端口，并要求存储在项目本地 `.context/v2/runtime/secret` 中的能力令牌；令牌不会显示在 CLI 状态输出或写入事件日志。启动后，Runtime 持续观察当前 worktree 的 Git 状态：初始状态会记录 `git.state.observed`，分支/ref 切换记录 `git.branch.changed`，HEAD 更新记录 `git.head.changed`。这些事件会重建 branch workspace 投影，但不会自动创建 checkpoint 或将候选信息提升为已验证共识。
+只有真正保存了新 Snapshot 时 Note 才会被标记为已吸收；`no_change` 和 `rate_limited` 不会改变 Note。
+
+## CLI 能力地图
+
+完整参数请使用 `ctx <command> --help`。常用命令按用途分组如下。
+
+### 日常使用
 
-完成迁移并显式 `ctx runtime enable` 后，`ctx orient`、MCP `context_orient` 与 Claude Hook 会优先选择当前 worktree/ref 的 v2 workspace；它不会借用其他分支的 Context。v2 可用时，Knowledge 与 Deadend 由 journal 重放出的确定性倒排索引直接检索，默认仅返回已验证且适用的记录；无匹配 workspace、v2 状态不可用、journal 损坏、v1 尚未同步或 Runtime 已禁用时，接口会安全回退到既有 v1 选择逻辑。Runtime 停止时仍可读取已验证的 v2 状态，但运行中的 Runtime 负责持续 Git 观察和 v1 写入镜像。
+| 命令 | 用途 |
+| --- | --- |
+| `ctx init` | 初始化 `.context/` |
+| `ctx checkpoint` | 保存 Context Snapshot |
+| `ctx resume` | 恢复完整 Context 详情 |
+| `ctx orient` | 读取有界任务上下文 |
+| `ctx compile` | 生成结构化 Context Manifest |
+| `ctx note add/list` | 记录和查看 Note |
+| `ctx activity` | 查看只读 Note/Snapshot 时间线 |
+| `ctx status` | 查看项目和 Context 索引 |
+| `ctx doctor` | 检查文件和 Snapshot 完整性 |
 
-Claude Hook 仅在宿主提供稳定的 session 与 event 标识时记录 `host.session.started` 或 `host.prompt.submitted`。提示只保存按 `promptIntentMaxChars` 截断并经过敏感值脱敏后的 intent，绝不保存原始提示；缺少稳定标识时不写入事件。默认 Hook 不启动守护进程；将 v2 policy 的 `allowHookStartup` 设为 `true` 后，SessionStart 才会在严格超时内尽力启动 Runtime，失败仍会 fail open。UserPromptSubmit 不会启动 Runtime。
+### Knowledge 与 Deadend 治理
+
+```text
+ctx learn
+ctx knowledge
+ctx knowledge discover
+ctx knowledge verify
+ctx knowledge deprecate
+ctx knowledge reject
+ctx deadend
+ctx deadends
+ctx deadend verify
+ctx deadend obsolete
+ctx deadend reject
+ctx feedback use
+```
 
-### `ctx checkpoint` 和 `ctx resume`
+`feedback use` 只记录显式的使用信号，用于确定性排序；不会改变 Knowledge/Deadend 的验证状态、confidence、证据或适用性。
 
-第一次 checkpoint 创建 baseline，后续变化创建 patch。相同内容返回 `no_change`；短时间内的变化可能返回 `rate_limited`，应在完成更多阶段工作后再保存。`ctx resume` 返回轻量摘要和按需使用的完整 details，并会保留其既有的 `lastUsedAt` 更新语义。
+### 集成入口
 
-### `ctx note` 和 `ctx activity`
+```text
+ctx integrate claude inspect
+ctx integrate claude install
+ctx integrate claude install --apply
+ctx hook claude-code session-start
+ctx hook claude-code user-prompt
+ctx agent serve
+```
 
-`ctx note add` 是开发过程中的低成本记录入口，不创建 Snapshot。阶段性 checkpoint 可通过 `--absorb-notes` 吸收当前 Context 的 open Note。`ctx activity` 提供只读的 Note 与 Snapshot 时间线，适合人类查看 Agent 的进度。
+### 高级维护
 
-### Knowledge 与 Deadend
+```text
+ctx migrate v1 --dry-run
+ctx migrate v1 --apply
+ctx migrate verify
+ctx journal verify
+ctx runtime enable
+ctx runtime disable
+ctx runtime start
+ctx runtime stop
+ctx runtime status
+ctx filesystem enable
+ctx filesystem disable
+ctx filesystem status
+```
 
-`ctx learn` 和 `ctx deadend` 默认创建 `candidate` 项。普通发现与 `ctx orient` 只使用已验证项目共识；候选项需要通过 `ctx knowledge verify` 或 `ctx deadend verify` 显式确认，或以 `--all` 审查。验证后的 Knowledge 可用 `ctx knowledge deprecate` 退役，候选项可用 `ctx knowledge reject` 拒绝；验证后的 Deadend 可用 `ctx deadend obsolete` 退役，候选项可用 `ctx deadend reject` 拒绝。终态记录保留证据与治理原因，但不会被默认注入。
+CLI 业务命令默认输出 JSON；`--help` 是面向终端用户的纯文本；错误写入 stderr 并返回非零退出码；`ctx --version` 输出 JSON 字符串。
 
-新记录默认具有 `global` 适用性。需要限制到当前 worktree/ref 时，可使用 `--branch-mode exact`；`--paths` 只保存精确项目相对路径约束，当前版本不会推断目录前缀、Git 祖先关系、依赖关系或语义相似路径。`ctx orient` 的 `explanation` 字段会有界地给出 v2/v1 选择方式、排除计数和各类别截断原因。
+## 文件活动与 Runtime
 
-`ctx feedback use knowledge|deadend ... --event-id <stable-id>` 只记录一个幂等的 v2 使用信号。它只作为同等词法相关性结果的确定性排序因素，永不改变验证状态、confidence、evidence 或适用性；Orient、MCP 与 Hook 不会隐式写入该信号。
+文件观察默认关闭，需要显式开启：
 
 ```bash
-ctx learn "订单取消后不能再次进入支付中状态" --scope project
-ctx deadend --attempt "使用共享可变单例保存订单状态" --reason "并发测试出现跨用例状态泄漏"
-ctx knowledge discover "订单取消"
+ctx filesystem enable
+ctx filesystem status
+ctx filesystem disable
 ```
 
-## MCP 集成
+观察器只记录经过过滤的项目相对路径和有限 metadata，例如文件类型、大小和修改时间：
+
+- 不记录文件内容、diff、命令或 stdout；
+- 使用与 Context 关联文件相同的 `.contextignored` 和内置保护规则；
+- `ctx compile` 的 `activity` 只表示“观察到文件发生变化”，不表示文件已被读取、理解或测试；
+- `--activity-limit 0` 只关闭单次编译中的 activity 候选，不改变监听策略；
+- v1 fallback 没有等价的文件活动来源，因此 activity section 可能为空。
 
-`ctx agent serve` 启动一个 MCP stdio server，暴露一个工具：`context_orient`。该 server 的标准输入和输出均属于 MCP 协议，不能在交互式终端直接使用或混入日志。
+完成 v1 迁移并启用 Runtime 后，Runtime 会服务于当前项目的 v2 journal、Git 观察和可选文件观察。常用控制命令：
 
 ```bash
-ctx agent serve
+ctx runtime status
+ctx runtime enable
+ctx runtime start
+ctx runtime stop
+ctx runtime disable
 ```
 
-`context_orient` 接受可选的 `path`、`contextId`、`query`、`scope`、`maxChars`、`knowledgeLimit`、`deadendLimit` 和 `noteLimit`。它的结果与 `ctx orient` 相同：`ready` 是成功的任务定位结果，初始化但没有可恢复 Context 时返回成功的 `no_context`。输入验证或 Runtime 错误为单次工具错误，不会终止 server。
+已启用项目的 CLI Orient、MCP 和 Claude Hook 会尽力自动唤醒 Runtime；启动失败不会阻塞基础读取流程。`runtime disable` 会持久化关闭自动启动，直到再次执行 `runtime enable`。
 
 ## Claude Code 集成
 
-先查看项目是否需要安装集成：
+先检查当前项目：
 
 ```bash
 ctx integrate claude inspect
+```
+
+默认安装命令只输出预览，不写文件：
+
+```bash
 ctx integrate claude install
 ```
 
-`install` 默认只输出预览，不创建或修改文件。确认后才显式写入：
+确认后显式应用：
 
 ```bash
 ctx integrate claude install --apply
 ```
 
-安装会以幂等方式合并项目本地配置：
+集成会幂等合并项目本地：
+
+- `.claude/settings.json`：`SessionStart` 和 `UserPromptSubmit` Hook；
+- `.mcp.json`：名为 `fluffy-context` 的 stdio MCP server。
+
+它会保留无关的 Hook、权限和 MCP server；遇到无效 JSON、无效结构或同名冲突时拒绝覆盖。Hook 是 fail-open 的只读提示，不会自动创建 checkpoint 或 Note。
+
+## MCP 集成
+
+启动 MCP stdio server：
+
+```bash
+ctx agent serve
+```
+
+0.7.6 当前暴露以下工具：
+
+```text
+context_orient       只读、有界地获取任务上下文
+context_expand       只读地展开 selected compiler candidate
+context_compile      只读地生成确定性 Manifest
+context_resume       恢复 Context（可能更新 lastUsedAt）
+context_note_list    只读地列出 Note
+context_note_add     显式新增 Note
+context_checkpoint   显式保存 Context/Snapshot
+```
+
+输入字段与 CLI/Agent API 对齐：
+
+- `context_orient`：`path`、`contextId`、`query`、`scope`、`maxChars` 和各 source limit；
+- `context_compile`：编译选项及 `scenario`、`paths`、`activityLimit`、`trigger` 等字段；
+- `context_expand`：`manifestHash`、`candidateId` 或 `itemHash`、`level`、独立 `maxChars` 和原始 `compile` 参数；
+- `context_resume`：`contextId`、`maxChars`、`includeDetails`、`query`、`scope`；
+- `context_note_list`：`contextId`、`openOnly`、`limit`、`maxChars`；
+- `context_note_add`：必填 `message`，以及 Note 的 `kind`、`actor`、关联 Context/Snapshot、`relatedFiles` 和 `status`；
+- `context_checkpoint`：Context 输入字段、`absorbNotes` 和可选的 `lastError`。
 
-- `.claude/settings.json`：`SessionStart` 与 `UserPromptSubmit` Hook，分别调用 `ctx hook claude-code session-start` 和 `ctx hook claude-code user-prompt`。
-- `.mcp.json`：名为 `fluffy-context` 的 stdio MCP server，调用 `ctx agent serve`。
+成功调用同时返回 JSON `content` 和 `structuredContent`。结果分别对应 CLI/Agent API 的 Manifest、load result、Note 列表、单个 Note 或 checkpoint result。Checkpoint 保留 `saved`、`no_change` 和 `rate_limited` 状态，MCP 不自动重试，也不暴露绕过限流的参数。
 
-安装会保留无关的 Hook、权限和 MCP server；遇到无效 JSON、无效相关结构或同名冲突配置会拒绝覆盖。Hook 仅注入有界的 Orient/Plan/Implement/Verify/Handoff 指引，输入损坏、项目未初始化或查询失败时会 fail open，不阻塞 Claude Code 任务，也不会自动创建 checkpoint。
+读写边界如下：
+
+- `context_orient`、`context_expand`、`context_compile` 和 `context_note_list` 是只读操作；
+- `context_resume` 使用现有 `loadContext` 语义，可能更新 `lastUsedAt`，但不会创建 Snapshot；
+- `context_note_add` 会写入 Note，但不会创建 Snapshot；
+- `context_checkpoint` 会创建或更新 Snapshot、Context metadata 和 index，并可显式吸收 Note；
+- 任何工具都不会自动创建 Knowledge、Deadend、feedback 或重复 checkpoint；
+- Knowledge/Deadend 的记录和治理暂不提供独立 MCP 工具，继续使用 CLI/Agent API。
+
+MCP 的 stdin/stdout 属于协议通道，不能混入日志或交互文本。调用错误（包括输入验证、缺失 Context、空 Note message 和 stale Manifest hash）返回单次工具错误，server 继续运行。`context_expand` 与 CLI/Agent API 使用相同的无状态 Manifest hash 校验和 partial 预算语义。
 
 ## TypeScript Agent API
 
-使用公开包入口，不要导入内部 `dist/...` 文件：
+使用公开包入口，不要导入内部 `dist/...` 路径，也不要直接读写 `.context`：
 
 ```ts
-import { contextOrient, loadContext, saveContext, searchContext } from 'fluffy-context';
+import {
+  contextOrient,
+  compileContext,
+  contextExpand,
+  saveContext,
+  loadContext,
+  searchContext,
+} from 'fluffy-context';
 
 const orientation = await contextOrient(process.cwd(), {
   query: 'payment callback',
   maxChars: 2400,
 });
+
+const manifest = await compileContext(process.cwd(), {
+  query: 'payment callback',
+  maxChars: 4000,
+});
+```
+
+`fluffy-context/agent` 提供相同的公开入口。当前主要 API 包括：
+
+```text
+contextOrient
+compileContext
+contextExpand
+saveContext
+loadContext
+searchContext
+recordContextUse
+```
+
+Compiler identity 工具也通过公开入口导出：
+
+```text
+canonicalJson
+contentHash
+estimateTokens
+rebuildManifestHash
+validateManifestIdentity
 ```
 
-`fluffy-context/agent` 提供相同的 Agent API。公开类型声明随包发布。Runtime 的存储布局与内部模块不是兼容性承诺。
+存储布局不是公开兼容性承诺；调用方应根据返回结果处理 `status`、预算、截断和 fallback 信息。
 
-## `.contextignored` 与安全边界
+## 安全与隐私边界
 
-`.contextignored` 语法接近 `.gitignore`，用于排除不应作为关联文件保存的项目路径：
+### `.contextignored`
+
+`.contextignored` 使用接近 `.gitignore` 的规则排除不应作为关联文件保存的路径：
 
 ```gitignore
 private/
@@ -227,9 +519,83 @@ private/
 notes/draft-*
 ```
 
-内置保护规则优先，不能被否定规则绕过：`.context/`、`.git/`、依赖和构建目录、`.env` 文件、密钥、常见 credential/token 文件、绝对路径和 `..` 越界路径都不会被作为 Context 关联文件保存。
+内置保护规则优先于项目规则，不能通过否定规则绕过。默认排除包括：
+
+- `.context/`、`.git/`；
+- `node_modules/`、`dist/`、`build/`、`coverage/` 等依赖和构建目录；
+- `.env`、`.env.*`；
+- `*.pem`、`*.key`、`*.p12`、`*.pfx`；
+- 常见 credential、secret、token 文件；
+- 绝对路径和 `..` 越界路径。
+
+### 持久化边界
+
+- checkpoint、Note、Knowledge 和 Deadend 会保存用户显式提供的结构化任务文本；
+- 文件观察只保存过滤后的相对路径和 metadata，不保存内容或 diff；
+- Claude Hook 不保存原始 prompt，只在具备稳定标识时保存限长、脱敏后的 intent；
+- Runtime 仅绑定 `127.0.0.1`，使用项目本地能力令牌进行 IPC；令牌不会出现在状态输出或事件日志；
+- 集成、Runtime 或 v2 读取失败时，支持回退的宿主流程保持 fail-open。
+
+## v1 迁移
+
+已有 v1 `.context/` 数据时，先只读检查，再显式导入：
+
+```bash
+ctx migrate v1 --dry-run
+ctx migrate v1 --apply
+ctx migrate verify
+```
+
+- `--dry-run` 只检查，不创建 v2 数据；
+- `--apply` 才会追加 v1 provenance 事件；
+- 迁移不会重写或修复 v1 文件；
+- v1 与 v2 可以并存；
+- v2 不可用、损坏或尚未同步时，支持回退的读取接口继续使用 v1 行为；
+- `ctx journal verify` 可验证 v2 journal 的 hash chain 和记录完整性。
+
+## 常见问题
 
-## 开发与发布验证
+### `ctx orient` 返回 `no_context`
+
+项目已初始化，但还没有包含实际内容的有效 checkpoint。运行：
+
+```bash
+ctx checkpoint --title "当前任务" --progress "记录当前进度"
+```
+
+### checkpoint 返回 `rate_limited`
+
+这是默认写入保护，不是保存损坏。查看返回的 `retryAt`，完成更多阶段工作后再保存，不要循环重试。
+
+### 为什么文件没有进入 Snapshot 的 `relatedFiles`
+
+先检查 `.contextignored` 和内置保护规则。敏感、构建、依赖、绝对路径和越界路径会被排除，即使使用否定规则也不能绕过。
+
+### Context 找不到怎么办
+
+确认当前项目路径和 Context ID，然后运行：
+
+```bash
+ctx status --path path/to/project
+ctx doctor --path path/to/project
+```
+
+Git branch/ref 漂移通常是提示，不等于 Context 被删除。
+
+### 为什么 `--help` 不能用 JSON.parse
+
+输出类型不同：
+
+- `ctx --help`：纯文本；
+- `ctx --version`：JSON 字符串；
+- 业务命令：格式化 JSON；
+- 错误：stderr 和非零退出码。
+
+### Windows 下从 Node 子进程调用 `ctx`
+
+交互式终端通常可以直接运行 `ctx`。从 Node `spawn` 或其他程序调用时，Windows npm 可能需要使用 `ctx.cmd`；不要把未经转义的用户输入拼接进 shell 命令。
+
+## 开发与验证
 
 ```bash
 npm install
@@ -239,10 +605,23 @@ npm run pack:check
 npm pack --dry-run --json
 ```
 
-运行时依赖 `@modelcontextprotocol/server` 与 `zod` 以提供 MCP 适配；核心 Context 存储仍然保持本地优先。`prepack` 会重新构建发布产物，`prepublishOnly` 在未来手动发布前运行测试；这些命令不会发布 npm 包。
+发布包通过 `fluffy-context` 和 `fluffy-context/agent` 提供公开 Agent API，并包含 CLI、类型声明、README、LICENSE 和 `skills/fluffy-context/SKILL.md`。
+
+## 未来方向
+
+以下方向属于后续版本，不是 0.7.6 的当前能力：
+
+| 方向 | 目标 |
+| --- | --- |
+| Context expansion | 在现有 `context_expand` 基础上继续完善更丰富的分层内容 |
+| Decision Graph | 将决策变成可治理、可追溯的一等对象 |
+| Knowledge Evolution | 支持知识合并、替代、范围演化和 review-needed 信号 |
+| Journal maintenance | 提供安全的清理、归档和长期运行维护能力 |
+| Usage reporting | 统计估算 token、编译、展开、检索和反馈覆盖情况（`ctx report`） |
+| 外部协作 | 远程同步、多人协作和团队权限 |
 
-## 当前范围
+这些方向不会改变当前的边界：Git、项目文档和宿主规则继续由各自系统负责；Candidate 仍需要显式治理；模型调用和远程服务不是核心 Runtime 的隐式依赖。
 
-0.6.0 聚焦单项目、本地优先、可治理的 branch-aware Knowledge Runtime MVP：有界且可解释的 Orient、显式 checkpoint、journal 派生的确定性 Knowledge/Deadend 检索、终态治理、显式使用反馈、MCP `context_orient`、可选 Claude Code Hook，以及 v1 到 v2 的显式事件日志迁移和 Git-aware 本地 Runtime。完成迁移并启用 Runtime 后，Orient、MCP 与 Hook 使用当前 worktree/ref 的 workspace 选择分支正确的 Context，并在 v2 不可用时保持 v1 回退；Runtime 负责可靠捕获生命周期、Git 元数据与后续 v1 写入镜像。带稳定宿主标识的 Hook 事件仅以脱敏、限长 intent 进入 journal。
+## License
 
-远程同步、多人协作、复杂语义检索、自动模型总结、自动 checkpoint、Context merge、自动验证候选共识，以及更多状态变更型 MCP 工具不属于当前版本范围。
+MIT