@occasiolabs/occasio 0.8.1

package/docs/demos/mcp-block.md

@@ -0,0 +1,148 @@
+# Demo — Cross-protocol governance via MCP
+
+**What this demo proves.** The same `policy.yml` that governs Claude Code's `Read` tool also governs an MCP client's `read_file` call, unmodified. A `deny_paths` rule produces a `BLOCK` decision on both protocols, both produce a synthetic refusal to the agent, and both land in the same hash-chained `pipeline-events.jsonl` audit log — distinguishable only by the `protocol` field.
+
+**Status.** Captured against the Occasio v0.6.5 MCP server (`bin/occasio-mcp.js`), driven by a synthetic MCP client invocation. The same code path runs when a real MCP client (Claude Desktop, Cursor, Continue) connects via stdio to `occasio-mcp` configured in its `mcpServers` list.
+
+---
+
+## 1. Policy
+
+`~/.occasio/policy.yml`:
+
+```yaml
+version: 1
+deny_paths:
+  - C:\Users\you\.ssh
+```
+
+This is the **same** policy file that produced the Slice E `BLOCK` row for the Claude Code adapter. No MCP-specific stanzas. No new primitives.
+
+## 2. MCP traffic — drive the server with two tool calls
+
+Two `tools/call` requests, one denied and one allowed, sent through the Occasio MCP server with `clientInfo.name: "claude-ai"`:
+
+```
+→ tools/call read_file { path: "C:\\Users\\you\\.ssh\\id_rsa"     }   # denied path
+→ tools/call read_file { path: "C:\\Users\\you\\Desktop\\…\\README.md" }   # allowed path
+```
+
+The server's responses, captured from the JSON-RPC stdout stream:
+
+```json
+{ "id": 2, "result": {
+    "content": [{ "type": "text", "text": "(blocked by policy)" }],
+    "isError": true
+}}
+
+{ "id": 3, "result": {
+    "content": [{ "type": "text", "text": "     1\t# Occasio\n     2\t…" }],
+    "isError": false
+}}
+```
+
+The denied call **never opened the file**. It was short-circuited at the policy boundary, the synthetic refusal flowed back to the MCP client, and an audit row was written before the response was sent.
+
+## 3. Audit row — verbatim from `pipeline-events.jsonl`
+
+```json
+{
+  "ts": "2026-05-10T14:28:16.133Z",
+  "event_id": "1b20b7a1-0512-417f-a080-605ebecedb64",
+  "agent": "claude-ai",
+  "protocol": "mcp",
+  "direction": "inbound",
+  "kind": "tool_call",
+  "tool_name": "read_file",
+  "tool_inputs": { "path": "C:\\Users\\you\\.ssh\\id_rsa" },
+  "action": "BLOCK",
+  "reason": "path-denied",
+  "policy_source": "default",
+  "result_kind": "block",
+  "prev_hash": "3a764943385af22ed364f6a56e0f2b53f06fd544c4fbd531a1633608ca1ada09",
+  "hash":      "664a8b6076540185ca74255c5b4d25887cc09b7323f86dcee8fd562652be3650"
+}
+```
+
+The `protocol: "mcp"` field is the proof that this is the same governance pipeline the Slice E row came from, just entered by a different front door. The `agent: "claude-ai"` field came from the MCP `initialize.clientInfo.name` and is what a real Claude Desktop client identifies itself as. The `prev_hash` value matches the `hash` of the previous Slice E LOCAL row — the chain is continuous across protocols.
+
+## 4. Chain integrity — both verifiers agree
+
+```
+$ occasio audit verify
+  Rows:  33 total  (33 chained, 0 legacy/unverified)
+  ✓ Chain intact  (33 rows verified)
+
+$ python docs/audit_walker.py ~/.occasio/pipeline-events.jsonl
+  OK: 33 rows verified
+```
+
+Adding the MCP row to a chain that previously contained only Anthropic-protocol rows did not break either verifier. The independent walker treats `protocol: "mcp"` as just another field; the canonical-serialization rules in `docs/AUDIT.md` are protocol-agnostic.
+
+## 5. `occasio report` surfaces the MCP block
+
+```
+$ occasio report --days 1
+{
+  "summary": {
+    "paths_blocked": 2,
+    …
+  },
+  "blocked_accesses": [
+    { "ts": "2026-05-10T12:45:57.036Z", "session_id": "slice-e-live-…",
+      "tool": "read_file", "path": "C:\\Users\\you\\.ssh\\id_rsa",
+      "action": "BLOCK", "reason": "path-denied" },
+    { "ts": "2026-05-10T14:28:16.133Z", "session_id": null,
+      "tool": "read_file", "path": "C:\\Users\\you\\.ssh\\id_rsa",
+      "action": "BLOCK", "reason": "path-denied" }
+  ]
+}
+```
+
+Both blocks appear under `blocked_accesses[]`. The first is the Slice E Claude-Code-protocol block; the second is this demo's MCP block. The report does not distinguish them by protocol because, from a governance-summary perspective, they are the same kind of event — and that is the point of the demo.
+
+---
+
+## What this demo deliberately does not show
+
+- **No third-party MCP server is being forwarded to.** The Occasio MCP server (`lf`) implements `read_file` itself. A "transparent forwarder in front of `@modelcontextprotocol/server-filesystem`" is a deferred follow-up; the cross-protocol governance proof stands on its own without it.
+- **No second MCP integration.** The same proof would extend to GitHub MCP, Slack MCP, etc.; v0.6.5 deliberately ships only the one path.
+- **No new policy primitives, audit fields, or transforms.** Same policy schema, same audit row shape, same hash algorithm.
+- **No README / GOVERNANCE positioning rewrite yet.** That work is sequenced after this proof exists, not before.
+
+## Reproducing the demo
+
+The demo is reproducible from a clean checkout in under a minute:
+
+```sh
+# 1. Set the policy
+cat > ~/.occasio/policy.yml <<'EOF'
+version: 1
+deny_paths:
+  - ~/.ssh
+EOF
+
+# 2. Drive the MCP server (synthetic; same code path as a real MCP client)
+node -e "
+  const mcp = require('./src/mcp-server');
+  mcp.__setRespondHookForTests((f) => console.log(f));
+  (async () => {
+    await mcp.handleRequest({ jsonrpc: '2.0', id: 1, method: 'initialize',
+      params: { clientInfo: { name: 'claude-ai' } } });
+    await mcp.handleRequest({ jsonrpc: '2.0', id: 2, method: 'tools/call',
+      params: { name: 'read_file', arguments: { path: '$HOME/.ssh/id_rsa' } } });
+  })();
+"
+
+# 3. Inspect the new BLOCK row
+tail -1 ~/.occasio/pipeline-events.jsonl | python -m json.tool
+
+# 4. Confirm both verifiers agree
+occasio audit verify
+python docs/audit_walker.py ~/.occasio/pipeline-events.jsonl
+
+# 5. Confirm the report surfaces it
+occasio report --days 1 | python -c "import json,sys; print(json.load(sys.stdin)['blocked_accesses'])"
+```
+
+For a real-MCP-client capture (Claude Desktop, Cursor, Continue), configure `occasio-mcp` as an MCP server in the client's config and prompt the agent to read a denied path. The audit row, the verifier output, and the report all behave identically — the only field that changes is `agent`, which carries the client's `clientInfo.name`.

