pluribus-context 0.3.36 → 0.3.38

package/CHANGELOG.md

@@ -4,6 +4,14 @@
 
 All notable changes to Pluribus are documented here.
 
+## 0.3.38 - 2026-06-06
+
+- Added `pluribus demo mcp-audit-receipt`, a tiny npm-runnable demo that validates privacy-safe MCP tool-call audit events and low-cardinality usage metrics without logging raw prompts, args, results, tokens, or row data.
+
+## 0.3.37 - 2026-06-06
+
+- Published the canonical top-level Agent Skills layout (`skills/*/SKILL.md`) and backwards-compatible legacy mirrors so external skill registries can keep source links verifiable while package users get the current recipes from npm.
+
 ## 0.3.36 - 2026-06-05
 
 - Added `pluribus demo skill-use-rate`, a tiny npm-runnable demo that validates the packaged Skill use-rate receipt and warns when installed/attached Skills have no observed invocations.

package/README.md

@@ -14,7 +14,7 @@ The original sync workflow is still useful: Pluribus can keep project instructio
 
 It is **not** a persistent memory layer, retrieval system, agent orchestrator, enterprise ContextOps platform, or agent-merging framework. Think evidence for context boundaries: `CLAUDE.md`, `.cursorrules`, `copilot-instructions.md`, `AGENTS.md`, MCP Tool Search, Agent Skills, RAG/code-search, pruning, and compaction — with privacy-safe receipts instead of raw content dumps.
 
-**Reviewer shortcut:** evaluating Pluribus for a list, newsletter, package roundup, or tool directory? Use the [Community Review Packet](docs/community-review-packet.md) for copy-paste directory submission fields, safety/removability notes, feedback links, and disposable 60-second smoke tests. If you only run one command for the cross-tool audit, try `npx --yes pluribus-context@latest audit --json --fidelity-report` to see native discovery surfaces, generic fallbacks, load evidence, duplicate-load selection evidence, manual activation requirements, effective context scope, and semantic differences. For the agent-observability wedge, start with [context-budget receipts](docs/context-budget-receipts.md): privacy-safe evidence for what MCP schemas, skills, memory, subagents, CLI help, retrieval chunks, pruning runs, or compaction summaries crossed an agent boundary. If you want the same idea as a copyable skill, use the [context-receipts Agent Skill recipe](examples/agent-skills/context-receipts/). npm `latest` is currently aligned with the GitHub release; the review packet also documents a GitHub-release smoke fallback for future release-lag windows.
+**Reviewer shortcut:** evaluating Pluribus for a list, newsletter, package roundup, or tool directory? Use the [Community Review Packet](docs/community-review-packet.md) for copy-paste directory submission fields, safety/removability notes, feedback links, and disposable 60-second smoke tests. If you only run one command for the cross-tool audit, try `npx --yes pluribus-context@latest audit --json --fidelity-report` to see native discovery surfaces, generic fallbacks, load evidence, duplicate-load selection evidence, manual activation requirements, effective context scope, and semantic differences. For the agent-observability wedge, start with [context-budget receipts](docs/context-budget-receipts.md): privacy-safe evidence for what MCP schemas, skills, memory, subagents, CLI help, retrieval chunks, pruning runs, or compaction summaries crossed an agent boundary. If you want the same idea as a copyable skill, use the [context-receipts Agent Skill recipe](skills/context-receipts/). npm `latest` is currently aligned with the GitHub release; the review packet also documents a GitHub-release smoke fallback for future release-lag windows.
 
 ---
 
@@ -161,7 +161,7 @@ npx --yes pluribus-context@latest sync --dry-run
 
 If the preview looks right, run `npx --yes pluribus-context@latest sync` to write the tool-specific files.
 
