@c4a/context-cli 0.7.8 → 0.7.10-alpha.1

package/providers/context/resources/procedures/close-and-build.md

@@ -6,6 +6,22 @@ mediaType: text/markdown
 
 # Close and build
 
+At completed-scope delivery, follow the version-recording Route. The coordinator
+writes the semantic changelog from formal diffs and the conversation, including
+the triggering source and an explicitly known user (Git name is the default).
+Record after Close and package/template approval, before the final build, so the
+selected outputs are built with the new version once. Build records hashes without
+increasing versions. Never count temporary progress or a build retry as a change.
+
+Before an authorized external publication, run `context version publish-check
+--format json`. If `needs_version` is true, inspect with `context version inspect
+--publish --format json`, record a patch changelog using a `dist` trigger, and
+rebuild. Do not increment again if the workspace version already changed.
+If `unchanged` is true, there is no new delivery. Only after a successful external
+publication, use `context version published --hash <checked-hash> --receipt
+<successful-publication-reference> --format json`. Failure does not advance that
+baseline. These commands do not upload, publish or grant publishing authority.
+
 Close deterministically reconciles approved Markdown and current relationship
 inputs into `knowledge/structure.yaml`. It compacts repeated machine fields out
 of each Markdown page and validates the hydrated result. When an approved page
@@ -39,3 +55,39 @@ review decision in this conversation, together with its reviewed scope. Omit
 the section when no report was user-reviewed. Do not reconstruct it by scanning
 `.tmp`, invent a shareable URL, or classify fully managed or force approval as
 user review.
+
+Report every selected output separately: KB root, website `dist/<base>-site/`,
+and LLMS file when selected. Distinguish generated, failed and not selected; do not
+claim the whole delivery complete if a selected channel is missing. For a website,
+include a local preview command (or a URL only after verifying the server), reading
+navigation coverage, and the directory a separate hosting tool would deploy.
+Preview example: `python3 -m http.server 8000 --bind 127.0.0.1 --directory dist/<base>-site/`.
+Provide this command without starting a server unless the user requests a running
+preview. Use the build receipt for output paths and validation results; extra
+HTTP probes, ad hoc manifest queries and another verify are diagnostic tools,
+not mandatory version-recording or successful-build steps. Follow the returned
+Route directly instead of polling status after every successful action.
+Explain that users may request website output later; it reuses existing approved
+articles rather than requiring a new workspace or full source indexing.
+
+## Website deployment handoff after every successful build
+
+After every successful website build, including intermediate delivery and an
+unchanged output reused by build, tell the user the website can be deployed with
+a deployment skill. Include the actual `dist/<base>-site/` directory and whether
+it contains only the currently delivered scope. This notice does not wait for the
+whole knowledge task to finish and does not block its next Route.
+
+Reuse existing publishing configuration and the user's chosen target. Otherwise,
+inspect the available deployment skills, recommend a compatible static-site skill,
+or let the user specify one. Do not invent installed skills or a deployed URL.
+If no compatible skill is available, report that and provide the site directory
+for the user's deployment tool. Do not install a deployment dependency by default.
+
+When publishing is already authorized for that target, follow the selected skill
+with the built site directory; otherwise offer deployment and wait for the user's
+publishing instruction. Preserve the configured base path; rebuild if the target
+requires a different base. Pass only the website output, not sources, private
+workspace state or the entire KB package. Report success only after checking the
+hosting result and published URL. A failed deployment leaves the local build valid;
+report the deployment failure and its next step separately.

package/providers/context/resources/procedures/homogeneous-source-review.md

