pluribus-context 0.3.35 → 0.3.37

package/CHANGELOG.md

@@ -4,6 +4,18 @@
 
 All notable changes to Pluribus are documented here.
 
+## 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.
+
+
+- Added a GitHub Actions AI PR review receipt gate example that validates `agent.review_primitive_receipt.v1` evidence for AI-authored pull requests.
+- Added a memory write policy receipt guide and executable gate for approving or quarantining shared-memory updates before they become durable context across agents.
+
 ## 0.3.35 - 2026-05-31
 
 - Added canonical-output receipts for preserving the last clean version of an artifact as versioned evidence instead of treating old chats as source of truth.

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 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 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) and the [copyable PR template](examples/ai-pr-review-receipts/) 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 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. 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

@@ -10,6 +10,7 @@ import { runSync } from '../src/commands/sync.js'
 import { runValidate } from '../src/commands/validate.js'
 import { runWatch } from '../src/commands/watch.js'
 import { runAudit } from '../src/commands/audit.js'
+import { runDemo } from '../src/commands/demo.js'
 import { parseArgs } from '../src/utils/args.js'
 import { SUPPORTED_TOOLS } from '../src/skills/built-in.js'
 import { VERSION } from '../src/utils/version.js'
@@ -28,6 +29,7 @@ COMMANDS
   validate  Validate pluribus.md before syncing
   audit     Compare generated tool files with pluribus.md without writing
   watch     Watch pluribus.md and auto-sync after changes
+  demo      Run tiny packaged demos from npm without cloning the repo
   help      Show this help message
 
 OPTIONS (init)
@@ -64,6 +66,10 @@ OPTIONS (watch)
   --once          Exit after the first change-triggered sync
   --debounce      Debounce delay in ms (minimum 300, default 400)
 
+OPTIONS (demo)
+  --receipt       Validate a custom skill use-rate receipt JSON file
+  --json          Print machine-readable demo results
+
 EXAMPLES
   pluribus init
   pluribus init --dry-run
@@ -81,6 +87,8 @@ EXAMPLES
   pluribus audit --strict --github-annotations
   pluribus audit --json --fidelity-report
   pluribus watch --tools claude,cursor
+  pluribus demo skill-use-rate
+  pluribus demo skill-use-rate --json
 
 DOCS
   https://github.com/caioribeiroclw-pixel/pluribus