-For a fuller walkthrough, see the [Quickstart](docs/quickstart.md). To enforce generated context files in pull requests, use the [CI audit example](docs/ci-audit-example.md); to catch drift before commits leave your machine, use the [Pre-commit Audit Hook](docs/pre-commit-audit.md). If your repo already has `CLAUDE.md`, `.cursorrules`, Copilot instructions, or `AGENTS.md`, run a [Context Drift Audit](docs/context-drift-audit.md) first, try the intentionally drifted [audit example](examples/context-drift-audit/), then follow [Migrate Existing AI Context Files](docs/migrate-existing-context.md). If you switch between Cursor, Claude Code, Copilot, and terminal agents, try the [Cursor ↔ Claude Code context handoff guide](docs/cursor-claude-context-handoff.md) and its [example source file](examples/context-handoff/pluribus.md). If you run multiple AI sessions on the same project, try the [Coordination Contract guide](docs/coordination-contract.md) and its [example source file](examples/coordination-contract/pluribus.md) to keep event-log/scratchpad protocol rules aligned without turning Pluribus into an orchestrator. If you evaluate code-search, MCP retrieval, RAG-over-notes, or agent memory tools, use the [Orchestration-layer Search Receipts](docs/orchestration-search-receipts.md) sketch to measure retrieved context from the harness layer without asking retrieval tools to inspect whole transcripts. If you are adding agent observability, traces, or OpenTelemetry-style events, start with [Context Receipts for Agent Observability](docs/context-receipts-for-agent-observability.md), then use the [Context Input Evidence](docs/context-input-evidence.md) sketch and its [executable demos](examples/context-input-evidence/) to separate source bytes, canonical text, delivered hashes, post-hoc session-log receipts, skill/plugin invocation receipts, shared-memory retrieval receipts, self-remediating brain/doctor receipts, and OpenTelemetry-style SpanEvents. If you publish AI rules, skills, or instruction bundles as "portable", use the [Portability Fidelity Report](docs/portability-fidelity-report.md) and its [example source file](examples/portability-fidelity/pluribus.md) to make compatibility claims evidence-based instead of self-attested. Before committing shared or generated AI instructions, use the [Context File Review Checklist](docs/context-file-review.md). If you're deciding between Pluribus and a one-way rules converter, see [When to use Pluribus](docs/when-to-use-pluribus.md). If you are debugging "context drift" after compaction or long sessions, start with the [Context Drift Taxonomy](docs/context-drift-taxonomy.md) to separate file drift from runtime precedence drift. If you use MCP memory or knowledge-graph tools, try the [MCP memory handoff demo](docs/memory-mcp-handoff.md) to keep recall/store protocols aligned across AI coding tools without turning Pluribus into a memory server. If your shared-memory or knowledge-graph setup lets agents write durable facts, use [Memory write policy receipts](docs/memory-write-policy-receipts.md) and the [copyable gate](examples/memory-write-policy/) to require proposed diffs, scope, lifecycle, visibility, approval, and privacy checks before one run can teach every harness. If hooks, local gateways, or agent firewalls block risky tool calls, use [Agent firewall denial/audit receipts](docs/agent-firewall-denial-audit.md) and the [copyable checker](examples/agent-firewall-denial-audit/) to split model-visible denial from private operator audit evidence. If you are turning Claude Code/OpenClaw/Cursor into role-based “AI employee” agents with Skills and memory folders, use the [Controlled learning queue](docs/controlled-learning-queue.md) and [copyable example](examples/controlled-learning-queue/) to let agents propose durable memory changes without silently rewriting shared ICP, pricing, compliance, or process assumptions. If `PreCompact` / `PostCompact` or `SessionStart(compact)` workflows decide whether an agent may continue after summarization, use [Compaction resume receipts](docs/compaction-resume-receipts.md) and the [copyable gate](examples/compaction-resume-receipts/) to prove what was summarized, which instruction sources reloaded, what state was lost/kept, and whether `safe_to_resume` is actually true. If an MCP server is healthy but tools are missing in Claude Code/Cursor/Codex, use the [MCP tool visibility receipts](docs/mcp-tool-visibility-receipts.md) checklist to separate launch, handshake, `tools/list`, client catalog, and first invocation failures. If a Claude Code/OpenClaw-style Skill states a hard rule but the run still violates it, use the [Skill policy receipts](docs/skill-policy-receipts.md) guide and [copyable Skill recipe](examples/agent-skills/skill-policy-receipts/) to turn target decisions, refusals, and post-write guards into privacy-safe evidence. If a Skill, plugin resource, MCP instruction, or custom-agent file exists but disappears in ACP/Zed/CLI/chat parity tests, use [Loaded-resource boundary receipts](docs/loaded-resource-boundary.md) and the [copyable checker](examples/loaded-resource-boundary/) to prove discovered, attached, injected, readable, and skipped-resource stages. If long-lived projects keep old specs/TODOs that still match grep but are no longer authoritative, use [Temporal context receipts](docs/temporal-context-receipts.md) and the [copyable current-state example](examples/temporal-context-receipts/) to separate current authority from historical citations before an agent writes code. If AI-generated pull requests are hard to review because diff size hides operational risk, use [AI PR review receipts](docs/ai-pr-review-receipts.md), the [copyable PR template](examples/ai-pr-review-receipts/), and the [GitHub Actions receipt gate](examples/ai-pr-review-receipts/.github/workflows/ai-pr-review-receipt.yml) to review by blast radius: schema/data contracts, async paths, rollout gates, side effects, and ambiguous boundaries. If you delegate work to Codex/Claude Code/Cursor/OpenClaw-style specialist subagents, use [Subagent role receipts](docs/subagent-role-receipts.md) and the [example role definitions](examples/subagent-role-receipts/) to prove the requested role, effective role, loaded instruction source, allowed/refused capabilities, stop point, and next safe action. If you run Claude Code-style dynamic workflows, ultracode, or local LLM gateway orchestration that spawns many agents, use [Dynamic workflow run receipts](docs/dynamic-workflow-run-receipts.md) and the [copyable workflow example](examples/dynamic-workflow-run-receipts/) to prove phases, per-agent roles/models, context loaded/skipped, tool grants, token spend buckets, per-agent fuses, heartbeat, stop reasons, and known gaps. If your workflow routes Explore/Propose/Spec/Design/Tasks/Apply/Verify across OpenCode, Claude Code, Cursor, Codex, or different models, use [Phase-boundary contracts](docs/phase-boundary-contracts.md) and the [copyable Apply→Verify gate](examples/phase-boundary-contract/) to prove allowed input context, output artifact, evidence required before the next phase, dropped context, and stop conditions. If you need CI/reviewers to decide whether an agent handoff can continue, must be reviewed, or should be rejected, use the [Review primitive gate](docs/review-primitive-gate.md), its [copyable gate example](examples/review-primitive-gate/), and the [Claude Code review hook bridge](examples/claude-code-review-hook/) to validate assignment boundaries, approved scope/access changes, required checks, privacy flags, and `complete / partial / unsafe-to-resume` state from CI or Claude Code `TaskCompleted` / `PostCompact` hooks. If Claude Projects, long chats, or compaction make the last clean artifact hard to recover, use [Canonical output receipts](docs/canonical-output-receipts.md) and the [copyable index example](examples/canonical-output-receipts/) to track stable IDs, paths, versions, exact grep phrases, decisions, rejected options, and next actions. If a setup script installs MCP servers, Skills, instruction files, hooks, or plugins across multiple agents, use [Install-plan receipts](docs/install-plan-receipts.md) and the [copyable example](examples/install-plan-receipts/) to prove planned writes, backups, network behavior, and `writes_started=false` before mutation. After a Skill installer runs, use [Skill install/load receipts](docs/skill-install-receipts.md) and the [copyable checker](examples/skill-install-receipts/) to prove source ref, target agents/scopes, discovery/load status, context-cost bucket, and `safe_to_start_session` without logging raw Skill bodies. If you are pruning Skill sprawl after real sessions, use [Skill use-rate receipts](docs/skill-use-rate-receipts.md) and the [copyable checker](examples/skill-use-rate-receipts/) to separate discovered/installed/attached from invoked/acted-on and catch "installed but unused" resources. If you supervise multiple Claude Code/Cursor/Codex/OpenClaw sessions in parallel, use the [Parallel session review ledger](docs/parallel-session-review-ledger.md) and [copyable checker](examples/parallel-session-review-ledger/) to decide which sessions are complete, partial, blocked, or unsafe to resume without trusting an agent summary. If you are reviewing Pluribus for a list, newsletter, or tool directory, use the [Community Review Packet](docs/community-review-packet.md) for directory submission fields, a one-line description, safety notes, and a disposable 60-second smoke test. Maintainers can track package/repo discovery with the [Discovery Smoke Checks](docs/discovery-smoke.md).
+For a fuller walkthrough, see the [Quickstart](docs/quickstart.md). To enforce generated context files in pull requests, use the [CI audit example](docs/ci-audit-example.md); to catch drift before commits leave your machine, use the [Pre-commit Audit Hook](docs/pre-commit-audit.md). If your repo already has `CLAUDE.md`, `.cursorrules`, Copilot instructions, or `AGENTS.md`, run a [Context Drift Audit](docs/context-drift-audit.md) first, try the intentionally drifted [audit example](examples/context-drift-audit/), then follow [Migrate Existing AI Context Files](docs/migrate-existing-context.md). If you switch between Cursor, Claude Code, Copilot, and terminal agents, try the [Cursor ↔ Claude Code context handoff guide](docs/cursor-claude-context-handoff.md) and its [example source file](examples/context-handoff/pluribus.md). If you run multiple AI sessions on the same project, try the [Coordination Contract guide](docs/coordination-contract.md) and its [example source file](examples/coordination-contract/pluribus.md) to keep event-log/scratchpad protocol rules aligned without turning Pluribus into an orchestrator. If you evaluate code-search, MCP retrieval, RAG-over-notes, or agent memory tools, use the [Orchestration-layer Search Receipts](docs/orchestration-search-receipts.md) sketch to measure retrieved context from the harness layer without asking retrieval tools to inspect whole transcripts. If you are adding agent observability, traces, or OpenTelemetry-style events, start with [Context Receipts for Agent Observability](docs/context-receipts-for-agent-observability.md), then use the [Context Input Evidence](docs/context-input-evidence.md) sketch and its [executable demos](examples/context-input-evidence/) to separate source bytes, canonical text, delivered hashes, post-hoc session-log receipts, skill/plugin invocation receipts, shared-memory retrieval receipts, self-remediating brain/doctor receipts, and OpenTelemetry-style SpanEvents. If you publish AI rules, skills, or instruction bundles as "portable", use the [Portability Fidelity Report](docs/portability-fidelity-report.md) and its [example source file](examples/portability-fidelity/pluribus.md) to make compatibility claims evidence-based instead of self-attested. Before committing shared or generated AI instructions, use the [Context File Review Checklist](docs/context-file-review.md). If you're deciding between Pluribus and a one-way rules converter, see [When to use Pluribus](docs/when-to-use-pluribus.md). If you are debugging "context drift" after compaction or long sessions, start with the [Context Drift Taxonomy](docs/context-drift-taxonomy.md) to separate file drift from runtime precedence drift. If you use MCP memory or knowledge-graph tools, try the [MCP memory handoff demo](docs/memory-mcp-handoff.md) to keep recall/store protocols aligned across AI coding tools without turning Pluribus into a memory server. If your shared-memory or knowledge-graph setup lets agents write durable facts, use [Memory write policy receipts](docs/memory-write-policy-receipts.md) and the [copyable gate](examples/memory-write-policy/) to require proposed diffs, scope, lifecycle, visibility, approval, and privacy checks before one run can teach every harness. If hooks, local gateways, or agent firewalls block risky tool calls, use [Agent firewall denial/audit receipts](docs/agent-firewall-denial-audit.md) and the [copyable checker](examples/agent-firewall-denial-audit/) to split model-visible denial from private operator audit evidence. If you are turning Claude Code/OpenClaw/Cursor into role-based “AI employee” agents with Skills and memory folders, use the [Controlled learning queue](docs/controlled-learning-queue.md) and [copyable example](examples/controlled-learning-queue/) to let agents propose durable memory changes without silently rewriting shared ICP, pricing, compliance, or process assumptions. If `PreCompact` / `PostCompact` or `SessionStart(compact)` workflows decide whether an agent may continue after summarization, use [Compaction resume receipts](docs/compaction-resume-receipts.md) and the [copyable gate](examples/compaction-resume-receipts/) to prove what was summarized, which instruction sources reloaded, what state was lost/kept, and whether `safe_to_resume` is actually true. If an MCP server is healthy but tools are missing in Claude Code/Cursor/Codex, use the [MCP tool visibility receipts](docs/mcp-tool-visibility-receipts.md) checklist to separate launch, handshake, `tools/list`, client catalog, and first invocation failures. If a Claude Code/OpenClaw-style Skill states a hard rule but the run still violates it, use the [Skill policy receipts](docs/skill-policy-receipts.md) guide and [copyable Skill recipe](skills/skill-policy-receipts/) to turn target decisions, refusals, and post-write guards into privacy-safe evidence. If a Skill, plugin resource, MCP instruction, or custom-agent file exists but disappears in ACP/Zed/CLI/chat parity tests, use [Loaded-resource boundary receipts](docs/loaded-resource-boundary.md) and the [copyable checker](examples/loaded-resource-boundary/) to prove discovered, attached, injected, readable, and skipped-resource stages. If long-lived projects keep old specs/TODOs that still match grep but are no longer authoritative, use [Temporal context receipts](docs/temporal-context-receipts.md) and the [copyable current-state example](examples/temporal-context-receipts/) to separate current authority from historical citations before an agent writes code. If AI-generated pull requests are hard to review because diff size hides operational risk, use [AI PR review receipts](docs/ai-pr-review-receipts.md), the [copyable PR template](examples/ai-pr-review-receipts/), and the [GitHub Actions receipt gate](examples/ai-pr-review-receipts/.github/workflows/ai-pr-review-receipt.yml) to review by blast radius: schema/data contracts, async paths, rollout gates, side effects, and ambiguous boundaries. If you delegate work to Codex/Claude Code/Cursor/OpenClaw-style specialist subagents, use [Subagent role receipts](docs/subagent-role-receipts.md) and the [example role definitions](examples/subagent-role-receipts/) to prove the requested role, effective role, loaded instruction source, allowed/refused capabilities, stop point, and next safe action. If you run Claude Code-style dynamic workflows, ultracode, or local LLM gateway orchestration that spawns many agents, use [Dynamic workflow run receipts](docs/dynamic-workflow-run-receipts.md) and the [copyable workflow example](examples/dynamic-workflow-run-receipts/) to prove phases, per-agent roles/models, context loaded/skipped, tool grants, token spend buckets, per-agent fuses, heartbeat, stop reasons, and known gaps. If your workflow routes Explore/Propose/Spec/Design/Tasks/Apply/Verify across OpenCode, Claude Code, Cursor, Codex, or different models, use [Phase-boundary contracts](docs/phase-boundary-contracts.md) and the [copyable Apply→Verify gate](examples/phase-boundary-contract/) to prove allowed input context, output artifact, evidence required before the next phase, dropped context, and stop conditions. If you need CI/reviewers to decide whether an agent handoff can continue, must be reviewed, or should be rejected, use the [Review primitive gate](docs/review-primitive-gate.md), its [copyable gate example](examples/review-primitive-gate/), and the [Claude Code review hook bridge](examples/claude-code-review-hook/) to validate assignment boundaries, approved scope/access changes, required checks, privacy flags, and `complete / partial / unsafe-to-resume` state from CI or Claude Code `TaskCompleted` / `PostCompact` hooks. If Claude Projects, long chats, or compaction make the last clean artifact hard to recover, use [Canonical output receipts](docs/canonical-output-receipts.md) and the [copyable index example](examples/canonical-output-receipts/) to track stable IDs, paths, versions, exact grep phrases, decisions, rejected options, and next actions. If a setup script installs MCP servers, Skills, instruction files, hooks, or plugins across multiple agents, use [Install-plan receipts](docs/install-plan-receipts.md) and the [copyable example](examples/install-plan-receipts/) to prove planned writes, backups, network behavior, and `writes_started=false` before mutation. After a Skill installer runs, use [Skill install/load receipts](docs/skill-install-receipts.md) and the [copyable checker](examples/skill-install-receipts/) to prove source ref, target agents/scopes, discovery/load status, context-cost bucket, and `safe_to_start_session` without logging raw Skill bodies. If you are pruning Skill sprawl after real sessions, use [Skill use-rate receipts](docs/skill-use-rate-receipts.md) and the [copyable checker](examples/skill-use-rate-receipts/) to separate discovered/installed/attached from invoked/acted-on and catch "installed but unused" resources. If you supervise multiple Claude Code/Cursor/Codex/OpenClaw sessions in parallel, use the [Parallel session review ledger](docs/parallel-session-review-ledger.md) and [copyable checker](examples/parallel-session-review-ledger/) to decide which sessions are complete, partial, blocked, or unsafe to resume without trusting an agent summary. If you are reviewing Pluribus for a list, newsletter, or tool directory, use the [Community Review Packet](docs/community-review-packet.md) for directory submission fields, a one-line description, safety notes, and a disposable 60-second smoke test. Maintainers can track package/repo discovery with the [Discovery Smoke Checks](docs/discovery-smoke.md).
 
 ### Usage
 
