@c4a/context-cli 0.7.5 → 0.7.9

package/providers/context/resources/manuals/reference/code-extractors.md

@@ -0,0 +1,57 @@
+---
+id: context.sdk.code-extractors
+kind: procedure
+mediaType: text/markdown
+---
+
+# Code Parser Selection
+
+Code parsing is an Indexer Provider implementation detail. A knowledge
+workspace selects the Provider and profile in `src/indexers.yaml`; it does not
+declare a separate extraction phase in `src/index.ts`.
+
+## Selection order
+
+1. Identify the target boundary and the knowledge questions.
+2. Let the selected Provider inspect language, manifests, entries, routes, and
+   contracts.
+3. Use the smallest parser set that covers those questions.
+4. Keep deterministic parser output as Provider facts; let the Provider author
+   reader-oriented knowledge pages from those facts and readable sources.
+
+## Community parser packages
+
+| Package | Useful structural facts |
+|---|---|
+| `@c4a/extract-ts` | TypeScript/JavaScript symbols, exports, imports, calls, and React Router routes |
+| `@c4a/extract-go` | Go declarations, imports, calls, and common HTTP routes |
+| `@c4a/extract-rush` | Rush projects, tags, entries, dependencies, and owner boundaries |
+| `@c4a/extract-thrift` | Thrift services, methods and declared data types |
+| `@c4a/extract-proto` | Protobuf messages, fields and service definitions |
+| `@c4a/extract-mdx` | Markdown/MDX document structure and source spans |
+| `@c4a/extract-contract` | Supported structured API contract declarations |
+| `@c4a/extract-style` | Stylesheet declarations, selectors and related structure |
+| `@c4a/extract-sql` | Supported SQL schema declarations |
+| `@c4a/extract` | Shared extraction result and adapter contracts |
+
+These packages do not create Candidate rows, write `knowledge/`, or control
+Review. The CLI owns those lifecycle responsibilities; Providers interpret the
+supplied facts and sources and return structured semantic results. Package
+presence alone does not prove a parser is selected or supports every dialect.
+Use the selected profile's actual capabilities and parser diagnostics.
+
+## Unsupported technologies
+
+When a required boundary is unsupported, distinguish a parser limitation from
+missing writing guidance. Config can select supported behavior; instructions or
+templates cannot create missing structural facts. Follow the current Route's
+capability-gap report and smallest supported customization step. A program
+extension requires its existing execution authorization. Prefer a reusable
+parser when the same technology is useful across projects; do not create a
+parallel project-local knowledge pipeline.
+
+Mechanical inventory closure requires an explicit disposition for each supplied
+item. It does not prove that the pages answer the reader's questions. Review
+checks usefulness and fidelity separately. Internal or out-of-scope items can
+have justified exclusions without generating pages; symbol count is not a
+knowledge-quality measure.

package/providers/context/resources/manuals/reference/package-templates.md

@@ -188,7 +188,7 @@ Built-in variables:
 | `{{displayName}}` | Display name. Defaults to a title-cased `packageName`; override with `template.vars.displayName`. |
 | `{{knowledgeCount}}` | Number of selected approved Markdown files. |
 | `{{knowledgeTimestamp}}` | Latest `timestamp` from selected approved Markdown, or `1970-01-01T00:00:00.000Z` when empty. |
-| `{{knowledge}}` | Concatenated selected approved Markdown bundle. |
+| `{{knowledge}}` | Concatenated consumer projection of selected approved pages, with path headings and without lifecycle metadata. |
 | `{{approvedKnowledge}}` | Alias for `{{knowledge}}`. |
 | `{{knowledgeItems}}` | Array of selected approved knowledge page metadata for loops. |
 | `{{knowledgeGroups}}` | Selected approved knowledge pages grouped by OKF root and first directory segment; each item also exposes `internal_collection`. |
@@ -328,7 +328,7 @@ Approved Markdown under `knowledge/` and its deterministic
   revision, or build. Do not copy a compact page as a new page without using a
   Context authoring command;
 - do not nest Context production metadata under `context`; fields such as
-  `context.sources` and `context.code_symbols` are not part of the 0.6 profile;
+  `context.sources` and `context.code_symbols` are not accepted production fields;
 - section provenance lives in `<!-- context:section ... source_ref="..." -->`
   comments. When a Section needs more than one citation, the CLI preserves the
   complete set in its adjacent `context:source_refs` block;
