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

package/providers/context/resources/manuals/guides/package-outputs.md

@@ -21,11 +21,85 @@ close is required, run deterministic close before build. Current close derives
 final verify gate without rewriting approved Markdown. References, changelog,
 package index, and section fingerprint rebuilds are not current close output.
 
-## Recommended First Output: Agent Knowledge-Base Package
+## Default New-Workspace Outputs: Knowledge Base + Website
 
-Choose an agent knowledge-base package first when the knowledge should help
-Coding Agents work with the project. After the user chooses this semantic
-output shape, implement it with `kbPackage()`.
+Output channels support multiple selection. In a new workspace without explicit
+preferences, the Agent proposes and configures KB + website as the default. Honor
+user feedback, session authority and existing workspace declarations; LLMS is an
+additional selectable channel. This is an Agent configuration default, not an SDK
+change that silently enables websites for existing packages.
+
+### Static documentation website
+
+To include the default browser-readable site, enable `site` on the same
+package. The normal `context build` produces both the Agent KB and a standalone
+`dist/<base>-site/` directory containing `index.html`, article HTML,
+local search, scripts, styles and the selected bundled resources.
+
+`<base>` is the package name with one trailing `-kb` removed, when present.
+For example, `project-kb` produces `dist/project-kb/` and `dist/project-site/`;
+`project` produces `dist/project/` and `dist/project-site/`. Output directories
+must not collide with another package or website. `site.base` controls URL
+prefixes only, not filesystem output paths.
+
+```ts
+kbPackage({
+  name: "project-kb",
+  template: "src/package-templates/kb",
+  site: { title: "Project knowledge", lang: "en-US", base: "/" },
+});
+```
+
+`site` is opt-in; omission keeps the existing KB-only output. Optional fields
+are `title` (defaults to the package name), `description`, `lang` (defaults to
+`en-US`), and `base` (defaults to `/`; use `/docs/` when hosted under that path).
+The website uses a full-width VitePress theme with system fonts, compact navigation,
+a wide reading area and a smaller article outline. It starts in
+light mode regardless of the operating system; an explicit reader choice is
+remembered in browser storage. Search runs locally, without a search service.
+Mermaid renders in the browser with a restrained theme; invalid diagrams retain
+their source instead of blocking publication. Code samples and raw HTML are
+displayed as content, not executed as Vue components or scripts.
+
+The accepted `src/knowledge-map.yaml` controls sidebar organization. Entries
+bind to `artifact_ref` and optionally `section_key`; the builder resolves these
+against this package's selected approved articles. Navigation labels and parent
+groups do not determine website paths. One article may have several navigation
+placements while keeping one URL. Pending/excluded targets generate warnings
+and no invented link. Every selected article with an artifact identity must have
+a valid reading target before packaging, including packages without a website.
+Missing bindings or invalid section references block the staged output and
+return the missing article list plus a navigation-only task adjustment input.
+Category nodes can remain empty while future articles are planned. The builder
+does not infer business categories or alter article content.
+
+Top navigation contains the first-level reading directories. Selecting
+a section shows only its descendants in the left sidebar; opening an article
+directly selects its section. Skills and their Markdown references remain
+reachable as linked read-only pages, but have no automatically added navigation
+section. A reader-facing usage guide can link them where appropriate.
+Section landing pages have stable URLs separate from article URLs.
+
+`dist/<base>-site/context-site-map.json` records each article's approved path, KB path and
+site path, plus the projected menu and unresolved targets. URLs are derived from
+article identity; legacy pages without `artifact_ref` use their approved path,
+so moving those legacy files changes their URL. The shared knowledge map,
+KB layout and production Markdown remain unchanged.
+
+Article pages include a small source footer from recorded article source references and the source registry. Repository entries link to the recorded revision and module (or an explicitly referenced file); document entries link to their registered HTTP(S) URL. Unrecorded associations are not inferred from prose. Source-footer changes participate in the website build fingerprint without modifying knowledge Markdown.
+
+The website reuses resource delivery already performed for the KB: bundled
+resources are copied into the site's `resources/`; Git raw links remain remote,
+and explicit resource omission remains omission. It does not copy source trees
+or capture audits. Website generation completes in a sibling staging directory
+before either output is published, so a failed website build preserves the
+previous KB and website. The website is not included in the KB directory.
+Disabling the option removes the old site on the next successful package build.
+
+Preview through an HTTP static server. Deploy the **contents of `dist/<base>-site/`** using
+the user's chosen static hosting tool; no hosting SDK, login, deployment or
+platform-specific skill is part of Context's build. Keep hosting credentials
+out of package templates and published content.
 
 Typical output:
 
