@c4a/context-cli 0.7.5 → 0.7.8

package/indexers/bundles/context-sessions-indexer/references/article-catalog/decision-record-article-catalog.md

@@ -0,0 +1,7 @@
+# Article choices
+
+Use the current authority to choose an allowed intent and an applicable template. These are alternatives or complementary articles within one topic; do not generate every row. Author receives the chosen blueprint through its current workset. Missing evidence calls for an entry or a named investigation step, not invented conclusions.
+
+| Template | Reader article |
+| --- | --- |
+| `decision-record-c06-page` | 补充说明与决策 |

package/indexers/bundles/context-sessions-indexer/references/article-catalog/domain-reference-article-catalog.md

@@ -0,0 +1,14 @@
+# Article choices
+
+Use the current authority to choose an allowed intent and an applicable template. These are alternatives or complementary articles within one topic; do not generate every row. Author receives the chosen blueprint through its current workset. Missing evidence calls for an entry or a named investigation step, not invented conclusions.
+
+| Template | Reader article |
+| --- | --- |
+| `domain-reference-c01-page` | 模块／知识入口 |
+| `domain-reference-c02-page` | 业务概览 |
+| `domain-reference-c03-page` | 术语与标识 |
+| `domain-reference-d01-page` | 领域架构与服务地图 |
+| `domain-reference-d02-page` | 业务流程与跨层链路 |
+| `domain-reference-d03-page` | 业务规则 |
+| `domain-reference-q01-page` | 测试域概览 |
+| `domain-reference-s04-page` | 领域模型 |

package/indexers/bundles/context-sessions-indexer/references/article-catalog/faq-support-article-catalog.md

@@ -0,0 +1,8 @@
+# Article choices
+
+Use the current authority to choose an allowed intent and an applicable template. These are alternatives or complementary articles within one topic; do not generate every row. Author receives the chosen blueprint through its current workset. Missing evidence calls for an entry or a named investigation step, not invented conclusions.
+
+| Template | Reader article |
+| --- | --- |
+| `faq-support-c05-page` | 已知问题与排障 |
+| `faq-support-q07-page` | 缺陷模式与复盘 |

package/indexers/bundles/context-sessions-indexer/references/article-catalog/incident-review-article-catalog.md

@@ -0,0 +1,9 @@
+# Article choices
+
+Use the current authority to choose an allowed intent and an applicable template. These are alternatives or complementary articles within one topic; do not generate every row. Author receives the chosen blueprint through its current workset. Missing evidence calls for an entry or a named investigation step, not invented conclusions.
+
+| Template | Reader article |
+| --- | --- |
+| `incident-review-c05-page` | 已知问题与排障 |
+| `incident-review-c06-page` | 补充说明与决策 |
+| `incident-review-q07-page` | 缺陷模式与复盘 |

package/indexers/bundles/context-sessions-indexer/references/article-catalog/product-requirements-article-catalog.md

@@ -0,0 +1,8 @@
+# Article choices
+
+Use the current authority to choose an allowed intent and an applicable template. These are alternatives or complementary articles within one topic; do not generate every row. Author receives the chosen blueprint through its current workset. Missing evidence calls for an entry or a named investigation step, not invented conclusions.
+
+| Template | Reader article |
+| --- | --- |
+| `product-requirements-c02-page` | 业务概览 |
+| `product-requirements-c03-page` | 术语与标识 |

package/indexers/bundles/context-sessions-indexer/references/article-catalog/runbook-article-catalog.md

@@ -0,0 +1,12 @@
+# Article choices
+
+Use the current authority to choose an allowed intent and an applicable template. These are alternatives or complementary articles within one topic; do not generate every row. Author receives the chosen blueprint through its current workset. Missing evidence calls for an entry or a named investigation step, not invented conclusions.
+
+| Template | Reader article |
+| --- | --- |
+| `runbook-c05-page` | 已知问题与排障 |
+| `runbook-d04-page` | 运维与排障入口 |
+| `runbook-f09-page` | 构建与部署 |
+| `runbook-q05-page` | 测试数据与环境 |
+| `runbook-q06-page` | 工具与排障工具箱 |
+| `runbook-s07-page` | 事件、任务与对账 |

package/indexers/bundles/context-sessions-indexer/references/article-catalog/technical-guide-article-catalog.md

