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

package/plugins/skills/context-indexer-create/references/guides/indexer-skill-creation.md

@@ -1,99 +1,109 @@
 # Creating a reusable Indexer Skill
 
-A Provider is a portable Skill bundle. Workspace-local customization changes a
-selected Provider for one workspace; it is not the packaging format for a new
-Provider. Start from the source interpretation and reader task, then choose
-primary replacement or an advertised extension.
-
-## Package and protocol
-
-A typical instruction-only bundle contains:
-
-```text
-context-example-indexer/
-  SKILL.md
-  context-indexer.yaml
-  references/indexer.md
-  references/writing.md
-  templates/reader-guide.md
-```
-
-The name is illustrative. Use a discoverable context-…-indexer… name and an
-explicit Provider identity/version. SKILL.md describes when the lifecycle may
-select it; context-indexer.yaml declares context.indexer.provider/v1, domains,
-activation, profiles, operations and resources. Instructions and templates must
-be declared for the profiles using them. Do not copy unused profiles, composers
-or resource paths. Do not add a provider manifest to the creation assistant itself.
-
-Start from the [minimal manifest](indexer-manifest-example.md), which gives the
-field tree in three groups: required, required once a capability is declared, and
-optional. Read the [protocol](../reference/indexer-provider-protocol.md) for the
-subsystem rules behind those fields — selection validation, partition authority,
-overlays, controlled invocation — and the [selection
-guide](indexer-provider-and-customization.md) for composition.
-The four built-in examples are context-code-indexer, context-markdown-indexer,
-context-note-indexer and context-sessions-indexer. The latter two are independent
-source interpreters using markdown-domain contracts. Use their source-specific
-references instead of making a Markdown Provider accept everything.
-
-## Find a real example
-
-If Context CLI is available, inspect `context indexer catalog --format json`.
-Use the selected entry's guidance.skill_path and guidance.manifest_path to locate
-its bundle; read only that example and its declared resources. Alternatively use
-an exact Host-exposed installed Skill. Do not guess cache paths. This read-only
-catalog use is for Provider development, not a new production discovery gate.
-
-Choose one profile and follow its manifest references through instructions and
-template to its declared results. A code example demonstrates parser facts and
-public APIs; a document example demonstrates evidence-based consolidation;
-a note example demonstrates excerpts versus summaries; a sessions example
-separates decisions, rejected proposals and optional change associations.
-Adapt behavior, not only names. The example's breadth is not a minimum feature
-requirement for a specialized Provider.
-
-## Validate against the installed SDK
-
-Use the matching SDK's public exports. For community installations the package
-is @c4a/context; for an internal distribution use its supplied SDK coordinates.
-With the SDK available, this Node ESM check validates the manifest and declared resource paths:
-
-```js
-import { loadIndexerProviderManifest } from '@c4a/context';
-const manifest = await loadIndexerProviderManifest(process.argv[2]);
-console.log(manifest.id, manifest.version);
-```
-
-The argument is the Skill bundle directory. This check does not establish that
-all resources are usable or that the Provider can produce useful pages. Check
-all declared resource paths stay within the bundle and exist; validate templates
-with the SDK template loader and their declared profile contracts. Consult the
-installed exported signatures before writing the runner: do not invent a CLI
-validate command or fabricate a production Route to run a development check.
-
-Template protocol is context.indexer.template/v1. Semantic prose and deterministic
-Facts have separate variables; registered renderers own program blocks. A
-Provider cannot invent a renderer or an arbitrary document kind. Use supported
-profile/artifact contracts or the existing declared overlay mechanism.
-
-Use anonymous fixtures that demonstrate the advertised source interpretation:
-one useful result, material that cannot support a claim, and an existing-page
-update. Test primary/extension ownership only if that composition is advertised.
-Test the complete selected bundle in a disposable workspace through the normal
-lifecycle when the necessary CLI and materials are available. Preserve the
-user's live workspace. Record exact commands and failures; clearly distinguish
-schema/resource checks from semantic review and lifecycle verification.
-
-## Distribution and use
-
-Keep references and templates inside the bundle, with portable relative paths.
-The complete runtime file ledger determines integrity; do not hand-write a hash
-or copy another bundle's integrity. Use the target distribution's existing
-packaging/resolution tools. Development fixtures need not be shipped as runtime
-resources. Installation may use any supported organizational channel.
-
-A business Provider may be enabled through the host and selected instead of the
-default. Prefixes aid discovery; the manifest and verified resources determine
-compatibility. Select through the current Context Provider-selection Route when
-the user requests actual use. No new CLI install registry or creation-specific
-production state is needed.
+An Indexer is source-specific investigation and writing guidance. It helps the
+Agent understand authorized material and produce useful articles; it does not
+own workflow routing, source authorization, review or permanent article identity.
+Several skills may contribute to one module or article.
+
+## Minimal package
+
+Start with SKILL.md. Add references for substantial source-specific guidance,
+templates when they help readers, and scripts only when a concrete repeated
+operation needs deterministic assistance. A simple note interpreter needs no
+script, manifest, profile registry or template catalog.
+
+Use a discoverable name and a precise description. State when the skill helps,
+which sources it understands, and real limits. Refer to bundled resources by
+portable relative paths. Use an existing host-visible Indexer as a behavioral
+example, not as a collection of fields to copy.
+
+Do not generate context-indexer.yaml, an exact-version selection ritual,
+integrity receipts, primary/extension ownership, article producer records or
+a per-member disposition protocol. A release may have ordinary package
+metadata; that is not a requirement for the Agent to verify before working.
+
+## Investigation produces a skeleton
+
+Explain the recognizable source signals and how to examine them cheaply.
+For code, identify useful feature families from declarations or registrations,
+with names and locations. A dependency or filename is a hint, not proof of
+runtime behavior. For documents, use titles, opening excerpts and heading
+hierarchy, with optional full reading to settle grouping. For saved notes and
+sessions, directly interpret the provided record rather than scanning history.
+
+A technology-specific helper, if needed, must have an explicit input boundary,
+bounded time/output and a useful stopping behavior. Return names, counts and
+entry locations, not source bodies or a full symbol/relationship graph during
+planning. Distinguish checked counts from totals and identify unfinished scope.
+Do not fabricate feature counts from file counts or silently treat timeouts as
+empty results. Store large results in temporary files rather than long stdout.
+
+Document any prerequisites and error recovery. Do not install dependencies,
+parse the whole repository or read unrelated modules by default. A helper that
+needs expensive semantic analysis belongs to selected writing tasks, not the
+initial investigation path. Direct Agent investigation is a valid default
+when a helper adds no useful capability.
+
+## Guide topics without owning the plan
+
+Describe which reader questions visible signals can suggest, and what further
+evidence the writer needs. A route family, component or storage boundary may
+justify a recurring outline, but not an automatic fixed number of pages.
+A component manual may require individual analysis during writing.
+
+Use existing article titles, descriptions and references as navigation, then
+read relevant bodies or sources when necessary. Code can establish structure;
+documents may supply better business topics. Multiple authorized sources may
+form an article. Avoid duplicating a page merely because another skill or
+source family supplied its material.
+
+The current stage provides available-skill declarations and temporary planned
+usage. The Agent selects useful skills and article batches. Keep uncertain
+investigation and real evidence gaps visible. Required scope cannot be dropped
+to reduce processing cost, and long-term exclusions require the applicable
+user decision.
+
+## Writing and file handoff
+
+Explain source authority, meaningful reader output, real references and
+revision behavior. Keep examples, assumptions and confirmed facts distinct.
+A session summary is not a transcript; a change URL is not proof of deployment;
+a declaration or test double is not independently verified runtime behavior.
+
+Consume the current task directory, not a copied schema from a past release.
+New articles use the supplied Markdown/reference contract; revisions can use
+the task's base article and fragment edits. Write drafts and manifests to the
+designated Agent temporary directory. The coordinator submits a finished
+subset through the current CLI action and follows its receipt or recovery.
+
+Do not write formal knowledge or mutate sources directly. Do not add a
+parallel Author/Composer result envelope, semantic graph, field-by-field fact
+ledger or skill identity to formal content. Source permissions, input
+baselines, real citations and safe writes remain CLI responsibilities.
+
+## Validate the claimed capability
+
+Check skill frontmatter and every referenced local resource. Run new scripts
+against small anonymous fixtures, including an empty input, a bounded partial
+scan and any failure/recovery behavior they claim. Confirm the helper does not
+escape its selected scope or emit secret/source-body dumps.
+
+Exercise useful output, insufficient evidence and a revision of an existing
+article. For source families advertised by the skill, include representative
+differences: an unadopted proposal, a document requiring optional deeper reading,
+or two technologies in one module. Do not claim support for families not tested.
+
+A static resource check does not prove semantic quality, and a reviewed example
+does not prove the CLI submission works. If an actual Context run is available
+and requested, validate through the existing workflow in an isolated workspace,
+including report confirmation and file submission. Report unavailable checks
+honestly; do not fabricate a route or silently install tools to make it pass.
+
+## Distribution
+
+Keep the package portable and use the user's chosen installation channel.
+The host lists available skills; planning records only useful temporary usage.
+Formal articles, sources and necessary long-term scope decisions survive a
+new machine. Unfinished drafts, candidates, skill choices and execution receipts
+remain temporary; a new user can start a fresh production run without restoring
+the former skill bundle or process.

