feat(v0.7.71): relocate settled citations, widen revision evidence and document marketplace install

CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to Context are documented here.
 
+## 0.7.71 - 2026-10-14
+
+- `translate prepare` uses the stale translation itself as the draft and, when Git history holds the approved version it was translated from, writes a `source_diff` from that version. Without history, `source_diff` is `null`. Translations no longer store `source_parts`; existing ones are read as before. Drafts are never overwritten and are removed after a successful submission. A kept draft (`draft: kept`) has no `source_diff` and must be aligned with the whole current article, because the source may have changed again since it was written. The draft generation records, `rebase-required`, `*.unrecorded.md`, `*.previous.md` and the per-article `source_digest` submission field are removed.
+- Replacing a task in a plan amendment no longer copies its draft. The old draft directory is listed in `previous_drafts`, also when the same amendment is replayed, and in the new task's `task.md` on every preparation.
+- Planning no longer adds a revised article's cited sources to its task. Omitted citations are still inherited when submitting; list a source in the plan to re-confirm it.
+- Submission receipts no longer echo `resolved_references`.
+- Installation instructions list Bun alongside Node.js 20: knowledge workspaces install their dependencies with `bun install`.
+- A fragment may cite regions from at most three distinct source files, with several regions per file and up to eight regions in total; previously it was limited to three regions. Existing knowledge stays valid, but structures with more than three regions in a fragment cannot be read by earlier CLIs.
+- Rejected revision references are reported as user input (`user-input-invalid`) with the fragment and input path: an unmatched locator, an oversized fragment, or a source outside the revision, which now lists the allowed sources. Source-update decisions that omit a candidate page or name a page that is not one are reported the same way and list those pages.
+- A `heading` locator may include its ATX marker (`## Install`); the marker also selects the heading level.
+- `translate prepare` reseeds a leftover draft whose body is still the unedited seed, such as one left by an earlier CLI, and gives it a `source_diff` instead of reporting it as `kept`.
+- Reader pages also expose each fragment ID as an anchor, so links such as `page.md#upgrade` resolve, unless a heading on that page already owns the slug.
+- When a source update settles, citations of kept pages whose text only moved in the updated source are relocated, so `verify` no longer reports them. Repository content keeps its own settlement. Kept pages whose cited text changed or cannot be confirmed are listed in the completion result's `reference_warnings`; the citations keep their previous locations, and the pages can be corrected with `context revise` after the update queue finishes.
+- A revision citing a source outside its scope explains how to add new independent evidence: register the source, associate it with the requirement in `src/indexers.yaml`, then run `context task adjust`.
+- A source added with `context task adjust` during a multi-page revision stays citable by the remaining queued pages. Repeating the adjustment for an unchanged source no longer discards pages already prepared in the batch.
+- The translation guide explains that `source_diff` is `null` when approve-and-translate rounds ran without a commit in between.
+- The README documents installing the `c4a` plugin in Claude Code or Codex by adding this repository as a plugin marketplace; the CLI is still installed from npm.
+
 ## 0.7.70 - 2026-10-14
 
 - Revising an existing article no longer fails because its old citations are outside the new task's sources. A fragment that omits `references` keeps its validated citations; listing references re-confirms them against the task's authorized sources. Only candidate or approved citations are trusted, never a failed draft's.

README.md

@@ -42,14 +42,26 @@ for the method and results.
 
 ## Quick start
 
