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

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

@@ -1,180 +0,0 @@
-# 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

@@ -1,103 +0,0 @@
-# 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.