@c4a/context-cli 0.7.5 → 0.7.9

package/indexers/bundles/context-markdown-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-markdown-indexer/references/article-catalog/documentation-site-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 |
+| --- | --- |
+| `documentation-site-c01-page` | 模块／知识入口 |
+| `documentation-site-l05-page` | 组件库总览与接入 |

package/indexers/bundles/context-markdown-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-markdown-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-markdown-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-markdown-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-markdown-indexer/references/article-catalog/public-api-reference-article-catalog.md

@@ -0,0 +1,10 @@
+# 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 |
+| --- | --- |
+| `public-api-reference-f05-page` | API 集成 |
+| `public-api-reference-l02-page` | 公共组件与组件家族 |
+| `public-api-reference-s02-page` | API 目录 |
+| `public-api-reference-s03-page` | API／操作详情 |

package/indexers/bundles/context-markdown-indexer/references/article-catalog/release-migration-guide-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 |
+| --- | --- |
+| `release-migration-guide-c06-page` | 补充说明与决策 |
+| `release-migration-guide-f09-page` | 构建与部署 |
+| `release-migration-guide-l01-page` | 公共能力与使用指南 |
+| `release-migration-guide-l03-page` | 设计系统及基础规范 |
+| `release-migration-guide-l05-page` | 组件库总览与接入 |

package/indexers/bundles/context-markdown-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-markdown-indexer/references/article-catalog/standard-policy-article-catalog.md

@@ -0,0 +1,10 @@
+# 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 |
+| --- | --- |
+| `standard-policy-d03-page` | 业务规则 |
+| `standard-policy-d04-page` | 运维与排障入口 |
+| `standard-policy-f08-page` | 样式与设计系统 |
+| `standard-policy-l03-page` | 设计系统及基础规范 |

package/indexers/bundles/context-markdown-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-markdown-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-markdown-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-markdown-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-markdown-indexer/references/editorial-policy.md

@@ -5,11 +5,12 @@ review lead with a recommended outcome; it is not authority to change facts,
 cross Section boundaries, or discard evidence. Preserve exact links, code,
 commands, identifiers, numbers, conditions, attachments, and source meaning.
 
-The community policy owns scenario interpretation and revision guidance. The
-Context plan may also report syntax, protected-value, or safety-baseline
-signals. Use the same decision discipline for both, while leaving detection,
-source spans, stale checks, protected values, revision persistence, and final
-validation to Context.
+The Agent owns scenario interpretation and content assessment. Context checks
+structured inputs, source references, protected values and safe writes; it does
+not infer content quality from words, punctuation, Markdown layout or table size.
+The catalog below is review guidance, not a CLI scanner or readiness checklist.
+Suspected unfilled placeholders may be mentioned during the existing Review;
+they do not create another gate or require a rewrite to make a counter pass.
 
 ## Signal catalog
 
@@ -42,9 +43,9 @@ fit. File length, page count, deadline, or effort never changes the outcome.
 
 ## Outcomes
 
-- `keep`: use when there is no actionable signal, or for a `review` signal only
-  with a Section-specific assessment that proves a false positive or explains
-  why the proposed edit would damage source fidelity.
+- `keep`: use when the Section already serves its reader, including when a
+  suggested edit would damage source fidelity. The presence of a signal name
+  does not require an assessment or prevent keeping the Section.
 - `repair`: make a local presentation correction without changing facts or
   protected values.
 - `reshape`: reorganize the same supported material without broadening,
@@ -61,22 +62,14 @@ routine review pause. Managed authority does not lower these rules and does not
 turn genuinely missing input into `keep`; ask once for the remaining batched
 input after completing the independent analysis.
 
-## Assessment contract
+## Content assessment
 