-Install the CLI and its Agent plugin once. The plugin is installed for the
-Claude Code, Codex and Cursor hosts that are available on the machine:
+You need Node.js 20 or newer and [Bun](https://bun.sh), which knowledge
+workspaces use to install their dependencies. Install the CLI and its Agent
+plugin once. The plugin is installed for the Claude Code, Codex and Cursor
+hosts that are available on the machine:
 
 ```bash
 npm install -g @c4a/context-cli@latest
 context plugin install
 ```
 
+This repository is also a plugin marketplace. In Claude Code or Codex you can
+add it and install the `c4a` plugin through the host instead of
+`context plugin install`; the CLI is still required, because the plugin
+delegates the workflow and the bundled Indexers to it:
+
+```bash
+claude plugin marketplace add context4ai/context && claude plugin install c4a@c4a
+codex plugin marketplace add context4ai/context && codex plugin add c4a@c4a
+```
+
 Restart the Agent session and describe the knowledge you want:
 
 ```text

README.zh-CN.md

@@ -29,13 +29,20 @@ Context 把代码仓库、文档、笔记和会话整理成经过审阅、带版
 
 ## 快速开始
 
-安装 CLI 与 Agent 插件（一次即可）。插件会安装到本机可用的 Claude Code、Codex 与 Cursor：
+需要 Node.js 20 及以上，以及 [Bun](https://bun.sh)（知识工作区用它安装依赖）。安装 CLI 与 Agent 插件（一次即可）。插件会安装到本机可用的 Claude Code、Codex 与 Cursor：
 
 ```bash
 npm install -g @c4a/context-cli@latest
 context plugin install
 ```
 
+本仓库本身也是插件市场。在 Claude Code 或 Codex 中，可以添加它并通过宿主安装 `c4a` 插件，代替 `context plugin install`；CLI 仍需安装，因为插件把工作流和随包的 Indexer 交给它执行：
+
+```bash
+claude plugin marketplace add context4ai/context && claude plugin install c4a@c4a
+codex plugin marketplace add context4ai/context && codex plugin add c4a@c4a
+```
+
 重启 Agent 会话，用自然语言说明想要的知识：
 
 ```text

package.json

@@ -1,6 +1,6 @@
 {
   "name": "context",
-  "version": "0.7.70",
+  "version": "0.7.71",
   "packageManager": "bun@1.3.9",
   "repository": {
     "type": "git",

packages/context-cli/CLAUDE.md

@@ -85,7 +85,7 @@ adapter、对应 plugin shell、SDK 手册和 Graph tests，并运行 `bun run b
 - Approved Markdown 头部维护 `title`、`type`、`description`、`timestamp`，按需保留真实 `resource` 和阅读标签。正文保留稳定片段 ID；文章身份、路径、知识分类、可见性和片段来源区域仅在 `knowledge/structure.yaml` 的 `articles` 中维护。导出由结构引用生成读者溯源，不能要求 Agent 再维护一份来源列表。构建清单记录发布路径到批准文章的映射，不得改写 `knowledge/`。
 - PART1 重构不再要求 prose/structure knowledge 提取独立主体、填写 node_type 或主体 tags；文章知识分类仍保留，不以主体分类推导。
 - Markdown 不写 `article_id`、`sources`、`source_refs`、`visibility` 或 `code_symbols`；片段标记为 `<!-- context:section id="..." -->` 和对应结束标记，不附证据属性。
-- 实际引用由 `source_ref`、区域 `locator` 与工具计算的 `content_digest` 表达；每个输出片段最多 3 个位置，不是章节或文章的总上限。不维护独立事实／证据 ID 或逐绑定指纹。
+- 实际引用由 `source_ref`、区域 `locator` 与工具计算的 `content_digest` 表达；每个输出片段最多引用 3 个不同来源文件、共 8 个区域，不是章节或文章的总上限。不维护独立事实／证据 ID 或逐绑定指纹。
 - 当前 Indexer approved Markdown 不保存 `candidate_fingerprint`、Indexer digest 或 `code_origin`；
   current/stale 由本机 runtime 与批准页面的实际正文、来源共同判定。
 - 不写 `schema` 字段。协议版本由工具/文档和 verify 约束,不是 approved MD 的 frontmatter 字段。

packages/context-cli/README.md

@@ -33,13 +33,22 @@ an LLM itself.
 
 ## Install the Agent integration
 
+Requires Node.js 20 or newer. Knowledge workspaces install their dependencies
+with Bun (`bun install` after `context init`), so install Bun as well.
+
 ```bash
 npm install -g @c4a/context-cli@latest
 context plugin install # global installation
 # Alternatively, install only in a repository:
 context plugin install --local /path/to/repo --agent auto-detect
 ```
 
+The source repository is also a plugin marketplace. Claude Code and Codex can
+install the `c4a` plugin from it with `claude plugin marketplace add context4ai/context`
+and `claude plugin install c4a@c4a`, or `codex plugin marketplace add context4ai/context`
+and `codex plugin add c4a@c4a`. The CLI is still required; the plugin delegates
+the workflow and the bundled Indexers to it.
+
 `--local` requires explicit `--agent`: `claude`, `cursor`, `codex`, `all`, `auto-detect`, or `standalone`. The path is a repository root: explicit hosts install into `.claude`, `.cursor`, or `.agents` without detection. `all` installs all three. Only `auto-detect` checks existing `.claude`, `.cursor`, and `.agents` directories in the target repository, never PATH or installed desktop applications; it falls back to `.agents/skills` when none exist. `standalone` instead writes all skills directly to `<path>/skills`, with no commands or host subdirectory. All modes support `--dry-run` and preserve global configuration.
 
 Migration from 0.7.20: add `--agent auto-detect` to bare `--local`; for explicit hosts pass the repository root, not its host directory. Global installation is unchanged. Host detection does not verify runtime loading.

packages/context-cli/README.zh-CN.md

@@ -33,6 +33,8 @@ context plugin install # 全局安装
 context plugin install --local /path/to/repo --agent auto-detect
 ```
 
+源码仓库本身也是插件市场。Claude Code 与 Codex 可以从中安装 `c4a` 插件：`claude plugin marketplace add context4ai/context` 后执行 `claude plugin install c4a@c4a`，或 `codex plugin marketplace add context4ai/context` 后执行 `codex plugin add c4a@c4a`。CLI 仍需安装，插件把工作流和随包的 Indexer 交给它执行。
+
 `--local` 必须显式搭配 `--agent`：`claude`、`cursor`、`codex`、`all`、`auto-detect` 或 `standalone`。路径为仓库根；指定宿主直接写入对应 `.claude`、`.cursor`、`.agents` 子目录，不检测是否安装宿主。`all` 全装；只有 `auto-detect` 检测目标仓库已有的 `.claude`、`.cursor`、`.agents` 目录，不检测 PATH 或桌面应用；均不存在时兜底 `.agents/skills`。`standalone` 则直接写入 `<path>/skills`，不生成 commands 或宿主子目录。均支持 `--dry-run`，不改全局配置。
 
 从 0.7.20 迁移：裸 `--local` 补充 `--agent auto-detect`；指定宿主时传仓库根，不再传宿主目录。全局安装不变。自动探测不代表宿主已加载，安装后需刷新宿主。

packages/context-cli/context-workflow/provider.yaml

@@ -1,6 +1,6 @@
 schema: agent-graph.provider.v1
 id: c4a/context
-version: 0.7.70
+version: 0.7.71
 name: Context workflow
 description: Internal work contract for Context knowledge workspaces.
 graphs:

packages/context-cli/context-workflow/resources/manuals/guides/code-indexer-skill-authoring.md

@@ -50,7 +50,8 @@ proof of runtime behavior. Preserve expressions without executing project code,
 distinguish declaration defaults from implementation defaults, and state unknowns.
 
 Use the current stage's Markdown and reference-file schemas. Each fragment cites
-at most three actual source locations; the CLI computes regional digests. Split
+actual source regions from at most three files (up to eight regions); the CLI
+computes regional digests. Split
 an explanation when it needs separate evidence, not to fill a fixed template.
 Reuse stable article and fragment identities when revising. Supporting documents,
 notes or sessions may contribute to the same article without becoming code facts.

packages/context-cli/context-workflow/resources/manuals/guides/knowledge-updates.md

@@ -338,7 +338,7 @@ changing structure, adding a page or when a section has no unambiguous ID.
 To change a fragment's citations, include `references` alongside its `section_id`:
 each entry supplies `source_ref` and `locator` (`path`, `start_line`, `end_line`).
 Context computes the region fingerprint. This uses the same revision submission,
-with at most three source positions per fragment. Full Markdown may include a
+with at most three source files and eight regions per fragment. Full Markdown may include a
 `sections` list of reference edits; local section edits may change content,
 references, or both. Omission preserves citations; an empty list removes them.
 
@@ -703,17 +703,19 @@ Revision section edits may supply `references` as `source_ref` plus a
 `locator` containing `path`, `start_line`, and `end_line`. Context computes the
 regional digest. Omitted references preserve the current fragment's citations;
 an explicit empty list removes them, and deleting a fragment removes its
-citations. Each fragment may cite at most three source positions. Register and
+citations. Each fragment may cite at most three source files and eight regions. Register and
 authorize new material before citing it, then follow normal Review, close and
 build. Article links alone do not authorize reading new sources or prove a claim.
 
 ### Locating submitted references
 
 Submission locators also accept `{path, heading}` or `{path, quote}` instead of
-line numbers. Use exactly one form. A heading matches an exact ATX heading
-outside code fences in a Markdown source; its region ends before the next
+line numbers. Use exactly one form. A heading is the title text of an exact ATX heading
+outside code fences in a Markdown source; a leading `##` marker is optional and,
+when present, also selects the heading level; its region ends before the next
 same-level or higher-level heading. A quote is an exact, unique, nonempty
 substring (line endings are normalized). Ambiguous matches return candidate
 line ranges. Both forms resolve against authorized captured text before hashing;
 stored references still contain only `path`, `start_line` and `end_line`.
-The three-region limit applies after resolving and deduplicating positions.
+The per-fragment limits (three source files, eight regions) apply after
+resolving and deduplicating positions.

packages/context-cli/context-workflow/resources/manuals/guides/markdown-indexer-skill-authoring.md

@@ -45,7 +45,7 @@ submit the short stage-relative manifest. Title and description belong to the
 article, not an internal layout-mapping tuple.
 
 Keep stable article and fragment identities when revising. Each fragment cites
-at most three actual source regions. The CLI handles source digests and safety;
+actual source regions from at most three files (up to eight regions). The CLI handles source digests and safety;
 the Agent judges whether the evidence supports the explanation. For a local
 failure, use the returned fragment identifier or position to repair the affected
 part. Completed independent tasks can be submitted without the rest of the batch.