@@ -408,6 +408,7 @@ If you've felt this pain, tell me about your setup. What tools do you use? How d
 - [Composable Contexts](docs/composable-contexts.md) — local/remote imports, merge behavior, and safety rules
 - [MCP Memory Handoff](docs/memory-mcp-handoff.md) — demo for keeping memory recall/store protocols aligned across tool-specific instruction files
 - [MCP Tool Visibility Receipts](docs/mcp-tool-visibility-receipts.md) — checklist for debugging healthy MCP servers whose tools do not appear in the agent client catalog
+- [MCP Runtime Config Receipts](docs/mcp-runtime-config-receipts.md) — live-vs-template evidence for MCP permission/config drift review
 - [Remote Composable Context Imports](docs/remote-composable-context-imports.md) — design notes for lockfile/cache/auth hardening
 - [Context Format Spec](spec/context-format.md) — the `pluribus.md` format reference
 - [Skills Format Spec](spec/skills-format.md) — how adapters work and how to write custom skills

package/bin/pluribus.js

@@ -67,7 +67,7 @@ OPTIONS (watch)
   --debounce      Debounce delay in ms (minimum 300, default 400)
 
 OPTIONS (demo)
-  --receipt       Validate a custom skill use-rate receipt JSON file
+  --receipt       Validate a custom demo receipt JSON file
   --json          Print machine-readable demo results
 
 EXAMPLES
@@ -89,6 +89,8 @@ EXAMPLES
   pluribus watch --tools claude,cursor
   pluribus demo skill-use-rate
   pluribus demo skill-use-rate --json
+  pluribus demo mcp-audit-receipt
+  pluribus demo mcp-audit-receipt --json
 
 DOCS
   https://github.com/caioribeiroclw-pixel/pluribus

package/docs/community-review-packet.md

@@ -30,6 +30,8 @@ Use these fields for directories, awesome lists, or review forms that ask for a
 | One sentence | Emit privacy-safe receipts for what context crossed agent boundaries, and audit or sync the generated instruction files used by Claude Code, Cursor, Copilot, OpenClaw, Windsurf, Continue, Zed, and Bob. |
 | 280-char blurb | Pluribus is an open-source CLI for agent context evidence. It emits privacy-safe receipts for MCP/tools, skills, memory/RAG, pruning and compaction boundaries, then audits or syncs AI instruction files like `CLAUDE.md`, Cursor rules, Copilot instructions, and `AGENTS.md`. |
 | Safe first command | `npx --yes pluribus-context@latest audit` |
+| Agent Skill install smoke | `npx --yes skills add https://github.com/caioribeiroclw-pixel/pluribus --list` |
+| Agent Skill one-shot smoke | `npx --yes skills use https://github.com/caioribeiroclw-pixel/pluribus --skill context-receipts --full-depth` |
 
 ### Awesome-list Markdown entry
 
@@ -98,6 +100,23 @@ Expected result:
 - `sync --dry-run` previews generated context files without writing them.
 - `audit --ci` may exit `1` before generated files are synced; that is expected when outputs are missing or drifted.
 
+## 60-second Agent Skill smoke
+
+Use this when reviewing Pluribus for Skill directories such as Skills CLI, MCP Market, SkillFish, or Agent Skill Exchange. It proves the repo exposes copyable Skill recipes without requiring the reviewer to install them globally:
+
+```bash
+npx --yes skills add https://github.com/caioribeiroclw-pixel/pluribus --list
+npx --yes skills use https://github.com/caioribeiroclw-pixel/pluribus --skill context-receipts --full-depth | sed -n '1,40p'
+npx --yes skills use https://github.com/caioribeiroclw-pixel/pluribus --skill skill-policy-receipts --full-depth | sed -n '1,40p'
+```
+
+Expected result:
+
+- `skills add ... --list` finds `context-receipts` and `skill-policy-receipts`.
+- `skills use ... --skill context-receipts` prints a one-shot Skill prompt for privacy-safe context-boundary receipts.
+- `skills use ... --skill skill-policy-receipts` prints a one-shot Skill prompt for hard-policy receipts before/after writes.
+- No global Skill install is required for this review smoke; it only clones the public repo into the Skills CLI cache and prints the selected Skill body.
+
 ## 60-second native-vs-fallback smoke
 
 Use this when reviewing the fidelity-audit positioning. It demonstrates the difference between a native tool discovery surface and a generic fallback in a clean directory:

package/docs/context-budget-receipts.md

@@ -6,7 +6,7 @@ Privacy-safe receipts for answering a narrow operational question:
 
 This is different from generic token accounting. A context-budget receipt should prove which context surfaces were available, which ones crossed the boundary, which ones stayed deferred or suppressed, and how much budget remained — without exporting raw prompts, tool schemas, tool outputs, memory bodies, file paths, ticket text, secrets, or customer data.
 
-If you want a copyable Agent Skill recipe instead of a spec-style guide, see [`examples/agent-skills/context-receipts/`](../examples/agent-skills/context-receipts/). It turns the receipt pattern into a 60-second smoke checklist for Tool Search, skills, and subagent boundaries.
+If you want a copyable Agent Skill recipe instead of a spec-style guide, see [`skills/context-receipts/`](../skills/context-receipts/). It turns the receipt pattern into a 60-second smoke checklist for Tool Search, skills, and subagent boundaries.
 
 ## When to use this receipt
 

package/docs/mcp-runtime-config-receipts.md

