@c4a/context 0.7.9 → 0.7.10-alpha.1

package/docs/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/docs/guides/knowledge-updates.md

@@ -30,6 +30,20 @@ optional: preserve the original URL without falling back to body retrieval or
 changing credentials. Resolve intent from the conversation; refine provisional
 chapters and module boundaries from evidence after formal capture.
 
+## Agent-planned writing order
+
+Within the tasks available in the current Route, the Agent may choose a writing
+order from the reader's needs and relationships between topics. There is no
+fixed code-first or document-first rule. Prefer foundational concepts and shared
+terminology before walkthroughs or summaries that benefit from them, when this
+reduces rework. Independent topics can proceed without waiting; adjust the order
+as writing progresses instead of maintaining a separate scheduling artifact.
+
+This is an Agent working preference, not a new dependency or completion gate.
+Do not add dependency fields, fetch extra material, or delay useful work merely
+to establish an order. Keep current task boundaries, source permissions and
+submission rules; do not pull future batches forward or change the CLI Route.
+
 ## Workspace versions and changelog
 
 `package.json.version` is the workspace SemVer. At completed-scope delivery the
@@ -133,6 +147,13 @@ ordered `content` list of `{ "markdown": "new text" }` and/or
 selected section's source references remain intact. Use full Markdown when
 changing structure, adding a page or when a section has no unambiguous ID.
 
+To change a fragment's citations, include `references` alongside its `section_id`:
+each entry supplies `source_ref` and `locator` (`path`, `start_line`, `end_line`).
+Context computes the region fingerprint. This uses the same revision submission,
+with at most three source positions per fragment. Full Markdown may include a
+`sections` list of reference edits; local section edits may change content,
+references, or both. Omission preserves citations; an empty list removes them.
+
 For an optional check, append `--preview` to the current `action complete-current`
 command with the same revision and input file. It validates and returns the
 assembled page and previous text without accepting the edit. Submit the same
@@ -406,17 +427,17 @@ Indexer's read scope. Its `task adjust` scope also supplies the explicit
 `requirement_ref`. This extends the current page's available sources and keeps
 queued pages; it does not silently start another task or another Indexer.
 
-### Replacing supporting article identities
-
-When an upstream article is split, merged or removed, start `context revise` for
-its consumer and use `context task adjust --input - --format json` with
-`instruction` and `knowledge_dependencies: { dependencies }`. Each dependency
-uses an approved `artifact_ref`, optional `section_refs`, and `required` flag.
-The current Author input returns authorized replacement facts and their evidence.
-Repeat the adjustment with `knowledge_dependencies.sections`, selecting each
-retained `section_key` and its full `fact_refs` and `evidence_refs` support. Then
-revise the explanation and complete normal Review, close and build. An explicit
-empty dependency list removes the relationship only when remaining sections have
-valid direct support. Missing dependencies, changed approvals and invalid source
-references cannot silently become current evidence. Writing quality remains an
-Agent/Review decision; no chapter-count or wording gate is introduced.
+### Revising material reused from another article
+
+When a supporting article changes, revise the affected explanation using
+`context revise`. Read the relevant approved text and, where needed, its original
+sources. Keep direct source regions on the affected output fragments; do not
+recreate an article dependency graph or copy facts and evidence IDs.
+
+Revision section edits may supply `references` as `source_ref` plus a
+`locator` containing `path`, `start_line`, and `end_line`. Context computes the
+regional digest. Omitted references preserve the current fragment's citations;
+an explicit empty list removes them, and deleting a fragment removes its
+citations. Each fragment may cite at most three source positions. Register and
+authorize new material before citing it, then follow normal Review, close and
+build. Article links alone do not authorize reading new sources or prove a claim.

package/docs/guides/markdown-indexer-skill-authoring.md

@@ -1,136 +1,59 @@
 # Markdown Indexer Skill authoring
 