@@ -211,7 +285,9 @@ Typical output:
 
 ```text
 dist/<package-name>/
-└── llms.txt
+├── llms.txt                  # knowledge-map index
+├── llms-full.txt             # consolidated approved text
+└── llms/pages/<identity>.txt # individual approved articles
 ```
 
 Choose this when the user wants:
@@ -232,49 +308,139 @@ knowledge/
 └── ...
 ```
 
-## How To Ask The User
-
-When `workflow.current.reason_code` is `route.package.output-required`,
-explain the choices with the output tree. Do not ask the user to pick from
-unexplained labels.
-Use the host's native multi-choice tool when available. If unavailable, fall
-back to a short Markdown A/B/C question. The option labels should be:
-agent knowledge-base package, LLM text bundle, and skip package output for now.
-
-Recommended question shape:
+## Agent configuration and delivery recipe
+
+Use this guide when the user asks to generate a documentation website, selects
+outputs in the work-start report, or the current Route asks for package output.
+Read the current Route and existing `src/index.ts` first. Reuse settled choices;
+follow its configuration/read-acknowledgement contract rather than replaying a
+previous revision. The Agent edits SDK configuration; the user need not write code.
+
+1. Record all selected channels together. For new workspaces with no explicit
+   preference, use KB + website. Preserve existing declarations and explicit
+   KB-only, LLMS-only or deferred-delivery choices.
+2. Configure the existing KB declaration below, substituting the actual name,
+   title and workspace language. Retain its sources, phases, selection and resource
+   policy. This is one KB package with an additional website channel, not two KBs.
+3. If LLMS is selected, add its declaration and import in the same edit. Ensure
+   both template directories exist and resolve generic-template review using the
+   current Route. Do not independently ask approval for each already selected channel.
+4. Refresh `context status --format json`. Follow the returned continuation for
+   knowledge-map adjustment, required review, close, verification and build.
+   Missing article bindings require explicit targets from current CLI diagnostics;
+   do not classify articles from `wikis/` or `codeindex/` directory names alone.
+5. Run `context build` when ready. Verify each selected output and report its
+   actual location; a failed selected website is not completed delivery.
+6. Preview the generated website directory through a local HTTP server. Verify HTTP succeeds
+   before giving its URL. Publishing requires the user's chosen hosting tool and
+   authorization; do not install a hosting SDK merely to build the website.
 
-```text
-The reviewed knowledge is approved. The next decision is how to package it.
-
-Recommended: agent knowledge-base package
-dist/<name>-kb/
-├── AGENTS.md
-├── skills/knowledge-query/SKILL.md
-└── wikis/
-    ├── index.md
-    ├── <group-page>.md
-    └── <large-group>/index.md
-
-This is best if agents should use the knowledge as a reusable knowledge base.
-
-Alternative: LLM text bundle
-dist/<name>-llms/
-└── llms.txt
-
-This is best if you need one text bundle for model/RAG import.
-
-We can also skip package output for now and keep only knowledge/.
-
-Which one should I declare first?
+```ts
+import { defineProject, kbPackage, llmsPackage } from "@c4a/context";
+
+// Edit only the packages field of the existing defineProject declaration.
+// Keep the actual project's other declarations intact.
+const packages = [
+  kbPackage({
+    name: "project-kb",
+    template: "src/package-templates/kb",
+    site: { title: "Project knowledge", lang: "en-US", base: "/" },
+  }),
+  // Include this entry only when LLMS text is selected.
+  llmsPackage({ name: "project-llms", template: "src/package-templates/llms" }),
+];
+// Existing defineProject({ ...existing declarations, packages }).
 ```
 