@@ -0,0 +1,91 @@
+# MCP runtime config receipts
+
+MCP config review gets noisy when every file that looks like an MCP config is treated as an active permission change. A live `.mcp.json` can change what Claude Code, Cursor, Codex, Windsurf, Zed, or another client can load. A `.mcp.json.template`, `.sample`, `.example`, catalog entry, or disabled profile usually cannot.
+
+An MCP runtime config receipt records that boundary without dumping secrets or full config bodies. The question is not "does this repository contain MCP-shaped JSON?" The useful question is:
+
+> Can this changed file be loaded by an agent runtime now, and did it change the active tool/command/env permission surface?
+
+## Minimal receipt shape
+
+```json
+{
+  "schema": "pluribus.mcp_runtime_config_receipt.v1",
+  "run_id": "mcp-config-review-2026-06-05T23:00Z",
+  "generated_at": "2026-06-05T23:00:00Z",
+  "repository_ref": "github:example/app@pull/123",
+  "configs": [
+    {
+      "path": ".mcp.json",
+      "client": "claude-code",
+      "source_kind": "runtime_config",
+      "runtime_active": true,
+      "loaded_by": ["claude-code"],
+      "change_kind": "server_added",
+      "permission_surface_changed": true,
+      "sample_config_review": false,
+      "should_alert": true,
+      "evidence": [
+        { "kind": "config_digest", "ref": "sha256:9a1c..." },
+        { "kind": "client_discovery_rule", "ref": "claude-code:.mcp.json" }
+      ],
+      "redacted_env_keys": {
+        "required": ["GITHUB_TOKEN"],
+        "present": [],
+        "missing": ["GITHUB_TOKEN"]
+      }
+    }
+  ]
+}
+```
+
+## Review rule
+
+Use the receipt to keep these cases separate:
+
+| File/change | Runtime-active? | Default review result |
+| --- | --- | --- |
+| `.mcp.json`, Cursor/Windsurf/Zed/Codex/Claude settings that a client loads | yes | alert when server, command, env, or tool surface changes |
+| `.mcp.json.template`, `.sample`, `.example` | no | quiet by default |
+| disabled profile or catalog example | no | quiet by default |
+| sample/template review explicitly enabled | no | label as `sample_config_review`, not `runtime_permission_drift` |
+
+This avoids false positives that teach reviewers to ignore MCP permission checks.
+
+## Privacy boundary
+
+Do record:
+
+- path or reviewed alias;
+- target client/runtime;
+- whether the path is runtime-active;
+- source kind (`runtime_config`, `sample_config`, `disabled_config`, `catalog_example`);
+- change kind (`server_added`, `server_removed`, `command_changed`, `env_changed`, `tools_changed`, `unchanged`);
+- before/after digests or reviewed evidence refs;
+- required/present/missing environment **key names**.
+
+Do **not** record:
+
+- env values, tokens, API keys, cookies, credentials, or private server URLs;
+- raw full config bodies when a digest is enough;
+- prompts, transcripts, tool outputs, or customer data;
+- local absolute paths unless already safe to reveal in review.
+
+## Copyable checker
+
+The [MCP runtime config receipt example](../examples/mcp-runtime-config-receipts/) includes a tiny checker that validates the active-vs-template boundary and warns on review noise.
+
+```bash
+node examples/mcp-runtime-config-receipts/check-mcp-runtime-config-receipt.mjs \
+  examples/mcp-runtime-config-receipts/mcp-runtime-config-receipt.json
+```
+
+Expected output:
+
+```text
+mcp runtime config receipt ok: 3 configs checked, 1 runtime alert, 0 review-noise warnings
+```
+
+## Where this fits
+
+This is adjacent to [MCP tool visibility receipts](mcp-tool-visibility-receipts.md), but it answers an earlier review question. Tool visibility receipts ask why a healthy MCP server did not appear in a client catalog. Runtime config receipts ask whether a changed config file should count as an active permission/config drift event at all.

package/docs/skill-policy-receipts.md

@@ -84,4 +84,4 @@ The useful question is: **where did the boundary proof stop?**
 
 ## Try the copyable Skill recipe
 
-See [`examples/agent-skills/skill-policy-receipts/`](../examples/agent-skills/skill-policy-receipts/) for a small `SKILL.md` recipe you can copy into Claude Code/OpenClaw-style Skill workflows.
+See [`skills/skill-policy-receipts/`](../skills/skill-policy-receipts/) for a small `SKILL.md` recipe you can copy into Claude Code/OpenClaw-style Skill workflows.

package/examples/agent-skills/README.md

@@ -0,0 +1,10 @@
+# Legacy Agent Skill mirrors
+
+The canonical Pluribus Agent Skills live in [`/skills`](../../skills/):
+
+- [`skills/context-receipts/SKILL.md`](../../skills/context-receipts/SKILL.md)
+- [`skills/skill-policy-receipts/SKILL.md`](../../skills/skill-policy-receipts/SKILL.md)
+
+These `examples/agent-skills/*/SKILL.md` files are kept as backwards-compatible mirrors for external skill registries and older links that indexed the original example path before Pluribus adopted the canonical top-level `skills/*/SKILL.md` layout.
+
+New directories and package managers should index `/skills` directly.

package/examples/mcp-audit-receipts/README.md

@@ -0,0 +1,24 @@
+# MCP audit receipt demo
+
+This example validates a privacy-safe audit receipt for MCP `tools/call` activity.
+
+Run from any directory after `pluribus-context@latest` is published:
+
+```bash
+npx --yes pluribus-context@latest demo mcp-audit-receipt
+npx --yes pluribus-context@latest demo mcp-audit-receipt --json
+```
+
+Or validate your own receipt shape:
+
+```bash
+npx --yes pluribus-context@latest demo mcp-audit-receipt --receipt ./mcp-audit-receipt.json
+```
+
+The point is to split:
+
+- **audit events**: correlation IDs, hashed user/token subject, token scopes, tool name, redacted argument shape, status, duration, result shape, and error class;
+- **usage metrics**: low-cardinality counters/histograms such as tool name, status, and token scope;
+- **privacy boundary**: no raw prompts, raw SQL, row data, tokens, tool outputs, or private connection strings in the receipt.
+
+This is for MCP server/gateway operators who need to answer: “who invoked which tool, under what scope, and did it succeed?” without dumping sensitive content into logs.

package/examples/mcp-audit-receipts/mcp-audit-receipt.json

@@ -0,0 +1,70 @@
+{
+  "schema": "pluribus.mcp_tool_call_audit_receipt.v1",
+  "run_id": "mcp-audit-2026-06-06T22:00Z",
+  "generated_at": "2026-06-06T22:00:00Z",
+  "server": {
+    "name": "analytics-mcp",
+    "transport": "http",
+    "version": "1.4.0"
+  },
+  "client": {
+    "name": "claude-desktop",
+    "workspace": "hashed:7f3f0f5f"
+  },
+  "audit_policy": {
+    "raw_arguments": "redacted_shape_only",
+    "raw_results": "redacted_shape_only",
+    "privacy_boundary": "no prompts, raw SQL, row data, tokens, or private connection strings in receipt"
+  },
+  "tool_calls": [
+    {
+      "event": "mcp.tool_call",
+      "request_id": "req_01JY6GATEWAY",
+      "session_id": "sess_01JY6RUN",
+      "user_id_hash": "sha256:0d9b4a1a3f0a6f2fd0dc8aa9d0c6f2b7a35f4f5d0b2a4d3e1e04a8b4b6b2e5d8",
+      "token_subject_hash": "sha256:6aaf4a3b4d10c45c8fd2cb4f3c73b8cde42bb62779b7e1c6a2c5e0dd8d78f4a1",
+      "token_scopes": ["database:read", "query:run"],
+      "tool_name": "query_database",
+      "args_shape": {
+        "database_id": "number",
+        "query": "redacted_sql",
+        "limit": "number"
+      },
+      "status": "ok",
+      "duration_ms": 184,
+      "result_shape": "rows:12 columns:4",
+      "error_class": null
+    },
+    {
+      "event": "mcp.tool_call",
+      "request_id": "req_01JY6DENIED",
+      "session_id": "sess_01JY6RUN",
+      "user_id_hash": "sha256:0d9b4a1a3f0a6f2fd0dc8aa9d0c6f2b7a35f4f5d0b2a4d3e1e04a8b4b6b2e5d8",
+      "token_subject_hash": "sha256:6aaf4a3b4d10c45c8fd2cb4f3c73b8cde42bb62779b7e1c6a2c5e0dd8d78f4a1",
+      "token_scopes": ["database:read"],
+      "tool_name": "update_dashboard",
+      "args_shape": {
+        "dashboard_id": "number",
+        "mutation": "redacted_object"
+      },
+      "status": "denied",
+      "duration_ms": 12,
+      "result_shape": "policy_denial",
+      "error_class": "insufficient_scope"
+    }
+  ],
+  "usage_metrics": [
+    {
+      "name": "mcp_tool_calls_total",
+      "type": "counter",
+      "value": "1",
+      "labels": ["tool_name", "status", "token_scope"]
+    },
+    {
+      "name": "mcp_tool_call_duration_ms",
+      "type": "histogram",
+      "value": "184",
+      "labels": ["tool_name", "status"]
+    }
+  ]
+}

package/examples/mcp-runtime-config-receipts/README.md

