pluribus-context 0.3.40 → 0.3.41

package/CHANGELOG.md

@@ -4,6 +4,10 @@
 
 All notable changes to Pluribus are documented here.
 
+## 0.3.41 - 2026-06-10
+
+- Added npm Agent Skills discovery keywords (`agent-skill`, `skillpm`, and `agent-skills-registry`) so `pluribus-context` can be indexed by npm-backed skill package managers while continuing to ship the existing low-authority `skills/*/SKILL.md` recipes.
+
 ## 0.3.40 - 2026-06-09
 
 - Added `pluribus demo tool-surface-diff`, a tiny npm-runnable MCP dynamic-discovery receipt demo for proving discovered, activated, withheld, and blocked runtime tool-surface changes without logging raw schemas, prompts, or results.

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. It now explicitly covers the "Tool Search fixed MCP bloat" objection: the receipt proves which lane stayed deferred, which tool was expanded, and whether schemas leaked through `messages`/bootstrap anyway. For a 60-second runtime-discovery proof, run `npx --yes pluribus-context@latest demo tool-surface-diff --json`; it validates a receipt for discovered → activated → withheld/blocked MCP tools without raw schemas/prompts/results. 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.
+**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. It now explicitly covers the "Tool Search fixed MCP bloat" objection: the receipt proves which lane stayed deferred, which tool was expanded, and whether schemas leaked through `messages`/bootstrap anyway. For a 60-second runtime-discovery proof, run `npx --yes pluribus-context@latest demo tool-surface-diff --json`; it validates a receipt for discovered → activated → withheld/blocked MCP tools without raw schemas/prompts/results. If you are coming from Claude Code, GraphRAG, or memory tooling where retrieval succeeds but the agent ignores it, try the [context attention receipt example](examples/context-attention-receipts/) to prove required context was delivered, acknowledged, and cited before edits. 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.
 
 ---
 

package/docs/.well-known/agent-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/docs/.well-known/agent-skills/index.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
+  "skills": [
+    {
+      "name": "context-receipts",
+      "type": "skill-md",
+      "description": "Emit privacy-safe receipts for context selection, deferral, hydration, compaction, pruning, delegation, usage attribution, and boundary handoffs.",
+      "url": "context-receipts/SKILL.md",
+      "digest": "sha256:6d268a5ceac4afa87308ff4c79f01483e2785a8e9bb54e5d3147477e0bf724a1"
+    },
+    {
+      "name": "skill-policy-receipts",
+      "type": "skill-md",
+      "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.",
+      "url": "skill-policy-receipts/SKILL.md",
+      "digest": "sha256:633b4da097b56da8805476a69d0498602979b7f8c03c57996f886bb9e56ccca8"
+    }
+  ]
+}

package/docs/.well-known/agent-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/docs/index.html

