@c4a/context 0.7.10-alpha.2 → 0.7.10

package/docs/getting-started.md

@@ -17,7 +17,7 @@ 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: []`.
+and asks for confirmed `requirements` only, without `protocol` or `indexers` keys.
 
 Run workspace commands inside this initialized directory. Route paths and
 `.tmp/` belong to this workspace, not the surrounding repository.
@@ -27,8 +27,8 @@ Run workspace commands inside this initialized directory. Route paths and
 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 20260901 --module product-docs --local ../docs
+context source add repo 20260901 --module component-lib --local ../component-lib --configure
+context source add file 20260901 --module product-docs --local ../docs --configure
 ```
 
 Replace the date and paths with the actual inputs. Both commands register a
@@ -40,17 +40,21 @@ Do not exclude content merely because a filename looks old.
 For an authorized Lark document, registration instead looks like:
 
 ```bash
-context source add lark 20260901 --module handbook --doc-token "<actual-token>"
+context source add lark 20260901 --module handbook --doc-token "<actual-token>" --configure
 ```
 
-Use `captureLark()` for that registered document. Notes and conversation summaries
+`--configure` adds explicit source and default capture declarations to a simple
+project entry without fetching content. Existing custom settings are preserved;
+a `manual` configuration result asks for a focused edit, not a registration retry.
+Omit the flag when you only want registration. 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:
+The generated source/capture declarations can be combined with the selected output
+configuration. For the code and local-document example, `src/index.ts` contains:
 
 ```ts
 import { captureFile, defineProject, kbPackage, source } from "@c4a/context";
@@ -76,27 +80,26 @@ 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
+## 4. Plan the requested knowledge
 
 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`.
+scope, relevant Skills and the first pages to expect. The report requires user
+confirmation before writing, including in managed mode.
+
+The configuration Route supplies the requirements schema and guide. Record the
+reader purpose and authorized sources in `src/indexers.yaml`. The Agent chooses
+relevant installed Code, Markdown, Note, Sessions or custom Indexer Skills during
+planning; their use is recorded in the temporary plan, not a persistent Provider
+registry. There is no separate Provider selection gate.
+
+Plan reader topics, reusing related existing articles. Keep small document or
+single-module tasks local; do not redesign the whole workspace. Once the report
+is approved, write Markdown and references in the returned task directories and
+submit their manifest. The CLI creates Candidates. Do not create a second
+knowledge pipeline in `src/index.ts`.
 
 ## 5. Review and deliver pages
 
@@ -109,9 +112,8 @@ 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.
+Delivery scope follows the agreed task and current Route, not fixed page-count
+waves. Each delivery completes review, close and build before continuing.
 
 ## 6. Continue or update
 
@@ -133,8 +135,8 @@ explains their inputs, same-task adjustment and explicit rollback.
 
 - 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.
+- Fix requirements through the current configuration Route; use its supplied
+  schema rather than adding Skill selections to the requirements file.
 - 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/`

package/docs/guides/agent-guide.md

@@ -38,24 +38,18 @@ those mechanical operations or invent state to declare a step complete.
 ## Authoring boundary
 
 `src/index.ts` owns source capture and package output. `src/indexers.yaml` owns
-knowledge requirements and Provider selection. Keep these responsibilities
+long-term reader requirements and authorized sources. Keep these responsibilities
 separate.
 
-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
-CLI-bundled catalog in the current Action input, return only non-CLI visible
-Skill identities and semantic Indexer entries, and let the CLI perform routing,
-resolution, staging, validation, and atomic registry apply. External resolver
-results and non-allowlisted program decisions resume through subsequent
-`complete-current` Routes; do not invoke the low-level Provider commands.
-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. 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.
+Code, Markdown, Note, Sessions and custom Indexer Skills guide source investigation
+and writing. Record relevant Skill use in the temporary plan's `indexer_usage`,
+not `src/indexers.yaml`; there is no Provider resolution or registry-apply step.
+Read shared instructions once, then the relevant task materials. Write Markdown
+and reference files in the returned Agent directory and submit the short manifest
+with the current `context action complete-current` command. Completed subsets
+may be submitted without repeating accepted tasks. The CLI validates and persists
+Candidates and owns Review, `knowledge/` and `dist/` writes. Do not fill retired
+workset `results[]` protocols or put full article bodies in command arguments.
 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

package/docs/guides/indexer-provider-and-customization.md

@@ -28,7 +28,6 @@ production assignments. For example, replace the source and goals with the
 user's actual scope:
 
 ```yaml
-protocol: context.indexer.registry/v1
 requirements:
   - id: integration-guide
     purpose: Help application developers understand and integrate the system.
@@ -41,7 +40,6 @@ requirements:
     evidence_source_scope:
       targets:
         - source_ref: repo:sample