package/plugins/skills/context-markdown-indexer/SKILL.md

@@ -1,36 +1,32 @@
 ---
 name: context-markdown-indexer
-description: Context-managed Provider for source-grounded document knowledge. Use only when the Context Indexer lifecycle selects this Provider, not as a standalone workflow.
+description: Investigate captured document outlines and write source-grounded Context articles. Use when selected for the current authorized planning or writing task, not as a standalone import workflow.
 metadata:
   context-role: "indexer-provider"
   context-public-entry: "false"
-  context-provider-version: "1.1.3"
 ---
 
 # Context Markdown Indexer
 
-Provider authors must satisfy
-`node_modules/@c4a/context/docs/guides/markdown-indexer-skill-authoring.md` and
-the shared Provider/customization guide before publishing or extending this
-Skill. Those documents are authoring contracts; the current captured evidence,
-workset and Route remain execution authority.
+Use the current stage's reader purpose, authorized sources and submission schema.
+Read [planning](references/semantic-planning.md) during investigation and
+[writing](references/indexer.md) when writing. Consult
+[reader outcomes](references/classification.md) or
+[article boundaries](references/structure-and-artifacts.md) when the material
+raises a real grouping choice. Do not read every catalog or template by default.
 
-Use this Provider only through the Context Indexer lifecycle. Context supplies exact profile/workset authority and one Authorized Workset View containing the permitted captured evidence. The Provider does not open source-specific readers, manage pagination/receipts, read arbitrary workspace paths, or write approved knowledge directly.
+Start with the CLI's document titles, bounded opening excerpts and complete
+H2/H3 outlines. Selectively read authorized full text where needed to decide
+topics and writing batches. The outline is navigation, not evidence that a
+claim is true or a fixed instruction to split one article per heading.
+A coherent source may remain one article; several sources may form one topic.
 