@@ -358,8 +358,9 @@ treat the complete `source_ref` as opaque. Production pages do not expose
 Candidate fingerprints, Indexer digests, or `code_origin`.
 
 `#span:` refs retain source snapshot line ranges for human review, diffing, and
-stable re-pinning. They resolve against committed file/lark document snapshots,
-not the code symbol index.
+stable re-pinning. They resolve against the stored file/Lark snapshot or the saved
+Note/Sessions Markdown, not the code symbol index. A session's optional commit/MR
+association stays in its source file; knowledge does not duplicate those fields.
 
 The kb package root may contain agent files such as `AGENTS.md` and `skills/`.
 The OKF-compatible surface is the selected `wikis/`, `guides/`, `rules/`, and
@@ -379,11 +380,11 @@ The OKF-compatible surface is the selected `wikis/`, `guides/`, `rules/`, and
 6. Writes output under `dist/<package-name>/`.
 
 `context-build-inventory.json` records what was selected and why. Each selected
-file includes `selected_by` entries such as `{ "kind": "collection" }` and a
-`production_metadata` object for selected page-level production fields. Child
-and relationship records use the inventory's canonical structure projection,
-`{ "kind": "okf_root" }`, `{ "kind": "include" }`, or
-`{ "kind": "default" }`. The inventory also exposes package-visible typed
+file includes `selected_by` entries such as `{ "kind": "collection" }`,
+`{ "kind": "okf_root" }`, `{ "kind": "include" }`, or `{ "kind": "default" }`,
+and a `production_metadata` object for selected page-level production fields.
+Child and relationship records use the inventory's canonical structure
+projection. The inventory exposes package-visible typed
 edges under `structure.edge_records`; these records are filtered to edges whose
 endpoints are present in the selected package. Use those edge records for
 relationship citations inside the package instead of assuming the workspace

package/providers/context/resources/manuals/reference/project-api.md

@@ -32,14 +32,30 @@ state.
 
 ```ts
 const repo = source("20260901", "component-lib");
-const docs = source("product-docs", { type: "file" });
-const handbook = source("handbook", { type: "lark" });
-const everyRepo = allSources("repo");
+const docs = source("20260901/product-docs", { type: "file" });
+const handbook = source("20260901/handbook", { type: "lark" });
+const note = source("20260908/decision-context.md", { type: "note" });
+const session = source("20260908/design-discussion.md", { type: "sessions" });
+const everyRepo = allSources("repo"); // array: use ...everyRepo inside sources
+const everySession = allSources("sessions");
 ```
 
-References resolve against `sources/repo/index.yaml`,
-`sources/file/index.yaml`, and `sources/lark/index.yaml`. Register or refresh
-sources through `context source ...`; do not invent snapshot directories.
+Repo, file and Lark references resolve against their respective
+`sources/<type>/index.yaml`. Their names include the registration date and module.
+Register or refresh them through `context source ...`.
+
+Note and Sessions references resolve directly to saved Markdown under
+`sources/note/YYYYMMDD/topic.md` and `sources/sessions/YYYYMMDD/topic.md`.
+Use `context source import` to save them; they have no separate registry or
+capture phase. Explicitly include the desired typed references in `sources`,
+for example `sources: [note, session]`, or use `sources: [...everySession]`
+when all saved sessions are intended. Merely saving a source does not select it.
+
+A project's source list enables acquisition and initial selection; requirements
+and the selected Indexer's target/read scopes determine what it owns and may read.
+Supporting text does not require a separate page or primary Indexer. See
+[note preparation](../guides/note.md), [sessions preparation](../guides/sessions.md)
+and [knowledge updates](../guides/knowledge-updates.md).
 
 ## Capture phases
 