@@ -0,0 +1,20 @@
+# Article choices
+
+Use the current authority to choose an allowed intent and an applicable template. These are alternatives or complementary articles within one topic; do not generate every row. Author receives the chosen blueprint through its current workset. Missing evidence calls for an entry or a named investigation step, not invented conclusions.
+
+| Template | Reader article |
+| --- | --- |
+| `technical-guide-c01-page` | 模块／知识入口 |
+| `technical-guide-c04-page` | 依赖与协作边界 |
+| `technical-guide-c07-page` | 从知识继续查源码 |
+| `technical-guide-d01-page` | 领域架构与服务地图 |
+| `technical-guide-d02-page` | 业务流程与跨层链路 |
+| `technical-guide-d04-page` | 运维与排障入口 |
+| `technical-guide-f01-page` | 架构 |
+| `technical-guide-f06-page` | 类型模型 |
+| `technical-guide-f08-page` | 样式与设计系统 |
+| `technical-guide-l03-page` | 设计系统及基础规范 |
+| `technical-guide-l04-page` | 中间件、适配与运行模式 |
+| `technical-guide-s01-page` | 服务概览 |
+| `technical-guide-s05-page` | 数据模型 |
+| `technical-guide-s06-page` | 外部依赖 |

package/indexers/bundles/context-sessions-indexer/references/article-catalog/test-validation-article-catalog.md

@@ -0,0 +1,11 @@
+# Article choices
+
+Use the current authority to choose an allowed intent and an applicable template. These are alternatives or complementary articles within one topic; do not generate every row. Author receives the chosen blueprint through its current workset. Missing evidence calls for an entry or a named investigation step, not invented conclusions.
+
+| Template | Reader article |
+| --- | --- |
+| `test-validation-q01-page` | 测试域概览 |
+| `test-validation-q02-page` | 测试策略 |
+| `test-validation-q03-page` | 用例目录 |
+| `test-validation-q04-page` | 回归基线 |
+| `test-validation-q05-page` | 测试数据与环境 |

package/indexers/bundles/context-sessions-indexer/references/article-catalog/user-and-developer-guide-article-catalog.md

@@ -0,0 +1,13 @@
+# Article choices
+
+Use the current authority to choose an allowed intent and an applicable template. These are alternatives or complementary articles within one topic; do not generate every row. Author receives the chosen blueprint through its current workset. Missing evidence calls for an entry or a named investigation step, not invented conclusions.
+
+| Template | Reader article |
+| --- | --- |
+| `user-and-developer-guide-c02-page` | 业务概览 |
+| `user-and-developer-guide-f09-page` | 构建与部署 |
+| `user-and-developer-guide-l01-page` | 公共能力与使用指南 |
+| `user-and-developer-guide-l02-page` | 公共组件与组件家族 |
+| `user-and-developer-guide-l03-page` | 设计系统及基础规范 |
+| `user-and-developer-guide-l05-page` | 组件库总览与接入 |
+| `user-and-developer-guide-q06-page` | 工具与排障工具箱 |

package/indexers/bundles/context-sessions-indexer/references/classification.md

