@arnilo/prism 0.0.4 → 0.0.6

package/docs/providers/zai.md

@@ -1,62 +1,85 @@
-# ZAI provider package
+# Z.AI provider package
 
 ## What it does
 
-`@arnilo/prism-provider-zai` provides explicit, side-effect-free setup for the ZAI GLM
-API-key provider using Prism's OpenAI-compatible route with the
-`thinkingFormat: "zai"` model-compat setting, developer-role fallback, and
-GLM tool-stream quirks.
+`@arnilo/prism-provider-zai` provides explicit, side-effect-free setup for the Z.AI
+GLM Chat Completions API (`POST /chat/completions`) with official deep-thinking,
+reasoning-effort, and tool-stream request fields.
 
-The package registers a provider, default model metadata, and an `api_key` auth
-method through `createExtensionKernel().load([...])`.
+The package registers a provider, featured GLM model metadata, and an `api_key`
+auth method through `createExtensionKernel().load([...])`.
 
 ## When to use it
 
-Use it when a host app wants to run the ZAI GLM endpoint through Prism's
-`AgentSession` runtime with ZAI-specific thinking/tool-stream handling.
+Use it when a host app wants to run Z.AI GLM models through Prism's
+`AgentSession` runtime with official `thinking` / `reasoning_effort` /
+`tool_stream` mapping and implicit context caching.
 
-Do not use it for automatic credential discovery, catalog fetches, or
+Do not use it for automatic credential discovery, setup-time catalog fetches, or
 real-network tests.
 
 ## Inputs / request
 
 ```ts
-import { createZaiProviderPackage } from "@arnilo/prism-provider-zai";
+import {
+  createZaiProviderPackage,
+  defineZaiModel,
+  listZaiModels,
+} from "@arnilo/prism-provider-zai";
 
 createZaiProviderPackage(options: ZaiProviderPackageOptions): ProviderPackage
-defineZaiModel(config: ZaiModelConfig): ZaiModelConfig
+defineZaiModel(config: ZaiModelConfig): ModelConfig
+listZaiModels(options?: ListZaiModelsOptions): Promise<ModelConfig[]>
 ```
 
 | Field | Type | Purpose |
 | --- | --- | --- |
 | `apiKey` | `CredentialValueSource` | Direct/callback/resolver API-key source. |
 | `fetch` | `typeof fetch` | Optional fetch implementation for tests/hosts. |
-| `baseUrl` | `string` | Overrides the ZAI base URL. |
+| `baseUrl` | `string` | Overrides the Z.AI base URL (default `https://api.z.ai/api/paas/v4`). |
 | `id` | `string` | Overrides the provider id (default `zai`). |
-| `models` | `readonly ModelConfig[]` | Overrides `zaiModels` defaults. |
+| `models` | `readonly ModelConfig[]` | Overrides featured `zaiModels` defaults. |
 
-`ModelConfig.compat.thinkingFormat: "zai"` enables ZAI thinking handling;
-`developerRoleFallback` controls developer-role fallback.
+### Thinking / reasoning compat
+
+Official body fields (request `options.compat` wins over `model.compat`):
+
+| Compat / body field | Wire shape | Notes |
+| --- | --- | --- |
+| `thinking` | `boolean` or `{ type: "enabled" \| "disabled", clear_thinking?: boolean }` | Boolean `true`/`false` maps to `{ type: "enabled" }` / `{ type: "disabled" }`. |
+| `reasoning_effort` | string | GLM-5.2+: `max` (default) \| `xhigh` \| `high` \| `medium` \| `low` \| `minimal` \| `none`. |
+| `tool_stream` | boolean | GLM-4.6+: stream tool-call argument deltas (`false` by API default; featured 4.6+ models opt in). |
+| `clear_thinking` | boolean | Nested into `thinking.clear_thinking`. Default on the API is `true` (drop prior reasoning). Set `false` for Preserved Thinking. |
+| `preserveThinking` | boolean | Prism-local: when true (or when `clear_thinking: false`), replay prior thinking blocks as assistant `reasoning_content`. |
+
+`ProviderRequestOptions.cacheRetention: "none"` forces `thinking: { type: "disabled" }`.
+
+Shared Prism helpers (`applyThinkingLevel` / `thinkingFamilyForModel`) map portable
+levels into the `reasoning_effort` family for Z.AI; hosts can also set
+`thinking.type` directly for enable/disable.
 
 ## Outputs / response / events
 
 | Surface | Behavior |
 | --- | --- |