@@ -50,8 +66,55 @@ captureLark({ source: handbook });
 ```
 
 Capture only creates a deterministic readable snapshot. Classification,
-partitioning, authoring, Candidate creation, and Review belong to the selected
-Markdown Indexer.
+partitioning and authoring use the selected Provider's guidance. The CLI owns
+worksets, Candidate creation, Review application and delivery. Code, Markdown,
+Note and Sessions Providers can use authorized supporting documents without
+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:
+
+```ts
+import { fileURLToPath } from "node:url";
+import {
+  allSources, captureLark, defineProject, loadSourcesRegistry, source,
+} from "@c4a/context";
+
+const workspaceRoot = fileURLToPath(new URL("../", import.meta.url));
+const registry = await loadSourcesRegistry({ rootDir: workspaceRoot });
+const documents = registry.larks.map(entry =>
+  source(entry.name, { type: "lark" }),
+);
+
+export default defineProject({
+  sources: [...allSources("repo"), ...documents],
+  phases: documents.map(document => captureLark({ source: document })),
+  packages: [],
+});
+```
+
+Merge this pattern into existing declarations; preserve unrelated phases and
+package outputs. Adjust the root calculation if the entry lives elsewhere.
+Registry loading only reads local registrations; it does not fetch documents.
+
+- `sources/lark/index.yaml` owns document identities, URLs and titles. The project
+  selects those identities and declares capture settings. This example includes
+  future registrations too; use it only when the entire registered set is intended.
+- For a subset, filter registry entries by the intended namespace or names before
+  mapping. Apply exceptional resource settings within the same map instead of
+  declaring a second phase for the same document.
+- File documents use `registry.files`, `source(entry.name, { type: "file" })`
+  and `captureFile`. Group by actual processor needs; do not apply `mdxJsonDocs()`
+  indiscriminately to all file sources.
+- `allSources("lark")` selects a collection; its array contains a collection
+  reference, not individual documents. It neither expands capture phases nor
+  supports mapping its entries into `captureLark`.
+- 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.
 
 ## `customPhase`
 
@@ -71,6 +134,7 @@ kbPackage({
   name: "component-kb",
   template: "src/package-templates/kb",
   select: { collections: ["codeindex", "architecture"] },
+  site: { title: "Component knowledge", lang: "en-US", base: "/" },
 });
 
 llmsPackage({
@@ -83,10 +147,19 @@ llmsPackage({
 Package selection reads approved `knowledge/` only. `dist/` is generated and
 may be rebuilt; it is not an authoring source.
 
+`kbPackage.site` optionally adds a VitePress website at `dist/<base>-site/` in
+the same build, beside the KB directory. `<base>` removes one trailing `-kb`
+from the package name, if present. Omit it for KB-only output. It accepts `title`, `description`,
+`lang` and a deployment `base` path. Knowledge map is projected from
+`src/knowledge-map.yaml` independently of KB directories; see
+[Package Outputs](../guides/package-outputs.md#optional-static-documentation-website).
+
 ## Indexer registry
 
-The Agent and CLI maintain `src/indexers.yaml` through typed proposals and
-Review gates. Each selected Indexer binds requirements and scopes to one
+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.
@@ -96,6 +169,20 @@ current workflow Route when it is needed.
 
 ## Persistent versus runtime state
 
-Commit source registries, `src/index.ts`, `src/indexers.yaml`, package templates,
-and approved knowledge. Do not commit `.tmp/context-runtime/`; it contains
-recoverable execution state and is cleaned after a successful close.
+Source registries and snapshots, saved notes/summaries, project declarations,
+package templates and approved knowledge are durable inputs. Version them only
+when Git operations are authorized. Keep `.tmp/context-runtime/` out of Git;
+it contains unfinished execution state, not the sole source of recovery truth.
+
+`knowledge/structure.yaml` keeps shared page/source metadata and compact
+`processed_scopes` for completed requirement/source/module ranges. A partial
+update or failed build does not advance the whole range's processed version.
+Session commit/MR associations stay in the saved source frontmatter, not copied
+into every knowledge page. Use the CLI to adjust or roll back current work;
+do not edit these baselines or remove runtime files to simulate completion.
+
+## Source visual conversion preference
+
+Workspace `package.json` accepts `context.convertVisuals` (boolean, default `true`). Initialization writes it explicitly; older workspaces without the field also default to enabled. This lets a capable Author Agent attempt faithful structural diagram/table conversion. Explicit session instructions override the saved preference. It does not disable native table capture or existing Mermaid when false.
+
+Diagram style follows the workspace’s editable `AGENTS.md`; newly initialized workspaces default to minimal theme-aware diagrams without decorative colors. If the Agent cannot read the image or cannot preserve its meaning, it retains the original through the existing asset workflow. Source-based reuse avoids rereading unchanged visuals; file integrity and package hashes continue to reflect actual output changes.

package/providers/context/resources/manuals/reference/template-variables.md

@@ -25,7 +25,7 @@ Approved pages: {{knowledgeCount}}
 Values support dotted paths:
 
 ```md
