@c4a/context 0.7.5 → 0.7.9

package/README.md

@@ -13,7 +13,8 @@ knowledge are not produced by project phases in `src/index.ts`.
 ## Project boundary
 
 ```text
-sources/*/index.yaml       registered source boundaries
+sources/{repo,file,lark}/index.yaml   registered source boundaries
+sources/{note,sessions}/YYYYMMDD/*.md saved notes and conversation summaries
 src/index.ts               capture and package declarations
 src/indexers.yaml          knowledge-authoring authority
 knowledge/                 approved, human-readable knowledge
@@ -38,7 +39,7 @@ import {
   source,
 } from "@c4a/context";
 
-const docs = source("product-docs", { type: "file" });
+const docs = source("20260901/product-docs", { type: "file" });
 
 export default defineProject({
   sources: [docs],
@@ -64,7 +65,7 @@ never enter knowledge identity or package output.
 | API | Purpose |
 |---|---|
 | `defineProject()` | Declares the project boundary. |
-| `source()` / `allSources()` | References registered repo, file, or Lark sources. |
+| `source()` / `allSources()` | References registered repo/file/Lark sources or explicitly selects saved Note/Sessions. |
 | `captureFile()` / `captureLark()` | Creates deterministic document snapshots. |
 | `mdxJsonDocs()` | Configures the MDX/JSON documentation capture processor. |
 | `customPhase()` | Runs non-knowledge project orchestration. |
@@ -102,7 +103,10 @@ available from `node_modules/@c4a/context/templates/package-templates/`.
 Do not directly edit lifecycle files under `.tmp/context-runtime/`. The CLI
 owns Candidate state, Review application, recovery, close, verification, and
 build. Source registries, `src/index.ts`, `src/indexers.yaml`, approved
-`knowledge/`, and package templates are the durable project inputs.
+`knowledge/`, saved Note/Sessions and package templates are durable inputs.
+`structure.yaml` retains scope-level update baselines. Optional session commit/MR
+associations stay in the source file, not copied into knowledge headers. Saving
+a source alone does not start indexing.
 
 ## Documentation
 
@@ -113,3 +117,7 @@ build. Source registries, `src/index.ts`, `src/indexers.yaml`, approved
 - [Indexer Provider Protocol](./docs/reference/indexer-provider-protocol.md)
 - [Package Outputs](./docs/guides/package-outputs.md)
 - [Package Templates](./docs/reference/package-templates.md)
+
+- [Update existing knowledge](./docs/guides/knowledge-updates.md)
+- [Prepare notes](./docs/guides/note.md)
+- [Prepare conversation summaries](./docs/guides/sessions.md)

package/README.zh-CN.md

@@ -12,7 +12,8 @@ Profile、范围和定制。`src/index.ts` 中的项目阶段不再负责生产
 ## 项目边界
 
 ```text