-| Provider stream | Prism text, thinking (preserved only when `model.compat.preserveThinking` is true, otherwise downgraded to text), tool-call delta/final, `usage`, `done`, redacted `error`. |
-| Block preservation | Text, thinking, assistant `tool_call` → `tool_calls`, `tool_result` → role `tool` messages, images when `capabilities.input` includes `"image"`. |
+| Provider stream | Prism text, thinking (`delta.reasoning_content`), tool-call delta/final, `usage`, `done`, redacted `error`. |
+| Block preservation | Text; thinking → `reasoning_content` when Preserved Thinking is active (otherwise dropped, never flattened into text); assistant `tool_call` → `tool_calls`; `tool_result` → role `tool`; images when `capabilities.input` includes `"image"`. |
 | Auth method | `api_key` for the configured provider id, credential name `apiKey`. |
 
 Unsupported block placements or unclaimed images fail before fetch.
 
 ## Request/response example
 
-Example request body (OpenAI-compatible Chat Completions shape):
+Example request body (official Chat Completions shape):
 
 ```json
 {
-  "model": "glm-4.6",
+  "model": "glm-5.2",
   "messages": [{ "role": "user", "content": "Hello" }],
-  "stream": true
+  "stream": true,
+  "thinking": { "type": "enabled" },
+  "reasoning_effort": "max",
+  "tool_stream": true
 }
 ```
 
@@ -64,63 +87,89 @@ Example request body (OpenAI-compatible Chat Completions shape):
 
 ```ts
 import { createExtensionKernel } from "@arnilo/prism";
-import { createZaiProviderPackage } from "@arnilo/prism-provider-zai";
+import { createZaiProviderPackage, listZaiModels } from "@arnilo/prism-provider-zai";
 
 const kernel = createExtensionKernel();
 await kernel.load([createZaiProviderPackage({ apiKey: "fake-zai-key" })]);
+
+// Optional caller-gated discovery (never runs during package setup):
+const live = await listZaiModels({ apiKey: "fake-zai-key" });
+await kernel.load([createZaiProviderPackage({ apiKey: "fake-zai-key", models: live })]);
 ```
 
-Override the provider id and models:
+Per-turn thinking override:
 
 ```ts
-import { createZaiProviderPackage, defineZaiModel, zaiModels } from "@arnilo/prism-provider-zai";
-
-await kernel.load([
-  createZaiProviderPackage({ id: "zai", apiKey: "fake", models: zaiModels }),
-]);
+await session.prompt("Plan the refactor", {
+  providerOptions: {
+    compat: {
+      thinking: { type: "enabled", clear_thinking: false },
+      reasoning_effort: "high",
+      tool_stream: true,
+    },
+  },
+});
 ```
 
 ## Extension and configuration notes
 
-- Hosts choose base URL, provider id, model list, credential source, and `fetch`
-  impl.
-- `defineZaiModel` lets apps set ZAI-specific `compat` (thinking format, developer
-  fallback).
-- Package contributes models via the extension `api` and an `api_key` auth method.
+- Default base URL is the official international endpoint
+  `https://api.z.ai/api/paas/v4`. Hosts targeting China can pass
+  `baseUrl: "https://open.bigmodel.cn/api/paas/v4"`. Coding Plan hosts may use
+  `https://api.z.ai/api/coding/paas/v4`.
+- Featured `zaiModels` are offline bootstrap aliases (`glm-5.2`, `glm-5.1`,
+  `glm-5`, `glm-5-turbo`, `glm-4.7`, `glm-4.6`, `glm-4.5`) curated from the
+  official Chat Completions model enum and overview context sizes.
+- `listZaiModels()` is caller-gated OpenAI-compatible `GET /models` discovery
+  (not a first-class docs.z.ai list page). Setup never fetches.
+- `defineZaiModel` sets Z.AI-specific `compat` (`thinking`, `reasoning_effort`,
+  `tool_stream`, `clear_thinking`, `preserveThinking`).
 
 ### Cache behavior
 
 - Z.AI GLM models use **implicit context caching**: the server caches prompt
   prefixes automatically based on request content, with no explicit request-side
   cache payload. Catalog models declare `cache: { kind: "implicit" }`.
