@c4a/context-cli 0.7.5 → 0.7.9

package/providers/context/resources/procedures/knowledge-updates.md

@@ -0,0 +1,428 @@
+---
+id: procedure.knowledge-updates
+kind: procedure
+mediaType: text/markdown
+---
+
+# Update existing knowledge
+
+Use the same Context conversation and the current workspace. Identify whether
+this is a continuation, an adjustment to the current task, a correction to one
+page, or an independent task. An old Route does not incorporate a new request.
+For explicit workspace preparation, Git commit or historical restoration, use
+[prepare](workspace-prepare.md), [commit](workspace-commit.md) or
+[restore](workspace-restore.md); these Agent-led operations do not automatically
+start production. Otherwise, do not start an independent task while another remains: explain what is saved
+and unfinished, and obtain the user's choice to finish or roll back the current
+work. Do not delete runtime files to simulate rollback.
+
+For an unambiguous page correction, use `context revise "<path or title>"
+--instruction "<correction>" --format json`. Context supplies the existing text
+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.
+
+## First-task intake budget
+
+Before registration and capture, the Agent uses the user's task instructions and
+reads batch metadata titles across the explicitly supplied document list. Lark
+metadata requests accept at most 200 entries each, not 200 words or 200 documents
+overall. H1/H2 may be reused only when metadata returns them without
+body retrieval; Lark batch metadata returns titles, not headings. Batch failure
+falls back to at most 10 unresolved document title lookups total, unless a shared
+authentication failure makes those calls redundant. The Agent does not fetch
+source bodies, outlines, images or attachments. Missing title metadata is
+optional: preserve the original URL without falling back to body retrieval or
+changing credentials. Resolve intent from the conversation; refine provisional
+chapters and module boundaries from evidence after formal capture.
+
+## Workspace versions and changelog
+
+`package.json.version` is the workspace SemVer. At completed-scope delivery the
+workflow asks the Agent to inspect formal changes and record an increasing version
+with a concise changelog. Added modules or expanded material coverage increment
+minor; corrections, existing-module updates, navigation and persistent status
+changes increment patch. Major requires an explicit user instruction. Temporary
+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
+do not each receive a version.
+
+The workspace AGENTS.md and version-writing instructions require each entry's
+details to stay within 1500 visible characters, including punctuation across the
+title, changes, trigger descriptions and actor display name, excluding protocol
+keys, version and date. The Agent compresses longer drafts before submission,
+preserving main changes, impact and triggers instead of truncating text or splitting
+the iteration into extra versions. This is an Agent writing rule, not a prose-quality
+CLI gate.
+
+`context version inspect --format json` returns changed paths and a digest. The
+coordinator submits `context version record --input <file> --format json` with:
+
+```yaml
+expected_digest: "<digest returned by inspect>"
+version: 0.2.0
+title: Add module recovery guidance
+changes:
+  - Document recovery conditions and the supported retry flow.
+triggers:
+  - kind: module
+    description: Additional module material requested in this iteration.
+actor:
+  kind: lark
+  name: Example User
+```
+
+`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
+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.
+
+The CLI writes `changelog.yaml`, generated `CHANGELOG.md`, `package.json` and the
+`.context-version.json` content baseline together. Keep these formal files with
+the workspace; do not hand-edit generated baselines. Git-managed and unignored
+new files are compared (without Git, non-runtime workspace files are compared).
+Version metadata itself, `dist`, `.tmp` and dependencies do not cause changes.
+
+Successful builds record version and per-package hashes in `.context-builds.json`.
+They do not increase versions. Before publishing, `context version publish-check
+--format json` compares against `.context-published.json`. A same-version changed
+output requires a patch using `version inspect --publish` and a `dist` trigger,
+then a rebuild. Record `version published --hash <checked-hash> --receipt
+<successful-publication-reference> --format json` only after external success.
+No command commits, tags or uploads automatically.
+
+Website history is available at `changelog.html`: cards are newest first, the
+latest three expanded and older cards collapsed. The History button beside the
+theme switch and footer update timestamps link there. KB and LLMS outputs carry
+the same workspace version and changelog.
+
+## Customize the knowledge map at any time
+
+For a knowledge-map-only change, use the existing `context task adjust
+--input <file|-> --format json` action with `knowledge_map`. Supply its
+current `expected_revision`, explicit `upsert` entries and `remove` keys. Each
+entry retains its stable key, parent, title and order; optional targets use
+article identity and section key. The current structure preview supplies those
+identities. Read the persistent `src/knowledge-map.yaml`; use
+`expected_revision: null` only when no knowledge map exists.
+After adjustment, follow status to rebuild affected packages. This changes the
+reading organization without capturing sources or rewriting approved prose.
+Do not directly edit generated package navigation or use titles as identities.
+
+Users can ask in conversation to move a topic, rename a directory, change order,
+or organize the same articles for another reader task. Handle this during ongoing
+production or after completion through the same adjustment; no active Indexer
+task, source recapture or new mode choice is required. Finish or revoke active
+worker assignments before changing the map. Preserve unrelated entries and page
+identities. The map controls website navigation and LLMS organization together.
+
+For each new or changed article, the Agent decides whether to retain its current
+placement, add another placement, move it, or create a warranted category. Check
+these choices against the user's settled organization before structure approval
+and delivery. New articles must be bound even if the map revision has not changed;
+modifying a title alone is not a reason to change article identity. Never satisfy
+coverage by mechanically placing every new page under an unrelated catch-all.
+Build reports missing bindings for the Agent to resolve; it does not classify
+content. Moving a menu entry does not change the article URL.
+
+## Edit one section or review part of a batch
+
+The current approved-revision Route accepts either full `markdown` or explicit
+`sections` edits. Use an existing `writing_context.current_sections` ID and an
+ordered `content` list of `{ "markdown": "new text" }` and/or
+`{ "program": "exact current program token" }`. Unchanged sections and the
+selected section's source references remain intact. Use full Markdown when
+changing structure, adding a page or when a section has no unambiguous ID.
+
+For an optional check, append `--preview` to the current `action complete-current`
+command with the same revision and input file. It validates and returns the
+assembled page and previous text without accepting the edit. Submit the same
+input without that flag to continue. A preview is not approval and does not make
+a stale revision valid.
+
+Review can approve checked pages while leaving repair pages pending. The HTML
+review code includes pending positions; managed Review provides the same current
+scope as a JSON template. Send decisions only for pages actually reviewed. Omit
+means a durable exclusion, not repair. Partial approval alone does not build.
+
+When the user requests an earlier delivery, use the Route's `context run
+--deliver` request. Independently approved pages can pass close/build while
+pending candidates remain for Review or repair. Links to pending or missing
+pages keep their necessary scope together. Source processing baselines advance
+only after the entire update finishes. Failed builds retain the selected delivery
+and pending work; repair the cause and follow the current Route.
+
+## Acquire the selected change once
+
+Use the host's existing Git, code-hosting or document tools and their installed
+guidance. Context does not poll a platform, discover remote changes, or infer
+that a merge request is merged. Reading an already selected source does not
+require a new permission question when access was already authorized. Do not
+change the user's checkout or fetch another repository without that scope.
+
+For a branch or MR/PR, establish the repository, intended target branch, merge
+state and actual fixed target commit. An unmerged proposal is not the current
+mainline. A merge, squash or rebase can produce different commit identities;
+use the target branch's actual result, not the feature branch SHA. Include
+other intervening changes between the last processed version and the selected
+target when they affect the registered modules. Reverts are real changes.
+
+Use already available local Git objects to compare the selected module trees
+and necessary diffs. A new repository commit with unchanged module trees can
+be a no-knowledge-change conclusion. That conclusion must also account for any
+new note or development context. If a baseline is unavailable after force push,
+a shallow checkout or history cleanup, state that a complete old diff is
+unavailable; compare current material with approved knowledge in the confirmed
+scope. Do not claim no change because a Git command failed. A repeated MR may
+still bring new relevant context; it does not justify moving the code baseline
+backwards or summarizing unrelated commits as part of that MR.
+
+For documents, a revision shortcut is valid only if the host actually exposes a
+reliable version for the selected document and its needed images/attachments.
+Otherwise read that selected document and resources. Keep the returned bytes
+for the existing capture/import action; do not fetch them again as verification.
+An unchanged body does not prove images are unchanged. Distinguish lack of
+permission, deleted content, and moved content; a read failure is not permission
+to retire a knowledge page. CLI status describes local acquisition only.
+
+After the current source configuration and material identify the chosen fixed
+versions, submit the update with `context update --input <file|-> --format json`.
+Write ordinary YAML or JSON with the host's editor, without a generated wrapper
+program. Input files belong under this workspace's `.tmp/`.
+
+```yaml
+scopes:
+  - requirement_ref: reader-guide
+    source_ref: repo:20260901/library
+changes: The selected change adds one public option; inspect its explanation and examples.
+```
+
+`requirement_ref` is the existing requirement id. Omit `module_refs` for a whole
+confirmed source scope. `processed_version` may be supplied to bind the exact
+acquired commit or document content digest; otherwise Context captures it from
+the existing local material. A supplied version must match that material.
+Follow the returned Route. The candidate list is a conservative source match,
+not a list of pages that must change. Read the actual change and current pages,
+also checking additions that have no old page reference. The scope is complete
+only after every required change is reviewed, closed and built, or after an
+explicit conclusion that it needs no knowledge changes.
+
+Before importing a `note`, read [note source preparation](note.md).
+Before importing `sessions`, read [development summary preparation](sessions.md).
+Choose the reference for the actual input; do not read both by default.
+
+## Save text without an external file
+
+Use `context source import --input <file|-> --format json`:
+
+```yaml
+type: note
+name: 20260907/decision-context.md
+markdown: |
+  # Decision context
+
+  The selected discussion confirmed this exception for the stated situation.
+  The implementation has not yet changed. Source: the discussion supplied here.
+```
+
+The body is saved directly under `sources/note/` or `sources/sessions/`; no
+external `local`, capture, registry or second copy is required. Use a readable
+semantic filename under an eight-digit date directory. Do not put a date, hash
+or session id into the filename again. Keep the path for retries and later
+edits. To revise an existing source, read it and pass its current `base_digest`
+with the replacement Markdown. Distinct same-day material needs a distinct
+semantic name, never a silent overwrite. `source list`, `source get` and
+`source inspect` expose the actual source paths. Removal uses the existing
+preview and exact plan digest, and refuses still-referenced text.
+
+Saving alone does not start indexing. If the user only wants the source saved,
+report its path and stop. For production, reuse the existing requirement:
+put independent content in `target_scope`; put supporting material in
+`evidence_source_scope` and ensure the selected Indexer's existing `read_scope`
+covers it. Do not create a separate Markdown production target for a supporting
+explanation of a code page. In the source-update decision, include its exact
+`supporting_sources` on the affected page. Include that source's scope in this
+update so completion can distinguish code from newly processed context.
+
+## Development context accompanying a commit
+
+Use `trace-session` only as this conditional source-preparation step. If the MR,
+code and existing design already explain the relevant information, cite them.
+Write a `sessions` source only when real, explicitly available development
+context contains useful decisions, reasons or limits missing from those sources.
+Do not fabricate discussion from a diff, search host session storage, ask for
+nonessential history, or create an empty/skip report. This is only the code-related subcase. An authorized conversation summary
+without an MR or commit is also `sessions`; see the sessions source guide.
+Optional `changes` belongs in the source frontmatter, not knowledge headers.
+
+Use the available merge date, or commit date for a pure commit, for the initial
+directory; if unavailable or saving an unmerged discussion explicitly, use the
+current collection date and explain the context. Do not query a platform just
+for this date. Keep the path when later adding a reference or retrying another
+day. One coherent change can share one summary; separate unrelated changes.
+
+The shortest useful body is the real repository/MR/commit reference plus one
+paragraph explaining what the code does not tell a later reader. Describe only
+the actually associated commit subset. Omit a full change recap, transcript,
+test log, session id and formal approval claim. Write confirmed decisions as
+such, alternatives as alternatives, and unresolved proposals as unresolved.
+Do not claim execution or tests that were not observed. The writing aid below
+is optional; no section is mandatory:
+
+```markdown
+# <Change topic>
+
+<Reference the actual repository and MR or concrete commits already available.>
+
+<Explain the useful decision, reason or constraint absent from the code/design.
+State its applicability and distinguish implemented behavior from a proposal.>
+```
+
+Late context can update a page even when the code version is already processed.
+Reuse that fixed code version and current approved prose; do not restart Parser
+merely because a summary arrived. Import once, then include the necessary
+context with the same knowledge update. Saved context survives a failed build;
+saving it does not mean its knowledge impact has been delivered.
+
+## Optional correction of an upstream document
+
+Local knowledge approval and fully managed execution do not authorize a remote
+write. First determine whether the knowledge misunderstood correct source text,
+a confirmed decision has not reached the source, or the conclusion is still
+uncertain. The first needs only a local correction; the second can use a note
+locally while an upstream change is considered; uncertainty is not a fact.
+
+Present the exact document, affected passage, proposed before/after text, reason
+and affected knowledge. Reuse existing authorization for that concrete edit;
+otherwise ask for it. Before writing, read the affected passage again using the
+host document tool. Adapt only within the authorized scope if another person
+has edited it; ask again only when the requested change materially differs.
+
+Execute with the host tool and read back the result. If the write result is
+uncertain, read back before retrying an insertion. Only the actual returned
+source text and resources may refresh its snapshot. Feed them into the same
+local capture/update route; a note or proposed patch is not a remote snapshot.
+If the remote edit succeeded but local build failed, resume local delivery;
+do not repeat the remote edit. Explain remote and local outcomes separately.
+Do not automatically delete an absorbed note, post comments, notify groups or
+change permissions. Permission failure can leave a concrete suggestion for
+the user without blocking an independently supported local correction.
+
+## Import a document response already read by the host
+
+For a registered Lark source, retain the actual full JSON response from
+`lark-cli docs +fetch` and each returned continuation page. Do not reconstruct a
+response from a summary. Use the same source import command:
+
+```yaml
+type: lark
+name: 20260907/guide
+access_identity: user
+response_files: [.tmp/guide-response.json]
+media_files:
+  actual-image-token: .tmp/downloaded-image.png
+```
+
+Only include real media tokens and downloaded files. Context runs the ordinary
+capture normalization and resource checks on these bytes. It does not fetch the
+provided document again; missing required resources follow existing capture
+handling. Partial outline/section fragments cannot replace a full snapshot.
+Use the identity that actually produced the response, not a credential fallback
+chosen to bypass permissions. Subsequent local updates use the captured version
+and the same Review/build route.
+
+## Adjust or roll back current work
+
+For an explicit same-task change to native Indexer source inputs, use
+`context task adjust --input <file|-> --format json` with `scopes` containing the
+selected `source_ref` and optional `module_refs`, plus an `instruction` explaining
+the adjustment. It invalidates those old worksets and retains independent work.
+Import the fixed replacement material before following the refreshed Route.
+Do not execute the old batch payload. A local page correction still uses
+`revise`; it is not a reason to invalidate an entire source.
+
+For an independent task, complete the old Route unless the user chooses a
+concrete rollback. Without an identifiable baseline or attribution of changes,
+ask about that gap or offer completion; never guess original bytes. Prepare
+`context task rollback --input <file|-> --format json` using:
+
+```yaml
+summary: Restore the selected page and discard unfinished follow-up drafts; keep other work.
+discard_unfinished: true
+files:
+  - path: knowledge/guides/selected-page.md
+    base_digest: sha256:<current-file-digest>
+    content: |
+      <exact recoverable original Markdown, not a newly generated replacement>
+```
+
+`files` contains only the explicitly selected reversions. `content: null` removes
+an explicitly selected file that this task added; `base_digest: null` is for
+restoring an absent file. Include changed sources/configuration/processed scopes
+when they belong to the rollback. Leave unrelated and pre-existing edits alone.
+An empty list only discards unfinished work and must not be described as undoing
+already delivered pages. The preview shows actual before/after contents and
+draft loss. Once the user approves that exact scope, run the preview's apply
+command with its plan digest. Then follow the rollback Route through close,
+build and cleanup. A failed build retries delivery, not the already-applied
+reversions. Begin the independent task only after cleanup succeeds.
+
+A managed source can be explicitly renamed with `context source rename
+"<note:... or sessions:...>" --name "YYYYMMDD/new-name.md" --format json` after
+its active work is finished. Review the file/reference changes, then apply the
+returned digest-bound command. Existing references move with it; the original
+body is not copied into another source type. Follow status to refresh affected
+knowledge structure and packages.
+
+To move an approved page, use `context revise "<old path>" --move-to "<new path>"
+--instruction "<requested move and content changes>" --format json`. The new
+path stays in the same collection. The revision retains the page identity,
+rebases outgoing links and updates incoming Markdown links at approval. A new
+subject name alone only needs a title/content revision; do not create duplicate
+pages. Retirement is a content decision: explain the inapplicable material and
+supported replacement before changing its page and referring navigation.
+
+### Adjust inputs while a local update is unfinished
+
+`context task adjust --input <file> --format json` also applies to an active
+approved-page revision or source-update queue. Keep `scopes` and `instruction`
+explicit. First call without `refresh`; it authorizes replacing only those
+inputs and blocks page completion while acquisition is pending. Import the
+selected new material, then repeat with `refresh: true` to bind the actual local
+versions and obtain the new Route. Do not submit the old revision. Current
+prose and queued pages remain; an affected draft returns to writing/review.
+An unrelated queued page does not revoke an unchanged current page's review.
+If a page has already been applied, finish its close/build before changing its
+inputs. Only the final completed scope advances its processed baseline.
+
+For several documents, `source import` also accepts a JSON/YAML array of the same
+single-document inputs. Its receipt reports each zero-based input index and
+success or error separately; a partial batch returns a nonzero exit code.
+Keep successful sources and retry only failed entries. It does not fetch a
+successful prefetched document again or roll back an unrelated saved note.
+
+To add a new supporting source to an unfinished local revision, first save it
+and include it in the current requirement's evidence scope and the selected
+Indexer's read scope. Its `task adjust` scope also supplies the explicit
+`requirement_ref`. This extends the current page's available sources and keeps
+queued pages; it does not silently start another task or another Indexer.
+
+### Replacing supporting article identities
+
+When an upstream article is split, merged or removed, start `context revise` for
+its consumer and use `context task adjust --input - --format json` with
+`instruction` and `knowledge_dependencies: { dependencies }`. Each dependency
+uses an approved `artifact_ref`, optional `section_refs`, and `required` flag.
+The current Author input returns authorized replacement facts and their evidence.
+Repeat the adjustment with `knowledge_dependencies.sections`, selecting each
+retained `section_key` and its full `fact_refs` and `evidence_refs` support. Then
+revise the explanation and complete normal Review, close and build. An explicit
+empty dependency list removes the relationship only when remaining sections have
+valid direct support. Missing dependencies, changed approvals and invalid source
+references cannot silently become current evidence. Writing quality remains an
+Agent/Review decision; no chapter-count or wording gate is introduced.

package/providers/context/resources/procedures/note.md

@@ -0,0 +1,43 @@
+---
+id: procedure.note
+kind: procedure
+mediaType: text/markdown
+---
+
+# Prepare a note source
+
+Read this before importing or correcting a note. The CLI saves supplied Markdown;
+source preparation happens before knowledge production.
+
+A note may contain supplied original text, selected verbatim excerpts, a summary,
+or a useful combination. Do not require raw text plus a summary for every note.
+If both exist, distinguish them with readable headings or prose. Preserve short
+original text when useful; do not duplicate it just to fill a form. Label an
+external or Agent summary as a summary, never an original transcript.
+
+For long inputs, retain relevant excerpts or summarize within the agreed purpose.
+Keep qualifications, exceptions, disagreement and unresolved questions that affect
+the conclusion. State the available origin and selected scope, including material
+omissions when consequential. Quote only actual verbatim input. Do not invent
+links, speakers, dates or confirmation. A link does not mean its target was read;
+ask about essential missing context rather than fetching everything for a label.
+
+Save the body under sources/note/YYYYMMDD/topic.md with the existing import action.
+No extra raw/summary fields, sidecar, duplicate file or mandatory section template
+is needed. Saving alone does not start indexing. Independent reader topics can
+use the selected Note Provider (default or business replacement); supporting
+explanations use the current page's evidence/read scope, retaining its primary.
+When specialized interpretation is needed, explicitly select a compatible
+extension layer. Do not enable another skill merely because a note exists.
+
+Knowledge integrates the useful information into explanations, rules or steps
+for the reader. Do not copy the note wholesale or turn proposals into facts.
+An exact short passage is appropriate when its wording matters. Cite the stored
+material actually read, without claiming access to an unavailable original.
+
+If the note misrepresents the supplied material, explicitly correct the source
+with its current base_digest, following task adjust first for pinned inputs.
+Do not overwrite original text merely to fit new prose. If the source is correct
+but the knowledge is misleading, revise only that page through Author/Review.
+A confirmed future decision may differ from current implementation; make the
+boundary clear. Knowledge approval does not change or remove the note.

package/providers/context/resources/procedures/package-output.md

@@ -6,11 +6,14 @@ mediaType: text/markdown
 
 # Package output
 
+Before editing, read `context.sdk.package-outputs`, especially its Agent configuration
+and delivery recipe. It contains the concrete SDK declarations and preview steps.
+
 Package selection decides how approved knowledge is presented to downstream
 agents or text consumers. Explain the available Context package kinds and their
 directory shape before asking the user to choose.
 
-After confirmation, declare the package in `src/index.ts` using the SDK schema
+Using the settled multi-select choice or current session authority, declare the packages in `src/index.ts` using the SDK schema
 resource. The current Route's `configuration.contract` lists the supported
 output choices, required fields, mechanical defaults, and follow-up status
 command; do not infer another factory or hidden default. Templates may customize presentation, but they must not overwrite
@@ -46,3 +49,19 @@ external links and accepts responsibility for publishing and access. Use a
 confirmed immutable HTTPS prefix where possible; do not infer or probe an
 unknown host convention. Explicit omission keeps unresolved links and must be
 described as such.
+
+For a new workspace without explicit output preferences, use KB + website. Enable
+`site: { title: <workspace title>, lang: <workspace language> }` on the same
+`kbPackage` in `src/index.ts`; selecting LLMS also adds `llmsPackage`. Omit `site`
+when the user deselects the website. Existing declarations are not automatically
+changed. A request to generate a documentation website follows this same route,
+including after initial delivery. Inspect existing declarations before editing;
+do not register the request itself as source material or re-index unchanged knowledge.
+
+Validate reading targets before build. Website navigation uses the approved reading
+structure; repair missing bindings through the current structure adjustment action.
+Build cost is rendering and local search generation, not another Indexer run.
+Report measured cost only; do not promise a fixed duration for all workspaces.
+Website failure preserves the previous package and requires repair or an explicit
+change of output choice. Publishing is a separate action handled by the user's
+chosen deployment tool; producing a website never authorizes deployment.

package/providers/context/resources/procedures/parallel-agent-batch.md

@@ -0,0 +1,140 @@
+---
+id: procedure.parallel-agent-batch
+kind: procedure
+mediaType: text/markdown
+---
+
+# Parallel Partition and Author tasks
+
+This procedure applies only to a current Partition or Author Action with
+`tasks[]`. The Host runs the workers; Context does not launch models. The current
+Route, required readings and output schema remain authoritative. Delegation does
+not grant source access, approve a Gate or change the accepted scope.
+
+## Choose execution once per batch
+
+Use available native Host delegation only when current user/Host permissions
+allow it, at least two independent tasks are ready, and workers can read the
+assigned material and return their result without writing files. Respect an
+explicit single-Agent preference and Host capacity or budget limits. Do not
+install another agent runner, start nested CLI sessions or request broader
+permissions just to parallelize. If these conditions are absent, continue the
+same batch sequentially without a new user question.
+
+Resolve any existing scope or human decision before dispatching dependent tasks.
+Permission to use multiple Agents does not waive that decision.
+
+Choose `min(4, ready task count, available worker slots)` concurrent workers,
+excluding the coordinator. Use parallel mode only when that value is at least
+two. Do not split one task or enlarge a CLI batch to fill slots. Schedule later
+tasks from the same batch as workers finish; never prepare the next batch while
+this one is active. Known dependencies between tasks require sequential handling
+by the coordinator. A worker result never becomes evidence for a peer.
+
+Tell the user briefly, in their language, how many planning or writing workers
+will run when first enabling delegation or changing its concurrency/mode. Reuse
+that announcement across unchanged batches. Report a fallback once when it happens. Worker completion is draft
+progress; only CLI receipts establish accepted production progress.
+
+## Single coordinator and read-only workers
+
+The coordinator reads the Route, output schema and shared instructions, resolves
+existing human decisions, and owns all Context commands, receipts and writes.
+Workers consume only their assigned task reading and its authorized shared/detail
+files and captured source access. Material requiring CLI preparation is requested
+from the coordinator. Never let a worker run `context status`, a materializer,
+preview, completion, capture, parser, review, close or build.
+
+Use a Host read-only worker/tool profile when available. Workers must not run
+shell commands, Git, scripts or other tools that can change files or external
+state, and must not spawn workers. If the Host cannot honor this boundary, use
+single-Agent execution. Workers return results through Host messages; they do
+not write even scratch files. If a task cannot fit a complete response within
+the Host's output budget, the coordinator handles it sequentially and writes
+the payload itself. Do not truncate a result or publish a stub to fit transport.
+
+The coordinator alone writes the final payload under the workspace's
+`.tmp/agent-payloads/`, using a new file for each submission attempt. Never edit
+runtime readings or ledgers. This prevents worker file collisions without
+depending on filenames, worktrees or the project write lock to isolate them.
+
+## Assign and collect
+
+Use `template.indexer-agent-worker` from the current Route. Bind each assignment
+in coordinator memory to the current Route revision, Action `input_digest`,
+task manifest, instruction/resource digests and a unique attempt identifier.
+Task keys repeat across batches, so `task_key` alone is not an assignment ID.
+Copy these values; never compute or repair authority values from prose.
+
+Send one task entry, its exact Route-provided reading location and applicable
+shared instructions, the relevant output schema, and settled reader/scope
+decisions. Give enough instruction content or exact resource locations for the
+worker to read independently. A parent's reading does not populate a worker's
+context or authorize an unread receipt. Do not broadcast the entire batch,
+conversation, live repository or sibling task readings.
+
+Keep a mapping from Host worker ID to assignment attempt. Before dispatch, choose
+a finite task deadline supported by the Host (default ten minutes; shorten to
+the remaining session budget). Wait using native completion notifications or
+bounded waits while continuing user progress updates. A deadline is a Host
+execution limit, not a statement that evidence is missing.
+
+Accept a reply only from the active attempt for that task and only after it is
+complete. The worker uses the template's Host reply envelope to echo assignment
+identifiers separately from its single `{task_key, result}` entry. Check the Host
+worker ID and that binding against the saved assignment;
+do not insert coordination metadata into the Context semantic Result. Retain
+successful drafts in coordinator memory until the batch is assembled.
+
+## Merge and submit
+
+Reconcile Partition proposals against the settled reader purpose and accepted
+subjects, especially overlapping identities, primary member ownership and
+unresolved cross-task boundaries. Do not silently rename a subject or discard a
+member to make proposals fit. Resolve disagreements from authorized material
+in the coordinator; use the current schema's unresolved outcome when necessary.
+
+For Author, review consistency with the accepted page plans, evidence boundaries
+and reader terminology. A task may contain several planned articles: assign the
+whole task, not independent writers for its sections or articles. CLI performs
+the existing schema, ownership, reference and coverage validation.
+
+Assemble one entry per current task in task-key order, keeping the normal
+single-Agent output shape. Use the current Author preview when needed, then
+submit the complete batch once through the saved revision-bound command. Do not
+submit as each worker finishes or turn Host errors into `unsupported`,
+`catalog-only` or empty semantic results. Resolve unfinished work locally first.
+
+Finish or revoke every active assignment before any command that may change the batch or its material.
+Do not poll status merely to check workers. The revision-bound CLI command is
+the final freshness check; if an external change is observed, invalidate the
+assignments and obtain the current Route before submitting.
+
+## Failures and sequential fallback
+
+| Event | Coordinator action |
+| --- | --- |
+| Delegation unavailable, denied, or capacity below two before dispatch | Execute the batch sequentially. Do not retry permission prompts or simulate workers. |
+| Spawn failure, rate limit, timeout, tool failure, context loss or truncated reply | Stop dispatching for this batch. Revoke the failed attempt, cancel/close it if supported, and finish that task and unassigned tasks sequentially. Let healthy read-only peers finish within their deadlines. |
+| Missing/foreign task key, wrong attempt/revision, malformed or incomplete result | Discard that reply; take over its task sequentially using the original authorized input. Do not repeatedly respawn or treat the draft as committed. |
+| Conflicting proposals | Reconcile affected tasks in the coordinator; preserve unaffected drafts. Unresolved scope decisions follow the existing human Gate. |
+| Worker attempts a write, unauthorized tool or source access | Revoke all workers and stop parallel dispatch. Inspect any reported effects before continuing. If workspace integrity or authority is uncertain, follow current recovery guidance or report the concrete blocker. |
+| Route, task set or material binding changes | Revoke old attempts; discard incompatible drafts and follow the fresh Route. Never relabel an old reply with new digests or task keys. |
+| CLI accepts only part of a submission | Read `outcomes` and the returned next Route/task-only retry. Preserve committed peers; repair only the returned unfinished tasks sequentially. |
+| Completion reply is lost or next preparation fails | Inspect current status or the supplied recovery command before retrying. Accepted tasks may already be saved; never blindly replay the payload. |
+| Project write lock is held | Wait for the active writer using existing recovery guidance. Never remove its lock or launch another writer. |
+
+Revocation means marking the attempt inactive before taking over. Ignore all late
+replies, even if cancellation is unsupported. Such workers remain read-only;
+do not reuse their slots until the Host confirms termination. Do not start a
+new parallel batch while revoked workers are still active. A revoked read-only
+worker does not block the coordinator's sequential takeover or completion;
+its obsolete reply can no longer be accepted. If its read-only boundary is in
+doubt, use the violation handling above instead. After any execution
+failure, keep the rest of this batch sequential and reassess capability only at
+the next fresh batch. A user request to stay single-Agent persists.
+
+Sequential fallback preserves evidence, scope, review and completion requirements.
+If the coordinator also cannot complete the task, retain drafts and report the
+actual missing material, permission or Host limit through the existing workflow.
+Do not clear runtime state, widen sources or lower coverage to force progress.

package/providers/context/resources/procedures/project-configuration.md

@@ -9,6 +9,12 @@ mediaType: text/markdown
 Use the current route facts and Context SDK documentation to make only the
 declaration requested by the route in `src/index.ts`.
 
+Complete the required readings and run their `acknowledge-current` / `after_read`
+command **before editing**. Use the resulting current configuration Route for the
+edit. Editing changes the revision: afterwards refresh status, never run an
+acknowledgement bound to the pre-edit revision. Reading acknowledgement confirms
+the inputs, not approval or completion of the configuration change.
+
 - Do not invent sources, modules, collections, or output types.
 - Ask for a user decision when the route is gated and no current-session
   authority is present.