@c4a/context-cli 0.7.9 → 0.7.10-alpha.2

package/providers/context/provider.yaml

@@ -1,6 +1,6 @@
 schema: agent-graph.provider.v1
 id: c4a/context
-version: 0.7.9
+version: 0.7.10-alpha.2
 name: Context workflow
 description: Internal work contract for Context knowledge workspaces.
 graphs:

package/providers/context/resources/contracts/indexer-provider-guide.yaml

@@ -2,5 +2,5 @@ schema: agent-graph.resource.file.v1
 id: context.indexer.provider-guide
 kind: procedure
 mediaType: text/markdown
-path: skills/configure-indexer-providers/references/guides/indexer-provider-and-customization.md
-description: Current registry examples, Provider selection and customization instructions with bundled linked manuals.
+path: resources/manuals/guides/indexer-provider-and-customization.md
+description: Current requirements, lightweight Indexer guidance, stage-directory writing and temporary storage boundaries.

package/providers/context/resources/diagnostics/verification.md

@@ -10,14 +10,12 @@ Context reports one root diagnostic with counts and keeps derived findings in a
 separate detail view. Codes are stable machine identifiers; this document gives
 the shared recovery boundary.
 
-Broken source references or invalid stored structure require a corrected
-candidate or an explicit evidence-maintenance decision. Projection-only
+Invalid stored structure requires a corrected candidate. Projection-only
 failures can be repaired by deterministic close. Content-quality suggestions,
 including suspected unfilled placeholders, are advisory: they do not change a
 successful CLI outcome or add a gate. The existing Agent or user Review decides
 whether the content needs revision.
 
-`approved-source-orphaned` is a persistent warning produced only after an
-explicit `keep-orphaned` decision. It records that the page remains usable by
-policy while its original source document cannot be resolved. It does not
-permit changed source content to bypass replacement Review.
+Changed, missing or ambiguously relocated source regions identify articles to
+inspect through the normal revision workflow. Warnings do not add a separate
+maintenance gate, silently rewrite articles or confirm that the prose is current.

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

@@ -6,13 +6,11 @@ mediaType: text/markdown
 
 # Source-boundary dialogue
 
-For the first production task in a new workspace, use the required work-start
-procedure before presenting this source registration action. Read a supplied
-plan as task guidance, read batch metadata titles under that procedure's limits and
-10-document failure fallback (no bodies or outlines; retain URLs when titles are unavailable),
-resolve every required start condition, present the report and wait for feedback.
-Do not register the plan itself or begin capture merely because it contains source
-paths. Once confirmed, include the report path required by the current input schema.
+Confirm the reader purpose and source boundary, reusing explicit choices already
+provided by the user. Read a supplied plan as task guidance, not automatically as
+source material. Register and capture confirmed sources for lightweight
+investigation; the work-start report follows planning and must receive feedback
+before bulk writing. Source registration carries no report path or digest.
 
 Describe the boundary in user terms before showing a registration command. For
 code, distinguish a whole repository/subspace from one concrete package or

package/providers/context/resources/manuals/guides/code-indexer-skill-authoring.md

@@ -0,0 +1,84 @@
+---
+id: context.sdk.code-indexer-skill-authoring
+kind: procedure
+mediaType: text/markdown
+---
+
+# Code Indexer Skill authoring
+
+An Indexer exposes the source skeleton and guides source-grounded writing.
+Read [planning and writing guidance](./indexer-provider-and-customization.md)
+for the current workflow. Do not recreate routing inside a Skill.
+
+## Skill responsibilities
+
+Describe the supported technology, activation signals, useful reader questions,
+and how to investigate an authorized module. A module may use several Skills for
+different concerns. There is no exclusive primary owner, version pin, integrity
+receipt or production registration prerequisite. Skill names and optional usage
+configuration are temporary planning guidance, not article metadata.
+
+Keep `SKILL.md` focused on discovery and decisions. Put optional detailed writing
+guidance and reusable scripts beside it, with relative links and clear triggers.
+Distribution metadata does not impose workspace version validation.
+
+## Skeleton first
+
+During planning, prefer directories, manifests, registration points and bounded
+search. Either let the Agent inspect these directly or offer a fast helper suited
+to the stack. Report matching names, known counts and file locations. Do not
+require complete symbol extraction, call graphs or reading every implementation
+before proposing articles.
+
+Distinguish file-list counts from syntax-derived feature counts. A helper with a
+budget must identify inspected and uninspected scope, return a continuation when
+available, and label partial counts. Never present a stopped scan as a full total.
+Representative deeper reading is optional when it clarifies a topic boundary.
+
+Signals suggest topics; they do not prove semantics. A route registration can
+suggest an API topic, but not its error behavior or business meaning. Prefer
+reader questions to a mechanical page for each directory, symbol or heading.
+Keep module directories explicit in task guidance when needed, without adding
+a separate persisted boundary protocol or a new validation gate.
+
+## Writing and evidence
+
+Once the current report is confirmed, read the source needed for each assigned
+article. Describe contracts, state changes, failure behavior and integration
+points where relevant. Optional parsing can help locate declarations; it is not
+proof of runtime behavior. Preserve expressions without executing project code,
+distinguish declaration defaults from implementation defaults, and state unknowns.
+
+Use the current stage's Markdown and reference-file schemas. Each fragment cites
+at most three actual source locations; the CLI computes regional digests. Split
+an explanation when it needs separate evidence, not to fill a fixed template.
+Reuse stable article and fragment identities when revising. Supporting documents,
+notes or sessions may contribute to the same article without becoming code facts.
+
+The Agent plans batches and chooses reading order within the work released by
+the CLI. If supported, workers write assigned drafts and the coordinator submits
+completed subsets. Do not require every batch to finish before submission.
+Use the existing missing-material and repair outputs, not a per-member ledger,
+another content audit or a Skill-specific retry protocol.
+
+## Optional scripts
+
+Scripts serve a concrete repeated task; they are not mandatory for every stack.
+Take explicit authorized paths and bounded options, keep source files read-only,
+and return concise output or a file in the supplied temporary area. Do not execute
+repository code, read credentials, traverse unrelated directories or contact
+external services implicitly. Full parsing belongs to selected writing tasks.
+Report unsupported syntax and incomplete traversal separately from zero matches.
+
+## Validation and distribution
+
+Test supported technology with anonymous fixtures: feature discovery, bounded
+stopping, unsupported input, repeated names in different paths, and final article
+references. For generated API explanations, verify defaults, shared types and
+unresolved cross-file links in the final page as well as the parser output.
+Use relevant fixtures, not a mandatory matrix for unrelated technologies.
+
+Verify packaged relative links and executable helpers. Keep community examples
+free of company-specific services; organization and project knowledge belongs in
+their own Skills. Publishing or installing a Skill requires the appropriate
+authorization and does not add a hash or version check to knowledge production.