-An assessment is required only when keeping a reported `review` signal or when
-a repaired/reshaped result retains a review signal after rescan. It must:
-
-1. be Section-specific rather than copied across a batch;
-2. name every remaining signal code;
-3. cite concrete source evidence for a false positive, or state the exact
-   source fidelity loss the recommended edit would cause;
-4. explicitly say `false-positive` for a kept `request-input` signal;
-5. never cite time, cost, effort, workload, batch size, deadline, or progress.
-
-A `high` signal cannot be justified by assessment and kept unchanged; it must
-be resolved. A Section without a signal can be kept without an assessment.
-Every repair or reshape is subject to the same post-revision signal scan and
-protected-value validation; selecting an action is not proof of resolution.
+A Section-specific assessment can explain an editorial choice when useful; it
+is not a required signal-clearing receipt. Either confidence label is advisory.
+There is no CLI post-revision prose rescan, required keyword, or automatic
+failure for retaining a signal. Decide from source meaning and the reader task;
+keep legitimate examples, placeholders being documented, and historical facts.
+Protected-value and reference checks remain mechanical safeguards.
 
 ## Anonymous decision examples
 
@@ -97,10 +90,7 @@ protected-value validation; selecting an action is not proof of resolution.
 - A current rule followed by an undecided proposal: choose `reshape`, retain
   the rule, and isolate the proposal rather than omitting the whole Section.
 - Struck-through text that is the only surviving historical record may be kept
-  only with a Section-specific `strikethrough-only-block` assessment explaining
-  the exact source fidelity loss; ordinary obsolete-only prose should be
-  omitted.
+  when it has continuing reader value; no signal-specific receipt is required.
 
-Before returning a decision, confirm every Section has one outcome, every kept
-signal has a valid assessment, every omission has an eligible reason, and no
-revision changes authority, evidence, identity, or protected values.
+Before returning a decision, confirm every Section has one outcome and no
+revision accidentally changes authority, evidence, identity, or protected values.

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

@@ -2,6 +2,32 @@
 
 Classify and author at the source-backed Section level using only the current Authorized Workset View. A document profile describes reader intent; it is not an output directory. Mixed documents may contain Sections with different reader goals, but every Section must retain one stable subject, owner, source authority, and projection intent.
 
+Keep the requirement's `purpose` and open `reader_goals` visible in Partition,
+Author and Review. Select a supported page intent and template for that reader's
+task, save the outline and delivery boundary, and reuse those choices on retry.
+A how-to guide, FAQ and design explanation retain their distinct purposes;
+shared code evidence does not turn every document into a maintenance audit.
+If the purpose is already clear, do not ask it again because a field is absent.
+Managed execution does not authorize deciding a truly ambiguous purpose.
+
+During representative reading, actively distinguish sections that answer the
+reader's task from supporting context and material that may be unnecessary.
+Check available document status, intended audience, version applicability and
+substantive duplication. Age, titles, archived locations and document length are
+clues, not exclusion rules; historical decisions and older procedures can still
+be required. Preserve useful detail rather than replacing it with an inventory.
+If a substantial region raises an unresolved scope choice, explain what including
+or leaving it out means and ask before dependent writing, including in managed
+mode. Unneeded material increases token use, processing and review work, and can
+bury useful answers in repetitive or conflicting pages. Recommend boundaries
+from the user's task, not from a target page count or promised speedup. Reuse
+settled decisions, use the current Result's supported dispositions, and preserve
+accepted knowledge. Do not treat unread material as irrelevant or silently omit it.
+
+Context delivers an initial readable sample and subsequent page batches through
+the current Review, close and build routes. Continue the remaining accepted plan
+after each build; preserve already delivered pages and source-grounded prose.
+
 Use `classification.md` as the semantic source for `document_kind`, `reader_goal`, and current `artifact_kind` selection. Use `structure-and-artifacts.md` for mixed-document routing, Section-versus-Artifact promotion, density, duplicate/conflict handling, and target candidate resolution. The CLI-supplied profile contract remains the only authority for collection and path projection.
 
 Use `semantic-planning.md` for evidence authority, SubjectKey/target-resolution
@@ -10,7 +36,7 @@ stale/collision recovery behavior. It adapts the useful semantic gates from the
 former align path to the current Result ABI; it does not authorize legacy align
 commands or `context.structure.v1`.
 
-Use `editorial-policy.md` for scenario editorial signals, recommended outcomes, Section-specific assessments, omission eligibility, and anonymous decision examples. Context still owns signal spans, protected values, revision CAS/storage, rescans, and final validation.
+Use `editorial-policy.md` for editorial review hints and anonymous decision examples. Content assessment belongs to the Agent and user; hints do not trigger a CLI prose rescan, rejection, or additional gate. Context owns source references, protected values, revision CAS/storage, and structural validation.
 
 Preserve exact commands, identifiers, links, attachments, tables, and code blocks when they are evidence-bearing. Separate deterministic catalogs from explanation. Do not publish unsupported claims, conversion annotations, placeholders, or unresolved requests as knowledge.
 