-Markdown Providers use the same `context.indexer.provider/v1` manifest,
-versioning, Bundle, requirement, trust, Result and customization contracts as
-Code Providers. Read the shared
-[Code Indexer author checklist](./code-indexer-skill-authoring.md) and
-[Provider selection/customization guide](./indexer-provider-and-customization.md)
-first. This page defines the boundary for captured file/Lark documents.
-Saved notes and conversation summaries use their dedicated Note/Sessions
-Providers, or an explicitly selected business replacement, on the same protocol.
-They reuse Markdown reading without a second capture phase. A Markdown page may
-still consume either as authorized supporting material; specialized extension
-guidance does not transfer primary ownership.
-
-## Capture before semantics
-
-Capture owns source authorization, retrieval, revision identity, complete bytes,
-Markdown/MDX parsing and evidence spans. A Markdown Indexer starts only from a
-current captured source report and authorized evidence view. URLs, titles,
-filenames, headings and capture success are activation candidates, not semantic
-classification or proof that the whole document was read.
-
-The Provider cannot fetch the document again, follow new links, rewrite source
-revisions or widen capture scope. Missing/unsupported capture capability is an
-explicit unsupported result, never a prose fallback.
-
-## Activation and source roles
-
-Declare document activation signals and map evidence-backed sources to declared
-roles such as authoritative, explanatory, operational, decision or example
-material. Keep role selection separate from collection placement. One document
-may support multiple reader questions, but every consumed span retains its
-source/revision identity and cannot be promoted to a stronger authority by an
-instruction.
-
-## Section projection and collection mapping
-
-Author Results propose logical Sections and their intent; they do not write
-`knowledge/` paths. Each Section binds:
-
-- the canonical SubjectKey/Node target or an explicit independent target;
-- its reader-question refs and exact evidence spans;
-- an Artifact kind and Section key stable across content-only changes;
-- a projection intent describing purpose, not a physical filename;
-- structured content layers and their digests.
-
-Context owns the closed mapping from profile/Section intent to collection and
-path. The layout resolver reuses an existing Artifact by stable identity,
-detects add/remove/rename/split/merge/move changes. Ordinary production reviews
-the proposed new structure before Author, including new topics in an update.
-Protected changes to an approved layout have their own human-only Gate; this
-is distinct from ordinary structure review and its managed delegation. A Provider cannot
-avoid that Gate by emitting a path or relabeling the change.
-
-## Reusing Code Nodes
-
-Use the supplied subject catalog and TargetResolutionView. Equal SubjectKeys use
-the same NodeRef across Code and Markdown. `resolved` enriches the existing
-Node; `absent` may create an explicitly independent subject or a material gap;
-`ambiguous` fails before authoring. Titles, heading similarity and filenames
-are never identity fallback. Unrelated catalog changes must not make a workset
-stale.
-
-## Artifact and Section planning
-
-One logical unit may produce an Artifact Bundle with multiple meaningful
-Sections or semantic split Artifacts. Do not use fixed-count, ordinal or
-alphabetic batches. Do not create one page per heading/member or inflate page
-count to satisfy a metric. The CLI owns Artifact-policy eligibility, physical
-fan-out audit, layout actualization and the final Candidate compile.
-
-The first actual Section of each reader Artifact begins with one concise,
-source-backed level-one heading. Context uses that heading as the outline and
-Candidate Review display title. It never participates in SubjectKey derivation
-or ownership, and later Sections in the same Artifact do not repeat it.
-
-Each Section carries exact positive and negative dependency refs. Incremental
-impact is Section/Artifact-local: a source membership, question denominator,
-candidate pool, evidence span or run-envelope change invalidates only the
-dependent scope. A Provider must not replace this with source-wide or
-collection-wide recomputation.
-
-## Editorial policy
-
-Editorial instructions may guide clarity, consolidation, ordering and
-reader-facing terminology. They cannot alter facts, evidence, source role,
-requirement scope, protected values, revision identity or collection authority.
-Deterministic blocks render only registered facts; semantic prose cites consumed
-evidence. The Agent or user assesses missing explanations, speculation and
-unfilled placeholders in the existing content Review. Context does not scan
-words, braces, comments or headings to reject content, and an editorial hint
-does not create another gate or require a signal-clearing receipt.
-
-## Missing material
-
-When current material cannot answer a required canonical question, return the
-exact material-question disposition for the supplied owner cell, question
-contract and Subject target. Do not invent a new question contract or landing.
-Context reports the unresolved set in current reconciliation state; it does not
-create a second checkpoint ledger or published gap artifact.
-
-Capture the missing Markdown or other source normally, then rerun `main-index`.
-The new Result updates the same knowledge Candidate and enters the same final
-content Review. There is no answer-only operation or evidence-specific Review.
-A blocking gap closes only through current source or an explicit non-delegable
-requirement change.
-
-## Bounded execution
-
-Each captured document remains an independently recoverable Partition input,
-but Context may transport several documents in one bounded Agent step. Return
-one result for every supplied task key and let global convergence merge
-documents that establish the same Subject. Batch order, filename order and
-heading order never create Subject identity. Author and Review use the same
-bounded transport rule without adding intermediate user approvals.
-
-## Markdown author fixture checklist
-
-Release fixtures should cover:
-
-- complete Markdown and MDX capture plus unsupported parser/capture paths;
-- authoritative reference, guide, runbook, FAQ, decision, incident, policy,
-  test and release/migration document shapes using anonymous content;
-- per-Section projection into every supported collection intent;
-- existing Code Node reuse, independent subject, ambiguity and material gap;
-- content-only reuse plus add/remove/rename/split/merge/collection/path/Section
-  move in both directions;
-- protected values, links, images/assets and source-span fidelity;
-- editorial positives and placeholder/speculation/unsupported negatives;
-- material-gap runtime recovery, main-index retry and no-output-leak;
-- Section-local incremental invalidation, new membership/denominator/candidate
-  pool changes and unaffected Section reuse.
-
-Source authorization, capture revision safety, canonical question/collection
-contracts, layout confirmation, review and build remain Context authority and
-cannot be replaced by the Skill.
+Use the shared [planning and writing guidance](./indexer-provider-and-customization.md).
+Document Skills help interpret captured articles; notes and sessions have their
+own guidance but can support the same reader topic. No unique primary owner,
+version lock or per-document disposition ledger is required.
+
+## Captured sources
+
+Start from authorized captured Markdown and its source identity. Capture proves
+which bytes are available, not what they mean. Titles, headings and filenames are
+navigation aids, not proof that the Agent has read the body.
+
+Do not fetch new documents, follow external links or widen source authorization
+implicitly. Request missing material through the current workflow. Keep the
+distinction between a source being unavailable and its contents being irrelevant.
+
+## Planning
+
+Read the supplied titles, bounded introductions and complete H2/H3 outlines.
+The Agent may read additional sections or the full document when needed, then
+chooses article targets and writing batches. Do not require full-body reading of
+every document or a separate planning submission for an already explicit target.
+
+Consult code topics and existing article descriptions and references. Reuse a
+topic when its reader question fits, or propose a clearer business topic instead
+of forcing a document under a code directory. One document may support several
+articles and several authorized documents may support one article.
+
+The final work-start report follows the relevant source overview and plan, and
+must wait for the user before bulk writing, including in managed mode.
+
+## Writing and repairs
+
+Read the actual passages needed for the article. Distinguish authoritative rules,
+examples, decisions and proposals; a session suggestion is not an implemented
+behavior. Write Markdown and references in the supplied temporary directory and
+submit the short stage-relative manifest. Title and description belong to the
+article, not an internal layout-mapping tuple.
+
+Keep stable article and fragment identities when revising. Each fragment cites
+at most three actual source regions. The CLI handles source digests and safety;
+the Agent judges whether the evidence supports the explanation. For a local
+failure, use the returned fragment identifier or position to repair the affected
+part. Completed independent tasks can be submitted without the rest of the batch.
+
+Do not inflate page counts, produce a page for every heading, or turn missing
+evidence into speculative prose. A genuine material gap remains unfinished work;
+an explicit exclusion uses the existing exclusion mechanism. Neither requires
+a new reconciliation ledger or additional content-review stage.
+
+## Useful fixtures
+
+Cover an ordinary one-to-one article, multi-document synthesis, reuse of an
+existing topic, fragment repair, source line changes, links and images, and
+missing material for the document forms the Skill supports. Verify both source
+fidelity and the final page. Keep examples anonymous and check packaged links.
+Drafts and scheduling details remain temporary; deleting `.tmp` starts fresh
+production from formal knowledge and available sources, not a workflow migration.