@@ -0,0 +1,56 @@
+# Choose the reader outcome
+
+Classify useful passages, not the entire file. Source type, reader-facing form
+and operation are independent choices. One source can correct an existing FAQ,
+add a decision explanation and contain irrelevant conversation at the same time.
+Explain classifications in the user's language in the work-start report; the
+profile IDs below are protocol identifiers, not headings for the reader.
+
+| Material and reader need | Suitable profile | Action |
+| --- | --- | --- |
+| A concrete question with a supported answer | faq-support | Update the matching answer; create only if the question is distinct |
+| A repeatable task with prerequisites and checks | technical-guide / user-and-developer-guide | Integrate steps into the existing guide or propose a missing task |
+| Operational diagnosis and recovery | runbook | Preserve symptoms, checks, safe actions and verification |
+| Confirmed choice with rationale and limits | decision-record | Explain the choice, applicability and meaningful alternatives |
+| Agreed intended behavior and acceptance conditions | product-requirements | Keep intended behavior distinct from current implementation |
+| A reusable term, relationship or domain rule | domain-reference | Define it with scope and useful examples |
+| An incident account supported by observations | incident-review | Separate observations, causes and unverified hypotheses |
+| A test method or reported validation result | test-validation | Retain method, scope and what the result actually demonstrates |
+| Repetition, superseded claims, unresolved speculation without reader value | No new target | Support, defer or exclude with a concrete reason |
+| A required reader outcome needs a capability this Provider does not supply | `unsupported` for the affected material | Name the actual missing capability using the current Route; report its scope and recovery |
+
+“FAQ”, “knowledge improvement” and “knowledge accumulation” are not three source
+storage types. FAQ is a reader form; improvement usually revises approved prose;
+accumulation may add a topic or enrich an existing one. Decide from the actual
+reader question and existing coverage. Never route every note/session into FAQ.
+
+Choose the closest applicable declared profile by reader task, then adapt its
+outline to the useful content. Headings, grouping and examples are writing
+choices, not new capabilities. An existing project template override takes
+precedence; use supported customization when a reusable local template is
+needed, not as a prerequisite for ordinary writing. Do not invent profile IDs
+or claim unsupported tools, source access or output contracts.
+
+Reserve `unsupported` for a real capability gap that prevents the requested
+outcome within the authorized scope, not a mismatch with a stock outline. Name
+the missing capability in the current Route payload and explain which work is
+affected; follow its recovery instead of imposing an extra approval or stopping
+unrelated work yourself. Missing metadata or an unresolved claim can usually be
+bounded in useful prose. Request material only when the missing evidence is
+necessary to answer the reader's question; exclude material with no reader value.
+
+Reach for it rarely. The forms above are broad, and an awkward fit is not an
+absent one — a benchmark someone reported is test-validation, a complaint thread
+that reached a supported answer is faq-support, a walkthrough given in the
+discussion is a guide. What decides is the reader question, not how the
+conversation happened to unfold. A rambling thread, an unsettled status and an
+unfamiliar topic are none of them capability gaps; the first two are ordinary
+authoring work and the third is usually one of these forms under a name you have
+not seen before.
+
+Keep one subject identity for the same reader topic across updates. Two topics
+with the same title are not necessarily the same page; compare audience, scope
+and task. Do not merge different versions or platforms just to reduce page count.
+Conversely, do not split a coherent answer into thin pages because the source
+has many headings. Close the actual current inventory using the Route schema,
+including explicit dispositions for excluded material.

package/indexers/bundles/context-sessions-indexer/references/customization.md

@@ -0,0 +1,36 @@
+# Business replacement and customization
+
+Enable the chosen skill through the host's ordinary skill switch. Install it
+through your organization's own channel; Context has no additional business
+skill installation or enabled registry. The Agent discovers currently visible
+`context-…-indexer…` skills, then reads their real SKILL.md and sibling
+context-indexer.yaml. A matching name is a discovery hint, not compatibility.
+
+To replace a default, declare the business Provider as the primary for the
+selected requirement, using its observed version, supported profiles and actual
+distribution coordinates. Do not select the default too. Use the current
+Provider selection Route's host_visible_skills observation and indexers payload;
+let the host resolution action supply the actual bundle when requested. No host
+cache crawling or guessed version/integrity is needed.
+
+For a reusable wording/template change, these defaults support instructions-append
+and template-override, not config or program-extend. Ordinary heading and grouping
+choices do not require customization. Follow the selected Provider's actual
+capabilities if it is a replacement. For independent
+source interpretation a standalone business Provider is appropriate. To enrich
+another primary, declare extension profiles and compatible fragments in its
+manifest and bind them with kind extension. The existing protocol validates
+these declarations; CLI never decides which business interpretation is best.
+
+An override is named by the declared template ID, not its bundle filename:
+`src/indexer/<indexer-id>/templates/sessions-faq-support.md` overrides
+`sessions-faq-support`, whose default file is `templates/faq-support.md`.
+Keep the required origin comment pointing to the selected skill, observed
+version and profile. The same local override and `instructions.md` apply to
+initial writing and approved-page revision; no separate revision template is needed.
+
+The default template is a writing aid, not a mandatory business taxonomy.
+Customize reader questions and examples without changing source identity,
+revision authority, provenance or the single-primary rule. Check an unrelated
+session, an excerpt with unavailable original, a rejected proposal, an existing
+page correction and a mixed-code target before distributing a replacement.

package/indexers/bundles/context-sessions-indexer/references/diagrams.md

