@c4a/context-cli 0.7.4 → 0.7.8

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

@@ -0,0 +1,180 @@
+# Code Indexer Skill authoring
+
+This guide defines the release checklist for a Code Indexer Provider Skill.
+It does not reproduce Context's internal Agent Graph lifecycle. The Provider
+receives validated requirements, scopes, worksets and evidence views and
+returns only its declared structured Results/fragments.
+
+## Minimal package
+
+Use one `context-indexer.yaml` with protocol
+`context.indexer.provider/v1`. Give the Skill a SemVer version and publish the
+complete Bundle with a reproducible integrity digest. Instructions, templates,
+fixtures and portable program entries live below the Skill root. Do not invent
+source-specific manifest names or a second schema tree.
+
+Programs use a structured `runtime: node`, portable `entry` and literal `args`.
+They never use a free-form command. A detector only reports activation signals;
+an inspector only returns bounded evidence/enrichment. Neither is a hard-gate
+authority. CLI profile contracts and verified data-only overlays own mechanical
+rules, metric operators and thresholds.
+
+## Author contract checklist
+
+For generated API tables, test the final Candidate as well as the parser payload
+and template preview. Cover direct and supporting references, partial contracts,
+shared types with different implementation defaults, ambiguous or cross-file
+links, and an approved-page regeneration after the source changes. Keep a known
+field when only part of its implementation can be extracted. Do not equate an
+accepted result with a corrected page.
+
+Document what each supported language adapter actually establishes. Preserve
+written expressions without evaluating arbitrary code, distinguish declaration
+defaults from implementation defaults, and explain unresolved imports or types.
+Unknown material, an unsupported parse, and a renderer contradicting a known fact
+need different responses. Use existing material requests and repair routes;
+neither a new content-quality gate nor a Provider-specific retry ledger is needed.
+
+1. **Responsibility.** Classify supported code modules and produce evidence-
+   bound partitions, logical units, Artifact Bundles and Results. Do not own
+   source authorization, requirement approval, final review, CLI metrics or
+   package publication. Source-specific Note/Sessions layers may contribute
+   declared guidance to a code page; they do not become another primary or
+   turn a conversation's proposed change into implemented code behavior.
+2. **Manifest.** Use the sole `context-indexer.yaml` field tree. Bind domains,
+   profiles, operations/fragments, resources, source roles, logical units,
+   customization support and composition without duplicate aliases.
+3. **Resource composition.** Combine only declared programs, profile-bound
+   instructions, templates and optional detector/inspector resources. Omitted
+   capabilities remain unsupported; natural language cannot add them.
+   Put any Agent-executed grouping rules in those declared instructions or
+   templates so Context delivers them with the current View. A partition
+   strategy id or digest is not an instruction resource. Context selects and
+   records strategy attempts; the Agent returns semantic groups and dispositions,
+   without discovering strategy implementations or managing fallback order.
+4. **Activation and profiles.** Declare strong/supporting/negative signals.
+   Dependency names are candidates, not runtime proof. One module may combine
+   one primary profile with supporting/extensions and selected composers.
+5. **Sources and Artifacts.** Write for a reader outside the indexed module:
+   make responsibility, stable interfaces/entrypoints, handoffs and the core
+   state, failure, operation and source-of-truth facts needed for correct use
+   and attribution discoverable. Declare source roles and logical-unit intent;
+   select only CLI-registered Artifact kinds/policy variants. Keep logical unit
+   identity separate from physical Artifact count, and measure useful coverage
+   by answered profile questions rather than symbol or path counts.
+6. **Inventory protocols.** Close every input member with an explicit
+   disposition. Use stable aggregation, full-path example identity and
+   structured chain decisions; do not substitute page prose for inventory.
+7. **Metrics.** Reference registered metric ids as reader-quality guidance.
+   The CLI may report advisory observations, but a Provider cannot return a
+   pass, threshold, retry count, or risk-acceptance decision.
+8. **Revision boundary.** Hard contract or source failures block at their
+   owner. Reader-quality feedback reopens the same Author or Composer through
+   `context revise`; it does not create a metric retry ledger or risk Gate.
+9. **Reader questions.** Declare reusable question templates with stable refs,
+   target domains and allowed evidence contracts. Do not make a question id
+   globally unique to one SubjectKey group.
+10. **Inspector safety.** Accept only the versioned stdin request and bounded
+    authorized evidence view; emit strict JSON within limits. Never read the
+    repository, environment or network implicitly, and never expose raw
+    config values, secrets or unbounded stderr/stdout.
+11. **Base gates.** Do not reduce source scope integrity, identity, evidence,
+    requirement, disposition, reference-only or provenance gates. Provider
+    integrity identifies content; it does not grant pass authority.
+12. **Anonymous fixtures.** Cover at least a component library, Web app, API
+    service, SDK/library and runtime/worker with neutral paths and identifiers.
+13. **Release tests.** Validate the manifest/resource ledger, run positive and
+    negative fixtures, forward-test the complete Skill, pack it, reinstall the
+    exact artifact and compare Bundle bytes/digest.
+14. **Content ownership.** Public technology belongs in the community Skill;
+    company-wide infrastructure belongs in a separate namespaced Provider;
+    repository, service, team and business mappings belong in business/project
+    Providers. Community fixtures remain anonymous.
+15. **Marketplace layout.** Archives keep one top-level Skill directory with
+    `SKILL.md`, the manifest and referenced runtime resources. Exclude tests,
+    caches, credentials, local paths and Host-specific temporary manifests.
+16. **Material gaps.** Return a canonical question disposition in the same
+    main Result when required evidence is missing. Never render a gap as an
+    empty page or speculative prose. Registered Markdown or tool material may
+    enrich the same main indexing batch before Candidate generation; do not
+    create a separate answer operation, Candidate, checkpoint or Review. The
+    CLI projects allowed enrichment material into that same Authorized
+    Workset View; Providers must not reopen registered sources themselves.
+17. **Backend profiles.** Test neutral RPC/HTTP, Gateway, Event/function,
+    Cron/worker, sync/reconciliation, stateful service/storage and library
+    shapes. Local facts remain baseline when optional remote metadata is absent.
+18. **Versioning.** Use Skill/Provider SemVer, exact Provider pins and Bundle
+    integrity. Fixed dependencies require exact versions and resolved
+    integrity. `@context-indexer-origin` is required on workspace-local customization
+    files and grants no authority. It is not required on Provider bundle files.
+19. **Trust boundary.** Skill/manifest describes capabilities; the verified
+    Bundle supplies bytes; workspace customization supplies project deltas;
+    CLI contracts supply hard rules. Keep these four authorities distinct.
+20. **Requirement direction.** `IndexRequirementSet` constrains registry,
+    extractor and Result in one direction. Apply requirement/registry changes
+    through staged, digest-bound proposals and transactional apply; do not edit
+    a live registry around the Route.
+21. **Program and remote authority.** Programs must pass static policy and the
+    applicable trusted/sandbox authorization. Optional remote tools use a
+    versioned Host Action, exact source-bound request and readable receipt;
+    they never expand scope or perform writes.
+22. **End-to-end recovery.** Test discovery, exact Provider resolution,
+    content-addressed staging, controlled execution, Artifact/Evidence Result
+    validation and crash recovery. A resumed run reuses only complete accepted
+    records and never infers success from a partial receipt.
+23. **Customization ladder.** Preserve this order: Provider only → config →
+    instructions append → one template override → program extension →
+    restricted replace. Document the proof and exit condition at every step;
+    see [Provider selection and customization](./indexer-provider-and-customization.md).
+24. **Batch neutrality.** Write instructions for one semantic task and accept
+    that Context may transport several independent tasks in one Agent step.
+    Never derive identity, ordering, ownership or evidence scope from a task
+    key or batch position. Partition should decide consumer-facing ownership
+    from public anchors and unresolved material; detailed supporting Facts are
+    consumed in the bounded Author View rather than copied into every
+    Partition decision.
+
+The current Route delivers readable task material with goals and constraints
+first, followed by the authorized sources and facts. For behavioral explanations,
+read the complete source excerpts. Copy the displayed `source_items` into the
+section's `source_items`; use Fact references in `facts`, not as source items.
+Context resolves a text item's authorized source spans internally. Inventory
+identities and a repository reference do not identify section source material.
+These process-local excerpts are not new Facts or reader-page metadata. Do not
+reopen the repository or infer behavior from a locator alone when the supplied
+lines do not establish it. Batch size does not define a knowledge page boundary.
+
+Author task resources may point to one shared batch reading file. Read that path
+once, use shared material only for its listed task keys, and consider each task's
+own goals and source excerpts. Context shares identical material, not conclusions:
+prepare a separate result for each task and submit the `results[]` together through
+the current completion command. A retry includes the remaining tasks' material in
+full; no earlier batch file or additional reading command is required.
+
+## Result and composition rules
+
+Exactly one primary layer returns a complete partition/author Result for an
+operation. Pre-author extensions return only declared fragments and cannot
+change ownership, denominator or Subject identity. Post-author composers bind
+one current `PrimaryResultView` and return only a derived proposal fragment;
+an empty composer run still has a receipt. Composer selection is the
+intersection of registry selection, manifest declaration and current profile
+applicability, not array order.
+
+Use canonical SubjectKey schemas and the Context NodeRef formula. All selected
+Providers must reuse the same Node when the SubjectKey is equal. An
+enricher uses the supplied TargetResolutionView (`resolved`, `absent` or
+`ambiguous`) and never guesses identity from a title or path resemblance.
+
+Every Section uses the exact `document_kind`, `reader_goal` and
+`artifact_kind` tuple from the current profile's unique layout mapping. The
+Provider never returns a collection name; Context resolves the collection from
+that tuple and rejects missing or ambiguous mappings.
+
+## Publication gate
+
+Do not publish until the exact packed artifact passes manifest/schema
+validation, anonymous positive/negative fixtures, no-scope-expansion and
+secret-leak tests, deterministic Bundle reconstruction, exact-version install,
+controlled execution and forward tests. Publishing a new version does not make
+existing workspace pins current; workspace selection must re-resolve it.