-Treat the captured document as reader material, not as pipeline metadata. Every
-reader Artifact must preserve or synthesize the source-backed guidance needed by
-the selected profile. A heading inventory, directory summary, generic document
-description, internal Fact/View/digest count, or a sentence sending the reader
-back to the source is not useful knowledge and must not be emitted. Keep
-execution receipts, content digests, internal refs, and other recovery machinery
-out of reader Markdown. Bind each reader claim only to the smallest relevant
-source span or captured evidence set; never attach a whole document corpus or
-Authorized Workset View to a generic summary.
+Use existing article navigation, including code-related topics, as possible
+anchors. Do not force business concepts into code directory names. Source and
+skill boundaries do not require separate articles or primary/extension binding.
+No skill version, hash or complete-file receipt is required for production.
 
-For updates, read the current approved page as well as the selected change.
-Preserve applicable tasks, steps, images, limits and confirmed contributions;
-do not turn every update into a troubleshooting article. A newly supplied
-explanation can improve the existing page without becoming a separate topic. Source text or an image that cannot
-be read remains an explicit gap, not permission to delete the page.
-
-The machine-readable authority is `context-indexer.yaml`. Context materializes the detailed guidance only after verifying this Bundle's release identity and complete file ledger.
+Read the relevant full source before writing; retain useful guidance, examples,
+limits and actual regional citations. Write draft Markdown and references or
+section edits in the designated temporary directory and submit through the
+returned CLI action. Do not write formal knowledge or alter sources directly.