+- Official docs: hits appear in `usage.prompt_tokens_details.cached_tokens`.
 - The provider sends no `cache_control`, `prompt_cache_key`, `prompt_cache_retention`,
   or other explicit cache-control fields regardless of `ProviderRequestOptions.cache`
   / `cacheKey` / `cacheRetention` settings — those options have no effect on the
-  Z.AI request body. Hosts relying on cache hits should keep their stable prompt
-  prefix byte-stable and stable inputs unchanged.
-- Usage accounting is preserved: `prompt_tokens_details.cached_tokens` maps to
-  `Usage.cacheReadTokens` and `prompt_tokens_details.cache_write_tokens` maps to
-  `Usage.cacheWriteTokens` when the server reports them.
+  Z.AI request body (except `cacheRetention: "none"` disabling thinking).
+- Usage accounting: `prompt_tokens_details.cached_tokens` → `Usage.cacheReadTokens`
+  and `prompt_tokens_details.cache_write_tokens` → `Usage.cacheWriteTokens` when
+  the server reports them.
 
 ## Security and performance notes
 
-- SSE streams and HTTP error bodies use bounded `@arnilo/prism/providers/transport` helpers (`readSseData`, `readBoundedResponseText`).
+- SSE streams and HTTP error bodies use bounded `@arnilo/prism/providers/transport`
+  helpers (`readSseData`, `readBoundedResponseText`).
 - No network calls during import, setup, build, or default tests.
 - No automatic environment, file, keychain, or shell credential lookup.
 - API keys are resolved per request from caller-supplied values or resolvers and
-  redacted from errors.
+  redacted from errors (including discovery failures).
 - Caller-supplied `ProviderRequest.options.headers` can add non-owned headers,
   but provider-owned headers (`content-type`, `authorization`) are applied last
   and cannot be overridden by caller headers.
-- Live tests stay opt-in behind `PRISM_LIVE_PROVIDER_TESTS=1` plus fake-safe
-  provider-specific env names; default tests are network-free.
+- Live tests stay opt-in behind `PRISM_LIVE_PROVIDER_TESTS=1` plus `ZAI_API_KEY`;
+  default tests are network-free.
 
 ## Related APIs
 
 - [Provider packages](../provider-packages.md): `defineProviderPackage`,
-  `ModelConfig`/`compat`, thinking formats.
+  caller-gated discovery, per-turn thinking.
+- [Thinking and reasoning](../thinking-and-reasoning.md): portable
+  `applyThinkingLevel` → Z.AI `reasoning_effort` / `thinking.type`.
 - [Credentials and redaction](../credentials-and-redaction.md):
   `resolveCredentialValue`, `redactSecrets`.
-- [OpenAI-compatible provider](openai-compatible.md): underlying Chat Completions
-  adapter.
+- [Provider caching](../provider-caching.md): implicit GLM context caching.
 - [Provider conformance](../provider-conformance.md): network-free adapter tests.