@@ -0,0 +1,123 @@
+---
+id: procedure.homogeneous-source-review
+kind: procedure
+mediaType: text/markdown
+---
+
+# Review large homogeneous source groups before bulk work
+
+Apply during source exploration, the work-start report, Provider selection and
+before advancing into parser preparation, including an existing workspace's
+resume. Reuse confirmed decisions; this is the existing conversational scope
+review, not a new CLI approval flag or a semantic classifier in the CLI.
+
+## Find a real group, not just a large repository
+
+More than 100 files in a candidate group triggers a bounded homogeneity check,
+not automatic exclusion or a count-only stop. Use the supplied source inventory
+or authorized read-only file listing. Do not run symbol extraction to discover
+whether symbol extraction is needed. Record the source/repository and pinned
+revision, actual module/directory boundaries, counted paths, bytes when available,
+and representative file paths. Distinguish tracked source, captured copies,
+generated files and externally resolved dependencies; a path containing another
+repository name does not prove a new external checkout.
+
+Read a small diverse sample across relevant subdirectories, sizes and naming
+families. Establish a shared structure, generator, schema, repeated role or
+mechanical pattern from content. Examples include IDL definitions, schema-based
+configuration, generated clients/models, repeated migrations, and ordinary
+handwritten adapters or handlers with the same structural pattern. A common
+extension, a directory label, age, or boilerplate header alone is not sufficient.
+Do not call every TypeScript file homogeneous or treat all configuration as
+low-value. If samples differ substantially, split by evidenced characteristics
+or proceed normally; report uncertainty instead of claiming full inspection.
+
+For a confirmed group above 100 files with an unsettled treatment, pause before
+dependent bulk reading/parsing. Combine all currently known groups into one scope
+proposal. Do not ask per file or create 100-file approval batches. Groups below
+this threshold can still warrant discussion when their size or cost is material;
+file count is not a memory safety limit.
+
+## Present one concrete choice per group
+
+Show a compact directory tree and table with:
+
+- Repository/source, revision, exact directory or file-set boundary and whether
+  it is the whole source or a subset; physical file count versus distinct items.
+- Observed shared characteristics and two or three linked sample files with
+  short descriptions of their content. State sampling coverage honestly.
+- Connection to this task's questions, known callers/consumers and unresolved
+  dependencies; distinguish a recommendation from a confirmed exclusion.
+- Likely output, reading/parsing cost and the evidence for any estimate.
+
+Offer these treatments together, recommending one based on the user's task:
+
+| Choice | Consequence |
+| --- | --- |
+| Full indexing | Normal extraction, planning and writing over the selected group. It may yield multiple articles. Explain the extra work without asserting it is always low-value. |
+| Overview and lookup entry | List the boundary, inspect representative content and entrypoints, and plan one overview with directory/file lookup routes and concrete search instructions. Defer detailed extraction of the rest. Never first parse every file and then summarize it. |
+| Omit the source | Remove the entire source from this task's required production scope through the supported requirement/configuration flow. Do not delete captured files, caches or accepted knowledge. |
+| Exclude this subset | Keep the repository but exclude the explicitly selected directories/files from production scope. Clarify whether any are still required as supporting dependencies. |
+
+Only show subset exclusion as applicable when it is a subset; do not make the
+user distinguish two identical choices for a whole-source group. Users can give
+one policy for several groups or different choices per group. Record the exact
+scope of a shared answer. Generic managed/no-review authorization, source-read
+permission and permission to skip report feedback do not select a treatment.
+Reuse an explicit applicable treatment or explicit delegation of this scope
+choice. Otherwise ask and wait; elapsed time is not approval. Independent work
+outside the affected scope can continue if the current workflow supports it.
+
+Do not invent "one minute per group", token savings or a cost-benefit score.
+When comparable measurements exist, state the measured phase, input size,
+cold/cache conditions and uncertainty; separate parsing from Agent reading,
+writing and review. Without them state that duration is not reliably estimated.
+
+## Carry the answer into real execution
+
+Update the existing work-start report with the group boundaries, sample evidence,
+chosen treatment, user authorization and next action. Reuse that report and the
+conversation on retry; it is not itself a runtime execution receipt. Persist
+scope changes only through the existing requirement/configuration Actions and
+schemas. Exact exclusions use repository-relative paths, not invented wildcard
+fields. Retain unrelated requirements and accepted work. A source required by
+another requirement may remain active; disclose that instead of promising it
+will no longer be parsed.
+
+For full indexing, continue the current Route. For overview, resolve the actual
+production boundary and suitable existing Provider before proceeding: the
+selected entrypoints and samples support the overview; the remaining group is
+for lookup, not an exhaustive production target. Use directory-scoped routes
+when a per-file list would dominate the article. Include purpose, observed
+patterns, representative examples, source version, lookup/search procedure,
+limits of what was read and the next evidence request. Keep symbol/API facts
+unread as unknown. Do not forge a complete deep inventory, hand-write approved
+knowledge, or silently relabel the full scope as a summary profile.
+
+Check the resulting configuration before a command that prepares parser facts.
+In particular, contract-led profiles can still parse their entire registered
+boundary before article planning. Merely asking for one article does not reduce
+that work. If the current configuration route cannot express the selected
+narrow boundary or overview treatment, describe that concrete limitation and
+keep the affected bulk action paused; do not revert to full indexing or edit
+runtime receipts to make the choice appear applied.
+
+On continuation, unchanged groups with explicit decisions do not prompt again.
+New large groups, expansion beyond the agreed directory/file set, or changed
+characteristics/cost that invalidate the decision warrant a focused amendment.
+A content hash change within the agreed scope is not by itself a new question.
+If first discovered while a command is running, report the observation and
+safely interrupt the owned process when possible, preserve state and consult
+the latest Route before continuing. Do not launch a competing run or delete
+state. An uninterruptible stage must be reported, not called paused already.
+
+## Report progress with the correct denominator
+
+Keep source capture, module exploration, parser capability entries, file batches
+and delivered articles separate. A seven-file JSON entry does not mean that an
+IDL repository now contains seven relevant files. Report both the source and
+capability for each count; merging four results is not four completed modules.
+Only use completed/total modules when module boundaries and their completion
+have been observed. Before that, say module boundaries are being identified.
+Never infer percentage or scope reduction from time or RSS. RSS is not Node heap
+usage and being below a previous failure measurement does not establish safety.

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

