@c4a/context-cli 0.7.8 → 0.7.10-alpha.1

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.