@arnilo/prism 0.0.1 → 0.0.2

package/docs/compaction-conformance.md

@@ -0,0 +1,76 @@
+# Compaction conformance
+
+## What it does
+
+Compaction conformance helpers are dependency-free assertions for `CompactionStrategy` adapter tests. They exercise the summary-result shape, secret redaction, and abort observation of any `CompactionStrategy` without network or credentials.
+
+Exported from `@arnilo/prism/testing/compaction-conformance`:
+
+- `assertCompactionStrategyConforms(strategy, options?)`
+- `CompactionConformanceOptions`
+
+## When to use it
+
+Use this helper when implementing a custom `CompactionStrategy` (the core default strategy and the first-party LLM compaction package both conform). It asserts:
+
+- `compact()` returns a `CompactionResult` with a non-empty string `summary`
+- known secrets are redacted from the summary and any returned `entries`
+- (when `exerciseAbort: true`) an already-aborted `signal` is observed
+
+## Inputs / request
+
+```ts
+import { assertCompactionStrategyConforms } from "@arnilo/prism/testing/compaction-conformance";
+import type { CompactionStrategy } from "@arnilo/prism";
+
+const { summary } = await assertCompactionStrategyConforms(myStrategy, {
+  secrets: ["api-key-value"],
+  exerciseAbort: true,
+});
+```
+
+`CompactionConformanceOptions`:
+- `secrets?: readonly string[]` — secrets that must not appear in the summary or returned entries
+- `exerciseAbort?: boolean` — assert the strategy observes an already-aborted `signal`
+
+## Outputs / response / events
+
+Returns `Promise<{ summary: string }>`; throws a plain `Error` on the first contract violation. No events, no runner.
+
+## Request/response example
+
+```ts
+import { assertCompactionStrategyConforms } from "@arnilo/prism/testing/compaction-conformance";
+
+await assertCompactionStrategyConforms(myStrategy, { secrets: ["secret-value"] });
+// throws if the summary is empty, a secret leaks into the summary, or a
+// secret leaks into the returned entries.
+```
+
+## Implementation example
+
+```ts
+import { assertCompactionStrategyConforms } from "@arnilo/prism/testing/compaction-conformance";
+import { createDefaultCompactionStrategy } from "@arnilo/prism";
+
+await assertCompactionStrategyConforms(
+  createDefaultCompactionStrategy({ keepRecentEntries: 1, secrets: ["secret-value"] }),
+  { secrets: ["secret-value"] },
+);
+```
+
+## Extension and configuration notes
+
+- The helper builds a tiny two-message fixture; it does not call your strategy with production entries.
+- Abort observation is optional because not every strategy performs async work that can be aborted.
+
+## Security and performance notes
+
+- No credentials, no network, no real secrets required; pass fake secret strings.
+- The helper asserts redaction of exactly the secrets you supply (mirroring `createSecretRedactor`'s exact-match behavior); it does not detect arbitrary secret patterns.
+
+## Related APIs
+
+- [Compaction and retry](compaction-and-retry.md)
+- [Provider conformance](provider-conformance.md)
+- [Session store conformance](session-store-conformance.md)

package/docs/compaction-llm.md

@@ -33,7 +33,7 @@ Key exports:
 | `thinkingLevel` | Passed as `ProviderRequest.options.extra.thinkingLevel`. |
 | `reserveTokens` | Output budget basis; defaults to `16384`. |
 | `keepRecentTokens` | Approximate recent-token budget; defaults to `20000`. |
-| `maxSummaryTokens` / `maxOutputTokens` | Sets generic `model.parameters.maxTokens` and truncates oversized collected summaries. |
+| `maxSummaryTokens` / `maxOutputTokens` | Computes the summary output budget, writes it to `summaryModel/model.parameters.maxTokens`, and truncates oversized collected summaries. First-party providers serialize that generic field to their real request field (`max_output_tokens` for OpenAI Responses, `max_tokens` for OpenAI-compatible/Anthropic-style providers). |
 | `maxToolResultChars` | Tool-result JSON truncation limit; defaults to `2000`. |
 | `trackFileOperations`, `includeFileOperations` | Control file path extraction and final summary blocks. |
 | `secrets` | Exact strings to redact from serialized prompts and final summaries. |
@@ -61,12 +61,15 @@ import { createLlmCompactionStrategy } from "@arnilo/prism-compaction-llm";
 
 const strategy = createLlmCompactionStrategy({
   provider: summaryProvider,
-  model: { provider: "mock", model: "cheap-summary" },
+  model: { provider: "openai", model: "gpt-4.1-mini" },
   keepRecentTokens: 20_000,
   reserveTokens: 16_384,
+  maxOutputTokens: 800,
   providerOptions: { cacheRetention: "short" },
   customInstructions: "Focus on current files and failing tests.",
 });
+// Provider request model includes: { parameters: { maxTokens: 800 } }.
+// First-party serializers map it to max_output_tokens/max_tokens on the wire.
 
 await session.compact({ strategy, secrets: [apiKey] });
 ```
@@ -99,7 +102,7 @@ const agent = createAgent({ model, provider, compaction: { strategy, thresholdEn
 Registration only contributes an inert strategy. The host must resolve and pass it to runtime config.
 
 ## Security and performance notes
-Preparation is O(n) over branch entries and uses only arrays, strings, and JSON serialization. The strategy makes only the needed provider call(s): one history summary plus one split-turn prefix summary when needed. It does not discover credentials, read files, start background jobs, or add provider SDK dependencies. Redaction is exact-string only; pass every known secret that may appear in history or provider output.
+Preparation is O(n) over branch entries and uses only arrays, strings, and JSON serialization. Output-budget calculation is O(1) and does not add an extra summarization call. The strategy makes only the needed provider call(s): one history summary plus one split-turn prefix summary when needed. It does not discover credentials, read files, start background jobs, or add provider SDK dependencies. Redaction is exact-string only; pass every known secret that may appear in history or provider output.
 
 ## Related APIs
 - [Compaction and retry policies](compaction-and-retry.md): core compaction strategy surface.

package/docs/compaction-observational-memory.md

@@ -38,7 +38,7 @@ Key exports:
 | `recallObservationalMemory()` | Recover source evidence for a known observation/reflection id from supplied current-branch entries. |
 | `createMemoryId()` / `isMemoryId()` | Create/check 12-character ids. |
 | `resolveObservationalMemorySettings()` | Merge `observational-memory` settings with defaults and overrides. |
-| `createObservationalMemoryRuntime()` | Explicitly run observer/reflector/dropper workers for a supplied session/store/provider. |
+| `createObservationalMemoryRuntime()` | Explicitly run observer/reflector/dropper workers for a supplied session, owned append callback, and provider. |
 | `createObservationalMemoryCompactionStrategy()` | Render existing folded memory as a standard Prism compaction summary with `data.memory`. |
 | `createObservationalMemoryExtension()` | Inert extension helper that registers the strategy contribution unless disabled. |
 | `createRecallMemoryTool()` | Optional exact-id `recall` tool factory backed by host-supplied current-branch entries. |
@@ -74,7 +74,7 @@ const evidence = recallObservationalMemory(entries, "aaaaaaaaaaaa");
 
 const memory = createObservationalMemoryRuntime({
   session,
-  store,
+  appendEntry: (entry) => store.append(entry),
   workerProvider,
   workerModel: { provider: "mock", model: "memory" },
 });
@@ -92,7 +92,7 @@ await kernel.load([createObservationalMemoryExtension({ recallTool: { getEntries
 
 Settings are read from the `observational-memory` key only when a host calls `resolveObservationalMemorySettings()` or `runtime.flush()`. Defaults are `observeAfterTokens: 10000`, `reflectAfterTokens: 20000`, `compactAfterTokens: 81000`, `observationsPoolMaxTokens: 20000`, `observationsPoolTargetTokens: 10000`, `agentMaxTurns: 16`, `passive: false`, and `debugLog: false`.
 
-The runtime requires host-supplied `session`, matching `store`, `workerProvider`, and `workerModel`. Optional credential resolution is explicit; missing requested credentials skip worker execution.
+The runtime requires host-supplied `session`, an `appendEntry` callback bound to that session's owning store/branch, `workerProvider`, and `workerModel`. It no longer accepts a separate `store` option because mismatched session/store pairs can append memory entries outside the active branch. After each memory append, the runtime checks the appended entry is visible at the session leaf and fails closed/restores the previous checkout if the callback points elsewhere. Optional credential resolution is explicit; missing requested credentials skip worker execution.
 
 `createObservationalMemoryCompactionStrategy()` keeps recent message entries like the default compaction strategy, renders existing observations/reflections as the summary, and returns a standard Prism compaction entry. Its `data` includes `throughEntryId`, `keepEntryIds`, `strategy`, `trigger`, and `memory: { type: "om.folded", version: 1, fullFold, observations, reflections, droppedObservationIds }`. When active observations exceed `observationsPoolMaxTokens`, it performs a full fold into `data.memory`.
 
@@ -108,7 +108,7 @@ The runtime requires host-supplied `session`, matching `store`, `workerProvider`
 - Recall tool and commands only see current-branch entries supplied by the host callback.
 - Invalid or missing ids fail closed; invalid recall tool ids skip entry lookup.
 - Utilities and fast compaction are O(n) over supplied entries and use no provider, network, filesystem, timer, worker, credential, or settings access.
-- Workers serialize only supplied branch entries, enforce `agentMaxTurns`, and run one consolidation pipeline at a time per runtime.
+- Workers serialize only supplied branch entries, enforce `agentMaxTurns`, and run one consolidation pipeline at a time per runtime. Worker transcripts replay assistant `tool_call` messages before matching role `tool` `tool_result` messages so provider requests stay valid for call/result-pairing providers.
 - Compaction preserves raw history; Prism appends one standard compaction entry and rebuilds provider context from its summary plus kept recent messages.
 - Pass known secrets to render/recall/runtime/tool/command helpers to redact exact values from prompts, records, structured results, and text output.
 - Live tests are opt-in with `PRISM_LIVE_OBSERVATIONAL_MEMORY_TESTS=1`.

package/docs/configuration-and-manifests.md

@@ -69,6 +69,7 @@ parsePrismManifest(value: unknown): PrismManifest
 | `authMethod` | `authMethods` | Auth method descriptor; uses `credentialName`, never a resolved credential value. |
 | `providerRequestPolicy` | `providerRequestPolicies` | Provider request policy declaration. |
 | `systemPromptContribution` | `systemPromptContributions` | System prompt contribution declaration. |
+| `instructionInjector` | `instructionInjectors` | Instruction injector declaration; selected on `AgentConfig`/`RunOptions.instructionInjectors` (Phase 30). |
 
 ## Outputs / response / events
 
@@ -76,6 +77,7 @@ parsePrismManifest(value: unknown): PrismManifest
 - Later config layers override earlier layers.
 - Nested plain objects merge recursively.
 - Arrays and primitives replace previous values.
+- Config and manifest JSON object keys named `__proto__`, `prototype`, or `constructor` are rejected at any depth before merge/clone output is built.
 - `parsePrismManifest()` returns a validated manifest or throws a field-specific validation error.
 - No events are emitted and no registries are modified by these helpers.
 
@@ -106,6 +108,7 @@ const manifest = definePrismManifest({
     { kind: "authMethod", name: "demo.api-key", metadata: { credentialName: "apiKey" } },
     { kind: "providerRequestPolicy", name: "demo.cache" },
     { kind: "systemPromptContribution", name: "demo.prompt" },
+    { kind: "instructionInjector", name: "demo.injector" },
   ],
   resources: [{ uri: "package://demo/prompt.md", purpose: "prompt" }],
 });
@@ -123,13 +126,14 @@ console.log(config.demo);
 
 - Hosts choose the layer order. Prism documents `built-in -> manifest defaults -> host app -> optional user/global -> runtime overrides` but does not load those layers automatically.
 - Manifest contribution declarations are data. Hosts may later choose to import the declared module/export and register it, but parsing the manifest never does that.
-- Contribution `kind` values match `createContributionRegistries()` categories, including the Phase 14 provider primitives `providerPackage`, `authMethod`, `providerRequestPolicy`, and `systemPromptContribution`.
+- Contribution `kind` values match `createContributionRegistries()` categories, including the Phase 14 provider primitives `providerPackage`, `authMethod`, `providerRequestPolicy`, `systemPromptContribution`, and the Phase 30 `instructionInjector`.
 - Filesystem config loading is intentionally outside the root API and belongs to the optional [`@arnilo/prism/node/config`](node-filesystem-config.md) subpath.
 - Manifest `resources` entries are URI declarations; use [resource loading](resource-loading.md) helpers with a host-provided loader to fetch them.
 
 ## Security and performance notes
 
 - Config and manifest values must be JSON-compatible data.
+- Config/manifest JSON rejects `__proto__`, `prototype`, and `constructor` keys at every depth to block prototype pollution rather than silently dropping unsafe input.
 - Do not put resolved credential values, tokens, headers, or executable code in config defaults, manifests, or metadata.
 - Manifest parsing does not execute package code, dynamically import modules, resolve credentials, call providers/tools, or read resources.
 - Config merging is dependency-free and proportional to the total number of JSON fields.
@@ -140,3 +144,4 @@ console.log(config.demo);
 - [Extension kernel and event bus](extensions.md): hosts can load extensions after they decide to execute package code.
 - [Resource loading](resource-loading.md): load manifest, prompt, skill, and package resources through host-provided loaders.
 - [Credentials and redaction](credentials-and-redaction.md): credential values stay out of manifests and config layers.
+- [Contribution discovery (workspace)](contribution-discovery.md): opt-in scanner that resolves non-skill on-disk entries into `ManifestContributionDeclaration` envelopes.

package/docs/context-and-skills.md

@@ -6,7 +6,7 @@
 
 ## When to use it
 
-Use context resolution when a host wants project/session/context blocks resolved before prompt composition. Use the skill registry when a host wants explicit progressive skill disclosure.
+Use context resolution when a host wants project/session/context blocks resolved before prompt composition. Use the skill registry when a host wants explicit progressive skill disclosure. Declarative `AgentDefinition.skills` are inactive unless listed; omitted skills means none unless the host uses the migration-only `activateAllCapabilities: true` option.
 
 Do not use these helpers as an agent loop, package discovery mechanism, context cache, token budgeter, retrier, credential resolver, semantic skill ranker, tool activator, or permission system.
 
@@ -32,7 +32,10 @@ Skill selection:
 ```ts
 import { createSkillRegistry, resolveActiveSkills } from "@arnilo/prism";
 
-const registry = createSkillRegistry([{ name: "brief", instructions: "Answer briefly.", toolNames: ["echo"] }]);
+const registry = createSkillRegistry(
+  [{ name: "brief", instructions: "Answer briefly.", toolNames: ["echo"] }],
+  { duplicate: "error" },
+);
 const active = resolveActiveSkills({
   registry,
   names: ["brief"],
@@ -40,13 +43,15 @@ const active = resolveActiveSkills({
 });
 ```
 
+`createSkillRegistry(skills?, options?)` stores skills by `skill.name`. Duplicate names replace deterministically by default for compatibility. Pass `{ duplicate: "error" }` to throw `Duplicate skill: <name>` and prevent silent shadowing.
+
 `ResolveActiveSkillsOptions` accepts a `SkillRegistry`, requested skill names, and host-active `ToolDefinition[]`.
 
 ## Outputs / response / events
 
 `resolveContextProviders()` returns `readonly ContextBlock[]` in provider order. If a middleware registry is supplied, the `context` hook can transform the final block array.
 
-`resolveActiveSkills()` returns requested skills in requested order. Unknown skills and skills that reference inactive tools throw before prompt composition.
+`resolveActiveSkills()` returns requested skills in requested order. Unknown skills, duplicate skill registrations in strict mode, and skills that reference inactive tools throw before prompt composition.
 
 ## Request/response example
 
@@ -85,7 +90,7 @@ const request = await assembleProviderInput({
 
 ## Extension and configuration notes
 
-Extensions can contribute context providers and skills with `registerContextProvider()` and `registerSkill()`, but those contributions stay inert until the host selects providers or registers/selects skills. The agent/session runtime uses the `context` and selected `skills` arrays passed on `AgentConfig`; it does not auto-select contributions.
+Extensions can contribute context providers and skills with `registerContextProvider()` and `registerSkill()`, but those contributions stay inert until the host selects providers or registers/selects skills. `resolveAgentDefinition()` only selects skills named in `AgentDefinition.skills` by default; omitted declarative skills activate none. The agent/session runtime uses the `context` and selected `skills` arrays passed on `AgentConfig`; it does not auto-select contributions.
 
 ```ts
 const providers = [kernel.registries.contextProviders.resolve("project")];
@@ -95,19 +100,87 @@ const skills = resolveActiveSkills({ registry: skillRegistry, names: ["brief"],
 
 `context` middleware runs only when a middleware registry is supplied to the helper. Middleware transforms context data; it does not grant tool access. Skills can reference tool names, but only host-active tools satisfy those references.
 
+## Runtime skill selection and activation
+
+The agent/session runtime resolves skills per run and wires each active skill's `context` into the assembled provider input. Runtime `AgentConfig.skills` and declarative `AgentDefinition.skills` have different defaults:
+
+| Surface | Config shape | Run override | Active skills |
+| --- | --- | --- | --- |
+| Runtime agent | `AgentConfig.skills: SkillRegistry` | `RunOptions.activeSkills: ["brief"]` | Named skills only, resolved with `resolveActiveSkills({ registry, names, tools })`. |
+| Runtime agent | `AgentConfig.skills: SkillRegistry` | no `activeSkills` / no `skills` | All registry skills (`SkillRegistry.list()`). |
+| Runtime agent | `AgentConfig.skills: Skill[]` | `RunOptions.skills: [...]` | Override array only. |
+| Runtime agent | `AgentConfig.skills: Skill[]` | no `RunOptions.skills` | All configured array skills. |
+| Declarative definition | `AgentDefinition.skills: ["brief"]` | later runtime `activeSkills` optional | Listed names only. |
+| Declarative definition | omitted `AgentDefinition.skills` | `activateAllCapabilities` false/default | No skills active. |
+| Declarative definition | omitted `AgentDefinition.skills` | `activateAllCapabilities: true` | All registry skills, migration-only. |
+
+Runtime selection precedence mirrors the other `RunOptions` overrides (`redactor`, `validate`):
+
+1. `AgentConfig.skills` is a `SkillRegistry` and `RunOptions.activeSkills: readonly string[]` (names) is set → the runtime calls `resolveActiveSkills({ registry, names, tools })`.
+2. `RunOptions.skills: readonly Skill[]` is set → that array replaces `AgentConfig.skills` for the run. This override exists for the case where `AgentConfig.skills` is a plain `Skill[]` (no registry), so name resolution is impossible.
+3. Neither set → all configured runtime skills are active (current behavior; `SkillRegistry.list()` or the plain array as-is). This is not the declarative default.
+
+names win when a registry exists. `RunOptions.activeSkills` cannot be used against a plain-array `AgentConfig.skills` — use `RunOptions.skills` instead. Use `RunOptions.skills: []` for an explicit no-skills runtime run.
+
+Each active skill contributes two things the runtime now wires together:
+
+- `Skill.instructions` → rendered as system messages by `skillMessages()` (active set only).
+- `Skill.context: ContextProvider[]` → collected across active skills (`activeSkills.flatMap(s => s.context ?? [])`), resolved through the existing `resolveContextProviders(...)`, and merged into the request's `context` **after** host `AgentConfig.context` blocks. Inactive skills contribute neither instructions nor context.
+
+`toolNames` enforcement is live: because selection routes through `resolveActiveSkills()`, a skill demanding a host-inactive tool throws with `Skill ${name} requires inactive tool: ${missing}` **before the first provider turn** — no provider call, no store write, no partial side effect. This is the fail-fast contract the docs already claimed; the runtime now honors it.
+
+```ts
+import { createAgent, createSkillRegistry, type ContextProvider } from "@arnilo/prism";
+
+const schema: ContextProvider = { name: "schema", resolve: () => [{ title: "Schema", content: "selected schema" }] };
+const skills = createSkillRegistry([
+  { name: "summarize", instructions: "Summarize.", context: [schema], toolNames: ["echo"] },
+  { name: "translate", instructions: "Translate." },
+]);
+
+const agent = createAgent({ model, provider, skills, tools: [echo] });
+
+// Only summarize this run: its instructions render and schema context resolves;
+// translate stays inactive and contributes neither. If `echo` were not in the
+// active tool set, this run would throw before the first provider turn.
+await agent.createSession().run(input, { activeSkills: ["summarize"] });
+
+// Same config, different active skills on the next run:
+await agent.createSession().run(input, { activeSkills: ["translate"] });
+
+// Plain-array override (no registry on AgentConfig.skills):
+await session.run(input, { skills: [{ name: "verbose", instructions: "Be verbose." }] });
+await session.run(input, { skills: [] }); // explicit no skills for this run
+```
+
+Skill selection grants no tool access and cannot bypass permissions — a skill's `toolNames` can only *require* host-active tools, never activate or grant them. Declarative skills also do not activate themselves by presence in a registry; list names on `AgentDefinition.skills` (or pass runtime `activeSkills`) when wanted. Per-skill token budgeting is deferred; the merge order (host context, then skill context) is the only priority knob today.
+
+### Migration note
+
+For declarative agents, old configs that omitted `skills` should now add explicit names:
+
+```ts
+// New safe default: no skill activates by omission.
+resolveAgentDefinition({ name: "doc", model, skills: ["brief"] }, context);
+```
+
+Use `activateAllCapabilities: true` only as a temporary all-skills/all-tools compatibility opt-in during migration. Runtime `RunOptions.activeSkills` remains the per-run narrowing tool after an agent has a skill registry configured.
+
 ## Security and performance notes
 
 - Context providers run sequentially and deterministically in caller order.
-- Skill registry lookup is `Map`-backed, and selection is linear in requested skills plus active tools.
+- Skill registry lookup is `Map`-backed, and selection is linear in requested skills plus active tools. Strict duplicate mode adds one O(1) `Map.has()` check during registration only.
 - These helpers perform no provider calls, tool execution, resource loading, package discovery, filesystem/network access, retries, timers, or watchers by themselves.
 - Context and skill output is host/extension data. Do not include secrets unless the host explicitly accepts that prompt exposure.
-- Active tools remain host-supplied; skills and middleware do not activate tools or grant permissions.
+- Active tools remain host-supplied; skills and middleware do not activate tools or grant permissions. Use `duplicate: "error"` when loading third-party skills to prevent silent name shadowing.
 
 ## Related APIs
 
 - [Agent/session runtime](agent-session-runtime.md): consumes host-selected context providers and skills from explicit agent config.
 - [Input and prompt assembly](input-and-prompt-assembly.md): default prompt builder and provider-input assembly helper.
+- [Instruction injection](instruction-injection.md): package injectors contribute `contextBlocks` that merge after host+skill provider blocks.
 - [Public contracts](public-contracts.md): `ContextProvider`, `ContextResolutionContext`, `ContextBlock`, `Skill`, `SkillRegistry`, `PromptBuilder`, and `PromptBuildRequest`.
 - [Middleware hooks](middleware-hooks.md): `context` and `prompt_build` hooks.
 - [Contribution registries](contribution-registries.md): inert context provider and skill contributions.
+- [Contribution discovery (workspace)](contribution-discovery.md): opt-in filesystem scanner that turns `SKILL.md`/`manifest.json` into registered skills and descriptor stubs. (Per-agent `AGENT.md` bundles live under an app-controlled `configRoot`; see [Agent definitions](agent-definitions.md).)
 - [Tools](tools.md): host-owned active tools and permissions.

package/docs/contribution-discovery.md

@@ -0,0 +1,149 @@
+# Contribution discovery (workspace)
+
+## What it does
+
+Discovery scans the filesystem for workspace contribution directories and turns their on-disk files into inert `DiscoveredContribution` envelopes the host then registers. It reads text only — it never `import()`s, `require()`s, or otherwise executes contribution code, and it never grants tools, permissions, credentials, or provider slots.
+
+APIs (Node subpath `@arnilo/prism/node/contribution-discovery`, parsers and registrar on the main barrel):
+
+- `discoverContributions(options)` / `DiscoveryOptions`: directory-walking scanner for the workspace `.agents/` tree. One `readdir` per kind-root.
+- `parseSkillFile(text, path)`: stdlib-only frontmatter parser for `SKILL.md` (no YAML dependency, no `node:*` import). Re-exported from `@arnilo/prism`.
+- `registerDiscoveredContributions(registries, contributions)`: registers realized `Skill` objects for the `skill` kind and descriptor-only stubs for other kinds. Re-exported from `@arnilo/prism`.
+- `ContributionFileKind`, `DiscoveredContribution`: contract types re-exported from `@arnilo/prism`.
+- `createPathTrustPolicy` / `isPathInsideReal` (from `@arnilo/prism/node/trust`): realpath-resolved, fail-closed containment used to gate workspace roots.
+
+## When to use it
+
+Use discovery when a host or the `prism` CLI wants to honor a project-local contribution layout without wiring every contribution by hand. Typical hosts pass `--discover` on the CLI or call `discoverContributions()` on startup, then feed the result through `registerDiscoveredContributions()` into their existing `ContributionRegistries`.
+
+Do not use it to discover providers — provider/model packages stay config/package-driven (Phase 24; see [Provider packages](provider-packages.md)). Do not use it to auto-activate anything: discovery registers, never activates. Skills become selectable only when a run passes `RunOptions.activeSkills`, and `toolNames` is still enforced against the resolved tool set at activation time.
+
+## Inputs / request
+
+### Directory layout
+
+| Origin | Path | Scanned by |
+| --- | --- | --- |
+| Workspace | `<workspace>/.agents/{skills,tools,context,instructions}/<name>/` | `workspaceRoot`, gated by `trust` |
+
+### Per-kind entry file
+
+| Kind | Entry file | Parsed into |
+| --- | --- | --- |
+| `skill` | `<dir>/SKILL.md` | A realized `Skill` (placed in `DiscoveredContribution.skill`) |
+| `tool` / `context` / `instructions` | `<dir>/manifest.json` | A `ManifestContributionDeclaration` |
+
+### Frontmatter keys
+
+`SKILL.md` frontmatter (YAML-like, parsed by a stdlib-only parser — no YAML dependency):
+
+| Key | Meaning |
+| --- | --- |
+| `name` | Required if you want an explicit name; otherwise the parent directory name is used. |
+| `description` | Optional skill description. |
+| `toolNames` | Optional comma list (`[a, b]`) or YAML block list (`- a`). Enforced at activation, not at discovery. |
+
+The markdown body below the front fence becomes `Skill.instructions`. Unknown frontmatter keys are tolerated and collected into `Skill.metadata` (never fatal).
+
+`manifest.json` entries follow the [`ManifestContributionDeclaration`](configuration-and-manifests.md) shape: `kind`, `name`, and optional `module`/`exportName`/`resource`/`metadata`.
+
+### `DiscoveryOptions`
+
+| Field | Meaning |
+| --- | --- |
+| `kinds` | Which `ContributionFileKind` values to scan (`skill`, `tool`, `context`, `instructions`). |
+| `workspaceRoot` | Workspace root. Gated by `trust`; untrusted roots are skipped silently. |
+| `permission?` | `PermissionPolicy` asserting each directory read (`assertPermission`). |
+| `trust?` | `TrustPolicy` (e.g. `createPathTrustPolicy`) fail-closed against the workspace root. |
+
+### CLI flags
+
+| Flag | Meaning |
+| --- | --- |
+| `--discover` | Enable workspace contribution discovery. Opt-in; default runs never touch the filesystem. |
+| `--discover-kinds <csv>` | Kinds to scan. Defaults to `skill`. Accepts `skill,tool,context,instructions`. |
+| `--no-discovery` | Hard-disable discovery even if `--discover` is set. |
+
+## Outputs / response / events
+
+`discoverContributions()` returns `readonly DiscoveredContribution[]`. Each envelope has `kind`, `name`, `origin` (`"global"` | `"workspace"`), `path`, and either `skill` (for the `skill` kind) or `declaration` (a `ManifestContributionDeclaration` for other kinds), plus optional `metadata`. The envelope is inert: it contains no executable code, no credential, and no resolved provider/model/tool reference.
+
+`registerDiscoveredContributions(registries, contributions)` writes into the existing `ContributionRegistries`: `skills` get full `Skill` objects; `tool`/`context` get descriptor-only stubs whose `execute`/`resolve` throw (executable behavior is host-owned); `instructions` get descriptors with empty `text` (Phase 30 lifts `declaration.resource` into actual text). The host retains the original `DiscoveredContribution[]` for provenance — tool and context descriptors carry no `metadata.discovered` slot because `ToolDefinition` and `ContextProvider` have no metadata field. Phase 30 adds a host-owned `loadInstructionInjector` adapter (see [Instruction injection](instruction-injection.md)) that turns a discovered `kind: "instructions"` contribution into a live `InstructionInjector` — markdown-only → static `every_turn` injector; module-referenced → resolved through a host-supplied `moduleLoader` (core never auto-`import()`s).
+
+## Request/response example
+
+Discovering a workspace skill:
+
+```json
+[
+  { "kind": "skill", "name": "greeter", "origin": "workspace", "path": "/proj/.agents/skills/greeter/SKILL.md", "skill": { "name": "greeter", "description": "g", "instructions": "..." } }
+]
+```
+
+## Implementation example
+
+```ts
+import {
+  createContributionRegistries,
+  registerDiscoveredContributions,
+  createSkillRegistry,
+  createAgent,
+  createMockProvider,
+  providerDone,
+} from "@arnilo/prism";
+import { discoverContributions } from "@arnilo/prism/node/contribution-discovery";
+import { createPathTrustPolicy } from "@arnilo/prism/node/trust";
+
+// 1. Discover — workspace gated by trust.
+const trust = createPathTrustPolicy({ trustedRoots: [workspaceRoot] });
+const discovered = await discoverContributions({
+  kinds: ["skill"],
+  workspaceRoot,
+  trust,
+});
+
+// 2. Register — skills become full Skill objects; other kinds register as stubs.
+//    Discovery never imports or executes contribution code.
+const registries = createContributionRegistries();
+registerDiscoveredContributions(registries, discovered);
+
+// 3. Run — discovery did NOT activate anything. The run explicitly selects skills.
+const session = createAgent({
+  model: { provider: "mock", model: "demo" },
+  provider: createMockProvider([providerDone()]),
+  skills: createSkillRegistry(registries.skills.list()),
+}).createSession();
+
+await session.run("Hi", { activeSkills: ["greeter"] });
+```
+
+A complete runnable example lives at `examples/discover-skills.ts`.
+
+## Extension and configuration notes
+
+- Discovery is loader-driven, not module-driven. The on-disk contribution is a data file (`SKILL.md`/`manifest.json`); the host decides whether, when, and how to register and activate it. There is no `import()` of untrusted modules.
+- `ContributionFileKind` is the discovery-side kind name (`skill`/`tool`/`context`/`instructions`). The manifest-side kind is `ManifestContributionKind` ([Configuration and manifests](configuration-and-manifests.md)); the node scanner maps between them.
+- The `--discover-kinds` CSV lets a host scan a subset. The CLI default is `skill`; other kinds register descriptor stubs only (host-owned execution).
+- First-party skills are expected to ship as installable packages (separate request); Phase 29 ships discovery infrastructure only and adds no first-party skill package.
+
+## Security and performance notes
+
+- **Workspace gating**: workspace roots are checked through `createPathTrustPolicy` + `isPathInsideReal`, which resolve symlinks and fail closed (return false) if either root or target cannot be resolved. Untrusted workspace roots are skipped silently, never thrown over. Permission is asserted per directory read via `assertPermission`.
+- **Symlink handling**: symlinked entries that escape the kind root after realpath resolution are excluded. `SKILL.md` and `manifest.json` are also realpath-checked against their contribution directory before read, so an entry-file symlink cannot escape to another path.
+- **Opt-in**: discovery is opt-in — it runs only when the host passes `--discover` or calls `discoverContributions()` explicitly. Default runs perform no filesystem I/O.
+- **No auto-execute**: discovery reads text. It does not `import()`, `require()`, or run contribution code. `registerDiscoveredContributions` registers descriptor stubs whose execution methods throw — the host lifts them into live tools/providers itself.
+- **No auto-activate**: discovery registers skills; it does not select them. Activation requires explicit `RunOptions.activeSkills`, and `toolNames` is still validated against the resolved tool set. Discovery grants no tools, permissions, or provider slots.
+- **No provider scanning**: provider/model discovery stays config/package-driven (Phase 24). See [Provider packages](provider-packages.md).
+- **AGENTS.md / SYSTEM.md are not discovery kinds**: the root-level `AGENTS.md` (workspace) prompt file does not fit the named-subdir scanner and is loaded by a sibling Node loader, `loadSystemPromptFiles` from `@arnilo/prism/node/system-prompts`. See [System prompts](system-prompts.md). The CLI auto-loads `AGENTS.md` in print/json modes; RPC mode does not (host-owned).
+- **Secrets**: the secrets-redaction path is unaffected — discovery reads contribution files, not provider request content. Skill `instructions` flow through normal input assembly and the same redaction pipeline as any system message.
+- **Performance**: one `readdir` per kind-root per origin; missing kind directories are normal (ENOENT-tolerant). Default runs perform no discovery I/O at all. The merged output is inert.
+
+## Related APIs
+
+- [Contribution registries](contribution-registries.md): where discovered envelopes are registered.
+- [Context and skills](context-and-skills.md): `createSkillRegistry` / `resolveActiveSkills` and the `RunOptions.activeSkills` activation that consumes discovered skills.
+- [Extensions](extensions.md): host-provided extensions still register contributions programmatically; discovery is the filesystem-driven complement.
+- [Configuration and manifests](configuration-and-manifests.md): `ManifestContributionDeclaration` / `ManifestContributionKind` shapes used by non-skill entries.
+- [CLI/RPC](cli-rpc.md): the `--discover`, `--discover-kinds`, and `--no-discovery` flags.
+- [System prompts](system-prompts.md): `loadSystemPromptFiles` loads root-level `AGENTS.md` / `SYSTEM.md` — a sibling loader, not a scanner kind.
+- [Security/auth/trust](settings-auth-trust-security.md): `createPathTrustPolicy`, `assertPermission`, and the trust model.

package/docs/contribution-registries.md

@@ -18,15 +18,15 @@ Do not use them as a dependency injection container, manifest loader, settings l
 ## Inputs / request
 
 ```ts
-createContributionRegistry<T>(options?: { label?: string }): ContributionRegistry<T>
-createContributionRegistries(): ContributionRegistries
+createContributionRegistry<T>(options?: { label?: string; duplicate?: "replace" | "error" }): ContributionRegistry<T>
+createContributionRegistries(options?: { duplicate?: "replace" | "error" }): ContributionRegistries
 ```
 
 `ContributionRegistry<T>` methods:
 
 | Method | Input | Result |
 | --- | --- | --- |
-| `register(key, contribution)` | string key and contribution | Stores or replaces the contribution for that key. |
+| `register(key, contribution)` | string key and contribution | Stores/replaces the contribution for that key; throws `Duplicate <label>: <key>` when `duplicate: "error"`. |
 | `get(key)` | string key | Returns the contribution or `undefined`. |
 | `resolve(key)` | string key | Returns the contribution or throws `Unknown <label>: <key>`. |
 | `list()` | none | Returns contributions in insertion order. |
@@ -37,7 +37,7 @@ createContributionRegistries(): ContributionRegistries
 
 Registry calls return plain contribution objects. Unknown `resolve()` calls throw before provider, model, tool, credential, prompt, resource, or session behavior can run. `systemPromptContributions` are inert until a host passes selected values to `AgentConfig.systemPrompt` or `RunOptions.systemPrompt`.
 
-Registering the same key replaces the contribution deterministically. Registries do not emit events by themselves; the extension kernel may emit events when it uses them.
+Registering the same key replaces the contribution deterministically by default. Passing `duplicate: "error"` adds one `Map.has()` check before `set()` and throws `Duplicate <label>: <key>` instead of silently shadowing. Registries do not emit events by themselves; the extension kernel may emit events when it uses them.
 
 ## Request/response example
 
@@ -60,7 +60,7 @@ const tool: ToolDefinition = {
   },
 };
 
-const registries = createContributionRegistries();
+const registries = createContributionRegistries({ duplicate: "error" });
 registries.tools.register(tool.name, tool);
 registries.agents.register("demo", {
   name: "demo",
@@ -87,6 +87,8 @@ void skill;
 - Hosts can use contribution registries directly and skip extension loading entirely.
 - Extension packages should register contributions through the host-provided extension API once the extension kernel is in use.
 - Registry keys are explicit strings. Prefer stable ids/names such as `provider.id`, `tool.name`, `skill.name`, or package-qualified names when collisions matter.
+- Default duplicate policy is `"replace"` for compatibility and deterministic last-write-wins behavior. External apps that load third-party contributions should prefer `duplicate: "error"` to prevent silent shadowing.
+- Migration safety: when moving from legacy all-in-scope capability activation to named `AgentDefinition.tools` / `skills`, enable strict registries first so duplicate third-party names fail during registration instead of changing which capability a name resolves to.
 - Manifest contribution `kind` values match these registry keys. For example, `authMethods` accepts `authMethod` manifest declarations, `providerPackages` accepts `providerPackage`, `providerRequestPolicies` accepts `providerRequestPolicy`, and `systemPromptContributions` accepts `systemPromptContribution`.
 - Manifest and configuration loading are separate APIs; this page only covers in-memory registration.
 - Tool contributions are inert. They are not executable until the host registers selected definitions in an active tool registry and passes that registry to `dispatchToolCall()`.
@@ -96,7 +98,7 @@ void skill;
 
 ## Security and performance notes
 
-- Generic registries are `Map`-backed with O(1) lookup.
+- Generic registries are `Map`-backed with O(1) lookup; strict duplicate checks add one O(1) `Map.has()` during registration only.
 - Registries are explicit objects returned by factories. Prism does not create hidden global contribution registries.
 - Registries must not store resolved credential values, tokens, headers, or secret-bearing settings.
 - `credentialResolvers` may store resolver objects, but resolved credentials must stay at the edge that needs them.
@@ -116,3 +118,4 @@ void skill;
 - [Compaction and retry policies](compaction-and-retry.md): selected compaction strategy and retry policy behavior.
 - [Public contracts](public-contracts.md): contribution contract types stored in these registries.
 - [Credentials and redaction](credentials-and-redaction.md): credential resolver and secret-redaction rules.
+- [Contribution discovery (workspace)](contribution-discovery.md): opt-in directory scanner that fills these registries from `SKILL.md`/`manifest.json`.

package/docs/credentials-and-redaction.md

@@ -95,6 +95,7 @@ console.log(error.message);
 ## Extension and configuration notes
 
 - Hosts and extension packages can implement `CredentialResolver` and pass it explicitly to code that needs credentials.
+- `AgentConfig.credentials` is host-owned metadata for compatibility; `createAgent()` / `session.run()` do not call `credentials.resolve()`. Provider adapters, compaction workers, or request policies should receive and resolve credentials at the provider edge.
 - Use `createExplicitCredentialResolver()` when documenting a fixed order such as runtime override, stored credential, caller-provided env object, then fallback resolver.
 - Use `createEnvCredentialResolver()` only with an object supplied by the host; Prism does not read `process.env` for you.
 - Provider adapters should resolve credentials as late as possible, per request.
@@ -109,6 +110,7 @@ console.log(error.message);
 - Cycle and non-JSON value handling: `redactSecrets()` is cycle-safe via a `WeakSet` visited-set. Self-referential or mutually referenced objects render `"[Circular]"` at the back-reference instead of throwing. `Date` and `RegExp` values are passed through unchanged; `ArrayBuffer` and typed arrays are passed through unchanged; `Map` is normalized to a plain object and `Set` to an array so the output stays JSON-compatible. `errorToErrorInfo()` tolerates a cyclic `error.cause` (rendered via `String()`).
 - Use placeholders in tests and docs. Never commit real tokens.
 - Live provider/worker tests are gated behind explicit environment variables and skipped by default: `PRISM_LIVE_PROVIDER_TESTS`, `PRISM_LIVE_COMPACTION_TESTS`, `PRISM_LIVE_OBSERVATIONAL_MEMORY_TESTS`. Default `npm test` is network-free; do not add ungated network calls to default tests.
+- `AgentConfig.credentials` is not eagerly resolved, serialized into provider requests/events/stores, or passed to loops/compaction by the core runtime.
 - `resolveCredentialValue()` and `createExplicitCredentialResolver()` do not cache values. Add host-side caching only if a real credential source needs it.
 - `refreshOAuthCredential()` only calls the supplied OAuth provider and optional store; it has no built-in persistence or retry loop.