@@ -11,7 +11,7 @@ Open one report for the complete current candidate set and apply only a payload
 that matches its collection scope and candidate-set digest.
 
 Before Review, Context checks both sides of approved page identity: whether a
-candidate path is already owned by another `view_ref` / `node_ref`, and whether
+candidate path is already owned by another `article_id`, and whether
 the candidate `view_ref` is already approved at another path. Either conflict
 blocks Review. Follow the returned identity-coordination route: the default
 mechanical repair preserves the approved identity and approved path, then

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

@@ -22,18 +22,130 @@ 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.
 
-## Edit one section or review part of a batch
+## 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.
+
+## Agent-planned writing order
+
+Within the tasks available in the current Route, the Agent may choose a writing
+order from the reader's needs and relationships between topics. There is no
+fixed code-first or document-first rule. Prefer foundational concepts and shared
+terminology before walkthroughs or summaries that benefit from them, when this
+reduces rework. Independent topics can proceed without waiting; adjust the order
+as writing progresses instead of maintaining a separate scheduling artifact.
+
+This is an Agent working preference, not a new dependency or completion gate.
+Do not add dependency fields, fetch extra material, or delay useful work merely
+to establish an order. Keep current task boundaries, source permissions and
+submission rules; do not pull future batches forward or change the CLI Route.
+
+## 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:
 