@@ -0,0 +1,122 @@
+# Source-grounded diagrams
+
+Use a diagram only when it clarifies a reader task better than prose or a table.
+This guidance applies to existing templates and selected article programs alike.
+It does not require a diagram, create a new article type, or add a completion gate.
+
+## Choose the representation
+
+| Reader question | Representation | Place in the article |
+| --- | --- | --- |
+| Which layers or services depend on each other? | Mermaid `flowchart LR` | Architecture or dependencies, after the scope |
+| What action happens next, including failures? | Mermaid `flowchart TD` | Behavior or business flow |
+| Who communicates, and in what order? | Mermaid `sequenceDiagram` | Request, integration or event processing |
+| What changes state, under which conditions? | Mermaid `stateDiagram-v2` | State behavior, alongside transition evidence |
+| How are persisted entities related? | Mermaid `erDiagram` | Data model, beside the entity/relationship table |
+| Where are files, articles or component parts? | Fenced `text` tree | Entry map or composition |
+| What are exact fields, routes, keys or source locations? | Markdown table | Contract, catalog or source references |
+| What does a component or visual foundation look like? | Authorized source image with caption and text | Usage or design foundation; diagrams do not prove visual appearance |
+
+A domain concept relationship can use a labeled flowchart rather than pretending
+it is a database ER model. Unrelated entities belong in a catalog table. Do not
+infer transitions from enum order, cardinality from field names, runtime calls
+from package dependencies, or sequencing from a list of imports.
+
+## Writing and evidence
+
+Start with one sentence stating what the diagram explains and its applicable
+scope/version. Follow it with a short explanation and source coordinates or a
+compact node/edge-to-source table. The reader must still have a useful next
+inspection step when the consumer cannot render Mermaid. Keep Mermaid fenced
+source in the article; do not replace the only editable representation with an image.
+
+Every asserted relationship needs support in the authorized source. A registered
+route does not prove runtime access; a client contract does not prove a call.
+Stop at a named external boundary when its implementation is unavailable and say
+what material is needed next. Keep proposals and historical accounts explicitly
+labeled; notes and conversations do not automatically establish current behavior.
+Do not copy a source diagram without checking its version and evidence scope.
+
+One diagram answers one question. Split an unreadable graph by responsibility,
+not an arbitrary node limit. Link related diagrams instead of repeating them in
+an overview, API page and source-entry page. A short page can omit the diagram.
+
+## Style
+
+- Prefer simple Mermaid constructs: flowchart, sequenceDiagram, stateDiagram-v2
+  and erDiagram. Use `text` for trees, not large ASCII boxes for relationships.
+- Prefer left-to-right for architecture and top-to-bottom for decisions. Use
+  subgraphs only for real ownership, process or deployment boundaries.
+- Use short stable ASCII node IDs and quoted human-readable labels in the reader's
+  language. Preserve exact service, API and state identifiers where they matter.
+- Label edges with the relation or action. Sequence arrows show communication;
+  state arrows show a named trigger/condition. Do not reuse an unexplained arrow
+  for imports, runtime calls and data ownership.
+- Keep default theme and simple shapes. Avoid custom HTML, scripts, click actions,
+  remote icons, theme directives and color-only meanings. Do not hardcode a canvas
+  size; let the consumer theme and layout render it.
+- Put long paths and citations outside node labels. Unknown relationships are
+  explained in text, not connected speculatively to make the picture complete.
+- An optional syntax/render warning is not a writing gate. Correct malformed
+  syntax or retain the accurate textual explanation; do not invent evidence to
+  satisfy a diagram checker. Never claim rendering was tested unless it was.
+
+## Small anonymous examples
+
+The following fragments demonstrate notation only; they are not facts to copy.
+Use only the fragment whose relationships are supported by the current source.
+
+Architecture: the two arrows describe different, explicit relationships.
+
+```mermaid
+flowchart LR
+  page["Order page"] -->|requests| api["Order API"]
+  api -->|writes| store["Order repository"]
+```
+
+Decision flow: a failed validation has a visible outcome.
+
+```mermaid
+flowchart TD
+  submit["Submit draft"] --> valid{"Input valid?"}
+  valid -->|yes| save["Save order"]
+  valid -->|no| feedback["Keep draft and show error"]
+```
+
+Sequence: branches are supported outcomes, not asserted deployment success.
+
+```mermaid
+sequenceDiagram
+  participant UI as Order page
+  participant API as Order API
+  UI->>API: Submit draft
+  alt Invalid input
+    API-->>UI: Validation error
+  else Valid input
+    API-->>UI: Order identifier
+  end
+```
+
+State: include this only when the transition implementation or specification is known.
+
+```mermaid
+stateDiagram-v2
+  Draft --> Submitted: submit / validation succeeds
+  Submitted --> Cancelled: cancel / cancellation allowed
+```
+
+ER: the cardinality must come from a schema or supported relationship contract.
+
+```mermaid
+erDiagram
+  ORDER ||--|{ ORDER_LINE : contains
+```
+
+Tree: directory membership does not imply runtime invocation.
+
+```text
+Order module
+├── Entry and scope
+├── Request contract
+└── Source investigation
+```