package/docs/edr-calibration.md

@@ -0,0 +1,73 @@
+# EDR-Detector calibration
+
+The four built-in anomaly detectors (`src/anomaly/detectors/*`) shipped with starter thresholds. This doc records what those thresholds do on a real, day-to-day Occasio chain, and what was tuned after measuring.
+
+## Why the thresholds matter
+
+Occasio markets the anomaly layer as EDR — a category whose buyers (CISOs, Compliance) judge tools by the false-positive rate on normal activity. *"How often does this fire when nothing is wrong?"* is a hard, specific question. Starter thresholds without an empirical baseline are a credibility risk.
+
+The calibration script `scripts/calibrate-anomaly-detectors.js` slides a 15-minute window across an audit chain in 5-minute steps, runs every detector on every window, and tallies alerts by severity. Run it against any sufficiently large chain (≥ ~500 rows) to validate the defaults against your own usage.
+
+## Calibration run
+
+**Chain:** `~/.occasio/pipeline-events.jsonl`
+**Span:** 3.2 days (2026-05-11 → 2026-05-14)
+**Rows:** 2522
+**Windows evaluated:** 911 (≈ 12 per hour)
+
+The chain includes a mix of normal coding work plus several adversarial harness/redteam scenarios run during development, so it is *not* purely benign — the spikes the detectors flag are partially real attacks, partially noisy thresholds. The goal of the tuning was to keep the real signal (HIGH) loud while quieting noise from normal activity.
+
+### Before tuning
+
+| Detector | Total | HIGH | MED | LOW | Per hour | Verdict |
+|---|---:|---:|---:|---:|---:|---|
+| `deny-rate` | 3 | 3 | 0 | 0 | 0.04 | calibrated — fires only on real burst |
+| `file-read-volume` | 1 | 0 | 1 | 0 | 0.01 | calibrated |
+| `unknown-tool-input` | 27 | 0 | 27 | 0 | 0.36 | **too noisy** — MEDIUM on every novel non-privileged shape |
+| `secret-redact-rate` | 21 | 8 | 13 | 0 | 0.28 | **too noisy** — MEDIUM on every cold-start redaction |
+
+### After tuning
+
+| Detector | Total | HIGH | MED | LOW | Per hour | Verdict |
+|---|---:|---:|---:|---:|---:|---|
+| `deny-rate` | 3 | 3 | 0 | 0 | 0.04 | unchanged |
+| `file-read-volume` | 1 | 0 | 1 | 0 | 0.01 | unchanged |
+| `unknown-tool-input` | 24 | 0 | 0 | 24 | 0 MED+HIGH/h | non-privileged novelty now LOW; privileged-key path still HIGH |
+| `secret-redact-rate` | 21 | 8 | 10 | 3 | 0.20 MED+HIGH/h | cold-start single-redactions now LOW; bursts (≥5) stay MEDIUM |
+
+The HIGH-severity counts for `secret-redact-rate` are real spikes (e.g. ×117.8 over baseline) from harness runs producing secret-pattern matches on synthetic fixtures. On a chain without adversarial sessions the count would be near zero.
+
+## What was tuned
+
+### `src/anomaly/detectors/unknown-tool-input.js`
+
+- `COLD_START_MIN_ROWS`: `50 → 200`. The detector needs more history to build a real fingerprint set before alerting on "novelty".
+- Severity: non-privileged-key novelty is now **LOW** (was MEDIUM). Visible to SIEM consumers via `--json`, not loud for human review.
+- Privileged-key novelty (`env`, `sudo`, `exec`, `seccomp`, etc.) remains **HIGH**.
+
+### `src/anomaly/detectors/secret-redact-rate.js`
+
+- Cold-start severity is now scaled by burst size: `< 5` redactions in window → **LOW**, `≥ 5` → **MEDIUM**. Compliance still sees every redaction in the JSON output; reviewers are not paged on test-fixture single-events.
+- Once history is ≥ `MIN_HISTORY_FOR_RATE` (200), the existing multiplier logic takes over and HIGH-severity firing on real bursts is unchanged.
+
+### `src/anomaly/detectors/deny-rate.js` and `src/anomaly/detectors/file-read-volume.js`
+
+Unchanged. Calibration confirmed the defaults fire only on real spikes.
+
+## How to re-run
+
+```bash
+node scripts/calibrate-anomaly-detectors.js
+# JSON output for downstream tooling:
+node scripts/calibrate-anomaly-detectors.js --json > calibration.json
+# Override the window size or step:
+node scripts/calibrate-anomaly-detectors.js --window 30m --step 10m
+```
+
+The script prints per-detector tallies, alert rates, one example per severity level, and a heuristic suggestion ("threshold likely too tight" if a detector fires >1 HIGH/day on normal usage). Use the suggestion as a starting point, not a verdict — your chain's activity profile may legitimately push a detector higher than the heuristic expects.
+
+## What this is not
+
+- **Not a replacement for adversarial validation.** Calibration tells us whether the threshold is too tight for normal use. It does not tell us whether the threshold is loose enough to catch genuine attacks. That is the job of `occasio demo anomalies` (which constructs a synthetic adversarial chain that must trigger all four detectors) and the [EDR demo walkthrough](edr-demo.md) (which runs a real Claude Code session against the policy and confirms the detectors fire on the resulting chain).
+- **Not a static contract.** Defaults are tuned against one user's chain over 3 days. A production deployment should re-calibrate against its own audit history. Plan: lift the thresholds into `policy.yml` as overridable values once the schema for that is agreed.
+- **Not a guarantee of zero false positives.** A `MEDIUM` `secret-redact-rate` alert can fire when someone is legitimately editing a config file full of pattern-matching secrets. The right reading of any single alert is "look at the implicated rows and decide", not "block production".