@@ -22,7 +48,7 @@ source-backed. It is a display title for outline and final Candidate Review,
 not a SubjectKey, ownership signal, or identity fallback. Later Sections in the
 same Artifact must not add another level-one heading.
 
-When current source material cannot answer a required canonical question, return the exact material-question disposition for the supplied target. A later run may consume newly captured Markdown as ordinary source and update the same knowledge candidate. Context owns layout, collection mapping, runtime material-gap state, quality thresholds, the single final content Review, and close.
+When current source material cannot answer a required canonical question, return the exact material-question disposition for the supplied target. A later run may consume newly captured Markdown as ordinary source and update the same knowledge candidate. Context owns layout, collection mapping, runtime material-gap state, each delivery's content Review, and close.
 
 Return only the current `main-index` `IndexerResult`/`ArtifactResult` contract. Context derives the source dependencies needed for stale detection and recovery from that result. Do not emit a separate answer body, answer-only result, future Artifact/Section landing, or post-layout actualization.
 
@@ -50,3 +76,38 @@ coverage, preserve the source-backed content and improve its presentation
 rather than deleting it.
 
 Do not return output paths, collection names, arbitrary question text, new authority, or pass/fail claims.
+
+## Notes and conversation summaries as supporting material
+
+Use only the authorized excerpts or summaries and cite the material actually
+read. Distinguish quotations, paraphrases, confirmed decisions and proposals;
+write the explanation useful to the reader instead of copying the source.
+Keep claims within what the captured documents establish. A summary may record that participants reported an implementation or a passing
+test; attribute that report and retain its stated version and scope. Do not
+present it as independently verified in this task. Claims of direct validation
+need the actual relevant code, execution or test results in the authorized
+material. Discussion or a plan alone does not establish completion.
+
+Keep this Provider responsible for the existing page. If the host selects a
+Note/Sessions or business Provider extension, apply its supplied instructions
+to the same writing task. Do not load an unselected skill or create a second
+page solely because supporting material has a different source type. An
+independent reader task can use a dedicated Provider selected by the host.
+
+If the source is inaccurate, return the correction to the host source-input
+flow; do not edit it from the Indexer. If only the knowledge is misleading,
+revise the page from its approved text through Author/Review. Keep source
+associations in the source and page/section references in structure.yaml;
+do not add provenance fields to the knowledge header.
+
+## 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.
+
+## Reading selected article material
+
+Use the current task's combined writing brief: it includes selected article guidance, examples when supplied, and section/variable slots. Profile bindings can share one article Markdown source; do not open every binding or regenerate every listed article. Keep short collaboration notes and examples beside the relevant guidance instead of requesting separate files. Read extra source or full technical contracts only when this task needs them. The CLI applies executable contracts and evidence bindings; the Agent decides applicability, substance and useful diagrams. Reuse an already-read unchanged shared resource while it remains in context.

package/indexers/bundles/context-markdown-indexer/references/semantic-planning.md

@@ -9,7 +9,11 @@ second review workflow. Context remains the authority for schemas, SubjectKey
 normalization, identities, paths, collisions, stale state, layout changes,
 Review, and publication.
 
-## `reader-subject` partition strategy
+## Reader-subject grouping
+
+The rules below are the grouping guidance for the current document View.
+Context handles strategy selection, ordering, retry, and catalog fallback;
+do not retrieve a separate strategy definition or submit strategy metadata.
 
 For a partition workset, group captured document members by durable reader
 subject rather than by file, heading, route, or temporary capture batch. Use
@@ -17,6 +21,17 @@ the complete authorized document text together with maintained title,
 `source_path`, route, audience, and reader-task evidence. These fields are
 evidence for the decision; none is sufficient by itself.
 