package/indexers/bundles/context-sessions-indexer/references/extension-placement.md

@@ -0,0 +1,63 @@
+# Where sessions material belongs in a base profile's page
+
+A `sessions/…` profile is an extension. It does not own a page and does not open a
+parallel one. The module stays on its base profile and selected page plan,
+including an applicable project template override. Contribute to the relevant
+sections; the attachment examples below are guidance, not a heading whitelist.
+
+Do not restate a base section the summary has nothing to add to, and do not
+introduce a "discussion" section to hold everything that was said.
+
+## What a summary can establish that the base sources cannot
+
+Read the base profile's Chapter blueprint and notice which sections its own
+evidence can settle. Structure settles from code and contracts: entry points,
+signatures, registrations, schemas, dependency edges. Several sections in every
+base blueprint ask for something else — why a limit was chosen, what a timeout
+means for a caller, which combination is unsupported, what breaks on upgrade,
+which behavior is deliberate rather than accidental. Those are the sections a
+development discussion is for, and they are usually the ones a reader most wants.
+
+This is the useful division. A summary that repeats a signature adds nothing and
+risks contradicting the authoritative source. A summary that carries the reason
+behind a value, the case that was deliberately excluded, or the failure mode
+someone already hit belongs in the section that asks for exactly that.
+
+## Attachment points by family
+
+| Family | Base profiles | Sections a summary usually reaches |
+| --- | --- | --- |
+| Applications and containers | `monorepo-container`, `web-application` | `Dependency and layering constraints`, `Shared configuration and tooling`, `Configuration and environment selection`, `Known exclusions and source-of-truth links` |
+| Reusable capabilities | `component-library`, `sdk-library`, `cli-tool`, `plugin-extension` | `Compatibility and release constraints`, `Behavior, lifecycle, and errors`, `Recovery and rollback boundaries`, `Configuration, permissions, and isolation`, `Compatibility, failure, diagnostics, and recovery` |
+| Services and gateways | `api-service`, `gateway-facade`, `domain-service` | `Error, timeout, and compatibility behavior`, `Timeout, retry, compatibility, and failure translation`, `State, transaction, and idempotency behavior`, `Failure and recovery behavior`, `Configuration, observability, and release` |
+| Runtimes and data flow | `background-runtime`, `event-consumer`, `data-sync-reconciliation`, `storage-repository` | `Concurrency, ordering, retry, and idempotency`, `Idempotency, retry, checkpoint, and failure destination`, `Authentication, failure, retry, and fallback`, `Transaction, consistency, cache, and locking behavior`, `Failure recovery and observability` |
+| Boundaries and contracts | `adapter-integration`, `contract-source`, `derived-generated-source` | `Error, retry, fallback, and compatibility behavior`, `Versioning, compatibility, and deprecation`, `Generated versus maintained behavior`, `Compatibility and regeneration` |
+| Document profiles | `domain-reference`, `product-requirements`, `technical-guide`, `user-and-developer-guide`, `public-api-reference`, `runbook`, `faq-support`, `standard-policy`, `decision-record`, `incident-review`, `test-validation`, `release-migration-guide`, `documentation-site` | The base document blueprint keeps its shape; a summary adds a decision, an exception, an applicability boundary or a correction |
+
+Read the section names from the actual base template the Route delivered. The
+table lists the sections these families most often need and is not the complete
+set; a base profile may declare a better-fitting section than the one named here.
+
+## How the material reads once placed
+
+Attribute it, and keep its state. A base page's other sections are backed by code
+or contracts, so a sentence sourced from a discussion has to carry its own
+strength. Distinguish what was proposed, what was agreed, what is implemented and
+what has been verified — a placed sentence that loses this distinction is worse
+here than on a standalone page, because the surrounding sections are
+authoritative and the reader will not question this one.
+
+"Agreed in a design discussion: the retry limit stays at three to stay under the
+downstream quota" is placeable next to a code-established limit. "The retry limit
+is three" is the base section's line, not the extension's.
+
+An optional `changes` association on the source names what the discussion was
+about. It does not establish that the change merged, deployed or passed tests, so
+it can never be what makes a statement `implemented`. When the base page's reader
+would want to open the change, name it in the prose of the section it belongs to;
+never in the page frontmatter.
+
+When a summary contradicts what the code establishes, do not silently pick one.
+The code establishes current behavior; the discussion may record an intention, a
+state since changed, or a decision not yet carried out. Say which, in the section
+where a reader would otherwise be misled.