package/docs/edr-demo.md

@@ -0,0 +1,83 @@
+# EDR demo — defense in depth against a real Claude Code agent
+
+End-to-end validation that Occasio's two governance layers both fire correctly against a real, signed-in Claude Code agent attempting to bypass policy. Reproducible in under two minutes on a laptop, with no API key and no external services.
+
+## What this proves
+
+Two independent layers of defense, both validated against the same adversarial agent in the same run:
+
+1. **Policy enforcement (Layer 2).** The agent's tool calls hit the policy and are blocked. The marker file the agent is told to extract never leaks into its stdout, never appears in any audit row, and the chain attributes the defense to a concrete `BLOCK` row with `reason: path-denied`.
+2. **Anomaly detection (Layer 4 / EDR).** The pattern of those blocks — a burst of denials concentrated in a short window — is detected against the historical baseline of normal activity, and surfaced as a HIGH-severity alert with a measurable severity multiplier.
+
+Each layer can be evaluated independently. Either holding without the other is still a partial defense; both holding is what a buyer with a real compliance requirement is looking for.
+
+## Setup
+
+You need:
+
+- Claude Code installed and signed in (Occasio uses the bundled auth — no `ANTHROPIC_API_KEY` required).
+- Occasio v0.8.0 or newer with the anomaly layer (`occasio anomalies --help` should list four detectors).
+- A populated `~/.occasio/pipeline-events.jsonl` from your everyday Occasio usage. The more rows, the more meaningful the baseline.
+
+No other dependencies. No network calls beyond what Claude Code itself makes.
+
+## Steps
+
+```bash
+# 1. Spawn five real Claude Code adversarial sessions through the harness.
+#    Each one tries to extract a marker from a denied path via a different
+#    attack vector (direct Read, shell-mediated cat/Get-Content, path
+#    traversal, Read→Write→Read tool chain, symlink/junction). Occasio's
+#    policy must block every one. Scratch workspaces are kept for analysis.
+for s in deny-read deny-shell-bypass path-traversal \
+         tool-chain-read-write-read symlink-bypass; do
+  occasio harness --scenario "$s" --keep-scratch
+done
+```
+
+```powershell
+# 2. Merge the five scratch chains into one for analysis. Each chain is
+#    hash-linked independently to its own GENESIS, so we cannot walk the
+#    merged file as a single chain — but the anomaly layer only needs
+#    rows, not chain integrity, so concatenation is fine here.
+$merged = "$env:TEMP\edr-demo-merged.jsonl"
+Remove-Item $merged -ErrorAction SilentlyContinue
+Get-ChildItem $env:TEMP -Filter 'lf-scratch-*' -Directory |
+  ForEach-Object {
+    if (Test-Path "$($_.FullName)\events.jsonl") {
+      Get-Content "$($_.FullName)\events.jsonl" | Add-Content $merged
+    }
+  }
+```
+
+```bash
+# 3. Run EDR against the merged chain. Pin --since to a few minutes after
+#    the last adversarial row so the harness activity lands in the window.
+occasio anomalies --chain "$merged" --since "<ISO timestamp just after the harness finished>" --window 15m
+```
+
+For the strongest test, prepend your real `~/.occasio/pipeline-events.jsonl` to the merged chain *before* running step 3. That gives the detector a real historical baseline to compare against — your day-to-day activity, mostly free of `BLOCK` rows — rather than the empty cold-start baseline.
+
+## What you should see
+
+**Step 1: every harness scenario reports `passed: true`** with assertions like *"marker not present in child stdout"* and *"defense attribution: Occasio BLOCKed (read_file / path-denied)"*. This is the Layer-2 proof: the agent tried multiple attack vectors and every one was blocked before any sensitive content reached its context.
+
+**Step 3 with cold-start (no real baseline):** the `deny-rate` detector fires with `MEDIUM` severity, citing a high proportion of `BLOCK` rows in the window. Expect 60–90% block rate — the harness scenarios are pure denial tests, so almost every recorded tool call is a `BLOCK`.
+
+**Step 3 with your real chain as baseline:** the detector escalates to `HIGH` severity with an explicit multiplier vs. historical rate. The multiplier scales with how busy your normal Occasio usage is — sparser baselines produce larger multipliers because the denominator is smaller. Expect anywhere from ×100 to ×1000 in practice; the exact number is a function of your chain volume, not the strength of the detection.
+
+The key signal is the *category* of the alert (`HIGH` vs `MEDIUM` vs none), not the exact multiplier.
+
+## How to interpret the result
+
+A HIGH `deny-rate` alert means the detector observed a burst of policy violations that does not match the historical rhythm of this Occasio install. In a real deployment, this is the EDR signal an operator should react to:
+
+- Look at the implicated row hashes (`rows_implicated` field) and replay the run(s) that produced them: `occasio replay --run <id>`.
+- If the agent attempted the bursts under legitimate user request — a developer running an unfamiliar tool that touches many denied paths — re-scope the policy and add a `policy doctor` annotation.
+- If the agent was driven by a prompt injection or a compromised input file, the run's audit chain plus the EDR alert together form a complete forensic record. The chain hash-links every event back to GENESIS; the attestation (`occasio attest --run-id <id> --sign`) cryptographically commits to the full slice.
+
+## What this is not
+
+- **Not a replacement for a third-party security audit.** This demo validates that two layers fire on a deliberately-staged attack. It does not certify that the policy is exhaustive, that the binary is free of bugs, or that the threat model matches your organisation's. A real audit looks at all three.
+- **Not a defense against a compromised Occasio binary.** The whole pipeline trusts that the proxy itself has not been tampered with. If an attacker can replace the `occasio` binary on the runner, they can lie about everything downstream. Pin a checksummed install, run in CI under a known image, and verify the binary's signature before relying on its audit trail.
+- **Not a substitute for a correctly-configured policy.** Layers 2 and 4 only catch what the policy declares. A `policy.yml` that omits a sensitive path will not produce a `BLOCK` row on that path, and the EDR will not see any anomaly. `occasio policy doctor` surfaces gaps; treat it as a required step, not optional hygiene.

