@c4a/context-cli 0.7.4 → 0.7.8

package/plugins/skills/context-note-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/plugins/skills/context-note-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/plugins/skills/context-note-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/plugins/skills/context-note-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/plugins/skills/context-note-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/plugins/skills/context-note-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/plugins/skills/context-note-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/plugins/skills/context-note-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/plugins/skills/context-note-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/plugins/skills/context-note-indexer/references/classification.md

@@ -0,0 +1,55 @@
+# 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 result is test-validation, a complaint with a supported
+answer is faq-support, an onboarding checklist is a guide. What decides is the
+reader question, not how the record happens to be laid out. A messy record, an
+unstated applicability boundary 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/plugins/skills/context-note-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/note-faq-support.md` overrides
+`note-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/plugins/skills/context-note-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/plugins/skills/context-note-indexer/references/extension-placement.md

@@ -0,0 +1,57 @@
+# Where note material belongs in a base profile's page
+
+A `note/…` 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 note has nothing to add to, and do not
+introduce a "notes" section to hold everything a note said.
+
+## What a note 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. Those are the sections a saved note is for.
+
+This is the useful division. If a note repeats a signature the code already
+establishes, it adds nothing and risks contradicting the authoritative source. If
+it carries a constraint, a known pitfall or an applicability boundary, it belongs
+in the section that asks for exactly that.
+
+## Attachment points by family
+
+| Family | Base profiles | Sections a note 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 note adds applicability, an exception, a correction or a missing definition |
+
+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. A base page's other sections are backed by code or contracts, so a
+sentence sourced from a note has to carry its own strength or a reader will
+assume the whole page is equally authoritative. "Recorded in an operations note:
+the retry limit was set to three to stay under the downstream quota" is placeable.
+"The retry limit is three" is not, unless the code establishes it — and if the
+code establishes it, the base section already owns that line.
+
+A note may report one occurrence or document an explicitly confirmed rule.
+Retain that distinction and its attribution. Qualify missing dates or versions
+where they affect the base section's meaning; do not generalize a single case
+or demote a confirmed rule merely because either was saved as a note.
+
+When a note contradicts what the code establishes, do not silently pick one. The
+code establishes current behavior; the note may record an intention, an older
+state or a mistake. Say which, in the section where a reader would otherwise be
+misled.

package/plugins/skills/context-note-indexer/references/indexer.md

@@ -0,0 +1,39 @@
+# Interpret a note
+
+A note is a durable record, excerpt, observation or summary supplied for this
+workspace. It can contain both raw material and an author's interpretation.
+Read the source's own labels and actual content before deciding what it proves.
+Do not classify it by filename, a keyword like “FAQ”, or the fact it is Markdown.
+
+Separate original wording from commentary when both are present. An exact
+excerpt can support what its author wrote within the quoted scope. A paraphrase
+supports the supplied account, not a verbatim quotation. A local observation
+supports that observed case; it is not automatically a universal rule. A user
+correction may invalidate an existing page even when it cannot justify a new
+standalone article. Keep useful source boundaries; do not strip raw passages
+out of sources to make them look like final knowledge.
+
+For example, a note may contain an error message, a successful recovery command
+and “perhaps the default timeout is too short.” The error and successful attempt
+can support a bounded troubleshooting entry. The speculation must not become a
+default-value claim or a root cause. If current code or a maintained document is
+already in authorized scope, check it; otherwise identify what remains unknown.
+
+A second note may correct one sentence in an approved guide. Compare the old
+sentence, its source and the new correction. Revise the relevant explanation if
+supported; do not create a “knowledge improvement” page that merely announces
+the correction. A third note may define a durable term absent from the guide:
+that can justify a new reference entry when the reader needs it.
+
+Ask only about missing information that changes a decision: whether an apparent
+proposal was adopted, which version a correction applies to, or whether raw text
+is actually a quote. Do not demand every possible metadata field. Where the
+note itself states the boundary, use it and proceed within authorization.
+
+## 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/plugins/skills/context-note-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.
+`note/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/plugins/skills/context-note-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/plugins/skills/context-note-indexer/references/writing.md

@@ -0,0 +1,57 @@
+# 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.
+
+A note can contain an observation, excerpt, proposal or an explicitly confirmed
+decision. Judge the actual record, not its source type: retain a documented
+approval with its attribution and scope, without claiming to have read an
+unavailable original. Do not promote an unconfirmed proposal to policy or demote
+an explicit confirmation merely because it is stored as a note.
+
+State dates, versions and environments when they affect how the answer can be
+used. If a missing boundary matters and authorized material does not settle it,
+qualify that claim locally; do not fill every page with generic unknowns. Do not
+substitute the note's save date for the event date, or treat the absence of a
+recorded counter-example as proof that one observation generalizes.
+
+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.