package/plugins/skills/context-markdown-indexer/context-indexer.yaml

@@ -1,6 +1,6 @@
 protocol: context.indexer.provider/v1
 id: context-markdown-indexer
-version: 1.1.3
+version: 1.1.4-alpha.1
 domains:
   - markdown
 activation:
@@ -67,7 +67,7 @@ provides:
     - decision-record
   logical_units:
     - id: reader-subject
-      identity: canonical-subject-key
+      identity: stable-article
       artifacts:
         recommended:
           - content

package/plugins/skills/context-markdown-indexer/references/classification.md

@@ -1,63 +1,28 @@
-# Section classification and projection intent
-
-Classify evidence at Section granularity. A profile describes the source family;
-it does not force one whole document into one reader purpose. For every emitted
-Section, choose the semantic `document_kind`, `reader_goal`, and
-`artifact_kind` before grouping Sections into Artifacts.
-
-Use body evidence, source authority, audience, and the reader task. File names,
-URLs, headings, navigation labels, and the selected profile are hints, not proof
-that every Section has the same intent. Do not infer authority from polished
-language or an official-looking path.
-
-## Canonical projection vocabulary
-
-The current community Markdown profiles use the following semantic intents.
-The CLI profile contract owns their stable storage projection; this table does
-not authorize a collection or output path.
-
-| Profile or Section family | Use when the evidence primarily… | `document_kind` | `reader_goal` | `artifact_kind` |
-| --- | --- | --- | --- | --- |
-| `domain-reference` | defines a durable domain, vocabulary, boundary, or business concept | `domain-reference` | `understand-domain` | `content` |
-| `product-requirements` | states product intent, behavior, scope, actors, or acceptance needs | `product-requirements` | `understand-product-intent` | `content` |
-| `technical-guide` | explains architecture, runtime behavior, interfaces, or design constraints | `technical-guide` | `understand-technical-design` | `content` |
-| user/developer product guidance | explains a user-visible capability or product behavior | `product-requirements` | `understand-product-intent` | `content` |
-| user/developer technical guidance | explains implementation-facing design or integration context | `technical-guide` | `understand-technical-design` | `content` |
-| user/developer task guidance | gives a repeatable task, setup, operation, or troubleshooting sequence | `task-guide` | `complete-reader-task` | `content` |
-| public API contract | supports lookup of public operations, fields, compatibility, or examples | `public-api-reference` | `look-up-public-contract` | `content` |
-| public contract policy | states normative compatibility or usage constraints around a public contract | `public-contract-policy` | `follow-public-contract-policy` | `content` |
-| `runbook` | directs operation, diagnosis, mitigation, recovery, or rollback | `runbook` | `operate-or-recover-system` | `content` |
-| `faq-support` | answers a durable reader question with reusable evidence | `faq-support` | `resolve-reader-question` | `content` |
-| `standard-policy` | defines a stable rule, standard, policy, or compliance boundary | `standard-policy` | `follow-standard-or-policy` | `content` |
-| `decision-record` | records alternatives, a choice, rationale, and consequences | `decision-record` | `understand-decision-and-tradeoffs` | `content` |
-| `incident-review` | records impact, timeline, cause, response, and follow-up learning | `incident-review` | `learn-from-incident` | `content` |
-| `test-validation` | defines or reports verification, acceptance, or observed results | `test-validation` | `verify-behavior-or-acceptance` | `content` |
-| release explanation | explains what changed, compatibility, or release impact | `release-guide` | `understand-release-change` | `content` |
-| migration procedure | tells a reader how to migrate, verify, and recover | `migration-guide` | `complete-migration` | `content` |
-
-`documentation-site` is an umbrella router. Apply the matching row above to
-each source-backed Section; do not invent a site-wide projection intent and do
-not collapse a multi-document site to one classification.
-
-## Classification order
-
-1. Establish the Section's current source authority and audience from the
-   authorized evidence view.
-2. State the concrete question the Section enables a reader to answer or task
-   it enables them to complete.
-3. Choose the narrowest matching `document_kind` and `reader_goal` pair from
-   the current profile contract.
-4. Use `artifact_kind: content` for the current community Markdown Bundle. Do
-   not invent a specialized Artifact kind unless the supplied profile contract
-   explicitly registers it.
-5. Return the intent on every actual or template-projected Section. Do not put
-   a collection, directory, filename, or package root in the Result.
-
-When a Section mixes multiple reader tasks, split it along continuous evidence
-boundaries. Keep one Section only when the material forms one coherent answer
-for one reader goal. A heading change alone does not require a split, and a
-shared heading does not justify combining unrelated tasks.
-
-If no registered intent fits, return a material/capability disposition instead
-of selecting the nearest label. Unsupported or authority-ambiguous material
-must not become a reader Artifact.
+# Choose a useful reader outcome
+
+Use the content, audience and reader question, not a required classification
+tuple for every section. The current plan schema supplies supported output
+paths; article title and description belong in its Markdown.
+
+| Reader need | Useful form |
+| --- | --- |
+| Understand a term, boundary or business rule | Domain explanation with scope and examples |
+| Understand intended product behavior | Requirements and acceptance conditions, distinct from implementation |
+| Understand architecture or integration | Technical explanation, contracts and relevant limitations |
+| Complete a repeatable task | Guide with prerequisites, actions and checks |
+| Look up a public interface | Contract reference with actual parameters and examples |
+| Diagnose or recover | Runbook with symptoms, safe actions and verification |
+| Understand a choice | Decision, alternatives, rationale and consequences |
+| Learn from an incident | Impact, observations, causes and response, separating hypotheses |
+| Interpret a test | Method, scope and what the observed result establishes |
+| Follow a rule or migrate | Normative boundaries or migration steps, compatibility and recovery |
+
+These forms guide writing; they are not profile registrations or fixed
+templates. One useful article can contain related explanations, procedures and
+examples. Split only when distinct reader tasks require it, not because two
+sections would previously have had different projection labels.
+
+Do not turn a document site into one generic summary or every note into a FAQ.
+An unfamiliar topic or imperfect stock outline is not a missing capability.
+Ask for essential missing material; otherwise preserve bounded uncertainty
+and write what the authorized source actually establishes.