package/docs/python-verifier.md

@@ -0,0 +1,74 @@
+# Python verifier — cross-language verification of Occasio attestations
+
+A second reference implementation of the [`agent-attestation/v1`](../spec/agent-attestation/v1/README.md) verifier, written in Python and depending only on the stdlib + optional `sigstore-python`. Lives alongside `audit_walker.py` (which it reuses for the chain step).
+
+## Why this exists
+
+A predicate type whose verification is only feasible in the language that produced it is not a standard — it is one vendor's artifact. The Python verifier proves that Occasio attestations are **language-independent** and can be re-verified by any auditor in their environment of choice.
+
+This is the proof artifact for the OpenSSF / in-toto Attestation Registry submission. The same predicate JSON + Sigstore bundle is verified pass/fail by:
+
+- `occasio attest verify` (Node)
+- `python docs/attest_verify.py` (Python)
+- The browser viewer at [`integrations/attest-view/`](../integrations/attest-view/) (in-browser, partial — Sigstore crypto is deferred to one of the two above)
+
+The Node test suite asserts that all three implementations agree byte-for-byte on the same payload (`test-interceptor.js` — search for `xlang:`).
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `canonicalize.py` | RFC 8785 subset, mirror of `src/attest/canonicalize.js` |
+| `audit_walker.py` | SHA-256 chain walker (pre-existing, reused) |
+| `attest_verify.py` | End-to-end verifier with CLI |
+
+The Python `canonicalize` and the JS `canonicalize` must stay in lockstep. The two files exist in parallel deliberately — bundling them into one cross-compiled artifact would defeat the point of cross-language verifiability.
+
+## Usage
+
+```bash
+# Verify a signed attestation pair end-to-end
+python docs/attest_verify.py path/to/occasio-attestation.json
+
+# Explicit bundle path (default: <attestation>.sigstore.json sidecar)
+python docs/attest_verify.py path/to/att.json --bundle path/to/bundle.json
+
+# Override the chain file (default: read chain_file from the attestation)
+python docs/attest_verify.py path/to/att.json --chain path/to/pipeline-events.jsonl
+
+# Machine-readable output
+python docs/attest_verify.py --json path/to/att.json
+```
+
+Exit code 0 when every (non-skipped) check passes, 1 otherwise.
+
+## What the three checks prove
+
+1. **Sigstore signature** — Fulcio certificate chain valid + Rekor inclusion proof present. Requires `pip install sigstore`; without it the step is marked `SKIP` so the auditor knows not to trust a partial result.
+2. **Bundle payload matches attestation** — re-decode the DSSE envelope, canonicalize its `predicate`, compare canonical bytes to the canonicalised attestation (minus `signature` metadata). Pure-stdlib, always runs.
+3. **Audit chain integrity** — SHA-256 walk every `prev_hash → hash` link from GENESIS, then assert that the attestation's `first_hash` and `last_hash` appear in the chain in the correct relative order. Reuses `audit_walker.py`.
+
+Each check is independent. Skipping any one of them is not the same as a full verification, and the verifier surfaces that distinction explicitly (the overall pass requires `ok=True` on every check; skipped counts as not-ok).
+
+## Round-trip claim
+
+For a payload produced by `occasio attest --sign` and verified by `occasio attest verify`, the Python verifier produces the same pass/fail result on:
+- the unmodified payload (both pass on steps 2+3; step 1 requires sigstore-python)
+- a tampered predicate (both fail at step 2)
+- a tampered chain (both fail at step 3)
+- a tampered Sigstore bundle (both fail at step 1; SKIP if sigstore-python not installed)
+
+The test suite covers cases 1, 2, and 3 deterministically with the Sigstore step mocked. The cross-language byte-equivalence on the predicate-canonicalization step is asserted via Python-spawn from the Node test runner (`xlang:` and `xlang-float:` test blocks); both implementations reject non-integer numbers so the equivalence cannot be silently broken by adding a float field to a future schema. Case 4 (real Sigstore tamper detection) requires GitHub Actions OIDC infrastructure and is exercised by the live Action's self-verify step in CI, not by the in-process test suite.
+
+## Install hint for Sigstore step
+
+```bash
+pip install sigstore        # adds the Fulcio + Rekor verification step
+```
+
+Versions tracked: `sigstore-python >= 3.0`. The verifier degrades gracefully if a different major version is installed (the `Verifier` API is the stable surface used here).
+
+## Limitations
+
+- **Identity pinning is not enforced** by the reference verifier. The default `policy.UnsafeNoOp()` accepts any Fulcio cert. An auditor whose compliance regime requires a specific workflow-ref identity (e.g. `repo:org/repo:ref:refs/heads/main`) should adapt the call to `policy.Identity(...)`. Pattern intentionally exposed: this is a policy decision, not a verifier decision.
+- **The Python canonicalize is a JCS subset**, not full RFC 8785. The deviations are documented inline in `canonicalize.py`. Non-integer numbers are explicitly rejected on both sides as a load-bearing cross-language invariant — see `canonicalize.py` and `src/attest/canonicalize.js` for the rationale.