package/indexers/bundles/context-sessions-indexer/references/indexer.md

@@ -0,0 +1,44 @@
+# Interpret a sessions summary
+
+A sessions source is a bounded summary from a conversation. It may describe
+requirements, design choices, troubleshooting, operational practice or general
+knowledge discussion. It need not concern code and need not have a commit.
+Only the host or external supplier prepares that summary; the Indexer does not
+scan chat history, load a full transcript, or synthesize a conversation from a
+diff. Read only the summary and other sources authorized by the current Route.
+
+Extract the problem, the decisions actually reached, the reasons needed to
+understand them, remaining questions and applicability. A discarded alternative
+is useful only when it explains a current choice or prevents repeating a failed
+approach. Do not reproduce turn order, repeated summaries, tool logs or every
+intermediate attempt. Keep “proposed”, “agreed”, “implemented” and “verified”
+distinct; a confident final message does not prove all four.
+
+For example, a discussion of a review process may agree that urgent changes
+need a second reviewer, leave weekend coverage unresolved, and abandon a
+three-reviewer proposal. With no code involved, a process guide can state the
+agreed rule and its unresolved coverage boundary. Do not invent a commit or
+publish the abandoned proposal as policy. A design discussion that ends without
+a decision may be saved for context without creating approved knowledge.
+
+For a code-related session, optional source frontmatter `changes` can identify
+one or more changes: each entry has a full `commit` SHA or an `mr` URL, optionally
+`repository`. No associations is normal. These links state what was discussed;
+they do not prove merging, deployment, successful tests or source-read permission.
+Do not guess missing identifiers or copy them into every knowledge header.
+
+When a session explains why a retry limit was chosen, code can establish the
+actual limit and branches, while the summary establishes the stated rationale.
+If the summary says a fallback was only proposed and code lacks it, do not write
+that the fallback exists. If code changed later, preserve still-applicable
+reasoning and mark superseded details only where that affects the reader.
+Where no code has been read, qualify implementation claims rather than hiding
+that limitation behind a change URL.
+
+## Diagrams
+
+Use the materialized [diagram guidance](diagrams.md) when a diagram clarifies the reader task. This also applies to older templates, source diagrams and Composer summaries. Preserve source strength, version and external boundaries; diagram presence is not a completion requirement.
+
+## Existing source images and tables
+
+For authorized visual material, follow [source visual processing](visual-source-processing.md): preference, capability-aware conversion, accepted-result reuse and retention. Follow the workspace AGENTS.md for editable diagram style.

package/indexers/bundles/context-sessions-indexer/references/updates-and-composition.md

@@ -0,0 +1,37 @@
+# Updates and composition
+
+First inspect the authorized existing knowledge and requested outcome. Saving
+input alone does not authorize a new indexing target. If a paragraph corrects
+an existing explanation, revise that approved page. Retain its useful steps,
+examples, images, limitations and confirmed contributions. If the material
+supports a new reader task, propose that topic through normal structure review
+before Author; never write directly to approved knowledge. If it adds nothing
+new, retain the source without producing a duplicate page.
+
+Use one primary Provider per target. For an independent note/session topic this
+Provider may be primary with one of its declared document profiles. For an
+existing Code or Markdown page, retain that page's primary Provider. When this
+Provider's specialized interpretation is needed, select it as an extension
+layer and bind its prefixed extension profile to the active base profile, e.g.
+`sessions/component-library` extends `component-library`. `profile.additional`
+uses `kind: extension`, not `supporting`: supporting profiles belong to the
+same primary layer. Read actual manifests; do not invent a profile name for a
+business Provider.
+
+This is an instruction-only extension. Its selected references guide source
+interpretation in the primary task; it has no separate inspector/program and
+does not claim to emit machine fact fragments. It supplies source-backed
+distinctions, relevant reasons, conflicts and limits to the same writing task. It does not become a second author,
+replace the primary API table, or create a standalone session page merely
+because a source exists. Extend only the target's explicit evidence/read scope;
+a commit or URL in metadata does not authorize fetching it. If no extension is
+selected, the main Provider can still read authorized supporting material under
+its own guidance; do not silently enable an unavailable skill.
+
+An incorrect source summary needs explicit correction by the host import flow,
+with current base_digest and task adjustment for pinned inputs. An accurate
+source but misleading page needs only approved-page revision. This Provider
+must not rewrite the original source to make a new page seem supported.
+A rejected revision leaves source material and approved content available for
+repair. Knowledge approval never changes upstream code, approves an MR, or
+turns a proposal into an adopted decision.