@@ -0,0 +1,15 @@
+# MCP runtime config receipts
+
+This example validates the live-vs-template boundary for MCP config review.
+
+```bash
+node check-mcp-runtime-config-receipt.mjs mcp-runtime-config-receipt.json
+```
+
+Expected output:
+
+```text
+mcp runtime config receipt ok: 3 configs checked, 1 runtime alert, 0 review-noise warnings
+```
+
+The alert is intentional: the live `.mcp.json` changes what Claude Code can load. The template and disabled config are quiet by default because they are not runtime-active.

package/examples/mcp-runtime-config-receipts/check-mcp-runtime-config-receipt.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+import fs from 'node:fs'
+import path from 'node:path'
+
+const receiptPath = process.argv[2] || path.join(import.meta.dirname, 'mcp-runtime-config-receipt.json')
+const receipt = JSON.parse(fs.readFileSync(receiptPath, 'utf8'))
+const errors = []
+const warnings = []
+let runtimeAlerts = 0
+
+function fieldName(prefix, field) {
+  return prefix ? `${prefix}.${field}` : field
+}
+
+function requireString(value, field) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    errors.push(`${field} must be a non-empty string`)
+  }
+}
+
+function requireBoolean(value, field) {
+  if (typeof value !== 'boolean') {
+    errors.push(`${field} must be boolean`)
+  }
+}
+
+function requireArray(value, field) {
+  if (!Array.isArray(value)) {
+    errors.push(`${field} must be an array`)
+  }
+}
+
+function requireStringArray(value, field) {
+  requireArray(value, field)
+  for (const [index, item] of (value || []).entries()) {
+    if (typeof item !== 'string' || item.trim() === '') {
+      errors.push(`${field}[${index}] must be a non-empty string`)
+    }
+  }
+}
+
+const runtimeKinds = new Set(['runtime_config'])
+const inactiveKinds = new Set(['sample_config', 'disabled_config', 'catalog_example'])
+const allowedKinds = new Set([...runtimeKinds, ...inactiveKinds])
+const allowedChanges = new Set(['server_added', 'server_removed', 'command_changed', 'env_changed', 'tools_changed', 'unchanged'])
+
+if (receipt.schema !== 'pluribus.mcp_runtime_config_receipt.v1') {
+  errors.push('schema must be pluribus.mcp_runtime_config_receipt.v1')
+}
+
+requireString(receipt.run_id, 'run_id')
+requireString(receipt.generated_at, 'generated_at')
+requireString(receipt.repository_ref, 'repository_ref')
+
+if (!Array.isArray(receipt.configs) || receipt.configs.length === 0) {
+  errors.push('configs must be a non-empty array')
+}
+
+for (const [index, config] of (receipt.configs || []).entries()) {
+  const prefix = `configs[${index}]`
+  requireString(config.path, fieldName(prefix, 'path'))
+  requireString(config.client, fieldName(prefix, 'client'))
+  requireString(config.source_kind, fieldName(prefix, 'source_kind'))
+  requireString(config.change_kind, fieldName(prefix, 'change_kind'))
+  requireBoolean(config.runtime_active, fieldName(prefix, 'runtime_active'))
+  requireBoolean(config.permission_surface_changed, fieldName(prefix, 'permission_surface_changed'))
+  requireBoolean(config.sample_config_review, fieldName(prefix, 'sample_config_review'))
+  requireBoolean(config.should_alert, fieldName(prefix, 'should_alert'))
+  requireStringArray(config.loaded_by, fieldName(prefix, 'loaded_by'))
+
+  if (!allowedKinds.has(config.source_kind)) {
+    errors.push(`${prefix}.source_kind must be one of ${[...allowedKinds].join(', ')}`)
+  }
+
+  if (!allowedChanges.has(config.change_kind)) {
+    errors.push(`${prefix}.change_kind must be one of ${[...allowedChanges].join(', ')}`)
+  }
+
+  if (runtimeKinds.has(config.source_kind) && config.runtime_active !== true) {
+    errors.push(`${prefix}.runtime_active must be true for runtime_config`)
+  }
+
+  if (inactiveKinds.has(config.source_kind) && config.runtime_active !== false) {
+    errors.push(`${prefix}.runtime_active must be false for ${config.source_kind}`)
+  }
+
+  if (config.runtime_active && (!Array.isArray(config.loaded_by) || config.loaded_by.length === 0)) {
+    errors.push(`${prefix}.loaded_by must name at least one client when runtime_active is true`)
+  }
+
+  if (config.runtime_active && config.permission_surface_changed && config.change_kind !== 'unchanged') {
+    runtimeAlerts += 1
+    if (config.should_alert !== true) {
+      errors.push(`${prefix}.should_alert must be true when an active runtime permission surface changed`)
+    }
+  }
+
+  if (!config.runtime_active && config.should_alert && !config.sample_config_review) {
+    warnings.push(`${config.path || prefix} alerts even though it is not runtime-active; use sample_config_review or suppress as template noise`)
+  }
+
+  if (!Array.isArray(config.evidence) || config.evidence.length === 0) {
+    errors.push(`${prefix}.evidence must include at least one privacy-safe evidence ref`)
+  }
+
+  for (const [evidenceIndex, evidence] of (config.evidence || []).entries()) {
+    const evidencePrefix = `${prefix}.evidence[${evidenceIndex}]`
+    requireString(evidence.kind, fieldName(evidencePrefix, 'kind'))
+    requireString(evidence.ref, fieldName(evidencePrefix, 'ref'))
+  }
+
+  const envKeys = config.redacted_env_keys || {}
+  requireStringArray(envKeys.required, fieldName(prefix, 'redacted_env_keys.required'))
+  requireStringArray(envKeys.present, fieldName(prefix, 'redacted_env_keys.present'))
+  requireStringArray(envKeys.missing, fieldName(prefix, 'redacted_env_keys.missing'))
+}
+
+if (errors.length > 0) {
+  console.error('mcp runtime config receipt invalid:')
+  for (const error of errors) console.error(`- ${error}`)
+  process.exit(1)
+}
+
+const warningLabel = warnings.length === 1 ? 'warning' : 'warnings'
+const alertLabel = runtimeAlerts === 1 ? 'alert' : 'alerts'
+console.log(`mcp runtime config receipt ok: ${receipt.configs.length} configs checked, ${runtimeAlerts} runtime ${alertLabel}, ${warnings.length} review-noise ${warningLabel}`)
+for (const warning of warnings) console.log(`- ${warning}`)

package/examples/mcp-runtime-config-receipts/mcp-runtime-config-receipt.json