-If the user chooses the Agent knowledge-base package, explain that its OKF
-roots are flat within `dist/<package-name>/`; do not ask for a second namespace.
-If its Skills need a short prefix, the author maintains those final names
-independently from package paths; this is not a mandatory question.
+The configuration is a small source edit, not custom frontend implementation.
+Website output reuses approved articles, knowledge map and packaged assets;
+rendering/search generation adds build time and size, not another indexing pass.
+Measure actual cost instead of quoting a universal estimate.
+
+| User request | Agent action |
+| --- | --- |
+| KB + website | One `kbPackage` with `site` enabled |
+| KB only / disable website | Omit `site` on that KB and rebuild; old site output is removed |
+| Add website later | Add `site` to existing KB, repair missing reading bindings, rebuild |
+| Website only for distribution | Explain the KB is still built; share only the sibling website directory |
+| Also produce LLMS | Add `llmsPackage` alongside the KB in the same change |
+| Keep current knowledge only | Postpone packaging; do not label it completed package delivery |
+
+```sh
+python3 -m http.server 8000 --bind 127.0.0.1 --directory dist/project-site
+```
 
-If the user requests multiple outputs, declare and verify each requested package.
-There is no additional confirmation just because two outputs were already chosen.
-The default adaptive index policy avoids one-page directory indexes. Configure
-`kbPackage().navigation` when a package needs a different inline-entry
-threshold or a fully expanded index at every directory.
+The completion report lists KB root, website directory and LLMS file separately,
+with generated/failed/not-selected status. Include website navigation coverage,
+verified preview URL when running, and any remaining errors. The website contains
+source cards and article update times; it does not imply an article history browser.
+
+## How To Present The Choice
+
+Include a compact multi-select list in the work-start report, and reuse it later:
+
+- [x] Agent knowledge-base package — default for a new workspace.
+- [x] Documentation website — default with the KB, local preview or later hosting.
+- [ ] LLMS text — optional model-context or RAG input.
+
+Explicit choices override defaults. When current Route authority requires a user
+decision, ask once for the combination rather than a sequence of mutually exclusive
+questions. If the host tool supports only single selection, let the user state the
+combination in text instead of presenting it as multi-select. There is no `both`
+factory, separate website skill, or second permission per selected output.
+
+## 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.
+
+
+### Persistent knowledge map and report proposals
+
+`src/knowledge-map.yaml` is the persistent knowledge map; retain it after delivery.
+Its protocol is `context.knowledge-map/v1`; structure and adjustment inputs use
+`knowledge_map`, and SDK functions use `KnowledgeMap` naming. It organizes website
+navigation and LLMS without changing article identities or section bindings.
+
+The work-start report explains the proposed directory and chapters, followed by
+a text wireframe of the website. Material changes are communicated with the updated
+report link and a short explanation. This does not build a temporary website or
+create a persistent article-plan file. Website packaging uses the accepted knowledge map
+and approved articles; the report is not a configuration input.
+
+### Website LLM Docs
+
+Every website build also builds LLMS from the same selected approved articles and
+knowledge map. The final top-navigation item is always **LLM Docs**, opening
+`llms/index.html`. This page links to `llms.txt`, the structured index,
+`llms-full.txt`, the complete approved text, and raw Markdown text articles under
+`llms/pages/`. These files ship inside the sibling website directory and use the configured site base.
+No separate LLMS package declaration or additional build command is required.
+Website LLMS text files include a UTF-8 BOM so browsers can identify the encoding
+when a static host omits the charset. Hosting should serve them as
+`text/plain; charset=utf-8`. The HTML landing page shows one index/full-text
+toolbar followed by the knowledge map; Changelog is available in the site navbar.
+
+The index preserves knowledge-map grouping, order and repeated placements. The
+full text includes each selected article only once, in first-placement order.
+Only approved selected content is exported. A map or article change invalidates
+both website and LLMS outputs; failure preserves the previous staged package.
+Standalone `llmsPackage()` uses the same map organization and supplies the full
+text and raw article files alongside its template-rendered `llms.txt` index.

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

@@ -238,19 +238,15 @@ rejects it.
 The default kb template includes:
 
 - `skills/knowledge-query/SKILL.md`, a reusable skill that teaches agents to
-  query copied knowledge pages structure-first, cite page/section evidence, use
-  `context-build-inventory.json` edge records for package-visible
-  relationships, and report gaps instead of inventing unsupported answers. The
-  build inventory also exposes `structure.relationship_coverage` so a consumer
-  can distinguish an observed zero-edge result from unknown relationship
-  coverage. The
+  navigate copied knowledge pages, cite relevant text and its exported source
+  attribution, and report gaps instead of inventing unsupported answers. The
   default entry OKF root is `wikis/`; packages that select additional internal
   collections expose
   `guides/`, `rules/`, or `feats/` indexes when those roots are selected.
 - `skills/knowledge-query/scripts/search.mjs`, a dependency-free BM25 fallback
   for exact terms, mixed keyword queries, and large Markdown indexes. It chunks
   mechanically, returns inspectable paths and line ranges, and never replaces