-indexers: []
 ```
 
 Use registered source identities, not guessed paths or URLs. Keep any confirmed

package/docs/guides/knowledge-updates.md

@@ -16,6 +16,22 @@ and continues through Review and delivery. Expression-only changes need no
 source capture or Parser. Preserve prior confirmed contributions; distinguish
 actual behavior, a confirmed decision, and a proposal that is not implemented.
 
+## Keep planning local to the change
+
+For one or two documents or a clearly bounded module, retain the useful planning
+decision: add or revise which articles, and place them where readers expect them.
+Do not expand this into a whole-workspace taxonomy, full navigation redesign or
+multi-wave plan. Read related existing topics first and expand only as needed.
+One module can contain several topics; scope and ambiguity, not source count,
+determine how much investigation is useful.
+
+Reuse an approved stage's plan for in-scope additions through its existing amendment
+route. Keep completed work and unrelated pending investigation intact. If article
+targets are already decided before approval, the preparation route supports a
+known-task input to combine preparation and task creation. It still prepares
+navigation and retains report confirmation; it is not a bypass for new source
+authorization. Planning depth is an Agent judgment, not an additional CLI gate.
+
 ## First-task intake budget
 
 Before registration and capture, the Agent uses the user's task instructions and
@@ -56,7 +72,14 @@ progress under `.tmp/` never causes a version increase.
 Version recording runs at completed-scope delivery after Review, Close and package
 configuration/template approval, before the final build. The record response
 returns the next workspace Route, so no extra status call is needed. Build retries
-reuse the recorded version when formal content is unchanged. Intermediate batches
+reuse the recorded version when formal content is unchanged. If build preparation
+or rendering fails and formal corrections are needed, `version inspect` returns
+`reusable_version` for the current entry only while it has no successful build or
+publication receipt. Submit that same version with the complete iteration's title,
+changes and triggers, including the repair; this replaces the pending changelog
+entry rather than appending another version. Do not submit only the repair and
+lose the original delivery description. Once built or published, the version is
+sealed and further formal changes require an increase. Intermediate batches
 do not each receive a version.
 
 The workspace AGENTS.md and version-writing instructions require each entry's
@@ -85,7 +108,10 @@ actor:
 ```
 
 `actor` is optional; omit it to use local Git `user.name` when configured. Use a
-Lark display name only when explicitly known from the conversation. Trigger kinds
+Lark display name only when explicitly known from the conversation. Amending an
+unbuilt entry preserves its actor unless a replacement is explicitly supplied.
+If neither the conversation nor Git identifies the user, omit the actor and
+mention the missing identity in the delivery summary; never guess it. Trigger kinds
 are `initial`, `note`, `sessions`, `mr`, `module`, `document`, `navigation`,
 `repair`, `dist`, and `other`. Agent-written fields describe the actual diff and
 conversation; they must not expose credentials, raw transcripts or private IDs.

package/docs/guides/workspace-prepare.md

@@ -36,6 +36,23 @@ reports, unique material, unknown files and modified checkouts unless their
 specific loss is authorized. Do not delete locks, transaction records or active
 tool directories. Empty task directories can remain.
 
+Prefer cleanup after successful delivery, not immediately after close: version
+recording, build and retries may still need the current task. Completed production
+drafts and Review state are removed by delivery cleanup. Do not invoke
+`task resume` merely to make a completed workspace advance; it starts a new task
+and requires an actual new user request.
+
+Keep repository checkouts referenced by registered sources, including fixed
+commits: removing them can force a costly clone before the next update. Keep
+pending telemetry and source-region baselines; losing the latter reduces the
+ability to distinguish relocated text from changed text. Debug and historical
+views may be archived or removed after diagnosis when no operation is active,
+but unknown Agent files are not automatically disposable.
+
+After all scratch state is lost, an existing build receipt defaults the workspace
+to waiting for an explicit new task. This does not restore lost drafts or prove
+sources and outputs are current. Use the recovery checks below before resuming.
+
 ## Restore usable sources
 
 For repositories, run `context source recovery-plan --format json` and read

package/docs/reference/project-api.md

@@ -4,8 +4,8 @@ The project has two durable declarations with separate responsibilities:
 
 - `src/index.ts`: source references, document capture, custom non-knowledge
   orchestration, and package outputs.
-- `src/indexers.yaml`: knowledge requirements, Provider selection, target/read
-  scopes, profiles, and Provider customization.
+- `src/indexers.yaml`: long-term reader requirements, authorized target/supporting
+  sources and confirmed exclusions. Skill choices belong to the temporary plan.
 
 Do not describe the same knowledge transformation in both files.
 
@@ -53,6 +53,19 @@ and [knowledge updates](../guides/knowledge-updates.md).
 
 ## Capture phases
 