@@ -0,0 +1,82 @@
+{
+  "schema": "pluribus.mcp_runtime_config_receipt.v1",
+  "run_id": "mcp-config-review-2026-06-05T23:00Z",
+  "generated_at": "2026-06-05T23:00:00Z",
+  "repository_ref": "github:example/app@pull/123",
+  "configs": [
+    {
+      "path": ".mcp.json",
+      "client": "claude-code",
+      "source_kind": "runtime_config",
+      "runtime_active": true,
+      "loaded_by": ["claude-code"],
+      "change_kind": "server_added",
+      "permission_surface_changed": true,
+      "sample_config_review": false,
+      "should_alert": true,
+      "evidence": [
+        {
+          "kind": "config_digest",
+          "ref": "sha256:9a1c4b7d4f1a"
+        },
+        {
+          "kind": "client_discovery_rule",
+          "ref": "claude-code:.mcp.json"
+        }
+      ],
+      "redacted_env_keys": {
+        "required": ["GITHUB_TOKEN"],
+        "present": [],
+        "missing": ["GITHUB_TOKEN"]
+      }
+    },
+    {
+      "path": ".mcp.json.template",
+      "client": "claude-code",
+      "source_kind": "sample_config",
+      "runtime_active": false,
+      "loaded_by": [],
+      "change_kind": "server_added",
+      "permission_surface_changed": true,
+      "sample_config_review": false,
+      "should_alert": false,
+      "evidence": [
+        {
+          "kind": "config_digest",
+          "ref": "sha256:2e76a9c103ab"
+        }
+      ],
+      "redacted_env_keys": {
+        "required": ["EXAMPLE_API_KEY"],
+        "present": [],
+        "missing": ["EXAMPLE_API_KEY"]
+      }
+    },
+    {
+      "path": ".cursor/mcp.disabled.json",
+      "client": "cursor",
+      "source_kind": "disabled_config",
+      "runtime_active": false,
+      "loaded_by": [],
+      "change_kind": "command_changed",
+      "permission_surface_changed": true,
+      "sample_config_review": false,
+      "should_alert": false,
+      "evidence": [
+        {
+          "kind": "config_digest",
+          "ref": "sha256:66f3ec00a12b"
+        },
+        {
+          "kind": "disabled_profile_marker",
+          "ref": "filename:mcp.disabled.json"
+        }
+      ],
+      "redacted_env_keys": {
+        "required": [],
+        "present": [],
+        "missing": []
+      }
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pluribus-context",
-  "version": "0.3.36",
+  "version": "0.3.38",
   "description": "AI context and rules sync CLI for Claude.md, Claude Code, Cursor, and Copilot instructions, with privacy-safe context receipts that prove what memory, tools, skills, compactions, and security findings crossed agent boundaries without logging raw content.",
   "type": "module",
   "homepage": "https://github.com/caioribeiroclw-pixel/pluribus#readme",
@@ -22,6 +22,7 @@
     "spec/",
     "schemas/",
     "examples/",
+    "skills/",
     "CHANGELOG.md"
   ],
   "scripts": {

package/{examples/agent-skills → skills}/context-receipts/README.md

@@ -19,10 +19,10 @@ grep -E 'raw_(schema|query|args|result|output|transcript|text)_copied":false|raw
 
 Then manually check that the receipt contains counts, hashes, ids, buckets, and `audit_gap`, but does **not** contain private prompts, raw schemas, tool args/results, skill bodies, memory bodies, customer names, secrets, or transcript text.
 
-For executable fixture examples, see [`../../context-input-evidence/`](../../context-input-evidence/), including the ToolSearch propagation, pruning, and compaction transaction smokes:
+For executable fixture examples, see [`../../examples/context-input-evidence/`](../../examples/context-input-evidence/), including the ToolSearch propagation, pruning, and compaction transaction smokes:
 
 ```bash
-node ../../context-input-evidence/convert-subagent-toolsearch-propagation-log.mjs
-node ../../context-input-evidence/convert-pruning-log.mjs
-node ../../context-input-evidence/convert-compaction-transaction-log.mjs
+node ../../examples/context-input-evidence/convert-subagent-toolsearch-propagation-log.mjs
+node ../../examples/context-input-evidence/convert-pruning-log.mjs
+node ../../examples/context-input-evidence/convert-compaction-transaction-log.mjs
 ```

package/skills/context-receipts/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: context-receipts
+description: Emit privacy-safe receipts for context selection, deferral, hydration, compaction, pruning, delegation, usage attribution, and boundary handoffs.
+---
+
+# Context Receipts
+
+Use this skill when an agent workflow claims to save context by selecting, deferring, hydrating, summarizing, compacting, pruning, delegating, attributing usage, or isolating context.
+
+The job is not to log the private content. The job is to emit a small receipt that lets a reviewer answer:
+
+> what crossed the context boundary, what stayed out, and what audit gap remains?
+
+## Privacy defaults
+
+Never include raw prompts, raw tool schemas, raw tool arguments, raw tool results, raw skill bodies, memory bodies, secrets, customer names, or full transcripts in the receipt.
+
+Prefer:
+
+- stable ids or hashed ids;
+- counts and token/line buckets;
+- categorical reasons;
+- explicit booleans for raw content copied/not copied;
+- before/after context budget buckets;
+- an `audit_gap` field when the receipt proves routing but not semantic correctness.
+
+## 60-second Tool Search smoke
+
+For MCP Tool Search, lazy tool loading, or progressive disclosure, emit enough evidence to answer these seven checks:
+
+1. **Index-only startup:** did the session load a compact tool/server index instead of all full schemas?
+2. **Search/routing:** what hashed query/category or routing reason selected candidate tools?
+3. **Hydration:** which full tool definition was loaded, why, and how many definitions stayed suppressed?
+4. **Call:** which server/tool id was invoked, with argument/result redaction status and success/error status?
+5. **Boundary:** if a manager subagent or child agent was used, did raw child output return to the parent?
+6. **Budget:** what were the startup and post-hydration context-token buckets?
+7. **Audit gap:** what is not proven, such as whether the selected tool was semantically optimal?
+
+Minimal JSONL event names:
+
+```jsonl
+{"event":"mcp.tool_index.loaded","loaded_server_count":12,"loaded_tool_index_count":84,"full_schema_count":0,"suppressed_tool_count":84,"raw_schema_copied":false,"startup_token_bucket":"lt_1k"}
+{"event":"mcp.tool_search.performed","query_hash":"sha256:...","query_category":"repo_search","candidate_tool_count":5,"selected_tool_id":"github.search_code","raw_query_copied":false}
+{"event":"mcp.tool_definition.loaded","tool_id":"github.search_code","hydrate_reason":"selected_after_tool_search","suppressed_tool_count":83,"definition_token_bucket":"1k_2k","raw_schema_copied":false}
+{"event":"mcp.tool_call.completed","tool_id":"github.search_code","args_hash":"sha256:...","result_token_bucket":"2k_4k","raw_args_copied":false,"raw_result_copied":false,"status":"ok"}
+```
+
+## Skill / prompt context smoke
+
+For skills, rules, AGENTS.md overlays, or instruction files, answer:
+
+- which index/listing entered the session;
+- which full skill/rule/instruction body was selected;
+- which candidates were suppressed and why;
+- whether the body was loaded at session start, after a search, or after an explicit command;
+- source hash, delivered hash, and canonical form when available;
+- whether the skill/instruction text was copied into the receipt.
+
+Minimal event names:
+
+- `context.skill.registry.index.loaded`
+- `context.skill.registry.skill.read`
+- `context.skill.registry.skill.injected`
+- `context.input.loaded`
+- `context.input.candidate_suppressed`
+
+## Per-agent MCP injection smoke
+
+For role-specific subagents or per-agent MCP configs, prove the policy boundary before debugging model quality:
+
+- which subagent role/session requested tools;
+- which MCP servers were available to that role;
+- which servers were explicitly excluded before boot;
+- whether startup loaded full schemas or only a compact index;
+- how many tool definitions stayed deferred/suppressed; and
+- the startup token bucket after policy was applied.
+
+Minimal JSONL event names:
+
+```jsonl
+{"event":"subagent.mcp_policy.applied","subagent_role":"testing","available_server_count":2,"available_servers_hash":"sha256:...","excluded_server_count":5,"excluded_servers_hash":"sha256:...","policy_source":"role_config","raw_server_names_copied":false}
+{"event":"subagent.context_boot.evaluated","subagent_role":"testing","loaded_tool_definition_count":0,"deferred_tool_definition_count":48,"startup_token_bucket":"50k_75k","raw_schema_copied":false,"audit_gap":"proves injection boundary, not tool relevance"}
+```
+
+## ToolSearch propagation smoke
+
+For subagents that should inherit MCP through `ToolSearch`, distinguish policy, declaration, and runtime filtering:
+
+- did the parent/orchestrator intend to expose MCP or exclude it for this subagent?
+- was the subagent spawned immediately or after parent tool calls/orchestration work?
+- was the `tools:` declaration wildcard, explicit include, or exclusion style?
+- was `ToolSearch` declared and was it actually exposed in the subagent tool surface?
+- did MCP servers/tool definitions stay deferred, or did the channel collapse to zero?
+- was the agent registry loaded at session boot, making newly added agent files invisible until restart?
+
+Minimal JSONL event names:
+
+```jsonl
+{"event":"subagent.toolsearch.propagation.evaluated","spawn_path":"Task","tools_declaration_shape":"enumerated_include","toolsearch_declared":false,"toolsearch_exposed":false,"mcp_servers_available_bucket":"0","deferred_tool_definitions_bucket":"0","filtered_by":"frontmatter_tools_policy_or_runtime_filter","raw_tool_schemas_copied":false}
+{"event":"subagent.toolsearch.matrix.completed","tested_axis":"tools_frontmatter_shape","audit_gap":"proves ToolSearch exposure, not semantic tool relevance or runtime call success"}
+```
+
+## Retrieval / code-search smoke
+
+For semantic code search, repo RAG, or MCP tools such as Claude Context, separate "search returned" from "agent context loaded":
+
+- which index snapshot/version was used, without raw local codebase paths;
+- what query/category/filter identity selected the candidates, without raw query text;
+- which result ids/chunk hashes were returned, with rank, score bucket, stale flag, duplicate marker, path hash/extension, and range bucket;
+- which returned chunks were actually loaded into the agent context;
+- which chunks were suppressed as duplicate, stale, clipped, policy-blocked, or over budget;
+- whether raw code, raw prompts, raw paths, customer names, URLs, secrets, and ticket text stayed out of the receipt;
+- the audit gap: this proves retrieval/loading boundaries, not semantic answer quality.
+
+Minimal JSONL event names:
+
+```jsonl
+{"event":"code.index.snapshot.used","snapshot_id_hash":"sha256:...","codebase_path_hash":"sha256:...","indexed_chunk_count_bucket":"over_1k","raw_codebase_path_copied":false}
+{"event":"code.search.performed","query_hash":"sha256:...","query_category":"auth_debug","candidate_count_bucket":"over_1k","raw_query_copied":false}
+{"event":"code.search.result.returned","rank":1,"chunk_id_hash":"sha256:...","chunk_text_hash":"sha256:...","path_hash":"sha256:...","score_bucket":"high","stale":false,"raw_code_copied":false}
+{"event":"context.input.loaded","kind":"retrieved_code_chunks","loaded_chunk_count":3,"suppressed_chunk_count":2,"suppression_reasons":["duplicate","stale_snapshot_chunk"],"raw_code_copied":false}
+```
+
+## Usage attribution smoke
+
+For `/usage`, `/context`, `/doctor`, or other context-budget breakdowns, map each displayed category to evidence that can be reviewed without exposing private content:
+
+- what measurement window was used;
+- which categories were attributed, such as skills, subagents, plugins, MCP servers, rules, memory, or project files;
+- which components were loaded, deferred, hydrated, suppressed, pruned, or rolled back;
+- before/after or current token/cost buckets by category;
+- whether raw skill bodies, prompts, MCP schemas, tool outputs, and file paths were excluded;
+- the remaining audit gap, such as not proving semantic usefulness of a high-cost component.
+
+Minimal JSONL event names:
+
+```jsonl
+{"event":"context.usage.window.measured","window":"current_session","total_token_bucket":"100k_150k","raw_prompts_copied":false}
+{"event":"context.usage.category.attributed","category":"mcp_server","component_hash":"sha256:...","loaded_token_bucket":"10k_25k","deferred_definition_count":42,"hydrated_definition_count":3,"raw_schema_copied":false}
+{"event":"context.usage.breakdown.completed","categories":["skills","subagents","plugins","mcp_server"],"audit_gap":"proves attribution buckets, not whether each component was necessary"}
+```
+
+## Pruning / compaction smoke
+
+For context-cleaning, pruning, compaction, or doctor/guard tools, answer:
+
+- what prescription/trigger started the run;
+- which strategies changed context and which candidates were protected;
+- before/after token and byte buckets;
+- whether summaries, behavioral digests, team messages, and backups were preserved;
+- whether private transcript text, raw tool output, file paths, secrets, and customer text were excluded from the receipt;
+- the remaining audit gap, such as not proving semantic quality of the pruned text.
+
+Minimal JSONL event names:
+
+```jsonl
+{"event":"context.prune.started","prescription":"balanced","trigger":"manual_dry_run","before_token_bucket":"150k_200k","raw_transcript_copied":false}
+{"event":"context.prune.strategy.evaluated","strategy":"tool-output-trim","candidate_bucket":"10_25","changed_bucket":"5_10","protected_bucket":"1_5","raw_tool_output_copied":false}
+{"event":"context.prune.completed","after_token_bucket":"75k_100k","backup_verified":true,"protected_summary_count":2,"raw_text_copied":false,"audit_gap":"proves pruning/protection counts, not semantic disposability"}
+```
+
+For failed compaction, also prove transaction safety:
+
+- did the summary call succeed, fail, or timeout;
+- was a candidate summary validated before any swap;
+- did the harness commit a context swap or preserve the original context;
+- were deferred-tool registries and system-reminder queues restored on rollback;
+- did stale system reminders/tool results replay as fresh state;
+- was post-token metadata recorded as success even though summary failed.
+
+Minimal JSONL event names:
+
+```jsonl
+{"event":"context.compaction.summary.attempted","summary_call_status":"failed_rate_limited","candidate_summary_available":false,"raw_error_copied":false}
+{"event":"context.compaction.rollback.completed","swap_committed":false,"original_context_preserved":true,"deferred_tool_registry_restored":true,"system_reminder_queue_restored":true,"replayed_system_reminder_count":0}
+{"event":"context.compaction.transaction.completed","status":"rolled_back","authoritative_state":"pre_compaction_context","post_tokens_recorded_as_success":false,"raw_context_copied":false}
+```
+
+## Subagent / manager boundary smoke
+
+For subagents, manager agents, or child workers, answer:
+
+- what task was delegated, by category and hashed objective;
+- what large output was captured by the child, as line/token buckets;
+- what bounded summary returned to the parent;
+- whether raw child output, tool results, or MCP schemas entered the parent context;
+- the remaining audit gap.
+
+Minimal event names:
+
+- `subagent.delegation.requested`
+- `subagent.tool_output.captured`
+- `subagent.summary.returned`
+- `parent.context_budget.evaluated`
+
+## Good receipt test
+
+A receipt is useful if a maintainer can debug one of these failures without seeing private content:
+
+- the agent never found the right tool/skill;
+- the full definition loaded too early;
+- too many definitions stayed in context;
+- a child/subagent saved no budget because raw output returned to the parent;
+- compaction/pruning happened but no one can prove what was changed, protected, backed up, summarized, or dropped.
+
+A receipt is not enough if it only says “Tool Search enabled” or “used subagent”. It must prove the boundary behavior.

package/{examples/agent-skills → skills}/skill-policy-receipts/README.md

@@ -19,4 +19,4 @@ The receipt should prove:
 - post-write guard passed or failed;
 - no raw prompt, code, secret, customer data, stack trace, or full transcript was logged.
 
-Related guide: [`docs/skill-policy-receipts.md`](../../../docs/skill-policy-receipts.md).
+Related guide: [`docs/skill-policy-receipts.md`](../../docs/skill-policy-receipts.md).

package/skills/skill-policy-receipts/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: skill-policy-receipts
+description: Use when a task must obey a hard project policy, such as "do not generate tests for internal services", "do not call production APIs", or "do not edit generated files". Emits a privacy-safe receipt before writes and after guard checks.
+---
+
+# Skill Policy Receipts
+
+This Skill turns natural-language guardrails into an inspectable policy receipt.
+
+## Preflight: decide before writing
+
+Before creating or editing files:
+
+1. List intended targets using coarse paths or globs.
+2. For each target, decide `allowed` or `refused`.
+3. Give a short reason.
+4. If any target is refused, stop before writing.
+5. Emit a receipt with `write_started=false` and `stopped_at="policy_refused"`.
+
+Receipt shape:
+
+```json
+{
+  "receipt_type": "skill.policy.v1",
+  "skill": "skill-policy-receipts",
+  "policy_scope": "<short policy name>",
+  "targets": [
+    {
+      "target": "<coarse path or glob>",
+      "decision": "allowed|refused",
+      "reason": "<short reason>"
+    }
+  ],
+  "write_started": false,
+  "post_write_guard": "not_run",
+  "stopped_at": "policy_refused|all_targets_allowed"
+}
+```
+
+Do not include raw prompts, code, secrets, customer data, stack traces, or full tool output.
+
+## Write only after all targets are allowed
+
+If every target is allowed:
+
+1. Emit or state `stopped_at="all_targets_allowed"`.
+2. Perform the write.
+3. Run the configured post-write guard.
+4. Emit whether the guard passed or failed.
+
+Post-write receipt shape:
+
+```json
+{
+  "receipt_type": "skill.policy.v1",
+  "skill": "skill-policy-receipts",
+  "policy_scope": "<short policy name>",
+  "write_started": true,
+  "post_write_guard": "passed|failed|not_configured",
+  "stopped_at": "guard_passed|guard_failed"
+}
+```
+
+## Example policy: no internal-service unit tests
+
+Policy:
+
+> Do not generate unit tests for internal services. If the requested test imports `internal/`, `@/internal`, or a known private service module, refuse before writing and explain the safer target.
+
+Example guard:
+
+```bash
+grep -R "from ['\"]\.\./\.\./internal\|from ['\"]@/internal\|require(['\"]@/internal" \
+  -- '*test.*' '*spec.*'
+```
+
+If the grep finds a match in generated tests, stop and report `post_write_guard="failed"`.

package/src/commands/demo.js

@@ -7,7 +7,11 @@ import * as path from 'path'
 import { fileURLToPath } from 'url'
 
 const DEFAULT_DEMO = 'skill-use-rate'
+const SKILL_USE_RATE_DEMO = 'skill-use-rate'
+const MCP_AUDIT_RECEIPT_DEMO = 'mcp-audit-receipt'
+const AVAILABLE_DEMOS = [SKILL_USE_RATE_DEMO, MCP_AUDIT_RECEIPT_DEMO]
 const SKILL_USE_RATE_SCHEMA = 'pluribus.skill_use_rate_receipt.v1'
+const MCP_AUDIT_RECEIPT_SCHEMA = 'pluribus.mcp_tool_call_audit_receipt.v1'
 
 /**
  * @param {Record<string, string | boolean>} args
@@ -16,29 +20,42 @@ const SKILL_USE_RATE_SCHEMA = 'pluribus.skill_use_rate_receipt.v1'
 export async function runDemo(args, positional = []) {
   const demoName = positional[0] || DEFAULT_DEMO
 
-  if (demoName !== DEFAULT_DEMO) {
-    console.error(`❌ Unknown demo: ${demoName}`)
-    console.error('   Available demos: skill-use-rate')
-    process.exit(1)
+  switch (demoName) {
+    case SKILL_USE_RATE_DEMO:
+      return runSkillUseRateDemo(args)
+    case MCP_AUDIT_RECEIPT_DEMO:
+      return runMcpAuditReceiptDemo(args)
+    default:
+      console.error(`❌ Unknown demo: ${demoName}`)
+      console.error(`   Available demos: ${AVAILABLE_DEMOS.join(', ')}`)
+      process.exit(1)
   }
+}
 
-  const receiptPath = typeof args.receipt === 'string' && args.receipt.trim()
-    ? path.resolve(process.cwd(), args.receipt)
-    : bundledSkillUseRateReceiptPath()
-
-  let receipt
+function readReceipt(receiptPath, label) {
   try {
-    receipt = JSON.parse(fs.readFileSync(receiptPath, 'utf8'))
+    return JSON.parse(fs.readFileSync(receiptPath, 'utf8'))
   } catch (err) {
-    console.error(`❌ Could not read skill use-rate receipt at ${receiptPath}: ${err.message}`)
+    console.error(`❌ Could not read ${label} receipt at ${receiptPath}: ${err.message}`)
     process.exit(1)
   }
+}
 
+function selectedReceiptPath(args, defaultPath) {
+  return typeof args.receipt === 'string' && args.receipt.trim()
+    ? path.resolve(process.cwd(), args.receipt)
+    : defaultPath
+}
+
+function runSkillUseRateDemo(args) {
+  const receiptPath = selectedReceiptPath(args, bundledSkillUseRateReceiptPath())
+  const receipt = readReceipt(receiptPath, 'skill use-rate')
   const result = validateSkillUseRateReceipt(receipt)
+
   if (Boolean(args.json)) {
     console.log(JSON.stringify({
       ok: result.errors.length === 0,
-      demo: DEFAULT_DEMO,
+      demo: SKILL_USE_RATE_DEMO,
       receipt: path.relative(process.cwd(), receiptPath) || receiptPath,
       summary: result.summary,
       warnings: result.warnings,
@@ -65,10 +82,48 @@ export async function runDemo(args, positional = []) {
   if (result.errors.length > 0) process.exit(1)
 }
 
+function runMcpAuditReceiptDemo(args) {
+  const receiptPath = selectedReceiptPath(args, bundledMcpAuditReceiptPath())
+  const receipt = readReceipt(receiptPath, 'MCP audit')
+  const result = validateMcpAuditReceipt(receipt)
+
+  if (Boolean(args.json)) {
+    console.log(JSON.stringify({
+      ok: result.errors.length === 0,
+      demo: MCP_AUDIT_RECEIPT_DEMO,
+      receipt: path.relative(process.cwd(), receiptPath) || receiptPath,
+      summary: result.summary,
+      warnings: result.warnings,
+      errors: result.errors,
+    }, null, 2))
+  } else {
+    console.log('🧪 Pluribus demo: MCP audit receipt')
+    console.log(`   Receipt: ${path.relative(process.cwd(), receiptPath) || receiptPath}`)
+    console.log('')
+
+    if (result.errors.length === 0) {
+      console.log(`✅ MCP audit receipt ok: ${result.summary.toolCallCount} tool calls, ${result.summary.auditEventCount} audit events, ${result.summary.metricCount} metrics`)
+      for (const warning of result.warnings) console.log(`   • ${warning}`)
+      console.log('')
+      console.log('Why this matters: production MCP needs audit events and low-cardinality metrics, not raw prompt/tool dumps. Prove who invoked which tool, under which scope, with redacted argument/result shape.')
+      console.log('Try your own receipt: pluribus demo mcp-audit-receipt --receipt path/to/mcp-audit-receipt.json')
+    } else {
+      console.error('❌ MCP audit receipt invalid:')
+      for (const error of result.errors) console.error(`   • ${error}`)
+    }
+  }
+
+  if (result.errors.length > 0) process.exit(1)
+}
+
 function bundledSkillUseRateReceiptPath() {
   return fileURLToPath(new URL('../../examples/skill-use-rate-receipts/skill-use-rate-receipt.json', import.meta.url))
 }
 
+function bundledMcpAuditReceiptPath() {
+  return fileURLToPath(new URL('../../examples/mcp-audit-receipts/mcp-audit-receipt.json', import.meta.url))
+}
+
 export function validateSkillUseRateReceipt(receipt) {
   const errors = []
   const warnings = []
@@ -153,3 +208,102 @@ export function validateSkillUseRateReceipt(receipt) {
     },
   }
 }
+
+export function validateMcpAuditReceipt(receipt) {
+  const errors = []
+  const warnings = []
+
+  function requireString(value, field) {
+    if (typeof value !== 'string' || value.trim() === '') {
+      errors.push(`${field} must be a non-empty string`)
+    }
+  }
+
+  function requireArray(value, field) {
+    if (!Array.isArray(value) || value.length === 0) {
+      errors.push(`${field} must be a non-empty array`)
+    }
+  }
+
+  function requireNonNegativeNumber(value, field) {
+    if (typeof value !== 'number' || Number.isNaN(value) || value < 0) {
+      errors.push(`${field} must be a non-negative number`)
+    }
+  }
+
+  if (receipt.schema !== MCP_AUDIT_RECEIPT_SCHEMA) {
+    errors.push(`schema must be ${MCP_AUDIT_RECEIPT_SCHEMA}`)
+  }
+
+  requireString(receipt.run_id, 'run_id')
+  requireString(receipt.generated_at, 'generated_at')
+  requireString(receipt.server?.name, 'server.name')
+  requireString(receipt.server?.transport, 'server.transport')
+  requireString(receipt.client?.name, 'client.name')
+  requireString(receipt.audit_policy?.raw_arguments, 'audit_policy.raw_arguments')
+  requireString(receipt.audit_policy?.raw_results, 'audit_policy.raw_results')
+  requireString(receipt.audit_policy?.privacy_boundary, 'audit_policy.privacy_boundary')
+  requireArray(receipt.tool_calls, 'tool_calls')
+  requireArray(receipt.usage_metrics, 'usage_metrics')
+
+  if (receipt.audit_policy?.raw_arguments !== 'redacted_shape_only') {
+    errors.push('audit_policy.raw_arguments must be redacted_shape_only')
+  }
+  if (receipt.audit_policy?.raw_results !== 'redacted_shape_only') {
+    errors.push('audit_policy.raw_results must be redacted_shape_only')
+  }
+
+  const lowCardinalityMetricLabels = new Set(['tool_name', 'status', 'token_scope', 'user_type'])
+
+  for (const [index, call] of (receipt.tool_calls || []).entries()) {
+    const prefix = `tool_calls[${index}]`
+    requireString(call.event, `${prefix}.event`)
+    requireString(call.request_id, `${prefix}.request_id`)
+    requireString(call.session_id, `${prefix}.session_id`)
+    requireString(call.user_id_hash, `${prefix}.user_id_hash`)
+    requireString(call.token_subject_hash, `${prefix}.token_subject_hash`)
+    requireArray(call.token_scopes, `${prefix}.token_scopes`)
+    requireString(call.tool_name, `${prefix}.tool_name`)
+    requireString(call.status, `${prefix}.status`)
+    requireNonNegativeNumber(call.duration_ms, `${prefix}.duration_ms`)
+    requireString(call.result_shape, `${prefix}.result_shape`)
+
+    if (call.event !== 'mcp.tool_call') errors.push(`${prefix}.event must be mcp.tool_call`)
+    if (!['ok', 'empty', 'error', 'timeout', 'denied'].includes(call.status)) {
+      errors.push(`${prefix}.status must be one of ok|empty|error|timeout|denied`)
+    }
+    if (!call.args_shape || typeof call.args_shape !== 'object' || Array.isArray(call.args_shape)) {
+      errors.push(`${prefix}.args_shape must be an object with redacted argument types/shapes`)
+    }
+    if (typeof call.args_preview === 'string' || typeof call.result_preview === 'string') {
+      errors.push(`${prefix} must not include raw args/results previews; use args_shape/result_shape instead`)
+    }
+    if (call.error_class != null && typeof call.error_class !== 'string') {
+      errors.push(`${prefix}.error_class must be string or null`)
+    }
+  }
+
+  for (const [index, metric] of (receipt.usage_metrics || []).entries()) {
+    const prefix = `usage_metrics[${index}]`
+    requireString(metric.name, `${prefix}.name`)
+    requireString(metric.type, `${prefix}.type`)
+    requireString(metric.value, `${prefix}.value`)
+    requireArray(metric.labels, `${prefix}.labels`)
+
+    for (const label of metric.labels || []) {
+      if (!lowCardinalityMetricLabels.has(label)) {
+        warnings.push(`${prefix}.labels includes high-cardinality label ${label}; prefer ${[...lowCardinalityMetricLabels].join(', ')}`)
+      }
+    }
+  }
+
+  return {
+    errors,
+    warnings,
+    summary: {
+      toolCallCount: Array.isArray(receipt.tool_calls) ? receipt.tool_calls.length : 0,
+      auditEventCount: Array.isArray(receipt.tool_calls) ? receipt.tool_calls.length : 0,
+      metricCount: Array.isArray(receipt.usage_metrics) ? receipt.usage_metrics.length : 0,
+    },
+  }
+}

package/src/utils/version.js

@@ -1 +1 @@
-export const VERSION = '0.3.36'
+export const VERSION = '0.3.38'