-  source-backed relationship evidence.
+  reading the relevant source-backed explanation.
 - `wikis/index.md`, the editable OKF bundle entry page for the generated
   `dist/<package-name>/wikis/` directory.
 
@@ -267,10 +263,8 @@ The generated
 KB entry surface. Internal collections are mapped into OKF roots during build:
 `codeindex`, `business`, and `product` go to `wikis/`; `architecture`, `sop`,
 `faq`, `decision`, and `incident` go to `guides/`; `standards` and `test` go to
-`rules/`; and `feats` goes to `feats/`. Treat `wikis/` as the structured
-entity-and-relationship layer. Guides and rules may explain, operationalize,
-or constrain that knowledge, but directory placement alone does not establish
-a relationship.
+`rules/`; and `feats` goes to `feats/`. These roots organize articles by content
+type; directory placement does not establish a relationship or a subject graph.
 
 Default navigation rules:
 
@@ -313,54 +307,36 @@ wants project-specific behavior beyond knowledge lookup.
 
 ## Context OKF Profiles
 
-Approved Markdown under `knowledge/` and its deterministic
-`knowledge/structure.yaml` projection form the authoring source of truth:
-
-- top-level YAML frontmatter uses OKF fields such as `type`, `title`,
-  `description`, `tags`, `timestamp`, and `resource`;
-- each Markdown page keeps reader fields, stable page identity, `sources`, and a
-  small recovery capsule (`resource`, `node_type`, containment fields, and
-  relationship mode);
-- large or repeated machine state such as complete `code_symbols`, code
-  evidence, relationship records, candidate fingerprints, and optimization
-  decisions lives once in the corresponding `structure.yaml` view record;
-- Context readers hydrate that machine state in memory before verify, audit,
-  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 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;
-- do not add frontmatter `source_refs`; page-level provenance is derived from
-  section source refs when needed;
-- do not add `context` or `schema` fields.
-
-Package knowledge pages under `dist/<package-name>/` use a consumer projection.
-They retain reader-facing fields such as `title`, `type`, `description`, `tags`,
-`timestamp`, and custom non-lifecycle fields. Node identity, `resource`,
-`sources`, Section evidence comments, and build-only fields are omitted from the
-page. `context-build-inventory.json` records the distributed path, approved
-knowledge path, node identity, source summary, and package-visible structure.
-Maintainers return to the mapped `knowledge/` page for exact `sources` and
-`source_ref` attribution. `knowledge/` is never rewritten by this projection.
-
-Accepted section `source_ref` forms:
-
-```text
-src-N#symbol:<file>:<symbol-id>:<kind>@<digest>
-src-N#span:<heading-hint> L<start>-<end>@<span-hash>
-```
-
-The code symbol form includes the source-relative file so same-name symbols in
-different files resolve to one exact symbol-index row. Consumers should still
-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 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.
+Approved Markdown under `knowledge/` and the article index in
+`knowledge/structure.yaml` have separate responsibilities:
+
+- Markdown owns `title`, `type`, `description` and the ISO UTC `timestamp`.
+  `resource` and `tags` are optional reader metadata, not required identities.
+- Structure owns stable `article_id`, `path`, `collection`, `visibility`,
+  and fragment `sections` with their region `references`.
+- Markdown fragment markers contain only their stable ID:
+  `<!-- context:section id="usage" -->` and `<!-- /context:section -->`.
+  Structure records each corresponding ID and at most three source positions
+  per fragment, not three per article.
+- A reference contains `source_ref`, `locator: { path, start_line, end_line }`
+  and the Host-computed regional `content_digest`. Do not duplicate this in
+  Markdown frontmatter or comments.
+- Neither Markdown nor structure keeps a node graph, parser fact ledger,
+  evidence-binding table or a second copy of article prose.
+- Article moves retain identity through Context's existing revision workflow.
+  Direct Markdown copies alone do not include complete provenance.
+
+Package pages under `dist/<package-name>/` retain reader metadata and receive
+a generated Sources section derived from the article references and source
+registry. Repository links include file and line ranges; document links retain
+the captured document attribution. This export does not rewrite `knowledge/`.
+The build inventory maps exported pages back to their approved article paths.
+
+Source snapshots and regional baselines remain machine-managed. Update checks
+compare cited regions, relocating unchanged text only when its new position is
+unambiguous. Missing, changed or ambiguous regions require review; an unchanged
+region does not prove that uncited new material is irrelevant. A session's
+optional commit/MR association stays with its source document.
 
 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