@@ -0,0 +1,38 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Pluribus Context Receipts</title>
+  <style>
+    :root { color-scheme: dark light; --bg:#0b1020; --card:#121a33; --text:#e8ecf8; --muted:#aab4cf; --accent:#8ee6c4; --border:#283454; }
+    body { margin:0; font:16px/1.55 system-ui,-apple-system,Segoe UI,sans-serif; background:var(--bg); color:var(--text); }
+    main { max-width:880px; margin:0 auto; padding:56px 20px; }
+    a { color:var(--accent); }
+    .card { background:var(--card); border:1px solid var(--border); border-radius:18px; padding:24px; margin:20px 0; }
+    code { background:#060a15; padding:.15rem .35rem; border-radius:6px; }
+  </style>
+</head>
+<body>
+  <main>
+    <h1>Pluribus Context Receipts</h1>
+    <p>Privacy-safe evidence for AI context boundaries: what crossed into the agent, what stayed out, and what should stop before edits or tool calls.</p>
+    <div class="card">
+      <h2>Browser playground</h2>
+      <p>Try receipt validation without installing anything or sending data to a server. Current samples cover MCP tool-surface diffs, retrieved-context attention, and CLAUDE.md rule-attention drift.</p>
+      <p><a href="receipt-playground.html">Open the receipt playground →</a></p>
+    </div>
+    <div class="card">
+      <h2>CLI quick checks</h2>
+      <p><code>npx --yes pluribus-context@latest demo tool-surface-diff --json</code></p>
+      <p><code>npx --yes pluribus-context@latest validate</code></p>
+    </div>
+    <div class="card">
+      <h2>Agent Skills discovery</h2>
+      <p>Pluribus publishes a well-known Agent Skills index so compatible clients can discover the low-authority <code>context-receipts</code> and <code>skill-policy-receipts</code> skills without scraping GitHub.</p>
+      <p><a href=".well-known/agent-skills/index.json">Open <code>/.well-known/agent-skills/index.json</code> →</a></p>
+    </div>
+    <p><a href="https://github.com/caioribeiroclw-pixel/pluribus">GitHub repo</a> · <a href="https://www.npmjs.com/package/pluribus-context">npm package</a></p>
+  </main>
+</body>
+</html>

package/docs/receipt-playground.html

@@ -0,0 +1,250 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Pluribus Receipt Playground</title>
+  <style>
+    :root { color-scheme: dark light; --bg:#0b1020; --card:#121a33; --text:#e8ecf8; --muted:#aab4cf; --accent:#8ee6c4; --bad:#ff8f9c; --warn:#ffd166; --ok:#8ee6c4; --border:#283454; }
+    * { box-sizing:border-box; }
+    body { margin:0; font:15px/1.5 system-ui,-apple-system,Segoe UI,sans-serif; background:linear-gradient(180deg,#0b1020,#10182e); color:var(--text); }
+    main { max-width:1120px; margin:0 auto; padding:34px 18px 48px; }
+    h1 { font-size:clamp(2rem,4vw,3.4rem); line-height:1.05; margin:.2rem 0 1rem; letter-spacing:-.04em; }
+    h2 { margin-top:0; }
+    p, li { color:var(--muted); }
+    a { color:var(--accent); }
+    .grid { display:grid; grid-template-columns:1fr; gap:16px; }
+    @media (min-width:900px) { .grid { grid-template-columns:1.1fr .9fr; } }
+    .card { background:rgba(18,26,51,.92); border:1px solid var(--border); border-radius:18px; padding:18px; box-shadow:0 20px 80px rgba(0,0,0,.24); }
+    textarea { width:100%; min-height:560px; resize:vertical; border:1px solid var(--border); border-radius:14px; padding:14px; background:#060a15; color:#e8ecf8; font:13px/1.45 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; }
+    button, select { border:1px solid var(--border); border-radius:999px; background:#182344; color:var(--text); padding:10px 14px; cursor:pointer; }
+    button:hover, select:hover { border-color:var(--accent); }
+    .controls { display:flex; flex-wrap:wrap; gap:10px; align-items:center; margin:0 0 12px; }
+    .result { white-space:pre-wrap; overflow:auto; border-radius:14px; padding:14px; background:#060a15; border:1px solid var(--border); min-height:210px; font:13px/1.45 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; }
+    .ok { color:var(--ok); }
+    .bad { color:var(--bad); }
+    .warn { color:var(--warn); }
+    .pill { display:inline-block; border:1px solid var(--border); border-radius:999px; padding:.2rem .55rem; color:var(--muted); margin:.1rem .2rem .1rem 0; }
+    code { background:#060a15; padding:.12rem .32rem; border-radius:6px; color:#d7e2ff; }
+  </style>
+</head>
+<body>
+  <main>
+    <p><a href="index.html">← Pluribus</a></p>
+    <h1>Receipt playground</h1>
+    <p>Paste a Pluribus receipt and validate the boundary evidence locally in your browser. No network calls, no raw prompts/results required.</p>
+    <div class="grid">
+      <section class="card">
+        <div class="controls">
+          <select id="sample">
+            <option value="toolSurface">Sample: MCP tool-surface diff</option>
+            <option value="attentionPass">Sample: context attention pass</option>
+            <option value="attentionFail">Sample: context attention fail</option>
+            <option value="ruleAttention">Sample: CLAUDE.md rule attention drift</option>
+            <option value="skillInstall">Sample: Agent Skill install provenance</option>
+          </select>
+          <button id="load">Load sample</button>
+          <button id="validate">Validate</button>
+        </div>
+        <textarea id="receipt" spellcheck="false"></textarea>
+      </section>
+      <aside class="card">
+        <h2>Validation result</h2>
+        <div id="result" class="result">Click Validate.</div>
+        <h2>What this checks</h2>
+        <p><span class="pill">tool-surface diff</span> proves runtime discovery changes without logging raw schemas/prompts/results.</p>
+        <p><span class="pill">context attention</span> proves required retrieved context was delivered, acknowledged, and cited before edits.</p>
+        <p><span class="pill">rule attention</span> shows whether project rules were re-read, cited in the pre-edit plan, and checked before changes.</p>
+        <p><span class="pill">skill install provenance</span> shows which <code>SKILL.md</code> source path won, which mirrors were ignored, and whether install metadata stayed content-safe.</p>
+        <h2>CLI equivalent</h2>
+        <p><code>npx --yes pluribus-context@latest demo tool-surface-diff --json</code></p>
+      </aside>
+    </div>
+  </main>
+  <script>
+    const samples = {
+      toolSurface: {
+        schema: 'pluribus.mcp_tool_surface_diff_receipt.v1',
+        run_id: 'tool-surface-diff-demo',
+        generated_at: '2026-06-09T13:00:00Z',
+        platform: { name: 'enterprise-mcp-dynamic-discovery', audit_sink: 'admin-center-or-siem' },
+        catalog: { server_id: 'mcp://sales-ops-gateway', previous_hash: 'sha256:previous-catalog-redacted', current_hash: 'sha256:current-catalog-redacted' },
+        runtime_discovery: { enabled: true, trigger: 'runtime_tool_catalog_diff' },
+        privacy_boundary: { raw_schemas: 'omitted_hash_only', raw_prompts: 'omitted', raw_results: 'omitted' },
+        tools: [
+          { tool_id: 'tool:crm.search_accounts', name_hash: 'sha256:0cc2...', schema_hash: 'sha256:6f4f...', status: 'activated', validation_outcome: 'accepted', diff_summary: { added_fields: 1, removed_fields: 0, changed_fields: 0 } },
+          { tool_id: 'tool:crm.export_contacts', name_hash: 'sha256:f38f...', schema_hash: 'sha256:95dd...', status: 'blocked', validation_outcome: 'blocked_by_rai', diff_summary: { added_fields: 4, removed_fields: 0, changed_fields: 2 } },
+          { tool_id: 'tool:billing.refund_invoice', name_hash: 'sha256:abfd...', schema_hash: 'sha256:3b4f...', status: 'withheld', validation_outcome: 'entitlement_filtered', diff_summary: { added_fields: 0, removed_fields: 0, changed_fields: 0 } }
+        ]
+      },
+      attentionPass: {
+        schema: 'pluribus.context_attention_receipt.v1', receipt_id: 'attn_demo_pass', task_id: 'claude-code-refactor-184', agent_surface: 'claude_code', retrieval_system: 'graph_memory_mcp',
+        required_context: [{ id: 'ctx:architecture:tenant-routing' }, { id: 'ctx:decision:readonly-audit-first' }],
+        delivery: { surface: 'mcp_tool_response', delivered_context_ids: ['ctx:architecture:tenant-routing', 'ctx:decision:readonly-audit-first'], raw_context_omitted: true, evidence_path: '.pluribus/receipts/context-attention.ndjson' },
+        attention: { acknowledged_before_plan: ['ctx:architecture:tenant-routing', 'ctx:decision:readonly-audit-first'], cited_in_plan: ['ctx:architecture:tenant-routing', 'ctx:decision:readonly-audit-first'], missing_context_stop: false },
+        privacy: { raw_prompts_omitted: true, raw_documents_omitted: true, source_code_omitted: true, tool_outputs_omitted: true, tokens_omitted: true, customer_data_omitted: true },
+        result: { status: 'safe_to_continue', next_safe_action: 'continue with dry-run refactor plan' }
+      },
+      attentionFail: {
+        schema: 'pluribus.context_attention_receipt.v1', receipt_id: 'attn_demo_fail', task_id: 'claude-code-refactor-185', agent_surface: 'claude_code', retrieval_system: 'graph_memory_mcp',
+        required_context: [{ id: 'ctx:architecture:tenant-routing' }, { id: 'ctx:decision:readonly-audit-first' }],
+        delivery: { surface: 'mcp_tool_response', delivered_context_ids: ['ctx:architecture:tenant-routing', 'ctx:decision:readonly-audit-first'], raw_context_omitted: true, evidence_path: '.pluribus/receipts/context-attention.ndjson' },
+        attention: { acknowledged_before_plan: ['ctx:architecture:tenant-routing'], cited_in_plan: [], missing_context_stop: false },
+        privacy: { raw_prompts_omitted: true, raw_documents_omitted: true, source_code_omitted: true, tool_outputs_omitted: true, tokens_omitted: true, customer_data_omitted: true },
+        result: { status: 'unsafe_to_continue', next_safe_action: 'stop and re-deliver required context before editing' }
+      },
+      ruleAttention: {
+        schema: 'pluribus.claude_code_rule_attention_receipt.v1',
+        receipt_id: 'rule_attn_demo_62087',
+        task_id: 'claude-code-long-session-62087',
+        agent_surface: 'claude_code',
+        context_boundary: { session_phase: 'post-compaction-long-session', before_first_edit: true },
+        rules: [
+          { rule_id: 'CLAUDE.md:test-after-plan', source: 'CLAUDE.md#workflow', last_loaded_at: '2026-06-09T22:41:00Z', last_referenced_at: null, cited_in_pre_edit_plan: false, edit_check: 'missing', violation_category: 'loaded_but_not_referenced' },
+          { rule_id: 'CLAUDE.md:no-skip-steps', source: 'CLAUDE.md#workflow', last_loaded_at: '2026-06-09T22:41:00Z', last_referenced_at: '2026-06-09T22:58:00Z', cited_in_pre_edit_plan: true, edit_check: 'pass', violation_category: null }
+        ],
+        privacy: { raw_prompts_omitted: true, raw_claude_md_omitted: true, source_code_omitted: true, tool_outputs_omitted: true, tokens_omitted: true, customer_data_omitted: true },
+        result: { status: 'unsafe_to_edit', next_safe_action: 'stop, re-read missing rule ids, and restate the pre-edit plan with citations' }
+      },
+      skillInstall: {
+        schema: 'pluribus.agent_skill_install_provenance_receipt.v1',
+        receipt_id: 'skill_install_openskills_demo',
+        installer: { name: 'agent-skill-package-manager', mode: 'universal', target_agent_dir: '.agent/skills' },
+        source: { kind: 'github_repo', repo: 'caioribeiroclw-pixel/pluribus', requested_ref: 'v0.3.40', resolved_sha: 'sha256:resolved-commit-redacted' },
+        discovery: {
+          requested_skill_names: ['context-receipts', 'skill-policy-receipts'],
+          discovered_source_paths: [
+            'skills/context-receipts/SKILL.md',
+            'examples/agent-skills/context-receipts/SKILL.md',
+            'docs/.well-known/agent-skills/context-receipts/SKILL.md',
+            'skills/skill-policy-receipts/SKILL.md',
+            'examples/agent-skills/skill-policy-receipts/SKILL.md',
+            'docs/.well-known/agent-skills/skill-policy-receipts/SKILL.md'
+          ],
+          duplicate_resolution: 'prefer_top_level_skills_dir'
+        },
+        selected_skills: [
+          { name: 'context-receipts', selected_source_path: 'skills/context-receipts/SKILL.md', target_path: '.agent/skills/context-receipts/SKILL.md', operation: 'install', lockfile_entry_written: true },
+          { name: 'skill-policy-receipts', selected_source_path: 'skills/skill-policy-receipts/SKILL.md', target_path: '.agent/skills/skill-policy-receipts/SKILL.md', operation: 'install', lockfile_entry_written: true }
+        ],
+        ignored_duplicates: [
+          { name: 'context-receipts', ignored_source_path: 'examples/agent-skills/context-receipts/SKILL.md', reason: 'duplicate_mirror_not_canonical' },
+          { name: 'context-receipts', ignored_source_path: 'docs/.well-known/agent-skills/context-receipts/SKILL.md', reason: 'duplicate_mirror_not_canonical' },
+          { name: 'skill-policy-receipts', ignored_source_path: 'examples/agent-skills/skill-policy-receipts/SKILL.md', reason: 'duplicate_mirror_not_canonical' },
+          { name: 'skill-policy-receipts', ignored_source_path: 'docs/.well-known/agent-skills/skill-policy-receipts/SKILL.md', reason: 'duplicate_mirror_not_canonical' }
+        ],
+        safety: { content_sanitizers: ['frontmatter-parse', 'markdown-only'], raw_secret_or_env_values_copied: false, scripts_or_hooks_installed: false, network_capability_added: false, manual_review_required: true },
+        privacy: { raw_skill_body_omitted: true, raw_env_values_omitted: true, auth_headers_omitted: true, customer_data_omitted: true },
+        result: { status: 'safe_to_install_after_review', installed_count: 2, ignored_duplicate_count: 4 }
+      }
+    }
+
+    const receiptEl = document.querySelector('#receipt')
+    const resultEl = document.querySelector('#result')
+    document.querySelector('#load').addEventListener('click', loadSample)
+    document.querySelector('#validate').addEventListener('click', validate)
+    document.querySelector('#sample').addEventListener('change', loadSample)
+    loadSample()
+
+    function loadSample() {
+      const key = document.querySelector('#sample').value
+      receiptEl.value = JSON.stringify(samples[key], null, 2)
+      validate()
+    }
+
+    function validate() {
+      let receipt
+      try { receipt = JSON.parse(receiptEl.value) }
+      catch (error) { return render({ ok:false, errors:[`invalid JSON: ${error.message}`], warnings:[] }) }
+      if (receipt.schema === 'pluribus.mcp_tool_surface_diff_receipt.v1') return render(validateToolSurface(receipt))
+      if (receipt.schema === 'pluribus.context_attention_receipt.v1') return render(validateAttention(receipt))
+      if (receipt.schema === 'pluribus.claude_code_rule_attention_receipt.v1') return render(validateRuleAttention(receipt))
+      if (receipt.schema === 'pluribus.agent_skill_install_provenance_receipt.v1') return render(validateSkillInstall(receipt))
+      render({ ok:false, errors:[`unsupported schema: ${receipt.schema || '(missing)'}`], warnings:[] })
+    }
+
+    function validateToolSurface(r) {
+      const errors = [], warnings = []
+      const privacy = r.privacy_boundary || {}
+      if (!r.catalog?.current_hash) errors.push('catalog.current_hash is required')
+      if (!Array.isArray(r.tools) || r.tools.length === 0) errors.push('tools must include at least one discovered/activated/withheld/blocked tool')
+      for (const field of ['raw_schemas','raw_prompts','raw_results']) if (!String(privacy[field] || '').startsWith('omitted')) errors.push(`privacy_boundary.${field} must be omitted`)
+      const counts = countBy(r.tools || [], 'status')
+      if (!counts.activated && !counts.withheld && !counts.blocked) warnings.push('receipt has no activated/withheld/blocked status counts')
+      return { ok: errors.length === 0, schema:r.schema, summary:counts, errors, warnings }
+    }
+
+    function validateAttention(r) {
+      const errors = [], warnings = []
+      const required = ids((r.required_context || []).map(x => x.id))
+      const delivered = ids(r.delivery?.delivered_context_ids)
+      const ack = ids(r.attention?.acknowledged_before_plan)
+      const cited = ids(r.attention?.cited_in_plan)
+      if (!required.length) errors.push('required_context must name at least one id')
+      for (const id of required) {
+        if (!delivered.includes(id)) errors.push(`required context not delivered: ${id}`)
+        if (!ack.includes(id)) errors.push(`required context not acknowledged before plan: ${id}`)
+        if (!cited.includes(id)) errors.push(`required context not cited in plan: ${id}`)
+      }
+      if (r.delivery?.raw_context_omitted !== true) errors.push('delivery.raw_context_omitted must be true')
+      for (const field of ['raw_prompts_omitted','raw_documents_omitted','source_code_omitted','tool_outputs_omitted','tokens_omitted','customer_data_omitted']) if (r.privacy?.[field] !== true) errors.push(`privacy.${field} must be true`)
+      if (errors.length && r.attention?.missing_context_stop !== true) errors.push('missing_context_stop must be true when required attention evidence is incomplete')
+      if (!r.delivery?.evidence_path) warnings.push('delivery.evidence_path is missing')
+      return { ok: errors.length === 0, schema:r.schema, required_count:required.length, delivered_count:delivered.length, acknowledged_count:ack.length, cited_count:cited.length, errors, warnings }
+    }
+
+    function validateRuleAttention(r) {
+      const errors = [], warnings = []
+      const rules = Array.isArray(r.rules) ? r.rules : []
+      if (!rules.length) errors.push('rules must include at least one project rule')
+      for (const rule of rules) {
+        if (!rule.rule_id) errors.push('each rule must include rule_id')
+        if (!rule.source) errors.push(`${rule.rule_id || 'rule'} must include source`)
+        if (!rule.last_loaded_at) errors.push(`${rule.rule_id || 'rule'} must include last_loaded_at`)
+        if (rule.cited_in_pre_edit_plan !== true) warnings.push(`${rule.rule_id || 'rule'} was not cited in the pre-edit plan`)
+        if (!['pass','fail','missing'].includes(rule.edit_check)) errors.push(`${rule.rule_id || 'rule'} edit_check must be pass, fail, or missing`)
+      }
+      for (const field of ['raw_prompts_omitted','raw_claude_md_omitted','source_code_omitted','tool_outputs_omitted','tokens_omitted','customer_data_omitted']) if (r.privacy?.[field] !== true) errors.push(`privacy.${field} must be true`)
+      const missing = rules.filter(rule => rule.cited_in_pre_edit_plan !== true || rule.edit_check !== 'pass')
+      if (missing.length && r.result?.status === 'safe_to_edit') errors.push('result.status cannot be safe_to_edit while a required rule is uncited or failing')
+      return { ok: errors.length === 0 && missing.length === 0, schema:r.schema, rules_count:rules.length, uncited_or_failing_rules:missing.map(rule => rule.rule_id), errors, warnings }
+    }
+
+    function validateSkillInstall(r) {
+      const errors = [], warnings = []
+      const selected = Array.isArray(r.selected_skills) ? r.selected_skills : []
+      const ignored = Array.isArray(r.ignored_duplicates) ? r.ignored_duplicates : []
+      const discovered = Array.isArray(r.discovery?.discovered_source_paths) ? r.discovery.discovered_source_paths : []
+      if (!r.source?.repo) errors.push('source.repo is required')
+      if (!r.source?.resolved_sha) errors.push('source.resolved_sha is required')
+      if (!r.installer?.target_agent_dir) errors.push('installer.target_agent_dir is required')
+      if (!selected.length) errors.push('selected_skills must include at least one installed skill')
+      for (const skill of selected) {
+        if (!skill.name) errors.push('each selected skill must include name')
+        if (!skill.selected_source_path) errors.push(`${skill.name || 'skill'} must include selected_source_path`)
+        if (!skill.target_path) errors.push(`${skill.name || 'skill'} must include target_path`)
+        if (skill.lockfile_entry_written !== true) warnings.push(`${skill.name || 'skill'} did not write lockfile metadata`)
+      }
+      const selectedNames = selected.map(skill => skill.name).filter(Boolean)
+      for (const name of selectedNames) {
+        const discoveredForName = discovered.filter(path => path.includes(`/${name}/`) || path.includes(`${name}/SKILL.md`)).length
+        const ignoredForName = ignored.filter(item => item.name === name).length
+        if (discoveredForName > 1 && ignoredForName === 0) errors.push(`${name} has multiple discovered paths but no ignored_duplicates evidence`)
+      }
+      if (r.safety?.raw_secret_or_env_values_copied !== false) errors.push('safety.raw_secret_or_env_values_copied must be false')
+      if (r.safety?.scripts_or_hooks_installed !== false) errors.push('safety.scripts_or_hooks_installed must be false for a low-authority skill receipt')
+      if (r.safety?.network_capability_added !== false) errors.push('safety.network_capability_added must be false for a skill-only install')
+      for (const field of ['raw_skill_body_omitted','raw_env_values_omitted','auth_headers_omitted','customer_data_omitted']) if (r.privacy?.[field] !== true) errors.push(`privacy.${field} must be true`)
+      if (selected.length !== new Set(selectedNames).size) errors.push('selected_skills contains duplicate names after resolution')
+      return { ok: errors.length === 0, schema:r.schema, selected_count:selected.length, ignored_duplicate_count:ignored.length, discovered_source_count:discovered.length, selected_source_paths:selected.map(skill => skill.selected_source_path), errors, warnings }
+    }
+
+    function countBy(items, key) { return items.reduce((acc, item) => (acc[item[key] || 'unknown'] = (acc[item[key] || 'unknown'] || 0) + 1, acc), {}) }
+    function ids(v) { return Array.isArray(v) ? v.filter(x => typeof x === 'string' && x) : [] }
+    function render(obj) {
+      resultEl.className = 'result ' + (obj.ok ? 'ok' : 'bad')
+      resultEl.textContent = JSON.stringify(obj, null, 2)
+    }
+  </script>
+</body>
+</html>

package/examples/context-attention-receipts/README.md

@@ -0,0 +1,41 @@
+# Context attention receipts
+
+This example is for the `r/ClaudeCode` / GraphRAG failure mode: a graph, memory, RAG, or MCP retrieval system finds the right context, but the coding agent behaves as if it never saw it.
+
+Pluribus should not replace graph memory, RAG, or MCP search. The useful boundary is smaller: emit a privacy-safe receipt proving whether selected context actually crossed the agent boundary and was treated as required before planning or editing.
+
+## What the receipt proves
+
+`pluribus.context_attention_receipt.v1` records low-cardinality evidence only:
+
+- which retrieval/memory/tool context IDs were required for the task;
+- which surface delivered them (`mcp_tool_response`, `claude_hook`, `CLAUDE.md`, `AGENTS.md`, etc.);
+- whether the agent acknowledged those IDs before plan/edit;
+- whether the final plan cites the IDs it depended on;
+- whether missing context forced a stop instead of a best-effort edit;
+- whether raw documents, prompts, source code, transcripts, tokens, or customer data were omitted.
+
+It intentionally does **not** store the retrieved chunks themselves. Use stable IDs, hashes, coarse labels, and evidence paths instead.
+
+## Smoke test
+
+```bash
+node examples/context-attention-receipts/check-attention-receipt.mjs \
+  examples/context-attention-receipts/attention-receipt-pass.json
+
+node examples/context-attention-receipts/check-attention-receipt.mjs \
+  examples/context-attention-receipts/attention-receipt-fail.json
+```
+
+The first command should pass. The second should fail because the graph/memory result was retrieved but not acknowledged or cited before editing.
+
+## Why this exists
+
+A high-quality retrieval layer is still weak if the next agent turn can ignore it. The receipt makes that failure visible:
+
+- retrieval succeeded;
+- required context was or was not delivered to the agent surface;
+- the agent did or did not acknowledge it before changing files;
+- the wrapper/hook did or did not stop the run when required context was missing.
+
+That is the narrow Pluribus angle: not more memory, not a new graph database, and not another router — evidence that the context boundary was actually crossed.

package/examples/context-attention-receipts/attention-receipt-fail.json

@@ -0,0 +1,49 @@
+{
+  "schema": "pluribus.context_attention_receipt.v1",
+  "receipt_id": "attn_2026_06_09_demo_fail",
+  "task_id": "claude-code-refactor-185",
+  "agent_surface": "claude_code",
+  "retrieval_system": "graph_memory_mcp",
+  "required_context": [
+    {
+      "id": "ctx:architecture:tenant-routing",
+      "source_type": "knowledge_graph",
+      "source_hash": "sha256:7bf3e0c1-redacted",
+      "why_required": "routes tenant-scoped writes through the policy gateway"
+    },
+    {
+      "id": "ctx:decision:readonly-audit-first",
+      "source_type": "decision_log",
+      "source_hash": "sha256:11ab91d4-redacted",
+      "why_required": "requires dry-run/audit before writes"
+    }
+  ],
+  "delivery": {
+    "surface": "mcp_tool_response",
+    "delivered_context_ids": [
+      "ctx:architecture:tenant-routing",
+      "ctx:decision:readonly-audit-first"
+    ],
+    "raw_context_omitted": true,
+    "evidence_path": ".pluribus/receipts/context-attention.ndjson"
+  },
+  "attention": {
+    "acknowledged_before_plan": [
+      "ctx:architecture:tenant-routing"
+    ],
+    "cited_in_plan": [],
+    "missing_context_stop": false
+  },
+  "privacy": {
+    "raw_prompts_omitted": true,
+    "raw_documents_omitted": true,
+    "source_code_omitted": true,
+    "tool_outputs_omitted": true,
+    "tokens_omitted": true,
+    "customer_data_omitted": true
+  },
+  "result": {
+    "status": "unsafe_to_continue",
+    "next_safe_action": "stop and ask the retrieval wrapper to re-deliver required context before editing"
+  }
+}

package/examples/context-attention-receipts/attention-receipt-pass.json

@@ -0,0 +1,53 @@
+{
+  "schema": "pluribus.context_attention_receipt.v1",
+  "receipt_id": "attn_2026_06_09_demo_pass",
+  "task_id": "claude-code-refactor-184",
+  "agent_surface": "claude_code",
+  "retrieval_system": "graph_memory_mcp",
+  "required_context": [
+    {
+      "id": "ctx:architecture:tenant-routing",
+      "source_type": "knowledge_graph",
+      "source_hash": "sha256:7bf3e0c1-redacted",
+      "why_required": "routes tenant-scoped writes through the policy gateway"
+    },
+    {
+      "id": "ctx:decision:readonly-audit-first",
+      "source_type": "decision_log",
+      "source_hash": "sha256:11ab91d4-redacted",
+      "why_required": "requires dry-run/audit before writes"
+    }
+  ],
+  "delivery": {
+    "surface": "mcp_tool_response",
+    "delivered_context_ids": [
+      "ctx:architecture:tenant-routing",
+      "ctx:decision:readonly-audit-first"
+    ],
+    "raw_context_omitted": true,
+    "evidence_path": ".pluribus/receipts/context-attention.ndjson"
+  },
+  "attention": {
+    "acknowledged_before_plan": [
+      "ctx:architecture:tenant-routing",
+      "ctx:decision:readonly-audit-first"
+    ],
+    "cited_in_plan": [
+      "ctx:architecture:tenant-routing",
+      "ctx:decision:readonly-audit-first"
+    ],
+    "missing_context_stop": false
+  },
+  "privacy": {
+    "raw_prompts_omitted": true,
+    "raw_documents_omitted": true,
+    "source_code_omitted": true,
+    "tool_outputs_omitted": true,
+    "tokens_omitted": true,
+    "customer_data_omitted": true
+  },
+  "result": {
+    "status": "safe_to_continue",
+    "next_safe_action": "continue with dry-run refactor plan"
+  }
+}

package/examples/context-attention-receipts/check-attention-receipt.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+const [receiptPathArg] = process.argv.slice(2)
+
+if (!receiptPathArg) {
+  fail(['usage: node check-attention-receipt.mjs <receipt.json>'], 2)
+}
+
+const receiptPath = resolve(process.cwd(), receiptPathArg)
+let receipt
+try {
+  receipt = JSON.parse(readFileSync(receiptPath, 'utf8'))
+} catch (error) {
+  fail([`could not read receipt JSON: ${error.message}`], 2)
+}
+
+const errors = []
+const warnings = []
+
+if (receipt.schema !== 'pluribus.context_attention_receipt.v1') {
+  errors.push('schema must be pluribus.context_attention_receipt.v1')
+}
+
+const requiredIds = ids(receipt.required_context?.map((item) => item.id))
+const deliveredIds = ids(receipt.delivery?.delivered_context_ids)
+const acknowledgedIds = ids(receipt.attention?.acknowledged_before_plan)
+const citedIds = ids(receipt.attention?.cited_in_plan)
+
+if (requiredIds.length === 0) errors.push('required_context must name at least one context id')
+
+for (const id of requiredIds) {
+  if (!deliveredIds.includes(id)) errors.push(`required context not delivered: ${id}`)
+  if (!acknowledgedIds.includes(id)) errors.push(`required context not acknowledged before plan: ${id}`)
+  if (!citedIds.includes(id)) errors.push(`required context not cited in plan: ${id}`)
+}
+
+if (receipt.delivery?.raw_context_omitted !== true) {
+  errors.push('delivery.raw_context_omitted must be true')
+}
+
+const privacy = receipt.privacy || {}
+for (const field of [
+  'raw_prompts_omitted',
+  'raw_documents_omitted',
+  'source_code_omitted',
+  'tool_outputs_omitted',
+  'tokens_omitted',
+  'customer_data_omitted'
+]) {
+  if (privacy[field] !== true) errors.push(`privacy.${field} must be true`)
+}
+
+if (errors.length > 0 && receipt.attention?.missing_context_stop !== true) {
+  errors.push('missing_context_stop must be true when required context attention evidence is incomplete')
+}
+
+if (receipt.result?.status === 'safe_to_continue' && errors.length > 0) {
+  errors.push('result.status cannot be safe_to_continue when required evidence is incomplete')
+}
+
+if (!receipt.delivery?.evidence_path) {
+  warnings.push('delivery.evidence_path is missing; reviewers need a pointer to the audit trail')
+}
+
+const output = {
+  ok: errors.length === 0,
+  receipt_id: receipt.receipt_id || null,
+  task_id: receipt.task_id || null,
+  agent_surface: receipt.agent_surface || null,
+  required_count: requiredIds.length,
+  delivered_count: deliveredIds.length,
+  acknowledged_count: acknowledgedIds.length,
+  cited_count: citedIds.length,
+  status: receipt.result?.status || null,
+  next_safe_action: receipt.result?.next_safe_action || null,
+  errors,
+  warnings
+}
+
+if (output.ok) {
+  console.log(JSON.stringify(output, null, 2))
+  process.exit(0)
+}
+
+console.error(JSON.stringify(output, null, 2))
+process.exit(1)
+
+function ids(value) {
+  return Array.isArray(value) ? value.filter((id) => typeof id === 'string' && id.length > 0) : []
+}
+
+function fail(errors, code) {
+  console.error(JSON.stringify({ ok: false, errors }, null, 2))
+  process.exit(code)
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pluribus-context",
-  "version": "0.3.40",
+  "version": "0.3.41",
   "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",
@@ -89,7 +89,10 @@
     "agent-context-audit",
     "agent-memory",
     "bob",
-    "bob-rules"
+    "bob-rules",
+    "agent-skill",
+    "skillpm",
+    "agent-skills-registry"
   ],
   "author": "Caio Ribeiro",
   "license": "MIT",

package/skills/context-receipts/README.md

@@ -1,6 +1,6 @@
 # Context receipts Agent Skill recipe
 
-This is a small, copyable Agent Skill recipe for context-engineering users who are adopting Tool Search, lazy MCP loading, skills, memory, compaction, or subagents and need to verify what actually crossed the context boundary.
+This is a small, copyable Agent Skill recipe for context-engineering users who are adopting Tool Search, lazy MCP loading, dynamic tool discovery, skills, memory, compaction, GraphRAG/code search, transcript review, or subagents and need to verify what actually crossed the context boundary.
 
 It is intentionally markdown-only so it can be copied into a local skills directory such as:
 
@@ -8,6 +8,11 @@ It is intentionally markdown-only so it can be copied into a local skills direct
 - `.opencode/skills/context-receipts/SKILL.md`
 - `.agents/skills/context-receipts/SKILL.md`
 
+The two newest smoke paths are:
+
+- **Runtime tool-surface diff:** prove which MCP tools were discovered, activated, withheld, or blocked without copying raw schemas/prompts/results.
+- **Context attention:** prove that retrieved/baseline context was delivered, acknowledged before planning, and cited before edits/tool calls.
+
 ## Quick smoke
 
 Ask an agent or harness using the skill to emit a receipt for one workflow and verify these constraints:
@@ -19,9 +24,15 @@ 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 [`../../examples/context-input-evidence/`](../../examples/context-input-evidence/), including the ToolSearch propagation, pruning, and compaction transaction smokes:
+For executable fixture examples, see:
+
+- [`../../examples/tool-surface-diff-receipts/`](../../examples/tool-surface-diff-receipts/) for runtime MCP tool-surface diff receipts.
+- [`../../examples/context-attention-receipts/`](../../examples/context-attention-receipts/) for retrieved-context attention receipts.
+- [`../../examples/context-input-evidence/`](../../examples/context-input-evidence/) for ToolSearch propagation, pruning, and compaction transaction smokes.
 
 ```bash
+node ../../examples/context-attention-receipts/check-attention-receipt.mjs \
+  ../../examples/context-attention-receipts/attention-receipt-pass.json
 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

@@ -45,6 +45,71 @@ Minimal JSONL event names:
 {"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"}
 ```
 
+## Runtime tool-surface diff smoke
+
+For MCP dynamic discovery, gateways, admin/Purview-style audit trails, or runtime tool catalogs, separate discovery from activation:
+
+- which platform/gateway/audit sink observed the runtime catalog change;
+- which catalog/version/hash was active before and after discovery;
+- which tools were discovered, activated, withheld, or blocked;
+- which validation outcome applied, such as `accepted`, `blocked_by_rai`, `blocked_by_xpia`, `schema_invalid`, or `entitlement_filtered`;
+- whether only low-cardinality ids, hashes, counts, and outcome codes entered the receipt;
+- the audit gap, such as not proving the tool was semantically right for the user task.
+
+Minimal JSON shape:
+
+```json
+{
+  "receipt_type": "pluribus.mcp_tool_surface_diff_receipt.v1",
+  "runtime_discovery": {
+    "trigger": "turn_start|admin_refresh|tool_search|manual_refresh",
+    "before_catalog_hash": "sha256:...",
+    "after_catalog_hash": "sha256:..."
+  },
+  "summary": {
+    "discovered_count": 3,
+    "activated_count": 1,
+    "withheld_count": 1,
+    "blocked_count": 1
+  },
+  "privacy": {
+    "raw_schemas_copied": false,
+    "raw_prompts_copied": false,
+    "raw_results_copied": false
+  },
+  "audit_gap": "proves tool-surface boundary, not semantic usefulness"
+}
+```
+
+## Context attention smoke
+
+For GraphRAG, memory, code search, transcript review, or baseline-first workflows, separate retrieval from attention:
+
+- which required context ids were selected or retrieved;
+- where they were delivered, such as prompt, tool result, memory result, subagent packet, or file read;
+- which ids were acknowledged before planning;
+- which ids were cited before edits/tool calls;
+- what the agent must stop on if a required id is missing;
+- whether raw docs, prompts, results, paths, customer text, and full transcript snippets stayed out of the receipt.
+
+Minimal JSON shape:
+
+```json
+{
+  "receipt_type": "pluribus.context_attention_receipt.v1",
+  "required_context_ids": ["ctx:auth-boundary", "ctx:migration-plan"],
+  "delivered_context_ids": ["ctx:auth-boundary", "ctx:migration-plan"],
+  "acknowledged_before_plan_ids": ["ctx:auth-boundary", "ctx:migration-plan"],
+  "cited_before_edit_ids": ["ctx:auth-boundary"],
+  "missing_context_stop": "stop_before_edit",
+  "privacy": {
+    "raw_context_copied": false,
+    "raw_transcript_copied": false
+  },
+  "audit_gap": "proves required context was acknowledged/cited, not that the edit is correct"
+}
+```
+
 ## Skill / prompt context smoke
 
 For skills, rules, AGENTS.md overlays, or instruction files, answer:

package/src/utils/version.js

@@ -1 +1 @@
-export const VERSION = '0.3.40'
+export const VERSION = '0.3.41'