package/providers/context/resources/manuals/guides/indexer-provider-and-customization.md

@@ -0,0 +1,117 @@
+---
+id: context.sdk.indexer-provider-and-customization
+kind: procedure
+mediaType: text/markdown
+---
+
+# Indexer guidance for planning and writing
+
+Follow the current Route returned by `context run` or `context status --format json`.
+The CLI prepares a stage directory and returns its instructions, schemas and
+submission command. Use those files instead of copying long content into arguments.
+
+## Responsibilities
+
+An Indexer helps expose the source skeleton and guides source-grounded writing.
+It is not a mandatory full symbol scan or a semantic classifier owned by the CLI.
+Use a visible Skill directly, or its bounded CLI-assisted discovery, as appropriate
+for the technology. Multiple Indexers may explain different aspects of one module.
+There is no mandatory primary-owner selection or Provider resolution stage.
+
+At the start of this continuous work, declare the available relevant Skills and
+whether the Agent can schedule sub-agents. Use the capability schema supplied in
+the stage directory. A new session must declare its actual capabilities; do not
+inherit another session's parallel scheduling claim. Skill names and optional
+configuration are guidance, not version pins or evidence of completed reading.
+Do not inspect caches, compare Skill hashes, resolve exact versions or create a
+second installation registry. Installation and enabling Skills belong to the Host.
+
+## Confirmed requirements
+
+The configuration Route names the required file and supplies its schema. The
+requirements-only registry records reader goals and authorized sources, not
+production assignments. For example, replace the source and goals with the
+user's actual scope:
+
+```yaml
+protocol: context.indexer.registry/v1
+requirements:
+  - id: integration-guide
+    purpose: Help application developers understand and integrate the system.
+    reader_goals: [understand-system, integrate-system]
+    coverage_domains:
+      architecture: required
+    target_scope:
+      targets:
+        - source_ref: repo:sample
+    evidence_source_scope:
+      targets:
+        - source_ref: repo:sample
+indexers: []
+```
+
+Use registered source identities, not guessed paths or URLs. Keep any confirmed
+exclusions and supporting-source boundaries. Sources needed for another requirement
+are not globally excluded. Module directory boundaries can be supplied in task
+instructions by the Agent or CLI; do not invent persistent article fields or
+extra module-path validation. A module name alone does not identify its directory.
+
+## Lightweight investigation and planning
+
+For code, inspect directories, manifests and registration points. Return names,
+known counts and locations, not every symbol, call graph or implementation detail.
+Discovery has a bounded budget. Report incomplete coverage honestly; partial
+feature counts are not totals. Read representative code only when it helps make
+the plan. Deep extraction belongs to writing the selected topic.
+
+For documents, start with titles, bounded introductory text and heading outlines.
+Read more when necessary. Reuse code topics or existing articles where the content
+belongs, without forcing business concepts into physical directory names. Notes
+and sessions can directly suggest a new article or an amendment to an existing one.
+
+Submit article paths, reader questions, source associations and writing batches
+using the supplied planning schema. Record selected Skill names and configuration
+in the temporary plan's `indexer_usage`; the CLI can return it during planning
+and writing. It is not persisted on articles, sections or production results.
+Known one-to-one tasks can use the direct-writing path without an extra semantic
+planning submission. Do not create an inventory-member disposition ledger.
+
+Present the final work-start report after the relevant source overviews and plan
+are ready, before bulk writing. Wait for the user's confirmation, including in
+managed mode. Do not add approval for internal batch counts or Skill choices.
+
+## Directory-based writing
+
+The CLI determines which batches are ready and supplies their material and
+acceptance rules. Within that authorized work the Agent chooses reading order,
+writing order and, when supported, sub-agent scheduling. Without sub-agent support,
+work serially through the returned batch. Workers may write their assigned draft
+files; the coordinator submits completed subsets and owns shared CLI writes.
+
+Write Markdown and references into the stage's temporary output directory. Submit
+the short file manifest with stage-relative paths. Whole-article submissions and
+section repairs use the returned schemas. Read the receipt for accepted tasks,
+precise errors and next ready work; do not resubmit accepted content unnecessarily.
+Multiple authorized sources may support an article. A new task or changed plan
+must still respect confirmed requirements and the work-start report boundary.
+
+## Storage and continuation
+
+Drafts, capability declarations, plans, candidates, acceptance receipts and
+transaction state remain in `.tmp`. Only formal knowledge, necessary source
+material and long-term requirements belong in durable project content.
+With intact temporary state the current work can resume or retry safely. After
+clearing `.tmp` or cloning elsewhere, start new production from formal knowledge
+and sources; do not reconstruct the old workflow. There is no historical protocol
+migration or compatibility path.
+
+Source authorization, real references, safe file reads and concurrent-write
+protection still apply. Skill identity is not a production acceptance condition.
+
+## When maintaining a Skill
+
+For an explicitly requested Skill change, use the
+[code Skill authoring guide](./code-indexer-skill-authoring.md) or
+[document Skill authoring guide](./markdown-indexer-skill-authoring.md).
+These are authoring references, not additional reading required for routine
+knowledge production.