package/indexers/bundles/context-sessions-indexer/references/visual-source-processing.md

@@ -0,0 +1,42 @@
+# Source visuals: conversion and reuse
+
+Use during Author for authorized source images, tables and diagrams; Review checks fidelity. This is shared internal guidance, not another Provider, capture phase or approval step. See [diagram writing](diagrams.md) for diagram types. Follow the workspace's user-editable AGENTS.md for style; default to minimal diagrams, approximately 1px lines and theme-default text/strokes without color decoration. Do not force Mermaid theme directives to emulate viewer styling.
+
+## Preference and access
+
+Read `package.json` → `context.convertVisuals` (missing means true) and current user instructions. A session/image-specific opt-out wins; do not silently persist it. False disables new semantic conversion, not source capture, native tables, existing Mermaid, or downloading evidence. Explicit new user requests can override a saved preference.
+
+Current document material supplies `visual_resources`: registered `ref`, exact `content_hash`, `read_path`, original link, and accepted prior results. Read only authorized resources. No filename, alt text or link proves that an image was read. For code documentation or saved attachments without registered visual resources, preserve the original and use the existing source-material path if registration is necessary; never invent a visual ref or scan an unrelated checkout.
+
+Prefer available structured whiteboard JSON or table CSV. If interpretation uses more than one resource (for example both JSON and preview), list the additional authorized visual refs in `also_read`; all actually used resource hashes participate in reuse. Merely available but unread previews do not. Use a supported image-reading tool when needed. No capability, unreadable input, mixed screenshot or ambiguous relationships means retain; do not install OCR or loop requesting the same unavailable capability. Keep screenshots, photos, visual designs and illustrations when the appearance is the information. Convert clear flow, sequence, state, entity/UML relationships to supported Mermaid; convert tables only when labels, values, units, merged-cell meaning and footnotes survive. Encode meaningful colors as labels/legend. Do not guess relationships or numbers.
+
+## Submit inside the existing article
+
+Keep normal source-backed `sections[].markdown` and `source_items`. For each image represented in that section add `sections[].visuals`:
+
+```json
+{
+  "resource": "<visual ref from current material>",
+  "context": ["<exact source caption or relevant explanation>"],
+  "requirements": "English; sequence diagram; preserve all branches",
+  "disposition": "converted",
+  "format": "mermaid",
+  "markdown": "```mermaid\nsequenceDiagram\n  Client->>Service: Request\n```"
+}
+```
+
+`context` lists the actual source excerpts used to interpret this visual, not nearby unrelated paragraphs. Empty is valid only when no contextual explanation is needed. `requirements` records language/representation/explicit semantic requirements; exclude theme, stroke width, timestamps and ordinary tool versions. `format` is `mermaid`, `table` or `original`; retained decisions use `original` and may give a short `reason` such as `screenshot` or `tool-unavailable`. Keep the source document citation and source_items; the resource identity does not replace section evidence. This is semantic writing, never verbatim capture.
+
+Visual output is appended to the chosen section. Do not duplicate it in prose or template variables. Converted prose must not also include the replaced image, its download link or a resource-selector comment. Retained output keeps the original reference. Never delete captured files or edit managed assets yourself. Shared references determine asset retention; package building continues to include only referenced knowledge assets.
+
+## Incremental decisions
+
+Compare the current resource hash, exact associated context and effective requirements with `previous`. Matching accepted output can be reused by submitting the same resource/context/requirements/disposition/format and omitting markdown. Read the current approved result; revisions are authoritative. Changed resource or meaningful caption → reconsider that visual only. Unrelated paragraphs, movement within a document, temporary URLs, tool versions and style changes do not require reinterpreting unchanged visuals. Identical bytes in another document/context are not automatically the same interpretation.
+
+When several accepted copies disagree, choose the intended article's current result explicitly instead of guessing. Missing/invalid result → read authorized input or retain. A previous tool-unavailable retention may be retried when capability becomes available; no retries in a task without new capability. A user can request a new conversion or style revision explicitly. Style-only changes may replace the presentation using accepted content without rereading the image.
+
+The reuse hash is source-based and excludes presentation. Article integrity, approval and build hashes still cover actual output bytes. This prevents stale packages and does not claim that a changed file has identical bytes. Compact source receipts travel with approved sections; never fabricate hashes, receipt comments or successful conversion claims.
+
+## Review and fallback
+
+Check critical nodes, direction, conditions, units and values against the source. Text/code fences being syntactically present does not prove semantic fidelity. An invalid optional conversion produces an advisory and retains the authorized original. Do not make writing/style differences a hard gate. Existing source-integrity, authorization and required-material checks remain in force. No browser-specific Mermaid renderer is required to finish other articles.

