rag-wright 0.8.0__tar.gz → 0.10.0__tar.gz

{rag_wright-0.8.0 → rag_wright-0.10.0}/.claude/skills/authoring-a-capability/SKILL.md

@@ -37,9 +37,13 @@ MCP) follows automatically for invokable kinds; 4b (a bespoke MCP server) is opt
 1. **Implementation** — the real code, in that kind's home (see per-kind below).
 2. **The invoke factory + `impl_ref`** (invokable kinds: subgraph/model) — write a co-located
    `async def ainvoke(resources, inputs)` (subgraph) / `def <name>(resources, inputs)` (model) in the capability's
-   own module. A subgraph factory builds over the opaque `WorkspaceHandle` (`resources._store`,
-   `resources._embedder`, `resources.model_id(role)`), never env; a model factory is store-independent and ignores
-   `resources`. The manifest's `impl_ref="module:attr"` points to it. The invoker imports
+   own module. A subgraph factory builds over the opaque `WorkspaceHandle`, never env: its store access with
+   `pack_store(resources, YourStore)` (your pack's store extension over the workspace's store) and its models with
+   `resources.model_id(role)`; its query embedder with `resources.embedder` (or `workspace_embedder(resources)`, its
+   `rag_wright.pack_sdk` twin; built from the workspace's embedding profile) and its options with `resources.config`; a model factory is
+   store-independent and ignores `resources`. A builder that takes the store as a keyword goes through `pack_store`
+   too: `pack_store(resources, lambda store: production_x(store=store, ...))`. The handle's underscored attributes
+   are engine-internal; the reference pack's factories show the public form. The manifest's `impl_ref="module:attr"` points to it. The invoker imports
    it LAZILY and calls it — there is **NO central adapter dict** (EP-CORE-2). A plain function/agent_skill/mcp_tool
    declares no `impl_ref`.
 3. **ARD manifest + register it** — a `CapabilityManifest(slug, kind, display_name, description,
@@ -57,8 +61,9 @@ MCP) follows automatically for invokable kinds; 4b (a bespoke MCP server) is opt
    A downstream product can register without touching the canonical set (`register_capability` does not check
    slugs), BUT `manifests.author()` rejects a non-canonical slug, so a product that publishes ARD JSON must call
    `register_canonical_slugs` for its slugs first.
-   Publish to `~/.air/registry` with `uv run python scripts/publish_manifests.py`; that script publishes only the
-   engine's reference pack (it calls `load_reference_pack()`), so a product publishes its own with `publish_all`.
+   Publish the ARD JSON (`urn:air`) of what is registered with `publish(slug, root=...)` or `publish_all(root=...)`
+   from `rag_wright.api` (the root defaults to `ARD_REGISTRY_ROOT`, else `~/.air/registry`); a slug must be canonical
+   (`register_canonical_slugs`, above). The engine's `scripts/publish_manifests.py` does this for its reference pack.
    Callable kinds get `ResponseBounds` (defaulted); `agent_skill` must NOT declare bounds (loaded, not called).
 4. **Invocable + MCP for free** — once registered with an `impl_ref`, the capability is callable as
    `ainvoke_subgraph(slug, inputs, resources=ws)` / `invoke_model(slug, inputs, resources=ws)` (or
@@ -79,7 +84,7 @@ MCP) follows automatically for invokable kinds; 4b (a bespoke MCP server) is opt
 - **Invoke:** the co-located `async def ainvoke(resources, inputs)` factory (impl_ref target) builds + awaits the graph.
 - Retry/dead-letter come from the graph scaffold, not the invoker. `CapabilityManifest` has no contract field (only
   the internal `CapabilityRegistry.register(contract=...)` takes one); where the typed I/O must be declared, set
-  `capability_interface` on the manifest.
+  `capability_interface` on the manifest (`CapabilityInterface`, from `rag_wright.pack_sdk`).
 
 ### function — a plain, typed callable
 - **Home:** `capabilities/<slug>.py` (generic) or `packs/<pack>/capabilities/<slug>.py` (domain). A deterministic or model-backed callable with a Pydantic in/out contract.
@@ -103,7 +108,9 @@ MCP) follows automatically for invokable kinds; 4b (a bespoke MCP server) is opt
 - **Home:** `skills/<slug>/SKILL.md` (generic) or `packs/<pack>/skills/<slug>/SKILL.md` (domain, e.g.
   `packs/compliance/skills/compliance_judgment/SKILL.md`) + the agent runtime (e.g. `skills/rlm/`). It is LOADED (progressive
   disclosure), not called: no `ResponseBounds`. Declare `requires=(...)` for a closure over other skills and
-  `skill_runtime` for its intrinsic runtime.
+  `skill_runtime` (`SkillRuntime`, from `rag_wright.pack_sdk`) for its intrinsic runtime.
+- A product's agent (a Deep Agents harness) is not a capability kind yet: an `agent` kind is a later engine workstream
+  (PS-33, engine ADR-0139). Build agents in the product, on `agent_chat_model` for their model.
 
 ### mcp_tool — a capability exposed over MCP
 - A distinct ARD identity (`<slug>_mcp`) for the same underlying capability exposed as a cross-agent MCP tool.
@@ -129,7 +136,7 @@ add it to `_RESERVED_WITHOUT_MANIFEST` with a one-line reason. The engine's `tes
 pack, so these tests see its slugs.
 
 **The import boundary (engine repo).** `pyproject.toml` `[tool.importlinter]` has three forbidden contracts: every
-generic engine package (`source_modules`: `rag_wright.api`, `capabilities`, `contracts`, `corpus`, `ingestion`,
+generic engine package (`source_modules`: `rag_wright.api`, `capabilities`, `contracts`, `corpus`, `evals`, `ingestion`,
 `models`, `ontology`, `pack_sdk`, `skills`, `spans`, `store`, `subgraphs`, `util`) must never import
 `rag_wright.packs`; pack code (`rag_wright.packs`) imports only `rag_wright.api` and `rag_wright.pack_sdk` (plus
 itself), never another engine package directly; and `rag_wright.packs.contracts` must never import