package/plugins/skills/context-markdown-indexer/references/editorial-policy.md

@@ -92,5 +92,5 @@ Protected-value and reference checks remain mechanical safeguards.
 - Struck-through text that is the only surviving historical record may be kept
   when it has continuing reader value; no signal-specific receipt is required.
 
-Before returning a decision, confirm every Section has one outcome and no
-revision accidentally changes authority, evidence, identity, or protected values.
+Before submitting, check that the revision preserves authority, evidence,
+identity and protected values. Do not submit an outcome ledger for every section.

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

@@ -1,113 +1,57 @@
-# Markdown Indexer authoring contract
-
-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
-judgment, relation and structured-claim gates, content-purpose precision, and
-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 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.
-
-When a captured document already contains coherent reader-facing guidance, preserve and organize that supported content instead of replacing it with a heading inventory, directory summary, or a sentence that points the reader back to the source. Summarize only repetition or navigation scaffolding. A shorter Artifact is acceptable only when it still answers the selected reader questions and retains the source's useful contracts, examples, conditions, compatibility notes, and uncertainty.
-
-For each reader Artifact, start the first actual Section with exactly one
-level-one heading that names the reader subject. Keep the heading concise and
-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, 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.
-
-Return all knowledge through the current Indexer result; do not create an independent authoring pipeline.
-
-## Quality guidance and production checks
-
-Context blocks only conditions it can derive from current inputs: the complete
-source inventory needs dispositions, the selected reader-question set needs a
-complete plan, answered questions must satisfy their evidence contracts, and
-references, layout and currentness must remain valid.
-
-Profile metrics are writing guidance rather than a separate pass decision.
-They point out duplicated facts, enumeration where explanation was expected,
-repeated template scaffolding, oversized quoted bodies, traversal-ordered
-Partitions, reference-only targets and unsupported optional Artifacts. Treat a
-finding as a prompt to reread the Section. Do not adjust wording, headings,
-sentence counts or Partitions merely to move a counter.
-
-Natural-language statements are not mechanically checked sentence by sentence.
-Use only behavior stated by the supplied material, record a material gap when
-the source does not establish a needed conclusion, and rely on final Review to
-reject unsupported interpretation. When shape guidance conflicts with source
-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.
+# Write source-grounded document knowledge
+
+Read the relevant full source, not only the planning outline. Keep the
+confirmed reader purpose visible: a how-to guide, FAQ and design explanation
+serve different needs even when they cite the same code.
+
+Preserve or synthesize the useful guidance in the source: actual steps,
+contracts, conditions, examples, compatibility limits, images and uncertainty.
+An inventory of headings, a generic summary or a link back to the source does
+not replace an article that answers the reader. Preserve exact commands,
+identifiers, numbers and destinations where they matter; do not reproduce
+secrets or incidental conversion metadata.
+
+Use [editorial guidance](editorial-policy.md) for a concrete presentation
+problem. It is advice for the Agent and user, not a signal-clearing protocol or
+a CLI prose-quality score. Legitimate code, templates and historical details
+must not be removed merely because they resemble a placeholder.
+
+## File submission and references
+
+Write a complete new article using the current stage's Markdown and reference
+file schema. For an existing article, use its supplied base and submit only
+needed section edits when appropriate. Stable section markers and title and
+description follow that schema; there is no ArtifactResult, subject identity
+or profile-owned output mapping to assemble.
+
+For each output fragment, cite the actual source regions used, at most three
+locations. Use source_ref and an inclusive file/line locator; the CLI computes
+content digests. Do not attach an entire corpus to a generic paragraph or
+combine unrelated locations into a fabricated continuous span. Split genuinely
+distinct explanations when they need distinct references.
+
+Place drafts and manifests in the Agent's designated temporary directory.
+Submit completed tasks or a finished subset using the returned action. Do not
+pass long article bodies in shell arguments, write approved knowledge directly,
+or store skills, process receipts or separate provenance lists in article
+frontmatter. Acceptance saves this run's candidate; Review and formal delivery
+remain separate.
+
+## Supporting notes and sessions
+
+Use only authorized saved material and cite what was actually read. Separate
+quotations, paraphrases, proposals, confirmations and reported test results.
+A discussion can explain rationale but does not independently establish that
+a change merged, deployed or passed tests. Several selected skills may help
+the same article; no primary/extension ownership is required.
+
+Correct misleading knowledge through a revision. Correct an inaccurate source
+through its authorized import flow, not by editing evidence from this skill.
+Keep useful prior contributions and real gaps visible during updates.
+
+## Visual material
+
+Use [diagram guidance](diagrams.md) when it clarifies an important relationship.
+For actual source images or tables, read [visual processing](visual-source-processing.md).
+Preserve source strength and external boundaries; diagrams are not a completion
+requirement. Follow the workspace's visual conventions.