-{{context.package}}
+{{buildInventory.package.name}}
 ```
 
 ### Loop
@@ -108,7 +108,7 @@ Read node_modules/@c4a/context/docs/reference/template-variables.md.
 | `skillPath` | string | Final package-relative `SKILL.md` path for the Skill currently being rendered. Empty outside a Skill template. |
 | `knowledgeCount` | number | Selected approved Markdown file count. |
 | `knowledgeTimestamp` | string | Latest selected approved Markdown `timestamp`, or epoch when empty. |
-| `knowledge` | string | Concatenated selected approved Markdown bundle. Use carefully; it can be large. |
+| `knowledge` | string | Concatenated consumer projection of selected approved pages, with path headings. It omits lifecycle metadata and can be large. |
 | `approvedKnowledge` | string | Alias for `knowledge`. |
 | `knowledgeItems` | array | One record per selected approved Markdown page. |
 | `knowledgeGroups` | array | Selected pages grouped by OKF root and the first directory segment under that root; each item also exposes `internal_collection`. |
@@ -137,7 +137,7 @@ Each item contains:
 
 | Field | Meaning |
 |---|---|
-| `path` | Package-relative OKF path, for example `wikis/component-lib/symbol/button.md`. |
+| `path` | Package-relative OKF path, for example `guides/architecture/entity/button.md`. |
 | `sourcePath` | Approved knowledge path before OKF output mapping, for example `architecture/entity/button.md`. |
 | `approved_path` | Alias for `sourcePath`. |
 | `dist_path` | Alias for `path`. |
@@ -148,11 +148,11 @@ Each item contains:
 | `okf_root_path` | Final flat package-relative OKF root. |
 | `node_ref` | Stable NodeRef from approved frontmatter, for example `entity/button`. |
 | `view_ref` | Stable ViewRef from approved frontmatter, for example `architecture:entity/button`. |
-| `pathWithinCollection` | Path below the OKF root, for example `component-lib/symbol/button.md`. |
+| `pathWithinCollection` | Path below the OKF root, for example `architecture/entity/button.md`. |
 | `href` | Link relative to the template file currently being rendered. Use this in custom templates. |
 | `hrefFromTemplate` | Alias for `href`. |
-| `hrefFromPackageRoot` | Link from a package-root file such as `AGENTS.md`, for example `./wikis/component-lib/symbol/button.md`. |
-| `hrefFromCollectionIndex` | Link from the current OKF root index, for example `./component-lib/symbol/button.md` for a `wikis` item. |
+| `hrefFromPackageRoot` | Link from a package-root file such as `AGENTS.md`, for example `./guides/architecture/entity/button.md`. |
+| `hrefFromCollectionIndex` | Link from the current OKF root index, for example `./architecture/entity/button.md` for a `guides` item. |
 | `title` | Page title from frontmatter, or a title derived from the file name. |
 | `type` | OKF `type` from frontmatter. |
 | `description` | OKF `description` from frontmatter, when present. |
@@ -188,7 +188,7 @@ Each group contains:
 | `count` | Number of selected pages in this group. |
 | `hasIndex` | Whether the active package navigation policy generates `indexPath`. |
 | `has_index` | Alias for `hasIndex`. |
-| `indexPath` | OKF-root-aware index path, for example `wikis/component-lib/index.md`, `guides/component-lib/index.md`, or `rules/index.md` for a root group. |
+| `indexPath` | OKF-root-aware index path, for example `wikis/codeindex/index.md`, `guides/architecture/index.md`, or `rules/index.md` for a root group. |
 | `indexHrefFromTemplate` | Link from the template file currently being rendered to `indexPath`. Check `hasIndex` before rendering it. |
 | `indexHrefFromCollectionIndex` | Link from the OKF root index to `indexPath`. |
 | `items` | `knowledgeItems` in the group. |

package/providers/context/resources/procedures/approved-revision.md

@@ -0,0 +1,159 @@
+---
+id: procedure.approved-revision
+kind: procedure
+mediaType: text/markdown
+---
+
+# Revise an approved page
+
+The current action contains the approved page and the user's instruction. Read
+the entire page first. Revise only what the instruction and available sources
+support; retain still-correct explanations and confirmed user contributions.
+
+For an expression-only change, the approved text is enough. Do not capture,
+parse, partition, or reconfigure its source. For changed facts, read the relevant
+registered material with the available host tools. Missing evidence is a reason
+to ask about the affected claim, not to reconstruct the whole knowledge base.
+Record new factual contributions as managed sources before expanding source
+ownership; an editing instruction alone is not a permanent factual source.
+
+Return the full revised Markdown in the supplied output schema, preserving the
+page's identity, source list, and source-bound section markup. Do not silently
+turn paraphrased text into a verbatim quotation. Do not directly write knowledge
+files. Context prepares a Candidate and routes it through the existing Review,
+apply, close, and build steps. Managed mode delegates Review, not source truth.
+
+If Context reports that the approved page changed, read that version and restart
+the revision. Never overwrite a concurrent edit with the old page snapshot.
+
+When `target.base_digest` is null, this is a new page in the confirmed update scope.
+The supplied Markdown contains only its stable identity and initial metadata.
+Read the specified source material and write the complete page with source-bound
+sections, using the existing purpose and page forms. Do not treat the initial
+heading as an already written page.
+
+Use `target.source_refs` as the final page source list. It can include explicitly
+selected supporting material absent from the old Markdown. Read that material
+before using it, add only its relevant explanation, and cite it in the affected
+sections. A session rationale is not proof of runtime behavior.
+
+When `target.previous_path` is present, the user explicitly selected a page move.
+Keep its stable Node/View identity. The supplied Markdown already rebases its
+relative links for `target.path`; do not put them back at the old location.
+Explain the move in the review summary. Approval moves the page and updates
+incoming Markdown navigation together; do not create a second copy or manually
+delete the old file. A changed destination or original page requires a fresh
+revision, not an overwrite.
+
+For selected `note` inputs, read [note guidance](note.md). For `sessions`,
+read [sessions guidance](sessions.md). Read only the applicable source guide.
+
+
+Read `writing_context` for the selected Provider, reader profile, current sections
+and actual template resources. These apply to direct page corrections too.
+Preserve the current page form; choose a different form only for an explicit
+change of purpose. Do not replace API tables with generic explanatory prose.
+The current sections are approved content, not freshly extracted API facts.
+For source updates or an explicit regeneration request, `program_blocks` contains API tables computed from current
+scoped Parser facts with the ordinary deterministic renderer. Select only the
+relevant blocks and place their exact `token` inside the corresponding sourced
+section. The CLI expands it at submission; do not retype its rows. Do not use an
+unrelated declaration merely because it shares a module. If a needed block is
+absent, report the missing material rather than present an old table as fresh.
+
+Compare the relevant generated rows with the requested correction before
+submitting. If the source is available but its type or expression cannot be
+resolved, state that specific limit instead of requesting the same files again
+or guessing a value. If a supplied block contradicts a confirmed fact, report the
+field and source location; do not rewrite the token's table by hand. The final
+Candidate still needs Review: a token or accepted submission does not establish
+that the requested correction reached the page.
+
+Context collects complete pages into a delivery batch. An Author completion can
+therefore lead to another Author before Review. Follow that Route; do not close
+or build after each page. Review, close and build operate on the assembled batch.
+A new topic reaches this action only after its affected structure is approved.
+
+After a Review rejection, the current Author action contains the rejected draft
+and its original task. Apply the user's feedback, or ask what should change if
+it is unclear; do not resubmit the same rejected proposal without addressing the
+decision. Other approved pages remain approved. Revisiting an earlier batch page
+also retains the interrupted Author in the same task queue, so follow the next
+Route instead of restarting the update.
+
+For note/sessions contributions, `writing_context.sources` supplies the exact
+saved-source paths and optional known change associations. Read the relevant
+summary before revising. A source change reference does not authorize an external
+fetch or prove upstream adoption. Keep the existing knowledge header minimal;
+page/section source relationships belong in structure.yaml.
+
+When the Route selects merge recovery, approved content changed during revision.
+Read its latest target and merge_context, retain the concurrent edits and any
+still-applicable draft changes, and submit the merged Markdown with the returned
+revision. Ask the user if the changes conflict in meaning; a deleted page is not
+permission to recreate it. The CLI checks the new baseline again and sends the
+result through ordinary Review. Unaffected batch pages and queued operations stay
+in place. Do not retry an older revision or overwrite the approved file directly.
+
+## Local section edits and optional preview
+
+For a small change, submit `sections` instead of `markdown`. Select exact IDs from
+`writing_context.current_sections`; each edit contains `section_id` and `content`,
+an ordered array of `{ "markdown": "replacement text" }` or
+`{ "program": "exact token from program_blocks" }`. The CLI retains untouched
+sections, page identity and the edited section's source references. Do not include
+section wrappers in replacement text. Use full Markdown for new pages, changed
+structure or pages without unambiguous section IDs. Both forms use the current
+Action schema and the same source and baseline validation.
+
+For example, after substituting IDs/tokens from this Route:
+
+```json
+{"stage":"approved-revision","sections":[{"section_id":"usage","content":[{"markdown":"Revised explanation."},{"program":"<current program token>"}]}]}
+```
+
+Use `--input <file>` on the Route command. If useful, append `--preview` to that
+same command: it returns the assembled Markdown and prior text without accepting
+or advancing the revision. Submit without `--preview` after checking it. Preview
+is optional; it does not replace Review or authorize a stale revision.
+
+## Interpreting generated API output
+
+Check fields, types, requiredness and supported defaults against the selected
+source version. A table can completely express a simple declaration; omitting
+that duplicate folded declaration is intentional. Complex relationships or
+constraints not represented in rows remain in a named declaration. Program
+`declaration_status`, when present, distinguishes `table-complete`,
+`component-wrapper`, `retained` and `not-provided`; its `fact_ref` and `source_ref`
+locate the input. Missing folds alone do not establish a parser failure.
+
+If the user explicitly requires a different presentation, explain the difference
+and resolve that choice before accepting it. Do not rerun unchanged Repair to
+force a format the program deliberately omits. Check the actual resulting page;
+accepted tasks or an empty Composer result alone do not demonstrate a correction.
+
+## Changed supporting articles
+
+`knowledge_input` separates approved interpretation from source-bound facts.
+Recheck the relevant interpretation when an upstream article changes; ordinary
+revision refreshes its version only after Review. Waiting input does not make
+old statements current, and a wording-only edit must retain the review warning.
+
+For a split, merge or removed upstream, use the existing `context task adjust
+--input - --format json` with `instruction` and `knowledge_dependencies`:
+
+```json
+{"instruction":"Rebind the affected explanation to the approved replacement","knowledge_dependencies":{"dependencies":[{"artifact_ref":"<approved article identity>","section_refs":[],"required":true}]}}
+```
+
+Select identities from the authorized approved article catalog; do not guess
+paths or promote prose into parser facts. Read the new current Route's
+`knowledge_input`, then repeat the adjustment with the same dependencies plus
+`sections`: each item has the retained `section_key`, selected `fact_refs` and
+`evidence_refs`. These are a full support replacement for those sections, not an
+append. Use only the supplied replacement facts or still-valid direct facts.
+An empty dependency list explicitly removes the old relationship; the remaining
+explanation still needs valid direct evidence. Revise the text to match the
+selection before submitting. The CLI checks identity, scope and version; the
+Agent and Review judge the explanation. Pending upstream approval remains a
+concrete task to finish or adjust, not a reason to clear the warning manually.

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
@@ -23,7 +39,12 @@ Build runs only after close and verification are current. It writes declared
 packages under `dist/` and records an inventory receipt with added, updated,
 removed, and index changes.
 
-Run only the current route command, then evaluate again. A successful build
+Follow the returned continuation. Automatic execution runs mechanical close and
+build steps and re-evaluates the Graph after each step. Recommended diagnostic
+resources are optional; do not materialize or acknowledge them merely to run an
+immediate repair command. While a command is running, wait for its result using
+the existing process handle; inspect logs only to diagnose an actual failure or
+suspected stall, not as a routine prerequisite for progress. A successful build
 means the currently declared scope is current; newly captured or newly declared
 targets can reopen earlier graph nodes.
 
@@ -34,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.