+
+## Official evidence
+
+- [Deep Thinking](https://docs.z.ai/guides/capabilities/thinking)
+- [Thinking Mode](https://docs.z.ai/guides/capabilities/thinking-mode) (Preserved Thinking / `clear_thinking`)
+- [Tool Streaming](https://docs.z.ai/guides/capabilities/stream-tool)
+- [Context Caching](https://docs.z.ai/guides/capabilities/cache)
+- [Chat Completion](https://docs.z.ai/api-reference/llm/chat-completion)
+- [Migrate to GLM-5.2](https://docs.z.ai/guides/overview/migrate-to-glm-new)
+- [Models overview](https://docs.z.ai/guides/overview/overview)

package/docs/public-contracts.md

@@ -15,7 +15,7 @@ Current contract groups:
 - Extensions/middleware: `ExtensionLifecycleEventName`, `ExtensionEvent`, `Extension`, `ExtensionAPI`, `MiddlewareHookName`, `Middleware`, `MiddlewareNext`, `MiddlewareRegistry`
 - Configuration/manifests: `ConfigProvider`, `ConfigLayer`, `ConfigLoadContext`, `PrismManifest`, `ManifestContributionDeclaration`, `ManifestResourceDeclaration`, `ManifestContributionKind`
 - Stores/resources/settings/credentials/compaction/retry/cache helpers: `SessionEntry`, `SessionStore`, `StoreFactory`, `Resource`, `ResourceLoader`, `ResourceLoadContext`, `SettingsProvider`, `CredentialRequest`, `Credential`, `CredentialResolver`, `CompactionStrategy`, `CompactionContext`, `CompactionResult`, `CompactionOptions`, `CompactionMiddlewarePayload`, `CompactionEntryData`, `DefaultCompactionStrategyOptions`, `RetryPolicy`, `RetryContext`, `RetryDecision`, `RetryOptions`, `RetryMiddlewarePayload`, `DefaultRetryPolicyOptions`, `CacheUsageReport`, `sanitizeCacheKey`, `mapCacheRetention`, `applyCacheControl`, `cacheHitRate`, `cacheSavings`, `cacheUsageReport`
-- Production persistence (adapter-facing): `ProductionPersistenceStore`, `CheckpointStore`, `CheckpointKey`, `CheckpointSaveInput`, `CheckpointRecord`, `CheckpointQuery`, `LeaseStore`, `LeaseKey`, `LeaseAcquireInput`, `LeaseClaimInput`, `LeaseRecord`, `PersistencePage`, `PersistenceQuery`, `OwnershipScope`, `SessionRecord`, `SessionQuery`, `BranchRecord`, `BranchQuery`, `SessionEntryQuery`, `RunRecord`, `RunQuery`, `AgentEventRecord`, `AgentEventQuery`, `ToolCallRecord`, `ToolCallQuery`, `UsageRecord`, `UsageQuery`, `AgentDefinitionRecord`, `AgentDefinitionQuery`, `RetentionPolicy`, `RetentionPolicyQuery`, `MigrationRecord`, `MigrationQuery`
+- Production persistence (adapter-facing): `ProductionPersistenceStore`, `CheckpointStore`, `CheckpointKey`, `CheckpointSaveInput`, `CheckpointRecord`, `CheckpointQuery`, `LeaseStore`, `LeaseKey`, `LeaseAcquireInput`, `LeaseClaimInput`, `LeaseRecord`, `PersistencePage`, `PersistenceQuery`, `OwnershipScope`, `SessionRecord`, `SessionQuery`, `BranchRecord`, `BranchQuery`, `SessionEntryQuery`, `RunRecord`, `RunQuery`, `RunFeedbackRecord`, `RunFeedbackStore`, `RunFeedbackQuery`, `AgentEventRecord`, `AgentEventQuery`, `ToolCallRecord`, `ToolCallQuery`, `UsageRecord`, `UsageQuery`, `AgentDefinitionRecord`, `AgentDefinitionQuery`, `RetentionPolicy`, `RetentionPolicyQuery`, `MigrationRecord`, `MigrationQuery`
 
 ## When to use it
 
@@ -142,9 +142,10 @@ Important request shapes:
 | `SystemPromptContribution` | Explicit caller-selected prompt layer with source, mode, text, and metadata. |
 | `ConfigLayer` | Named JSON config layer consumed by `mergeConfigLayers()`. |
 | `PrismManifest` | Data-only package manifest with config defaults, contribution declarations, and resource declarations. |
-| `ProductionPersistenceStore` | Adapter-facing interface for durable, paginated, multi-tenant storage plus optional `checkpoints?: CheckpointStore` and `leases?: LeaseStore`. No SQL/ORM/host file storage/network dependency. |
+| `ProductionPersistenceStore` | Adapter-facing interface for durable, paginated, multi-tenant storage plus optional `checkpoints?: CheckpointStore`, `leases?: LeaseStore`, and `feedback?: RunFeedbackStore`. No SQL/ORM/host file storage/network dependency. |
 | `CheckpointStore` | Generic versioned checkpoint capability: save/load/bounded-list/delete by namespace and key, with ownership, exact-version CAS, and lease fencing. `createMemoryCheckpointStore()` is the reference implementation. |
 | `LeaseStore` | Atomic acquire/renew/release/get by namespace and key, with opaque claim tokens, expiry, ownership scope, and monotonically increasing takeover fences. `createMemoryLeaseStore()` is the reference implementation. |
+| `RunFeedbackStore` | Immutable append, bounded owned query, and owned deletion for ratings/comments/tags linked to existing run/trace/evaluation IDs. `createMemoryRunFeedbackStore()` is the reference implementation. |
 | `EventMultiplexer<T>` | Generic bounded fan-in from async sources. `createEventMultiplexer()` owns queue limits, overflow policy, abort, source teardown, and close behavior. |
 | `PersistencePage<T>` | Cursor-paginated result page: `items`, optional `nextCursor`, optional `total`. |
 | `PersistenceQuery` | Common pagination controls: `cursor?`, `limit?`, `order?: "asc" \| "desc"`. |
@@ -155,7 +156,7 @@ Important request shapes:
 | `RunRecord` / `RunQuery` | Stored run and filters: session, branch, status, timestamps, ownership. |
 | `AgentEventRecord` / `AgentEventQuery` | Event ledger row with `redacted` flag and filters by type, session, run, entry, timestamp, ownership. |
 | `ToolCallRecord` / `ToolCallQuery` | Tool-call row with `redacted` flag and filters by name, status, session, run, entry, timestamps, ownership. |
-| `UsageRecord` / `UsageQuery` | Usage row and filters: session, run, entry, recorded-at range, ownership. |
+| `UsageRecord` / `UsageQuery` | Usage row and filters: `provider_turn`/`run_total` scope, turn/attempt, session, run, entry, recorded-at range, ownership. |
 | `CacheUsageReport` | Numeric cache diagnostics from normalized `Usage`: read/write tokens, hit rate, estimated savings, and optional currency. |
 | `AgentDefinitionRecord` / `AgentDefinitionQuery` | Versioned agent-definition snapshot and filters. Does not store credentials or provider instances. |
 | `RetentionPolicy` / `RetentionPolicyQuery` | Retention policy and filters: age, entry count, byte limits, archive store, applied kinds. |
@@ -412,8 +413,8 @@ void credentials;
 - Contracts are host-owned and package-friendly. External packages can implement `AIProvider`, `ToolDefinition`, `CommandDefinition`, `AgentDefinition`, `InputBuilder`, `PromptBuilder`, `Middleware`, `ContextProvider`, `Skill`, `Extension`, config providers, data-only manifests, compaction strategies, store factories, resource loaders, settings providers, and credential resolvers.
 - `ExtensionAPI` is implemented by the extension kernel. It exposes explicit registries, ordered middleware registration, ordered event subscription/emission, and registration methods for Phase 2 contribution categories.
 - `AgentConfig.provider` can hold a direct provider instance for simple host wiring. Hosts that need config-driven selection should use `ModelConfig.provider` with explicit `createProviderRegistry()` / `createModelRegistry()` objects; Prism does not create a hidden global provider registry.
-- `SettingsProvider` and `CredentialResolver` are explicit dependencies. Prism must not hide global settings or credentials behind these contracts, and `CredentialResolver` should be passed only to the edge that needs a credential. `AgentConfig.settings` and `AgentConfig.credentials` are host-owned metadata; the session runtime does not call `settings.get()` or `credentials.resolve()`.
-- `AgentConfig.extensions` is host-owned metadata; the session runtime does not load extensions or call `Extension.setup()`. Use `createExtensionKernel().load(...)` before creating an agent, then pass selected contributions into `AgentConfig`.
+- `SettingsProvider` and `CredentialResolver` are explicit dependencies. Prism must not hide global settings or credentials behind these contracts, and `CredentialResolver` should be passed only to the edge that needs a credential. These seams are host-owned outside `AgentConfig`; the session runtime does not call `settings.get()` or `credentials.resolve()`.
+- Extension loading is host-owned outside `AgentConfig`; the session runtime does not load extensions or call `Extension.setup()`. Use `createExtensionKernel().load(...)` before creating an agent, then pass selected contributions into `AgentConfig`.
 - `PrismManifest` is data-only. It can describe contribution modules/resources and config defaults, but parsing it does not import modules, execute package code, or mutate registries.
 - Resource helper functions decode resources from a caller-provided `ResourceLoader`; Prism does not include host file storage, network, package, or URI router loaders.
 - `createDefaultInputBuilder()` is a small default implementation of `InputBuilder`. It is replaceable and only loads explicit URI resources through a caller-provided `ResourceLoader`.

package/docs/rag.md

@@ -0,0 +1,113 @@
+# Retrieval-augmented generation (RAG)
+
+## What it does
+
+`@arnilo/prism-rag` is an optional package for deterministic plain-text/Markdown chunking, bounded embedding/vector indexing, filtered semantic retrieval, stable citations, and explicit `ContextProvider` injection. It reuses `Embedder` and `VectorStore` from `@arnilo/prism-memory`; Prism core input assembly is unchanged.
+
+## When to use it
+
+Use it when a host already owns trusted document text and needs small retrieval primitives without a document framework. Do not use it for PDF/HTML/LaTeX parsing, semantic chunking, metadata extraction agents, reranker pipelines, GraphRAG, crawling, URL fetching, or filesystem discovery.
+
+## Inputs / request
+
+Chunking:
+
+| API/field | Meaning |
+| --- | --- |
+| `chunkText(text, options)` | Character-bounded plain-text chunks |
+| `chunkMarkdown(markdown, options)` | Same engine, preferring heading/paragraph boundaries |
+| `sourceId` | Required stable, non-secret source identifier |
+| `size` / `overlap` | Character ceiling and repeated context |
+| `metadata` | JSON metadata copied to every chunk |
+
+Index/retrieve:
+
+| Field | Required | Meaning |
+| --- | --- | --- |
+| `embedder` / `store` | yes | Phase 7 `Embedder` and `VectorStore` |
+| `scope` | yes | `{ tenantId, resourceId, corpusId }`; corpus maps to vector thread isolation |
+| `chunks` | indexing | `RagChunk[]` from package chunkers or compatible host parser |
+| `topK` / `queryCandidates` | retrieval | Returned result count and bounded pre-filter candidates |
+| `filter` | no | Shallow JSON metadata equality filter |
+| `redactor` / `secrets` | no | Redact before embedding, persistence, and injection |
+| `signal` | no | Abort embedding, vector operations, and batch progression |
+
+## Outputs / response / events
+
+- `chunkText()` / `chunkMarkdown()` return frozen `RagChunk[]` with `sourceId`, zero-based index, offsets, and stable IDs such as `guide#0001`.
+- `indexChunks()` returns `{ indexed, sourceIds }` after bounded batch upserts.
+- `retrieveContext()` returns `{ query, text, hits, citations, truncated }`. Rendered text uses `[citation-id] text` blocks.
+- `createRagContextProvider()` returns one ordinary context provider. Empty queries/results contribute no block.
+- No events, tools, permissions, provider calls, loaders, or network requests are added.
+
+Default hard ceilings include 1,000/16,384 chunk characters, 100/4,096 overlap, 1,048,576/8,388,608 document characters, 2,048/8,192 chunks, 32/128 embed batch, top-K 5/32, candidates 20/128, result 64/512 KiB, and context 2,000/8,000 estimated tokens.
+
+## Request/response example
+
+```json
+{
+  "scope": { "tenantId": "t1", "resourceId": "docs", "corpusId": "handbook" },
+  "query": "How do approvals work?",
+  "topK": 1,
+  "result": {
+    "text": "[security-guide#0001] Recheck policy before side effects.",
+    "citations": [{ "id": "security-guide#0001", "sourceId": "security-guide" }]
+  }
+}
+```
+
+## Implementation example
+
+```ts
+import { createAgent, createMockProvider, providerDone, providerTextDelta } from "@arnilo/prism";
+import { createHashEmbedder, createMemoryVectorStore } from "@arnilo/prism-memory";
+import { chunkMarkdown, createRagContextProvider, indexChunks, retrieveContext } from "@arnilo/prism-rag";
+
+const embedder = createHashEmbedder(); // deterministic demo/test helper, not production semantic quality
+const store = createMemoryVectorStore();
+const scope = { tenantId: "t1", resourceId: "docs", corpusId: "handbook" };
+const chunks = chunkMarkdown("# Approval\n\nRecheck current policy before side effects.", {
+  sourceId: "security-guide",
+  metadata: { category: "security" },
+});
+await indexChunks({ chunks, embedder, store, scope });
+
+const found = await retrieveContext("approval policy", {
+  embedder,
+  store,
+  scope,
+  topK: 4,
+  filter: { category: "security" },
+});
+
+const agent = createAgent({
+  model: { provider: "mock", model: "demo" },
+  provider: createMockProvider([providerTextDelta("Policy checked."), providerDone()]),
+  context: [createRagContextProvider({ embedder, store, scope })],
+});
+console.log(found.text, await agent.createSession().run("How do approvals work?"));
+```
+
+## Extension and configuration notes
+
+- Supply any Phase 7-conforming embedder/vector store, including the in-memory reference or PostgreSQL/pgvector adapter.
+- Metadata filtering is package-local after a bounded candidate query so existing vector contracts/adapters remain unchanged. Increase `queryCandidates` only when selective filters measurably need it.
+- `createRagContextProvider()` derives its query from latest user text by default; pass a fixed string or callback for host-controlled query generation.
+- Load source text separately with a host-owned `ResourceLoader`. The RAG package intentionally accepts text, not URLs or filesystem paths.
+- Package is available directly or through `@arnilo/prism-all`; installation does not create an embedder, vector store, or context provider.
+
+## Security and performance notes
+
+- Every index/query includes exact tenant/resource/corpus scope; returned records are rechecked and malformed/foreign records fail closed.
+- Source IDs become citation/storage IDs and must be stable non-secret identifiers. Text and user metadata can be redacted before external embedding and persistence.
+- Retrieved documents are untrusted inert context. Prompt-injection text cannot activate tools, skills, credentials, permissions, or extensions.
+- Remote sources must pass existing resource/media trust, SSRF, MIME, and byte policies before their decoded text reaches this package.
+- Indexing is bounded per batch and checks abort between embed/upsert operations. A failure can leave completed batches persisted; retry is idempotent for the same stable source/chunk IDs.
+- Filtering scans at most `queryCandidates` hits; rendering stops at top-K, UTF-8 result bytes, or estimated context-token ceiling.
+
+## Related APIs
+
+- [Working and semantic memory](working-and-semantic-memory.md): shared `Embedder`/`VectorStore` contracts and adapters.
+- [Context and skills](context-and-skills.md): explicit `ContextProvider` injection and inert context semantics.
+- [Resource loading](resource-loading.md): host-owned trusted source loading.
+- [Multimodal content](multimodal-content.md): remote media SSRF/MIME/byte policies before text extraction.