package/indexers/bundles/context-sessions-indexer/references/writing.md

@@ -0,0 +1,63 @@
+# Write useful knowledge
+
+Start with the answer or action the reader needs. Explain when it applies and
+what they should do next. Source chronology is not the page structure. Keep the
+smallest source span supporting each claim; link the stored summary when that
+is all you read. Never pretend its original conversation or linked document was
+available. Missing originals limit confidence, not permission to invent detail.
+
+Select the declared profile template for the actual reader task. Its headings
+are prompts, not required empty sections. A FAQ answers a coherent reader question
+or related set of questions; a guide teaches a task; a decision explains a choice and its
+limits. Do not make one page per source heading or one page per input file.
+Separate unrelated topics even within one source, and combine corroborating
+passages from several sources when they answer the same question.
+
+Write claims at the strength of their sources. “Participants chose X for the
+next rollout” is not “X is running in production.” A report of a passing test
+is a reported result until the actual result is available. Quote only when the
+wording itself matters. Preserve dissent, dates and applicable versions when
+leaving them out would change the meaning. Do not publish personal exchanges,
+secrets or incidental tool logs that do not serve the authorized reader goal.
+
+Distinguish proposed, agreed, implemented and verified when the distinction
+matters; they describe different facts, not automatic stages every page must
+traverse. Agreement needs explicit confirmation by the relevant decision maker
+or a record that clearly attributes that confirmation. A confident closing
+message, silence or an Agent's summary alone is not approval. Preserve a
+confirmation recorded in a supplied summary without pretending to have read the
+original conversation. Implementation needs supporting code or maintained
+material in scope, and verification needs an actual relevant result. A report
+of implementation or verification can still be useful when attributed as such.
+
+Where the source carries an optional `changes` association, use it as a readable
+pointer for a reader who needs to check the change itself — name the repository,
+commit or MR in the prose of the section that discusses it. It stays out of the
+knowledge frontmatter, and it never raises a claim's strength: an association
+records what was discussed, not that the change merged, deployed or passed tests.
+When no code has been read, qualify the implementation claim rather than letting a
+change link stand in for having read it.
+
+For factual conflicts, compare scope, date and authority before choosing a
+statement. A confirmed future requirement can coexist with current code. Keep
+that distinction local to the explanation; do not silently overwrite one with
+the other. Ask about a missing decision if it changes scope or correctness.
+Other uncertainty can remain clearly bounded in a useful page.
+
+Use plain language. Avoid pipeline names, internal counts and execution receipts
+in the prose. Keep session IDs, change associations and Provider identities out
+of knowledge frontmatter. Existing structure.yaml page/section source links
+point to the stored source, where its optional metadata lives. Do not introduce
+a parallel registry or copy change metadata onto every page.
+
+Adjust the selected outline when the reader task needs different headings or
+grouping. Use the capability-gap criteria in [classification](classification.md)
+only when writing choices cannot solve the missing capability. Explain an actual
+tooling gap and the available recovery in the user's language, outside the
+knowledge page; do not turn an unfamiliar topic into a request for a new Provider.
+
+Before returning the current Route payload, read the page as a reader: can they
+answer the selected question without reconstructing the conversation? Check
+that each meaningful source topic is included, supporting, deferred or excluded
+with a concrete reason. A generic overview that drops the actual decision,
+exception or resolution is incomplete even if its headings look correct.