-sources/*/index.yaml       已登记的来源边界
+sources/{repo,file,lark}/index.yaml   已登记的来源边界
+sources/{note,sessions}/YYYYMMDD/*.md 保存的笔记与会话总结
 src/index.ts               采集与知识包声明
 src/indexers.yaml          知识生产的唯一权威配置
 knowledge/                 已批准、可读的知识
@@ -37,7 +38,7 @@ import {
   source,
 } from "@c4a/context";
 
-const docs = source("product-docs", { type: "file" });
+const docs = source("20260901/product-docs", { type: "file" });
 
 export default defineProject({
   sources: [docs],
@@ -61,7 +62,7 @@ Context 生命周期负责发现或更新 `src/indexers.yaml`，以有界批次
 | API | 用途 |
 |---|---|
 | `defineProject()` | 声明项目边界。 |
-| `source()` / `allSources()` | 引用已登记的代码仓库、本地文件或飞书来源。 |
+| `source()` / `allSources()` | 引用已登记的代码/文件/飞书来源，或明确选择保存的 Note/Sessions。 |
 | `captureFile()` / `captureLark()` | 生成确定性的文档快照。 |
 | `mdxJsonDocs()` | 配置 MDX/JSON 文档采集处理器。 |
 | `customPhase()` | 执行不生产知识的项目编排。 |
@@ -94,7 +95,9 @@ knowledge/architecture/product-guides/component-input-fields.md
 
 不要直接修改 `.tmp/context-runtime/` 下的生命周期文件。Candidate 状态、审核应用、
 恢复、close、验证与构建由 CLI 管理。来源注册表、`src/index.ts`、
-`src/indexers.yaml`、批准后的 `knowledge/` 和知识包模板才是长期项目输入。
+`src/indexers.yaml`、批准后的 `knowledge/`、保存的 Note/Sessions 和知识包模板是长期项目输入。
+`structure.yaml` 保留范围级更新基线；会话的可选 commit/MR 关联放在来源文件，
+不重复添加到知识页头部。保存来源不会自动开始索引。
 
 ## 参考文档
 
@@ -105,3 +108,7 @@ knowledge/architecture/product-guides/component-input-fields.md
 - [Indexer Provider 协议](./docs/reference/indexer-provider-protocol.md)
 - [知识包输出](./docs/guides/package-outputs.md)
 - [知识包模板](./docs/reference/package-templates.md)
+
+- [更新已有知识](./docs/guides/knowledge-updates.md)
+- [准备 Note](./docs/guides/note.md)
+- [准备 Sessions](./docs/guides/sessions.md)

package/docs/README.md

@@ -28,22 +28,34 @@ preload the whole manual set.
 | Author or inspect an Indexer Provider protocol | [Indexer Provider Protocol](./reference/indexer-provider-protocol.md) |
 | Select or customize an Indexer Provider | [Provider Selection and Customization](./guides/indexer-provider-and-customization.md) |
 | Author a Code or Markdown Indexer Skill | [Code Indexer Authoring](./guides/code-indexer-skill-authoring.md) and [Markdown Indexer Authoring](./guides/markdown-indexer-skill-authoring.md) |
+| Update approved pages, adjust current work, or roll back | [Knowledge Updates](./guides/knowledge-updates.md) |
+| Prepare, commit or restore a workspace | [Prepare](./guides/workspace-prepare.md), [Commit](./guides/workspace-commit.md), [Restore](./guides/workspace-restore.md) |
+| Save and use a note | [Note](./guides/note.md) |
+| Save a conversation summary with optional commit/MR associations | [Sessions](./guides/sessions.md) |
 | Choose a code extraction path | [Code Extractor Selection](./reference/code-extractors.md) |
 | Choose an Agent package or LLM document | [Package Outputs](./guides/package-outputs.md) |
 | Customize package files and indexes | [Package Templates](./reference/package-templates.md) and [Template Variables](./reference/template-variables.md) |
 | Preserve Lark images and embedded resources | [Lark Resource Materialization](./guides/lark-resources.md) |
 
+The defaults include Code, Markdown, Note and Sessions Indexers. The Host owns
+installation and skill switches; the Agent selects a compatible visible Provider,
+including a business replacement. Shared protocol does not mean shared editorial
+policy: read the selected skill's source-specific resources, not all source guides.
+
 ## Complete reference
 
 - [Getting Started](./getting-started.md) — end-to-end component-library flow.
 - [Agent Guide](./guides/agent-guide.md) — what an agent should do, and what it should not inspect manually.
 - [Agent Dialogue](./guides/agent-dialogue.md) — stable dialogue principles and how route-selected gate resources are discovered.
+- [Knowledge Updates](./guides/knowledge-updates.md) — page revisions, source updates, adjustment and rollback.
+- [Note](./guides/note.md) — originals, excerpts and summaries versus reader knowledge.
+- [Sessions](./guides/sessions.md) — conversation summaries, optional code links and independent topics.
 - [Package Outputs](./guides/package-outputs.md) — how to choose between an agent knowledge-base package, LLM text, or no package output.
 - [Lark Resource Materialization](./guides/lark-resources.md) — how embedded resources move from source evidence to approved knowledge and package assets.
 - [Project API](./reference/project-api.md) — `defineProject`, sources, capture, Indexers, and packages.
 - [Indexer Provider Protocol](./reference/indexer-provider-protocol.md) — manifest, controlled execution, detector/inspector I/O, customization, and staged project apply.
 - [Provider Selection and Customization](./guides/indexer-provider-and-customization.md) — registry-only selection, the six-level customization ladder, upgrade conflicts, debugging, and completion conditions.
-- [Code Indexer Authoring](./guides/code-indexer-skill-authoring.md) — the 23-point Provider Skill release contract and anonymous fixture expectations.
+- [Code Indexer Authoring](./guides/code-indexer-skill-authoring.md) — the Provider Skill release contract and anonymous fixture expectations.
 - [Markdown Indexer Authoring](./guides/markdown-indexer-skill-authoring.md) — capture/semantic boundaries, Section placement, material answers, editorial policy, and local incremental behavior.
 - [Code Extractor Selection](./reference/code-extractors.md) — inspect module technology signals and choose a built-in extractor, reusable structural package, or project adapter.
 - [Package Templates](./reference/package-templates.md) — `kbPackage`, `llmsPackage`, template variables, and examples.

package/docs/README.zh-CN.md

@@ -18,21 +18,33 @@
 | 配置来源、采集、Indexer 或产物 | [Project API](./reference/project-api.md) |
 | 选择或定制 Indexer Provider | [Provider Selection and Customization](./guides/indexer-provider-and-customization.md) |
 | 编写 Code/Markdown Indexer Skill | [Code Indexer Authoring](./guides/code-indexer-skill-authoring.md) 和 [Markdown Indexer Authoring](./guides/markdown-indexer-skill-authoring.md) |
+| 更新已有知识、调整当前任务或回滚 | [Knowledge Updates](./guides/knowledge-updates.md) |
+| 整备、提交或恢复历史工作区 | [整备](./guides/workspace-prepare.md)、[提交](./guides/workspace-commit.md)、[历史恢复](./guides/workspace-restore.md) |
+| 保存和使用笔记 | [Note](./guides/note.md) |
+| 保存会话总结及可选 commit/MR 关联 | [Sessions](./guides/sessions.md) |
+| 查询 Provider 共同协议 | [Indexer Provider Protocol](./reference/indexer-provider-protocol.md) |
 | 选择代码提取方式 | [Code Extractor Selection](./reference/code-extractors.md) |
 | 选择 Agent 知识包或 LLM 文档 | [Package Outputs](./guides/package-outputs.md) |
 | 自定义包文件和索引 | [Package Templates](./reference/package-templates.md) 和 [Template Variables](./reference/template-variables.md) |
 | 保留飞书图片和内嵌资源 | [Lark Resource Materialization](./guides/lark-resources.md) |
 
+默认提供 Code、Markdown、Note、Sessions 四类 Indexer。安装和技能开关由 Host 管理；
+Agent 从当前可见技能选择兼容 Provider，业务 Provider 可以替换默认实现。协议相同不代表
+写作方式相同：按实际来源读取所选技能的指引，不要每次加载所有来源说明。
+
 ## 完整参考
 
 - [Getting Started](./getting-started.md)：从来源到知识包的端到端组件库示例。
 - [Agent Guide](./guides/agent-guide.md)：Agent 应该执行什么，以及哪些状态不能手工探查或修改。
 - [Agent Dialogue](./guides/agent-dialogue.md)：稳定的对话原则和 Route-selected Gate 资源发现方式。
+- [Knowledge Updates](./guides/knowledge-updates.md)：页面修订、来源更新、调整与回滚。
+- [Note](./guides/note.md)：原文、摘录、总结的保存与知识改写边界。
+- [Sessions](./guides/sessions.md)：会话总结、可选代码关联和独立知识主题。
 - [Package Outputs](./guides/package-outputs.md)：如何选择 Agent 知识包、LLM 文本或不构建产物。
 - [Lark Resource Materialization](./guides/lark-resources.md)：内嵌资源如何从来源证据进入正式知识和知识包。
 - [Project API](./reference/project-api.md)：`defineProject`、来源、采集、Indexer 和知识包声明。
 - [Provider Selection and Customization](./guides/indexer-provider-and-customization.md)：registry-only 选择、六级最小定制阶梯、升级冲突、调试与退出条件。
-- [Code Indexer Authoring](./guides/code-indexer-skill-authoring.md)：Code Provider Skill 的 23 项作者/发布契约。
+- [Code Indexer Authoring](./guides/code-indexer-skill-authoring.md)：Code Provider Skill 的作者/发布契约。
 - [Markdown Indexer Authoring](./guides/markdown-indexer-skill-authoring.md)：capture/semantic 边界、Section 投影、material answer、编辑策略与局部增量。
 - [Code Extractor Selection](./reference/code-extractors.md)：如何根据技术信号选择内建提取器、结构库或项目适配器。
 - [Package Templates](./reference/package-templates.md)：`kbPackage`、`llmsPackage`、模板变量和示例。

package/docs/getting-started.md

@@ -1,44 +1,65 @@
 # Getting Started
 
-Context turns registered code and documents into approved, reader-oriented
-knowledge. The normal user starts through the installed Context Agent entry;
-the Agent follows the Route returned by `context status --format json`.
+Context turns selected code, documents, notes and conversation summaries into
+approved knowledge. Start through the installed Context Agent entry and follow
+the current Route returned by the CLI.
 
-## 1. Initialize
+## 1. Initialize the workspace
 
 ```bash
 context init ./context
 cd ./context
+bun install
+context status --format json
 ```
 
-Initialization creates source registries, `src/index.ts`, an empty
-`src/indexers.yaml`, package templates, `knowledge/`, and `dist/`.
+Use the dependency-install command returned by initialization if it differs.
+Initialization creates the project configuration, source directories, package
+templates and workspace rules. Read the generated `AGENTS.md`. It does not create
+an empty `src/indexers.yaml`: the later configuration Route supplies its schema
+and asks for the confirmed requirements with `indexers: []`.
 
-## 2. Register source boundaries
+Run workspace commands inside this initialized directory. Route paths and
+`.tmp/` belong to this workspace, not the surrounding repository.
 
-Examples:
+## 2. Select and register sources
+
+This example uses a code module and a local documentation directory:
 
 ```bash
 context source add repo 20260901 --module component-lib --local ../component-lib
-context source add file product-docs --local ../docs
-context source add lark handbook --doc-token <token>
+context source add file 20260901 --module product-docs --local ../docs
 ```
 
-Choose a boundary that matches ownership. For a monorepo, register the package
-or service directory that should own the resulting knowledge rather than the
-whole repository by default.
+Replace the date and paths with the actual inputs. Both commands register a
+boundary; they do not decide what knowledge to write. For a monorepo, select the
+package or service needed for the reader's task. Discuss obsolete or unrelated
+areas before indexing them: unnecessary material costs reading time and tokens.
+Do not exclude content merely because a filename looks old.
+
+For an authorized Lark document, registration instead looks like:
 
-## 3. Declare capture and packages
+```bash
+context source add lark 20260901 --module handbook --doc-token "<actual-token>"
+```
 
-Use `src/index.ts` for capture and output only:
+Use `captureLark()` for that registered document. Notes and conversation summaries
+use `context source import`, without a source registry or capture phase. Read
+[note preparation](guides/note.md) or [sessions preparation](guides/sessions.md)
+for the actual input. Saving them alone does not start knowledge production.
+
+## 3. Declare capture and output
+
+For the code and local-document example, `src/index.ts` contains:
 
 ```ts
 import { captureFile, defineProject, kbPackage, source } from "@c4a/context";
 
-const docs = source("product-docs", { type: "file" });
+const repo = source("20260901", "component-lib");
+const docs = source("20260901/product-docs", { type: "file" });
 
 export default defineProject({
-  sources: [docs],
+  sources: [repo, docs],
   phases: [captureFile({ source: docs })],
   packages: [
     kbPackage({
@@ -50,66 +71,71 @@ export default defineProject({
 });
 ```
 
-Repo sources do not need a capture phase. The Code Indexer reads their pinned
-source boundary through its controlled workset.
-
-## 4. Let the lifecycle prepare Indexers
-
-Run the current route and follow its declared next action. The Agent will:
-
-1. turn the user goal into explicit requirements and reader questions;
-2. inspect source boundaries and select Code or Markdown Providers;
-3. prepare a registry-only proposal for `src/indexers.yaml`;
-4. ask only for choices that change scope, ownership, or visible output;
-5. read the current bounded workset, return one compact Partition decision,
-   and review the resulting semantic outline;
-6. author each accepted subject, run any selected Composer, and let Context
-   compile the current Candidate set.
-
-In ordinary mode, a compatible layout pauses twice: once for the semantic
-outline and once for the final Candidate pages. In explicitly authorized fully
-managed mode, the Agent performs both judgments without showing them to the
-user. Destructive or ambiguous changes to an already approved layout always
-stop for a human decision.
-
-Do not manually create a second extraction or Markdown pipeline in
+This example assumes an Agent knowledge-base package is the intended output;
+see [Package Outputs](guides/package-outputs.md) for alternatives. Repo sources
+need no capture phase. For saved text, declare an explicit typed `source()` or
+`allSources()` selection as described in [Project API](reference/project-api.md).
+
+## 4. Follow requirements and Provider selection
+
+The Agent researches representative material, reuses the user's stated goals,
+and asks about missing information that would change the scope or useful output.
+Fully managed mode does not authorize guessing those answers. For substantial
+new work, the selected workflow provides an opening report under `.tmp/`, with
+scope, Provider choices and the first pages to expect. The Agent invites the user
+to read it before continuing unless that pause was explicitly waived; this is
+conversation coordination, not a new approval record.
+
+The configuration Route supplies the initial registry schema and guide. Declare
+requirements with no selected Indexers, re-read the Route, then submit Provider
+selection through its completion command. The shipped Code, Markdown, Note and
+Sessions Providers share the same lifecycle. A compatible business Provider may
+replace a default; installation alone does not enable it.
+
+Partition organizes the selected material into reader topics. Its task batches
+are planning work, not finished-page deliveries. After the outline is reviewed,
+Author writes complete pages, selected Composers contribute where applicable,
+and the CLI compiles Candidates. Do not create a second knowledge pipeline in
 `src/index.ts`.
 
-## 5. Review Candidates
+## 5. Review and deliver pages
 
-Review shows readable paths, titles, summaries, and page content. Internal
-evidence IDs remain in runtime artifacts. Approve, reject, or revise based on
-whether the pages answer the intended reader questions and accurately reflect
-the source.
+In ordinary mode, the user reviews the proposed structure and then the actual
+Candidate pages. In explicitly authorized fully managed mode, the Agent performs
+delegatable reviews and reports the results. Human-only decisions, such as
+protected changes to an approved layout, still stop at their returned Gate.
 
-Revision reopens the owning Author or Composer workset and then recompiles the
-same Candidate identity. It does not create a parallel document-editing flow.
-
-After approval, `close` writes the accepted pages under readable paths such as:
-
-```text
-knowledge/codeindex/component-lib/button.md
-knowledge/architecture/product-docs/component-contract.md
-```
+Review shows readable titles, paths, summaries and content. Approval applies the
+pages to `knowledge/`; rejection or revision follows the current Route back to
+writing. `close` rebuilds `knowledge/structure.yaml` and verifies the approved
+knowledge without rewriting its prose. Build produces `dist/<package-name>/`.
+The first readable delivery normally contains 1–3 pages, followed by batches of
+30–50 pages or a smaller remaining tail. Each delivery completes review, close
+and build before continuing. These page counts do not count Partition tasks.
 
-The CLI retains only metadata needed to update or rebuild those pages.
+## 6. Continue or update
 
-## 6. Verify and build
+Use the latest Route and revision. Accepted tasks must not be resubmitted. If a
+completion points to `result_file` or `next_route.file`, read those files; do not
+infer failure from a shortened console response. Follow its recovery command if
+preparing the next Route failed after acceptance.
 
-The workflow verifies approved knowledge, then builds the declared package in
-`dist/<package-name>/`. Package pages are a reader projection and intentionally
-omit runtime evidence IDs and most digests.
+Approved knowledge and `structure.yaml` retain the durable information needed
+for updates; `.tmp/context-runtime/` holds unfinished execution state and can be
+cleaned after completed work. Its absence is not permission to replay accepted
+work or advance an unfinished source baseline.
 
-Source or requirement changes re-enter the same Indexer lifecycle. Successful
-work is recovered from persisted runtime state; successful close clears
-temporary Candidate and Review state.
+Use `context revise` for a selected page correction, and `context update` for a
+selected source change. [Update existing knowledge](guides/knowledge-updates.md)
+explains their inputs, same-task adjustment and explicit rollback.
 
 ## Troubleshooting boundary
 
-- Fix a missing or stale source with `context source ...`.
-- Fix capture configuration in `src/index.ts`.
-- Fix knowledge requirements, Provider selection, or customization through the
-  `src/indexers.yaml` proposal flow.
-- Fix reader output through Provider instructions/templates, not by adding a
-  parallel project phase.
-- Never treat generated `dist/` as source material.
+- Fix a missing or stale source through the source commands returned by the Route.
+- Fix capture and output configuration in `src/index.ts`.
+- Fix requirements or Provider selection through the current configuration or
+  proposal Route; use its supplied schema rather than guessing payload fields.
+- Correct page content through revision and Review. Change Provider guidance when
+  the same writing problem affects future pages.
+- Keep temporary input files under this workspace's `.tmp/`. Never use `dist/`
+  as an authoring source or hand-edit internal lifecycle state.

package/docs/guides/agent-dialogue.md

@@ -23,10 +23,10 @@ it knows which decision is current.
 
 The ordinary path also selects short mode guidance after workspace creation
 and source capture. Explain that ordinary review is the default, provides HTML
-reports at review decisions, and is currently estimated to take about 40%
-longer overall depending on scope and response time. Offer fully managed mode
-for the current conversation while explaining that it gives the user fewer
-opportunities to adjust intermediate content.
+reports at review decisions, and waits for user responses there. Offer fully
+managed mode for the current conversation when appropriate: the Agent performs
+delegatable reviews and reports results without requiring per-batch approval.
+Do not promise a fixed time saving; it depends on scope and response time.
 
 ## Stable Principles
 
@@ -39,8 +39,9 @@ opportunities to adjust intermediate content.
   use concise A/B/C choices with one impact sentence each.
 - Use semantic labels such as “Agent knowledge-base package” rather than SDK
   factory names such as `kbPackage`.
-- Do not infer a decision from a filename, URL, repository layout, example, or
-  previous conversation.
+- Reuse explicit decisions that still apply to this task. Do not infer a new
+  decision from a filename, URL, repository layout or example, and do not turn
+  another conversation's managed authority into current authorization.
 - Keep transition reports short: what changed, the current state, and the next
   decision or action.
 
@@ -58,6 +59,16 @@ question. A Gate may keep its ordinary inspection Action and dialogue resources
 while replacing them with a direct revision-bound resolution path only for a
 session-authority Route. Necessary evidence inspection remains selected for
 semantic scope or classification work. This authority is not project
-configuration and must not be persisted or reused in another conversation. It cannot choose source boundaries,
-authorize unread external sources or external operations, or bypass validation
-and verification.
+configuration and must not be persisted or reused in another conversation.
+Managed mode by itself does not authorize expanding sources or performing remote
+writes, and never bypasses validation. An explicit instruction to collect named
+documents already establishes that read scope; do not ask for the same permission
+again. Resolve essential missing goals or source boundaries before production.
+
+`grill-me` is targeted clarification, not a fixed questionnaire. Research what the
+available material can answer, then ask about consequential unknowns. A required
+schema field is not automatically a question for the user. For the first production
+task in a new workspace, the work-start report must resolve and display the agreed
+purpose, source families, language, settings, outputs and first delivery before
+source registration. Present it and wait for feedback even in managed mode. A
+report must not silently substitute guessed decisions for unanswered questions.

package/docs/guides/agent-guide.md

@@ -7,7 +7,10 @@ invent a separate pipeline for code, documents, or a particular host.
 
 Read `context status --format json`, then consume only the procedures, schemas,
 and manuals selected by `workflow.current.resources`. Preserve revision and
-authority flags in the next command. Do not infer progress from filenames or
+authority flags in the next command. Resolve files from the initialized workspace;
+its `.tmp/` and generated `AGENTS.md` belong to that same workspace. A resource
+may be a file or a returned command: follow its read order and `after_read`
+instructions instead of guessing a path or CLI subcommand. Do not infer progress from filenames or
 probe ignored runtime files when the Route already states the next action.
 
 ## Stable decisions
@@ -21,9 +24,16 @@ Ask the user only when the answer changes a durable boundary:
 - whether the proposed semantic outline organizes the requested knowledge;
 - whether the displayed Candidate content is approved.
 
-The Agent may decide mechanical details from evidence: parser selection within
-an approved Provider, deterministic partition execution, page slug generation,
-and recovery of an already completed step.
+Reuse answers and authority already supplied for the current task; these are not
+questions to repeat at every step. Even in fully managed mode, ask when missing
+purpose or scope would change the outcome. Before indexing a large boundary,
+identify irrelevant or obsolete areas with the user from actual material. Do not
+exclude them by naming heuristics or include them all merely because they exist.
+
+The Agent selects suitable Providers and makes semantic decisions about topics,
+organization and content. The CLI executes parsers, validates source/page
+identities, derives paths and schedules recovery. Do not make the Agent reproduce
+those mechanical operations or invent state to declare a step complete.
 
 ## Authoring boundary
 
@@ -31,7 +41,7 @@ and recovery of an already completed step.
 knowledge requirements and Provider selection. Keep these responsibilities
 separate.
 
-Code and Markdown Providers receive controlled worksets and return typed
+Code, Markdown, Note, Sessions and compatible business Providers receive controlled worksets and return typed
 results. They do not write Candidate, Review, `knowledge/`, or `dist/` files.
 Context validates and persists their result before the next action consumes it.
 Initial Provider selection follows the same rule: use the requirements and
@@ -44,10 +54,14 @@ For Partition and Author steps, one Route may contain several independent
 `tasks`. Read the shared instructions once, read each task's Authorized Workset
 View, and return one `results[]` item for every task key in that batch. Submit
 the whole batch with the Route's single `context action complete-current`
-command; a successful completion already carries the next prepared batch or
-the next lifecycle boundary. Do not materialize instructions or Views with
-separate commands, create a helper script, or construct internal Result,
-digest, receipt, Fact, or evidence-binding objects.
+command. Use a workspace `.tmp/` JSON or YAML input file for a large payload,
+then submit with `--input <file>`; avoid long JSON through an interactive PTY.
+A shortened completion may point to `result_file` and `next_route.file`; read
+them before deciding what was accepted. If preparing the next Route fails,
+keep accepted results and use the supplied refresh action. Retry only tasks
+still pending in the new Route, never the accepted tasks from an old batch.
+Do not construct internal Result, digest, receipt, Fact or evidence-binding
+objects, or materialize Views through commands the Route did not request.
 
 The batch is only a transport boundary. Keep every task's semantic answer,
 failure and retry independent, and do not combine unrelated Subjects merely
@@ -77,7 +91,22 @@ outline after all Partition shards converge; the second checks the final
 reader-facing Candidate set. Ordinary mode presents both to the user. Fully
 managed mode lets the Agent resolve both with current-conversation authority.
 A destructive or ambiguous layout change is separate and always human-only.
-Intermediate execution batches never create additional user approvals.
+Intermediate execution batches never create additional user approvals. Page
+delivery batches do complete their applicable content review, close and build;
+they are distinct from Partition transport batches. The first delivery normally
+contains 1–3 pages, followed by 30–50-page batches or a smaller remaining tail.
+
+For the first production task in a new workspace, follow the selected work-start
+report procedure using the user's task instructions and batch metadata titles for
+the supplied list, falling back to at most 10 unresolved title lookups if unavailable.
+Do not fetch source bodies or outlines before
+capture; missing titles may remain unknown. Detailed plans are provisional until
+captured evidence is available.
+Resolve its required start conditions, present it and wait for feedback before
+source registration or capture. Reuse explicit answers and defaults instead of
+asking a fixed questionnaire. Existing-workspace lightweight changes may keep a
+short conversational summary. The source-boundary Gate remains the confirmation
+authority; fully managed mode does not bypass the first report handoff.
 
 ## Quality bar
 
@@ -95,6 +124,15 @@ When dogfooding, compare the generated knowledge with an existing useful
 knowledge base. Feed gaps back into the Provider profile, instructions,
 templates, or parser coverage rather than editing generated pages by hand.
 
+## Corrections and source updates
+
+Use `context revise` for a selected approved page and `context update` for a
+selected source change. Writing starts from the existing approved text and uses
+the current Route's Provider, template and source material. New topics enter the
+applicable structure review before Author; they are not silent page additions.
+Use `task adjust` for changed inputs in the current task and explicit rollback
+for an agreed reversal. See [Update existing knowledge](knowledge-updates.md).
+
 ## Recovery and Git
 
 Runtime artifacts under `.tmp/context-runtime/` may be rich because they are

package/docs/guides/code-indexer-skill-authoring.md

@@ -21,16 +21,37 @@ rules, metric operators and thresholds.
 
 ## Author contract checklist
 
+For generated API tables, test the final Candidate as well as the parser payload
+and template preview. Cover direct and supporting references, partial contracts,
+shared types with different implementation defaults, ambiguous or cross-file
+links, and an approved-page regeneration after the source changes. Keep a known
+field when only part of its implementation can be extracted. Do not equate an
+accepted result with a corrected page.
+
+Document what each supported language adapter actually establishes. Preserve
+written expressions without evaluating arbitrary code, distinguish declaration
+defaults from implementation defaults, and explain unresolved imports or types.
+Unknown material, an unsupported parse, and a renderer contradicting a known fact
+need different responses. Use existing material requests and repair routes;
+neither a new content-quality gate nor a Provider-specific retry ledger is needed.
+
 1. **Responsibility.** Classify supported code modules and produce evidence-
    bound partitions, logical units, Artifact Bundles and Results. Do not own
    source authorization, requirement approval, final review, CLI metrics or
-   package publication.
+   package publication. Source-specific Note/Sessions layers may contribute
+   declared guidance to a code page; they do not become another primary or
+   turn a conversation's proposed change into implemented code behavior.
 2. **Manifest.** Use the sole `context-indexer.yaml` field tree. Bind domains,
    profiles, operations/fragments, resources, source roles, logical units,
    customization support and composition without duplicate aliases.
 3. **Resource composition.** Combine only declared programs, profile-bound
    instructions, templates and optional detector/inspector resources. Omitted
    capabilities remain unsupported; natural language cannot add them.
+   Put any Agent-executed grouping rules in those declared instructions or
+   templates so Context delivers them with the current View. A partition
+   strategy id or digest is not an instruction resource. Context selects and
+   records strategy attempts; the Agent returns semantic groups and dispositions,
+   without discovering strategy implementations or managing fallback order.
 4. **Activation and profiles.** Declare strong/supporting/negative signals.
    Dependency names are candidates, not runtime proof. One module may combine
    one primary profile with supporting/extensions and selected composers.
@@ -84,8 +105,8 @@ rules, metric operators and thresholds.
     shapes. Local facts remain baseline when optional remote metadata is absent.
 18. **Versioning.** Use Skill/Provider SemVer, exact Provider pins and Bundle
     integrity. Fixed dependencies require exact versions and resolved
-    integrity. `@context-indexer-origin` is optional on local customizations
-    only and grants no authority.
+    integrity. `@context-indexer-origin` is required on workspace-local customization
+    files and grants no authority. It is not required on Provider bundle files.
 19. **Trust boundary.** Skill/manifest describes capabilities; the verified
     Bundle supplies bytes; workspace customization supplies project deltas;
     CLI contracts supply hard rules. Keep these four authorities distinct.
@@ -113,12 +134,22 @@ rules, metric operators and thresholds.
     consumed in the bounded Author View rather than copied into every
     Partition decision.
 
-For behavioral explanations, the Author View also supplies `source-text`
-items with the authorized source lines. Each merged range links to existing
-source-span dependency nodes through `source_span_refs`; use those nodes for
-evidence bindings. These process-local snippets are reading material, not new
-Facts or reader-page metadata. Do not reopen the repository or infer behavior
-from a locator alone when the supplied lines do not establish it.
+The current Route delivers readable task material with goals and constraints
+first, followed by the authorized sources and facts. For behavioral explanations,
+read the complete source excerpts. Copy the displayed `source_items` into the
+section's `source_items`; use Fact references in `facts`, not as source items.
+Context resolves a text item's authorized source spans internally. Inventory
+identities and a repository reference do not identify section source material.
+These process-local excerpts are not new Facts or reader-page metadata. Do not
+reopen the repository or infer behavior from a locator alone when the supplied
+lines do not establish it. Batch size does not define a knowledge page boundary.
+
+Author task resources may point to one shared batch reading file. Read that path
+once, use shared material only for its listed task keys, and consider each task's
+own goals and source excerpts. Context shares identical material, not conclusions:
+prepare a separate result for each task and submit the `results[]` together through
+the current completion command. A retry includes the remaining tasks' material in
+full; no earlier batch file or additional reading command is required.
 
 ## Result and composition rules
 
@@ -130,8 +161,8 @@ an empty composer run still has a receipt. Composer selection is the
 intersection of registry selection, manifest declaration and current profile
 applicability, not array order.
 
-Use canonical SubjectKey schemas and the Context NodeRef formula. Code and
-Markdown Indexers must reuse the same Node when the SubjectKey is equal. An
+Use canonical SubjectKey schemas and the Context NodeRef formula. All selected
+Providers must reuse the same Node when the SubjectKey is equal. An
 enricher uses the supplied TargetResolutionView (`resolved`, `absent` or
 `ambiguous`) and never guesses identity from a title or path resemblance.