+Choose readable, durable subject names during Partition. Context's main-page
+path uses the subject namespace as the directory and local key as the basename;
+the group's key and authored title do not rename it. When the default namespace
+is a capture ID or opaque source token, use the existing explicit subject object
+with a source-supported product/platform namespace and topic key, such as
+`sample-web` / `faq`, under a permitted kind. Do not repeat the source token in
+both path segments or use random/hash suffixes to resolve collisions. Keep an
+existing subject and its approved path on updates; a title edit alone does not
+create a new identity. Review the proposed subject and final reader path, not
+only the page title. Context handles path normalization and layout confirmation.
+
 One group may contain multiple documents when they jointly explain the same
 reader subject. Split platform or runtime variants only when their supported
 contract, behavior, lifecycle, or reader task is materially different. Keep
@@ -24,8 +39,8 @@ navigation-only indexes, generated duplicates, empty placeholders, and
 superseded pages out of authored groups with an explicit inventory
 disposition. Every current inventory member must still receive exactly one
 partition disposition. If durable subject boundaries cannot be established,
-fail this semantic strategy so Context can use its existing catalog fallback;
-do not silently return one group per file under `reader-subject`.
+return a failed Partition Result explaining the missing boundary evidence so
+Context can choose the next attempt. Do not silently substitute one group per file.
 
 ## Evidence and authority
 
@@ -46,17 +61,16 @@ only because its path contains `ops/`.
 
 ## Subject boundary
 
-The primary logical-unit SubjectKey is fixed by the workset. Do not replace it
+For Author, the primary logical-unit SubjectKey is fixed by the workset. Do not replace it
 with a title-derived key. When Context supplies target-resolution entries,
 close every entry with exactly one current disposition:
 
 - `reuse-existing` only for an exact evidence-supported subject match;
 - `create-independent` only when evidence establishes a distinct durable
   subject and separate reader value under a permitted SubjectKey schema;
-- `request-material` when a semantic decision is possible but identity facts
-  or authority are insufficient;
-- `unsupported` when the required parser, evidence kind, or capability is not
-  available.
+- `unresolved` with a `reason_code` when the supplied material cannot establish
+  identity or the required capability is unavailable. `request-material` and
+  `unsupported` are whole-Result outcomes, not target-resolution dispositions.
 
 Treat local material as a Section before proposing an independent subject or
 Artifact. A heading, table row, FAQ label, warning, short example, relationship

package/indexers/bundles/context-markdown-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-markdown-indexer/templates/articles/c01.md

@@ -0,0 +1,37 @@
+---
+id: context.article.c01
+kind: procedure
+media-type: text/markdown
+program:
+  article: c01
+  policies:
+    - standard
+  sections:
+    scope: 定位与边界
+    capabilities: 核心能力
+    dependencies: 技术与依赖摘要
+    index: 知识索引
+    tasks: 任务导航
+    sources: 来源与适用版本
+---
+
+# C01 模块／知识入口
+
+This is a writing blueprint, not a completion gate. Adapt the headings and level of detail to the reader, evidence and language. Missing or additional chapters and ordinary version differences are advisory. Preserve real source coordinates and a useful next investigation step.
+
+适用：应用、服务、组件库、业务域或产品资料的主入口；具体对象的专业章节由对应模板补充。产出为普通知识文章，文件不必叫 SKILL.md。
+
+建议章节：
+
+1. **定位与边界**：解决什么任务、覆盖哪个产品／资料范围或仓库／模块、适用条件。
+2. **核心能力**：按业务任务归组，链接到已存在的文章或具体代码入口。
+3. **技术与依赖摘要**：仅在有技术材料且影响读者选择入口时出现；纯产品资料不强制此节。
+4. **知识索引**：主题、何时阅读、目标文章／代码位置。
+5. **任务导航**：开发、接口对接、排障、交付分别从哪里继续。
+6. **来源与适用版本**：文档身份／定位与适用版本；代码材料记录仓库、模块路径和证据版本。
+
+最低产出：对象身份、可信资料／起始文件／注册点和下一步阅读位置。浅索引模块可作为父级表格中的记录，不强制单页。禁止链接到尚未产出的模板占位文件。
+
+## 图示选择
+
+目录用 text 树；仅有已证实跨模块关系时在概览补 flowchart LR。 图放在对应解释章节，图前说明目的与范围，图后给来源和继续位置；按已下发的共用图示指导编写，无增益时省略，不增加独立必填章节。