@@ -92,6 +100,7 @@ const COMMAND_FLAGS = {
   validate: new Set(['source', 'update-imports']),
   audit: new Set(['source', 'tools', 'update-imports', 'strict', 'ci', 'json', 'output', 'github-annotations', 'fidelity-report']),
   watch: new Set(['source', 'tools', 'update-imports', 'dry-run', 'once', 'debounce']),
+  demo: new Set(['receipt', 'json']),
 }
 
 function getFlagNames(argv) {
@@ -152,6 +161,9 @@ async function main() {
       case 'audit':
         await runAudit(parsedArgs)
         break
+      case 'demo':
+        await runDemo(parsedArgs, commandArgs.filter((arg) => !arg.startsWith('--') && !Object.values(parsedArgs).includes(arg)))
+        break
       default:
         console.error(`❌ Unknown command: "${command}"`)
         console.log(`Run \`pluribus help\` for usage.`)

package/docs/agent-firewall-denial-audit.md

@@ -0,0 +1,95 @@
+# Agent firewall denial/audit receipts
+
+Claude Code hooks, OpenClaw policies, local MCP gateways, and agent firewalls can block destructive commands, outbound calls, or risky writes before an agent executes them.
+
+The hard part is not only blocking. If the model sees a vague failure, it may keep trying variants. If the model sees too much detail, the denial can leak secrets, raw policy logic, or bypass hints.
+
+Use a split receipt:
+
+1. **Model-visible denial envelope** — minimal structured feedback the agent can act on safely.
+2. **Operator audit record** — privacy-safe evidence for the human/operator, CI, or local dashboard.
+
+## Model-visible denial envelope
+
+The model should receive enough information to stop, ask, or choose a safe alternative, without exposing raw secrets, raw commands, or sensitive policy internals.
+
+```json
+{
+  "type": "agent_firewall_denial.v1",
+  "decision": "blocked",
+  "reasonClass": "destructive_git",
+  "requiresApproval": true,
+  "safeAlternative": "Explain the planned git operation and wait for explicit approval.",
+  "retrySafety": "unsafe_until_approved",
+  "correlationId": "deny_2026_06_02_2200_7f3a"
+}
+```
+
+Good `reasonClass` values are coarse and non-secret:
+
+- `destructive_git`
+- `filesystem_write_out_of_scope`
+- `outbound_after_secret_read`
+- `credential_exposure_risk`
+- `package_publish_requires_approval`
+- `unknown_policy_boundary`
+
+The denial should avoid:
+
+- raw shell commands;
+- raw file contents;
+- secret values or secret-looking substrings;
+- full policy source;
+- exact bypass instructions;
+- absolute private paths when a path class or hash is enough.
+
+## Operator audit record
+
+The operator needs more detail, but still not raw prompts, code, or secrets. Prefer hashes, policy ids, classes, and booleans.
+
+```json
+{
+  "type": "agent_firewall_operator_audit.v1",
+  "decision": "blocked",
+  "correlationId": "deny_2026_06_02_2200_7f3a",
+  "tool": "Bash",
+  "commandHash": "sha256:0e5751c026e543b2a6f2b4d7a7c8d8e5b81b69c5b9f7db2a5b94f31f987e7f44",
+  "cwdHash": "sha256:dcdb704109a454784b81229d2b05f368692e758bfa33cb61d04c1b93791b0273",
+  "matchedPolicyIds": ["git.destructive.requires_approval"],
+  "sessionTaint": {
+    "secretRead": false,
+    "privateFileRead": true,
+    "networkAccessed": false
+  },
+  "approval": {
+    "state": "missing",
+    "requiredFrom": "operator"
+  },
+  "retrySafety": "unsafe_until_approved",
+  "modelEnvelopeHash": "sha256:a1bcaa1cb2572ab0e735c30062a268391d0a9d1b3dd7ff4b14065d8b29513b2a"
+}
+```
+
+## Invariant
+
+A blocked tool call should never disappear into the middle ground of “the command just failed.”
+
+- The **model** gets a safe reason class and next action.
+- The **operator** gets policy evidence and retry safety.
+- The shared identifier is a correlation id plus hashes, not raw private payloads.
+
+That makes enforcement auditable without turning policy internals into model-visible bypass material.
+
+## Try the copyable example
+
+See [`examples/agent-firewall-denial-audit/`](../examples/agent-firewall-denial-audit/) for a tiny denial envelope, operator audit record, and local checker:
+
+```bash
+node examples/agent-firewall-denial-audit/check-denial-audit.mjs examples/agent-firewall-denial-audit
+```
+
+The checker is intentionally small. It fails if the model-visible envelope leaks command/path/policy/secret-looking fields, if the audit record lacks policy ids or hash evidence, or if the envelope/audit correlation id does not match.
+
+## How this fits Pluribus
+
+Pluribus is not an agent firewall. This recipe is for teams already using hooks, policy engines, or local gateways and needing privacy-safe evidence at the enforcement boundary: what was denied, what the model was safely told, and what the operator can audit later.

package/docs/ai-pr-review-receipts.md

@@ -124,6 +124,26 @@ This receipt does not include raw prompts, transcripts, source code, secrets, cu
 `next_safe_action:`
 ```
 
+## CI gate example
+
+The copyable example in [`examples/ai-pr-review-receipts/`](../examples/ai-pr-review-receipts/) includes:
+
+- a PR template for human-readable blast-radius review;
+- a GitHub Actions workflow that validates a machine-readable `agent.review_primitive_receipt.v1` receipt;
+- a passing fixture and an intentionally failing fixture.
+
+Run the smoke locally from the repository root:
+
+```bash
+node examples/review-primitive-gate/check-review-receipt.mjs \
+  examples/ai-pr-review-receipts/review-primitive-receipt.json
+
+node examples/review-primitive-gate/check-review-receipt.mjs \
+  examples/ai-pr-review-receipts/incomplete-review-primitive-receipt.json
+```
+
+The first command should pass. The second should fail because partial/unsafe or under-evidenced agent work should not silently pass a merge gate.
+
 ## How to use with Pluribus
 
 Pluribus does not need to own your PR workflow. Use it as the neutral language for evidence that crossed an agent boundary:

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/compaction-resume-receipts.md

@@ -0,0 +1,43 @@
+# Compaction resume receipts
+
+Claude Code and Codex users are asking for `PreCompact` / `PostCompact` hooks because long sessions lose thread detail, reload rules inconsistently, or continue after a summary that no one can audit.
+
+The risky moment is not compaction itself. The risky moment is **resuming as if nothing changed**.
+
+A compaction resume receipt is a small, privacy-safe handoff object emitted after a compaction/restore flow. It proves what was summarized, what instruction sources were reloaded, what state was lost or kept, and whether the next agent turn is safe to continue.
+
+## Receipt boundary
+
+A resume receipt should prove:
+
+- **event identity** — stable `compaction_event_id`, `session_id`, and trigger so a restore can be correlated with the hook that caused it;
+- **transcript boundary** — the compacted transcript range and hash, without logging raw transcript content;
+- **summary evidence** — summary hash and token count so downstream tools can detect stale or changed summaries;
+- **instruction reloads** — `AGENTS.md`, `CLAUDE.md`, skills, MCP/tool manifests, workflow plans, or project rules reloaded with hashes/mtimes;
+- **kept/lost fields** — explicit lists for active plan, open diffs, pending tests, rejected decisions, tool grants, or unresolved blockers;
+- **resume verdict** — `safe_to_resume: true | false | unknown` plus reasons;
+- **privacy flags** — no raw transcript, raw prompts, raw tool outputs, secrets, or full instruction bodies in the receipt.
+
+## 60-second gate
+
+The copyable example is in [`examples/compaction-resume-receipts/`](../examples/compaction-resume-receipts/):
+
+```bash
+node examples/compaction-resume-receipts/check-resume-receipt.mjs \
+  examples/compaction-resume-receipts/safe-resume-receipt.json
+
+node examples/compaction-resume-receipts/check-resume-receipt.mjs \
+  examples/compaction-resume-receipts/unsafe-resume-receipt.json
+```
+
+The first passes because the restore has a stable event id, compacted transcript hash, summary hash, reloaded instruction sources, explicit kept/lost state, privacy flags, and `safe_to_resume: true` with no blocking lost fields.
+
+The second fails because it tries to continue after missing `AGENTS.md`, hidden lost decisions, raw transcript logging, and an `unknown` verdict.
+
+## Positioning
+
+Memory systems remember. Hooks fire lifecycle events. This receipt answers the operational review question:
+
+> After compaction, do we have enough verified context to continue safely?
+
+That makes `PostCompact` / `SessionStart(compact)` restore flows auditable without turning Pluribus into a memory store or requiring private transcript capture.

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/controlled-learning-queue.md

@@ -0,0 +1,48 @@
+# Controlled learning queue for AI employee-style agents
+
+Claude Code, OpenClaw, Cursor, and MCP tools make it easy to turn a repository into a role-based worker: `CLAUDE.md` as the job description, Skills as procedures, and a `memory/` folder as durable knowledge.
+
+That pattern compounds quickly, but it has a failure mode: the agent can overlearn from one weird lead, support ticket, or edge case and rewrite shared memory for every future run.
+
+Use a controlled learning queue when an agent is allowed to **propose** durable memory changes but not silently promote them.
+
+## Split the folders
+
+```text
+role/                  # job contract: responsibilities, boundaries, escalation
+skills/                # callable procedures with inputs, outputs, stop conditions
+memory/durable.md      # approved facts only; small enough to review
+memory/working-notes.md# scratch observations; allowed to be messy/temporary
+learning_queue.md      # proposed durable changes awaiting promote/reject
+leads/                 # tiny job cards for active work
+```
+
+The key rule: `memory/durable.md` changes only through `learning_queue.md` proposals with source, reason, scope, expiry, and reviewer decision.
+
+## Proposal shape
+
+Each proposed learning should answer:
+
+- **Source:** what run, lead, issue, or transcript produced the observation?
+- **Observed:** what happened, without storing raw private text?
+- **Proposed durable change:** the exact fact/rule to add, edit, or remove.
+- **Reason:** why this should affect future runs, not just the current case.
+- **Scope:** global, client-specific, project-specific, channel-specific, or temporary.
+- **Expiry / review date:** when this fact should be rechecked.
+- **Status:** proposed, promoted, rejected, or expired.
+
+That is enough to preserve learning while keeping an agent from slowly corrupting ICP, pricing assumptions, escalation rules, or compliance boundaries.
+
+## Try the copyable example
+
+See [`examples/controlled-learning-queue/`](../examples/controlled-learning-queue/) for a tiny AI sales/ops worker layout and a local checker:
+
+```bash
+node examples/controlled-learning-queue/check-learning-queue.mjs examples/controlled-learning-queue/learning_queue.md
+```
+
+The checker is intentionally small. It fails proposals that are missing source/reason/scope/expiry/status, that try to auto-promote without review, or that paste raw secrets/private payloads into the learning queue.
+
+## How this fits Pluribus
+
+Pluribus is not trying to be the agent's brain. This pattern keeps intentional context reviewable: durable memory is a small versioned source of truth, while working notes and proposed learnings remain visibly provisional until promoted.

package/docs/install-plan-receipts.md

@@ -75,3 +75,5 @@ If an installer cannot answer that before mutation, treat it like running CI fro
 ## Try the copyable example
 
 See [`examples/install-plan-receipts/`](../examples/install-plan-receipts/) for a small review checklist and sample receipt you can copy into setup scripts, README install sections, or agent-managed onboarding workflows.
+
+After the installer has run, use [Skill install/load receipts](skill-install-receipts.md) when the next question is whether each target agent can discover/load the installed Skill and whether the install made the first session unsafe by adding too much always-loaded context.

package/docs/loaded-resource-boundary.md

@@ -0,0 +1,97 @@
+# Loaded-resource boundary receipts
+
+Use this when a Skill, plugin resource, MCP-provided instruction, or custom-agent file appears to be configured correctly but does not actually reach the agent runtime.
+
+This is the failure mode behind reports like:
+
+- "the Skill works in chat but not ACP/Zed/CLI";
+- "`/skills` or the skill list is unavailable in this client";
+- "the agent followed generic instructions because the real resource was never injected";
+- "a prompt workaround says resources are preloaded, but there is no proof they were readable by the runtime".
+
+Pluribus should not become a Skill manager. The useful boundary is a small receipt that proves what crossed from configuration into the run.
+
+## Receipt shape
+
+A loaded-resource receipt separates the stages that are often collapsed into "the skill exists":
+
+| Stage | Question |
+| --- | --- |
+| `expected` | Which resources did the user/config expect for this agent and task? |
+| `discovered` | Did the host find the resource on disk, in a plugin, registry, or MCP response? |
+| `attached` | Was the resource attached to the selected agent/profile/workspace? |
+| `injected` | Did the runtime put the resource into the model/tool context for this session? |
+| `readable` | Could the agent actually read the resource bytes or resolved prompt? |
+| `skipped` | If not, what precise stage and reason explain the gap? |
+
+Recommended privacy-safe fields:
+
+```json
+{
+  "receipt_type": "pluribus.loaded_resource_boundary.v1",
+  "scenario": "custom-agent skill parity across chat and ACP",
+  "expected_resources": [
+    {
+      "id": "skill:pr-review",
+      "kind": "skill",
+      "scope": "project",
+      "source_ref": ".kiro/skills/pr-review/SKILL.md",
+      "source_hash": "sha256:...",
+      "required": true
+    }
+  ],
+  "sessions": [
+    {
+      "runtime": "chat",
+      "client": "kiro-desktop",
+      "agent": "reviewer",
+      "discovered_resources": ["skill:pr-review"],
+      "attached_resources": ["skill:pr-review"],
+      "injected_resources": ["skill:pr-review"],
+      "readable_resources": ["skill:pr-review"],
+      "skipped_resources": []
+    },
+    {
+      "runtime": "acp",
+      "client": "zed",
+      "agent": "reviewer",
+      "discovered_resources": ["skill:pr-review"],
+      "attached_resources": ["skill:pr-review"],
+      "injected_resources": [],
+      "readable_resources": [],
+      "skipped_resources": [
+        {
+          "id": "skill:pr-review",
+          "stage": "injected",
+          "reason": "runtime_does_not_inject_resources"
+        }
+      ]
+    }
+  ]
+}
+```
+
+Do not include raw skill text, private prompts, credentials, or full project memory. Hashes, refs, stage names, and skip reasons are enough for a maintainer to reproduce the boundary.
+
+## Acceptance test
+
+For the same custom agent and the same attached Skill/resource, compare chat vs ACP/CLI/IDE sessions:
+
+1. The resource should be `discovered` in each runtime that claims to support it.
+2. If it is attached in chat but not in ACP/Zed/CLI, record `not_attached_to_agent`.
+3. If it is attached but absent from the model context, record `runtime_does_not_inject_resources`.
+4. If it was injected but the bytes cannot be resolved, record `resource_read_failed`.
+5. If trigger logic prevented loading, record `trigger_not_matched` and include the matched task label or hash, not the full prompt.
+
+A useful bug report is not "Skills are broken". It is:
+
+> For agent `reviewer`, `skill:pr-review` is discovered and attached in both chat and ACP. Chat injects and reads it; ACP/Zed does not inject it and reports `runtime_does_not_inject_resources`.
+
+## Try the example
+
+```bash
+node examples/loaded-resource-boundary/check-loaded-resource-boundary.mjs \
+  examples/loaded-resource-boundary/loaded-resource-boundary.json
+```
+
+The sample intentionally includes a chat-vs-ACP mismatch and treats that mismatch as the useful finding.

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/memory-write-policy-receipts.md

@@ -0,0 +1,41 @@
+# Memory write policy receipts
+
+Cross-agent memory tools usually optimize recall: make Claude Code, Codex, Cursor, OpenClaw, ChatGPT, or MCP clients find the same facts later.
+
+The adoption risk is different: **who is allowed to write durable memory, under what scope, and with what rollback or review path?**
+
+Pluribus should not become another memory server. This receipt is a small governance layer for shared memory systems: every durable memory update is treated like a proposed diff before it becomes trusted context for future agents.
+
+## Receipt boundary
+
+A memory write receipt should prove:
+
+- **source** — where the proposed memory came from, with a hash/ref instead of raw transcript or raw memory body;
+- **scope** — whether the write is repo, project, org, or user scoped;
+- **proposed diff** — adds/updates/supersedes/expires by stable refs and hashes;
+- **write policy** — proposed, approved, rejected, or quarantined; who/what approved it;
+- **lifecycle** — expiry or review date so stale facts do not become immortal;
+- **injection visibility** — future sessions can see which memory was injected;
+- **privacy flags** — no raw prompts, raw tool output, raw memory text, or secrets in the receipt.
+
+## 60-second gate
+
+The copyable example is in [`examples/memory-write-policy/`](../examples/memory-write-policy/):
+
+```bash
+node examples/memory-write-policy/check-memory-update.mjs \
+  examples/memory-write-policy/approved-memory-update.json
+
+node examples/memory-write-policy/check-memory-update.mjs \
+  examples/memory-write-policy/quarantined-memory-update.json
+```
+
+The first passes because the write is approved, scoped, hashed, visible to future sessions, and has a review lifecycle. The second fails because it tries to turn a quarantined, broad user-scoped, private/sensitive update into durable shared memory and includes raw text.
+
+## Positioning
+
+Memory systems remember. Hooks and workflow engines execute. This receipt answers a narrower review question:
+
+> Is this memory update allowed to become durable context for other agents?
+
+That makes shared memory safer without requiring the memory provider to expose private content or the agent transcript.