package/plugins/skills/context-indexer-create/references/guides/indexer-manifest-example.md

@@ -0,0 +1,103 @@
+# A minimal Provider manifest
+
+This is the smallest `context-indexer.yaml` that validates. Start from it and add
+only what your bundle implements. Reading an installed Provider's manifest is
+still worthwhile for behavior, but do not copy its declarations wholesale: they
+describe that bundle's resources, not yours.
+
+```yaml
+protocol: context.indexer.provider/v1
+id: context-example-indexer
+version: 1.0.0
+domains: [markdown]
+activation:
+  target_kinds: [document-set]
+  required_signals:
+    - id: prose-source
+      description: The target contains prose a reader would consult.
+  supporting_signals: []
+  negative_signals: []
+provides:
+  profiles: [reader-guide]
+  operations:
+    - id: main-index
+      consumes: context.indexer.main-workset/v2
+      produces: context.indexer.main-result/v1
+provider:
+  instructions:
+    - path: references/indexer.md
+      profiles: [reader-guide]
+  templates:
+    - { id: guide, profile: reader-guide, path: templates/reader-guide.md }
+customization:
+  supports: [instructions-append, template-override]
+```
+
+The three groups below are the reason this file exists: a field being absent from
+a manifest means something different depending on which group it belongs to.
+
+## Required
+
+The schema rejects a manifest missing any of these.
+
+- `protocol`, `id`, `version` — the protocol literal, a discoverable Provider
+  identity, and a semver version.
+- `domains` — at least one. Note and Sessions Providers use `markdown`.
+- `activation.target_kinds` — at least one. This is projected into the Provider
+  selection catalog, so it decides when your Provider can be selected at all.
+- `activation.required_signals` — at least one `{ id, description }`.
+- `activation.supporting_signals`, `activation.negative_signals` — the arrays
+  themselves are required; an empty array is the normal value.
+- `provides.profiles` — at least one. A profile whose id contains `/` is a
+  namespaced extension profile and additionally requires a matching
+  `composition.extensions` entry.
+- `provides.operations` — at least one. `main-index` is the only operation.
+- `provider` — at least one of `program`, `instructions` or `templates`.
+
+## Required once you declare a capability
+
+Declaring a customization capability without the resource that implements it is
+rejected at manifest validation:
+
+- `customization.supports` containing `config` requires `provider.config_schema`.
+- `customization.supports` containing `program-extend` requires
+  `provider.program`.
+
+Both inconsistencies used to surface only at use time — a non-empty config while
+validating the selection, `program-extend` while preparing the customization
+project. Declare only the hooks your bundle actually backs; `instructions-append`
+and `template-override` need no additional resource.
+
+Two related rules hold for every resource. Each `instructions` and `templates`
+entry must name a profile that `provides.profiles` declares, and every declared
+path must exist inside the bundle. The reverse also matters: a reference file
+that no entry declares is never delivered to the Agent, so adding a file is not
+the same as making it available.
+
+## Optional, and not uniformly enforced
+
+These are accepted and carry authoring intent. It is worth knowing which ones
+have a consumer, because declaring a field is not the same as gaining a check.
+
+- `quality_guidance.metric_ids` and `quality_guidance.repair` — read when
+  projecting Provider contract references; the repair path ships as a resource.
+- `activation.agent_questions` — questions this Provider wants asked before it
+  interprets material.
+- `provides.partition_strategies`, `provides.logical_units`,
+  `provides.composers`, `composition.extensions` — declare only what you
+  implement. Priorities must be unique per profile, and a composer contract
+  requires a post-author `derived-artifact-proposal` layer fragment.
+- `provider.completion_checks`, `provider.forbidden_fallbacks` — the schema
+  accepts and deduplicates them, and no execution consumer reads them today.
+  Declaring them records intent for a reader of the manifest; it does not add a
+  runtime check, and omitting them does not remove one. Material gaps in
+  particular are handled by result reconciliation, which does not read
+  `completion_checks`.
+
+## Validate it
+
+Use the installed SDK, as described in [the authoring
+guide](indexer-skill-creation.md). `parseIndexerProviderManifest` accepts the
+manifest text directly, which is enough to confirm the field tree; loading the
+bundle directory additionally confirms that declared resource paths resolve.
+Neither establishes that the Provider produces useful pages.