@@ -383,12 +359,10 @@ The OKF-compatible surface is the selected `wikis/`, `guides/`, `rules/`, and
 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
-`knowledge/structure.yaml` file is bundled.
+The `structure.articles` projection retains selected article identities and
+fragment source references. It does not contain graph nodes or typed edges.
+Published Markdown includes readable source attribution derived from these
+references; the Agent does not maintain a second source list in the page.
 
 For KB packages, the inventory records `package.distribution` as
 `layout: "flat"`, `knowledge_namespace: null`, and the four package-relative

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

@@ -71,6 +71,51 @@ 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`
 
 ```ts
@@ -89,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({
@@ -101,6 +147,13 @@ 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
 
 When this file is absent, the configuration Route supplies the initial schema:

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

@@ -141,13 +141,12 @@ Each item contains:
 | `sourcePath` | Approved knowledge path before OKF output mapping, for example `architecture/entity/button.md`. |
 | `approved_path` | Alias for `sourcePath`. |
 | `dist_path` | Alias for `path`. |
+| `article_id` | Stable article identity from the approved article index. |
 | `internalCollection` | Internal approved collection, for example `architecture`. |
 | `internal_collection` | Alias for `internalCollection`. |
 | `collection` | Internal approved collection; alias for `internalCollection`. |
 | `okf_root` | OKF output root, for example `wikis`, `guides`, `rules`, or `feats`. |
 | `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 `architecture/entity/button.md`. |
 | `href` | Link relative to the template file currently being rendered. Use this in custom templates. |
 | `hrefFromTemplate` | Alias for `href`. |
@@ -157,7 +156,7 @@ Each item contains:
 | `type` | OKF `type` from frontmatter. |
 | `description` | OKF `description` from frontmatter, when present. |
 | `timestamp` | OKF `timestamp` from frontmatter, when present. |
-| `source` | First top-level `sources` entry without the `repo:` prefix, or the group name. |
+| `source` | First actual source reference from the article index, or the group name. |
 | `group` | First path segment under the OKF root. |
 | `parentPath` | Parent path below the OKF root. |
 | `depth` | Segment count below the OKF root. |

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

@@ -18,7 +18,7 @@ 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
+page's stable fragment markers and metadata. 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.
@@ -27,18 +27,18 @@ 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.
+The supplied Markdown contains its initial metadata. Article identity stays in the structure.
 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
+Use `target.source_refs` as the allowed source scope, not as a list to copy onto the page. 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
+Keep its stable article identity and fragment IDs. 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
@@ -49,13 +49,22 @@ 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.
+Read `writing_context` for the confirmed reader requirements, current sections,
+authorized source entries and any available skill guidance from this temporary
+work session. A missing skill selection does not invalidate the approved page
+or require restoring a former Provider registration. These inputs 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
+Ordinary source updates do not automatically parse the repository or generate
+API tables. Read the changed material relevant to the requested correction;
+use a suitable scoped analysis capability when needed. Do not wait for a
+Provider selection, version check or program block before revising ordinary
+prose. Keep actual source citations and the current revision baseline.
+
+When an explicit regeneration request supplies `program_blocks`, they contain
+API tables computed from scoped Parser facts with the 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
@@ -101,11 +110,21 @@ For a small change, submit `sections` instead of `markdown`. Select exact IDs fr
 `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
+sections and page identity. Omitted references preserve the previous citations. 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.
 
+When a fragment's support changes, include `references` with its actual
+`source_ref` and `locator` (`path`, `start_line`, `end_line`). Each fragment allows
+up to three positions; Context reads the captured region and computes its digest.
+For full Markdown, optional `sections` contains only `{ section_id, references }`
+entries; for local edits it can accompany `content` or update references alone.
+An explicit empty list removes that fragment's citations. Deleted fragments lose
+their references; new fragments need their own selected sources, not copied IDs.
+Uniquely moved unchanged text can retain its fingerprint at its new position;
+changed or ambiguous regions remain visible for review, not silently refreshed.
+
 For example, after substituting IDs/tokens from this Route:
 
 ```json
@@ -131,29 +150,3 @@ 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.