-For a reading-directory-only change, use the existing `context task adjust
---input <file|-> --format json` action with `reading_structure`. Supply its
+```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. Use `expected_revision: null` only when no reading structure exists.
+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
@@ -41,6 +153,13 @@ ordered `content` list of `{ "markdown": "new text" }` and/or
 selected section's source references remain intact. Use full Markdown when
 changing structure, adding a page or when a section has no unambiguous ID.
 
+To change a fragment's citations, include `references` alongside its `section_id`:
+each entry supplies `source_ref` and `locator` (`path`, `start_line`, `end_line`).
+Context computes the region fingerprint. This uses the same revision submission,
+with at most three source positions per fragment. Full Markdown may include a
+`sections` list of reference edits; local section edits may change content,
+references, or both. Omission preserves citations; an empty list removes them.
+
 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
@@ -314,17 +433,17 @@ 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.
+### Revising material reused from another article
+
+When a supporting article changes, revise the affected explanation using
+`context revise`. Read the relevant approved text and, where needed, its original
+sources. Keep direct source regions on the affected output fragments; do not
+recreate an article dependency graph or copy facts and evidence IDs.
+
+Revision section edits may supply `references` as `source_ref` plus a
+`locator` containing `path`, `start_line`, and `end_line`. Context computes the
+regional digest. Omitted references preserve the current fragment's citations;
+an explicit empty list removes them, and deleting a fragment removes its
+citations. Each fragment may cite at most three source positions. Register and
+authorize new material before citing it, then follow normal Review, close and
+build. Article links alone do not authorize reading new sources or prove a claim.

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,39 @@
+---
+id: procedure.parallel-agent-batch
+kind: procedure
+mediaType: text/markdown
+---
+
+# Coordinate issued batch directories
+
+CLI owns stage boundaries and determines which batches are eligible. The Agent
+chooses how to finish the issued work. Enable `--multi-agent` only when this host
+can coordinate child Agents and current permissions allow them. Otherwise use
+the default single batch; do not simulate workers or seek extra permissions just
+to parallelize. A capability declaration does not waive any user decision.
+
+Assign disjoint output directories from the issued batches. Give each worker
+its task goals, relevant shared guidance, authorized source entrypoints and
+designated draft paths. Workers can read source text and write their assigned
+drafts. They do not change CLI-owned materials, formal articles, shared runtime
+state or a peer's drafts. One coordinator submits to Context and performs all
+shared-state CLI writes; workers return completed paths and unresolved issues.
+
+The host's capacity and the tasks determine scheduling; there is no fixed worker
+count, mandatory attempt ledger or new handoff schema. Use host completion
+notifications and ordinary bounded waits. Do not poll full Context status to
+check worker progress, or confuse a finished draft with a received article.
+
+The coordinator checks the outputs against their tasks, resolves cross-article
+terminology and source ambiguity where needed, and submits any completed subset
+through the stage file contract. Keep task input handles as supplied by CLI.
+Do not require every worker to finish before submitting independent work.
+
+If a worker fails or loses context, retain completed files and take over or
+redispatch only its unfinished work. Stop the old worker before another writer
+uses the same output paths, and ignore late results from revoked work. Ordinary
+host errors are not source exclusions or evidence that a task is complete.
+
+When capability is unavailable, omit `--multi-agent` on the next call. Already
+issued tasks and drafts stay valid. Source changes or task replacement use the
+CLI's existing task-local refresh and repair protocol, not skill-version checks.

package/providers/context/resources/procedures/production-requirements.md

@@ -0,0 +1,61 @@
+---
+id: procedure.production-requirements
+kind: procedure
+mediaType: text/markdown
+---
+
+# Long-term production requirements
+
+Use the reader purpose and source boundaries already confirmed by the user.
+Ask for missing decisions before writing; registering a source does not authorize
+unrelated modules. This is not the work-start report: the report follows the
+lightweight investigation and must still wait for user feedback.
+
+Write `src/indexers.yaml` with this minimal shape, replacing the example values
+with the user's actual purpose and registered source reference:
+
+```yaml
+requirements:
+  - id: service-readers
+    purpose: Explain the service responsibilities and supported usage
+    target_scope:
+      targets:
+        - source_ref: repo:service
+```
+
+Optional long-term decisions are `reader_goals` and `questions` (text lists),
+`coverage_domains` (domain to `required`, `optional` or `out-of-scope`), and
+`evidence_source_scope` with the same `targets` shape for authorized supporting
+sources. Existing `module_refs` are reading focus, not a module-to-path permission
+map. Use an ordinary task brief for relevant directories; no additional module
+mapping or scope receipt is required.
+
+An explicit exclusion belongs inside its requirement:
+
+```yaml
+exclusions:
+  - scope:
+      targets:
+        - source_ref: repo:service
+    paths: [generated]
+    reason: Generated outputs are outside the requested reader purpose
+```
+
+`paths` contains exact source-relative files or directories, not glob patterns;
+omit it only for a confirmed exclusion of the whole selected source scope.
+Do not automatically exclude something merely because it is large or costly.
+
+Do not add Provider selections, versions, hashes, run identifiers, candidate
+receipts or task assignments. Those are not long-term requirements. Skills and
+writing batches are declared in the temporary investigation plan.
+
+After editing, run `context status --format json` and consume its current Route.
+
+When article targets and source grouping are already clear, put the existing
+plan fields (`capabilities`, `articles`, optional `indexer_usage`) in a file under
+`.tmp/agent-work/`, omitting only `stage`, which does not exist yet. Each article
+contains `path`, `question`, `sources` and `batch`, with optional `brief` and
+`after`. Add `--input <that-file>` to the returned `action prepare-current`
+command to prepare those tasks without a separate investigation-plan submission.
+This does not approve the report or permit writing before user feedback.
+When targets are unclear, use normal preparation and investigate the skeletons.

package/providers/context/resources/procedures/production-stage-files.md

@@ -0,0 +1,57 @@
+---
+id: procedure.production-stage-files
+kind: procedure
+mediaType: text/markdown
+---
+
+# Production stage files
+
+The stage entry links CLI-owned requirements, planned skill guidance and task
+directories. Read relevant source text before writing; a skeleton is navigation,
+not semantic evidence. Skill names guide work, not article ownership or versions.
+
+Choose relevant code directories while planning or writing. A task brief may
+name useful reading scope; module labels do not imply directory permissions.
+No module mapping file, version receipt or article-level scope fields are needed.
+Read related code as needed within the user's authorized sources.
+
+Write results under the returned Agent directory. All submission paths are
+relative to that stage directory, even when the manifest is in `submissions/`.
+Copy the CLI's submission template, keep completed tasks only, and keep each
+task's prefilled `input`. Submit the manifest using the returned command.
+Do not edit submitted files until the command returns.
+
+A complete article uses `content` (Markdown) and `references` (YAML/JSON).
+Markdown has reader-facing title and description frontmatter, followed by the
+complete article with stable `context:section` markers. References contain
+`sections`, each with its matching `id` and `references` list. A reference is
+`source_ref` plus `locator: {path, start_line, end_line}` from actual authorized
+text. CLI computes source digests. A fragment may cite at most three distinct
+source positions; an article may have multiple fragments.
+
+A revision uses `edits` instead of `content`/`references`. The file contains an
+`edits` list. Each item maps `replace: [old-fragment-ids]` to `with: [...]`, whose
+entries contain `id` and the changed `markdown` and/or `references`.
+Omitted fields retain the previous value only for the same fragment identity.
+New identities require both fields. Empty `with` deletes the named fragments.
+A split or merge explicitly names old and new identities; merging cannot
+silently delete intervening article text. Insert with empty `replace` and
+`after: <existing-id>`, or `after: null` before the first fragment.
+Fragment Markdown excludes its outer markers, which CLI generates.
+
+The same edits format can repair a failed complete draft retained temporarily
+by CLI. If that draft is missing or structurally unusable, resubmit a corrected
+complete article. Failed tasks report a file/fragment when available; accepted
+tasks remain saved even if preparation of the next directory fails.
+
+The default is one batch. Supply `--multi-agent` only when this caller supports
+coordinating multiple batch directories. Omitting it safely downgrades scheduling
+without invalidating already-issued tasks or overwriting worker drafts.
+
+If the user explicitly asks to receive completed articles before the remaining
+work finishes, run `context run --deliver --format json`. This pauses writing,
+not approval: follow the returned Review, close and build routes. A successful
+build resumes the same stage; a failed build retains the pause and all tasks.
+To cancel that pause explicitly, use `context run --resume-writing --format json`.
+It preserves approved articles, candidates and existing task input handles.
+Partial delivery must include the approved articles needed by its local links.

package/providers/context/resources/procedures/source-boundary.md

@@ -10,6 +10,15 @@ A source boundary is a user decision about which repositories, modules, or
 documents may become approved knowledge. It affects extraction scope,
 provenance, output paths, and freshness checks.
 
+For the first production task, confirm the reader purpose and authorized material
+scope, reusing choices already explicit in the conversation. A supplied checklist
+is task guidance unless the user also selects it as source material. Register and
+capture the confirmed sources so lightweight investigation can produce code
+skeletons and document overviews. The formal work-start report belongs after that
+investigation and planning, before bulk writing; its presence or digest is never
+source-registration evidence or user approval. Do not broaden source authorization
+while gathering the plan.
+
 Do not infer this boundary by using the current directory, monorepo layout,
 package names, or Git remotes to select additional sources. Once the user has named a concrete local module
 or path, resolving its unique local directory and reading that checkout's Git