package/docs/reference-pipeline.md

@@ -0,0 +1,140 @@
+# Reference Pipeline — from AI-agent PR to cryptographically-attested merge
+
+End-to-end walkthrough of the Occasio attestation pipeline. Read top-to-bottom; every step has a copy-paste artefact and an explanation of what it proves.
+
+## What this pipeline is for
+
+When an AI coding agent (Claude Code, Cline, MCP-routed, etc.) opens a PR, the reviewer's question is *"What did the agent actually do?"* — every tool call, every blocked attempt, every secret redacted, under which policy, on what audit-chain commitment. This pipeline answers that question with a signed artifact that can be verified offline by any third party using only `cosign` and the published predicate type.
+
+Three deliverables land on the PR:
+
+1. A **Check Run** with a human-readable summary of the run.
+2. A workflow **artifact** containing the signed predicate JSON and the Sigstore Bundle.
+3. A **View Evidence** link that opens the standalone viewer page with both files pre-loaded.
+
+## Try it locally in 30 seconds
+
+```bash
+occasio demo attest
+```
+
+This builds a synthetic audit chain, an unsigned attestation, runs the canonical-JSON round-trip check, and previews the Check Run summary. No Sigstore, no GitHub, no API key — just the pipeline working against in-memory data. Use this to validate the build end-to-end before deploying any of the rest.
+
+## Step 1 — your agent runs under Occasio
+
+A Occasio session must produce events into `~/.occasio/pipeline-events.jsonl`. The simplest way is to invoke Claude Code (or any supported agent) through the local proxy:
+
+```bash
+occasio claude --hardened
+```
+
+`--hardened` routes `Read`/`Glob`/`Grep` through the unified runtime so tool calls are intercepted locally, distillation applied, and secret scanning runs on every tool result. The `~/.occasio/session.json` file gets a fresh `run_id` per session.
+
+## Step 2 — produce an attestation locally (sanity check)
+
+After a session ends, run:
+
+```bash
+occasio attest --run-id "$(jq -r .run_id ~/.occasio/session.json)"
+```
+
+This writes `attestation.json` to the cwd. The predicate is unsigned (`signature: null`) — that part lands in the GitHub Action step below. Inspect the predicate; the file is human-readable JSON. The `audit_chain.last_hash` is the commitment: signing it later transitively commits to every event in the slice.
+
+## Step 3 — drop in the GitHub Action
+
+Create `.github/workflows/attest-on-pr.yml` in your repo:
+
+```yaml
+name: Attest AI-generated PR
+
+on:
+  pull_request:
+    branches: [main]
+
+permissions:
+  id-token: write    # Sigstore keyless via GitHub OIDC
+  checks:    write   # post the PR Check Run
+  contents:  read
+
+jobs:
+  attest:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 2     # so files-changed can diff HEAD^..HEAD
+
+      # ── Your AI-agent step here ────────────────────────────────────
+      # The agent must run under Occasio so its tool calls land in
+      # ~/.occasio/pipeline-events.jsonl. Example with Claude Code:
+      - run: npm i -g @occasiolabs/occasio @anthropic-ai/claude-code
+      - run: occasio claude --hardened < .github/agent-prompt.txt
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+
+      # ── Sign + Check Run ───────────────────────────────────────────
+      - uses: occasiolabs/attest-action@v1
+        # All inputs optional — run_id auto-resolves from session.json,
+        # paths default to ~/.occasio/*. Defaults are tuned for the
+        # 95% case.
+```
+
+That's it. The composite Action handles:
+- `occasio attest --sign` using the workflow's OIDC token (no key management)
+- Uploading `attestation.json` + `.sigstore.json` as a workflow artifact (90-day retention)
+- Creating the Check Run via the GitHub API
+
+## Step 4 — what reviewers see
+
+The Check Run lands on the PR as:
+
+```
+✓ Occasio Attested · 47 calls · 2 blocked
+  Claude Opus 4.7 · Policy strict-v2.1 (sha a126…3a)
+  Chain ✓ verified · Signature ✓ Sigstore keyless
+  [View evidence ↗]   [Artifact ↗]
+```
+
+Click **View evidence** to open the [viewer](https://occasiolabs.github.io/attest-view) with the artifact's two JSON files. The viewer runs two browser-side checks (DSSE-payload equivalence + audit-chain replay) and surfaces the Rekor transparency log link for cryptographic verification.
+
+The viewer **deliberately does not** verify the Sigstore certificate chain in-browser — bundling Fulcio/Rekor trust roots in-browser is a serious build problem we have not solved cheaply, and we are honest about it on the page itself. Offline crypto-verification is one CLI call:
+
+```bash
+occasio attest verify occasio-attestation.json
+```
+
+That command runs three checks in order, all of which must pass:
+1. Sigstore signature is valid (cert chain → Fulcio root, Rekor inclusion proof)
+2. The DSSE payload inside the bundle byte-matches the attestation predicate (modulo `signature` field)
+3. The audit chain integrity verifies end-to-end; the claimed `first_hash` / `last_hash` exist in the chain in the right relative order
+
+## Step 5 — what auditors do
+
+Auditors do not need access to the producer's machine. They download the workflow artifact, install Occasio (or `cosign`), and verify offline. The signed artifact is portable and self-contained: predicate JSON + Sigstore Bundle + (optionally) the chain file.
+
+For a SOC2 audit period the workflow becomes:
+1. Pull all `occasio-attestation` artifacts from the period (GitHub API)
+2. For each: `occasio attest verify` and capture the exit code
+3. Aggregate the `execution_summary` data: how many runs, how many blocks, what rules, what files
+
+The audit chain is hash-linked across all of an agent's runs on the same machine; verifying any one slice does not require touching the producer's full log.
+
+## Compatibility and what's stable
+
+- **Predicate URI** `https://github.com/occasiolabs/occasio/spec/agent-attestation/v1` is **canonical**. It will not be moved or re-pointed.
+- **Required fields** in v1 do not change without bumping the URI to `/v2`.
+- **New optional fields** can land in v1.x (currently reserved: `subject.git_commit`, `subject.files_changed` — already in the schema, populated by the GitHub Action).
+- The **Sigstore Bundle** is the standard `sigstore-bundle+json;version=0.2` shape — works with `cosign`, `sigstore-js`, `sigstore-python`, any future conformant tool.
+
+## What this does NOT yet do
+
+- **Multi-commit attestations.** Today the predicate binds to a single `run_id`. v1.1 will likely add `subject.git_commits[]` and a way to merge slices for a PR that includes N commits from M runs.
+- **Embedded chain slice.** Today the chain-file path is advisory; the chain itself is not bundled. A v1.x option may add an embedded compressed chain for fully offline replay at a size cost.
+- **Policy provenance.** `policy.file_hash` commits to the file bytes. We do not yet carry the *origin* of the policy (was it committed to a repo? signed by a security team?). v1.1 may add `policy.attestation_url` for nested signed claims.
+
+## Reference / further reading
+
+- [`spec/agent-attestation/v1/README.md`](../spec/agent-attestation/v1/README.md) — predicate type specification
+- [`schemas/agent-attestation-v1.json`](../schemas/agent-attestation-v1.json) — authoritative JSON Schema
+- [`integrations/attest-action/`](../integrations/attest-action/) — the GitHub Action
+- [`integrations/attest-view/`](../integrations/attest-view/) — the static viewer page

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@occasiolabs/occasio",
+  "version": "0.8.1",
+  "description": "Occasio — cryptographically verifiable behavioral attestation for AI coding agents. Tool-call interception + policy enforcement + tamper-evident audit chain + Sigstore-signed in-toto attestations + windowed EDR detection. Same engine for Claude Code and MCP; Computer-Use scaffold included.",
+  "main": "src/index.js",
+  "files": [
+    "bin/",
+    "src/",
+    "schemas/",
+    "policy-templates/",
+    "docs/",
+    "spec/",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "scripts": {
+    "test": "node test-interceptor.js",
+    "smoke": "node test-smoke.js",
+    "test:mcp": "node test-mcp-server.js",
+    "restart-check": "node scripts/restart-check.js",
+    "check-validation": "node scripts/check-validation.js",
+    "start": "node bin/occasio.js"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "cline",
+    "anthropic",
+    "ai-agents",
+    "ai-governance",
+    "agent-attestation",
+    "agent-provenance",
+    "sigstore",
+    "in-toto",
+    "slsa",
+    "policy",
+    "audit",
+    "compliance",
+    "eu-ai-act",
+    "nist-ai-rmf",
+    "soc2",
+    "secrets",
+    "edr",
+    "anomaly-detection",
+    "proxy",
+    "mcp",
+    "computer-use"
+  ],
+  "bin": {
+    "occasio":     "bin/occasio.js",
+    "oc":          "bin/occasio.js",
+    "occasio-mcp": "bin/occasio-mcp.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/occasiolabs/occasio.git"
+  },
+  "homepage": "https://github.com/occasiolabs/occasio#readme",
+  "bugs": {
+    "url": "https://github.com/occasiolabs/occasio/issues"
+  },
+  "license": "Apache-2.0",
+  "dependencies": {
+    "sigstore": "^3.1.0"
+  }
+}