+For ordinary acquisition, add `--configure` to `context source add repo`, `file`,
+`lark` or `batch`. The command registers the selected inputs and generates explicit
+source references and default document capture phases in `src/index.ts`. It does
+not fetch content, select other registrations or change package outputs.
+
+Generation supports a literal `defineProject` with literal source/phase arrays
+and recognizable SDK calls. Existing capture settings are preserved, repeated
+registration is idempotent, and custom/dynamic entries remain untouched with a
+`configuration.status: manual` hint. Registration is still saved; edit only the
+needed declarations through the normal configuration path. For special processors
+or resource options, configure them before following the capture Route. Omitting
+`--configure` keeps registration-only behavior.
+
 ```ts
 captureFile({ source: docs });
 captureFile({ source: docs, processor: mdxJsonDocs() });
@@ -67,24 +80,27 @@ creating a second capture or knowledge pipeline.
 
 ### Batch capture from the source registry
 
-When all registered Lark documents are intended for this project and share capture
-settings, read the registry once instead of copying its module names into
-`src/index.ts`. For the standard `src/index.ts` entry:
+For documents with shared capture settings, prefer registry-driven configuration
+over repeating source declarations and capture calls, even for two documents.
+Select the task's intended registrations first. The example below assumes all
+registered Lark documents are in scope, with the standard `src/index.ts` entry:
 
 ```ts
 import { fileURLToPath } from "node:url";
 import {
-  allSources, captureLark, defineProject, loadSourcesRegistry, source,
+  captureLark, defineProject, loadSourcesRegistry, source,
 } from "@c4a/context";
 
 const workspaceRoot = fileURLToPath(new URL("../", import.meta.url));
 const registry = await loadSourcesRegistry({ rootDir: workspaceRoot });
+// For a subset, filter registry.larks by the authorized namespace/names here.
 const documents = registry.larks.map(entry =>
   source(entry.name, { type: "lark" }),
 );
 
 export default defineProject({
-  sources: [...allSources("repo"), ...documents],
+  sources: documents,
+  // Shared settings, independent source identities and capture phases.
   phases: documents.map(document => captureLark({ source: document })),
   packages: [],
 });
@@ -109,6 +125,10 @@ Registry loading only reads local registrations; it does not fetch documents.
 - The map declares one phase per document. It does not fetch URLs, change capture
   permissions, or request parallel execution. Run the declared phases through the
   existing CLI flow so each document retains independent refresh and retry behavior.
+  This reduces configuration repetition, not the number of capture operations.
+- Capture boundaries do not dictate article boundaries. During planning and
+  writing, combine related captured documents around reader tasks when useful;
+  do not create one article or a complete production cycle per source by default.
 
 ## `customPhase`
 
@@ -148,18 +168,18 @@ from the package name, if present. Omit it for KB-only output. It accepts `title
 `src/knowledge-map.yaml` independently of KB directories; see
 [Package Outputs](../guides/package-outputs.md#optional-static-documentation-website).
 
-## Indexer registry
+## Knowledge requirements and Indexer Skills
 
-When this file is absent, the configuration Route supplies the initial schema:
-write confirmed `requirements` with `indexers: []`, then re-evaluate. The Provider
-selection Action supplies its own completion schema; that payload is not the
-configuration file. Subsequent changes use typed proposals and applicable gates. Each selected Indexer binds requirements and scopes to one
-primary Provider, with optional declared layers or composers. Provider code
-must return the current Indexer result protocol; it must not write Candidate,
-knowledge, or Review files directly.
+When `src/indexers.yaml` is absent, the configuration Route supplies its schema.
+Write `requirements` only; do not add `protocol`, `indexers`, Provider selections
+or profiles. Re-evaluate after changing confirmed requirements.
 
-Detailed Provider protocol and customization guidance is selected by the
-current workflow Route when it is needed.
+Installed Indexer Skills guide investigation and writing. Relevant Skill choices
+and optional configuration use `indexer_usage` in the temporary production plan,
+not this durable file. There is no separate Provider selection or resolution gate.
+The Agent writes task drafts and reference files under the returned temporary
+directory; the CLI accepts them and owns Candidate, Review and formal output.
+See [Indexer guidance](../guides/indexer-provider-and-customization.md).
 
 ## Persistent versus runtime state
 

package/index.js

@@ -15959,7 +15959,7 @@ function validateIndexerArtifactResult(input) {
       capability_group_ref: group.capability_group_ref,
       member_ids: group.member_evidence.map((member) => member.member_id)
     })),
-    material_gap_proposal_refs: result.material_question_proposals.map((proposal) => proposal.proposal_ref)
+    material_gap_proposal_refs: result.question_target_dispositions.flatMap((disposition) => disposition.state === "material-gap" ? [disposition.material_question_proposal_ref] : [])
   });
   const targets = new Map(input.allowed_question_targets.map((target) => [target.question_target_key, target.question_ref]));
   assertUnique(result.question_target_dispositions.map((item) => item.question_target_key), "question targets");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c4a/context",
-  "version": "0.7.10-alpha.2",
+  "version": "0.7.10",
   "type": "module",
   "description": "Declarative SDK for Context knowledge sources, workflows, review, and package outputs",
   "license": "MIT",