package/providers/context/resources/manuals/guides/knowledge-updates.md

@@ -36,6 +36,20 @@ 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
@@ -139,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
@@ -412,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/manuals/guides/markdown-indexer-skill-authoring.md

@@ -0,0 +1,65 @@
+---
+id: context.sdk.markdown-indexer-skill-authoring
+kind: procedure
+mediaType: text/markdown
+---
+
+# Markdown Indexer Skill authoring
+
+Use the shared [planning and writing guidance](./indexer-provider-and-customization.md).
+Document Skills help interpret captured articles; notes and sessions have their
+own guidance but can support the same reader topic. No unique primary owner,
+version lock or per-document disposition ledger is required.
+
+## Captured sources
+
+Start from authorized captured Markdown and its source identity. Capture proves
+which bytes are available, not what they mean. Titles, headings and filenames are
+navigation aids, not proof that the Agent has read the body.
+
+Do not fetch new documents, follow external links or widen source authorization
+implicitly. Request missing material through the current workflow. Keep the
+distinction between a source being unavailable and its contents being irrelevant.
+
+## Planning
+
+Read the supplied titles, bounded introductions and complete H2/H3 outlines.
+The Agent may read additional sections or the full document when needed, then
+chooses article targets and writing batches. Do not require full-body reading of
+every document or a separate planning submission for an already explicit target.
+
+Consult code topics and existing article descriptions and references. Reuse a
+topic when its reader question fits, or propose a clearer business topic instead
+of forcing a document under a code directory. One document may support several
+articles and several authorized documents may support one article.
+
+The final work-start report follows the relevant source overview and plan, and
+must wait for the user before bulk writing, including in managed mode.
+
+## Writing and repairs
+
+Read the actual passages needed for the article. Distinguish authoritative rules,
+examples, decisions and proposals; a session suggestion is not an implemented
+behavior. Write Markdown and references in the supplied temporary directory and
+submit the short stage-relative manifest. Title and description belong to the
+article, not an internal layout-mapping tuple.
+
+Keep stable article and fragment identities when revising. Each fragment cites
+at most three actual source regions. The CLI handles source digests and safety;
+the Agent judges whether the evidence supports the explanation. For a local
+failure, use the returned fragment identifier or position to repair the affected
+part. Completed independent tasks can be submitted without the rest of the batch.
+
+Do not inflate page counts, produce a page for every heading, or turn missing
+evidence into speculative prose. A genuine material gap remains unfinished work;
+an explicit exclusion uses the existing exclusion mechanism. Neither requires
+a new reconciliation ledger or additional content-review stage.
+
+## Useful fixtures
+
+Cover an ordinary one-to-one article, multi-document synthesis, reuse of an
+existing topic, fragment repair, source line changes, links and images, and
+missing material for the document forms the Skill supports. Verify both source
+fidelity and the final page. Keep examples anonymous and check packaged links.
+Drafts and scheduling details remain temporary; deleting `.tmp` starts fresh
+production from formal knowledge and available sources, not a workflow migration.

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/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. |