dativo-io · sergeyenin · Jun 3, 2026 · Jun 3, 2026
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -91,7 +91,7 @@ gh api "/repos/dativo-io/talon/actions/workflows/release.yml/runs?per_page=1" -q
 docker pull ghcr.io/dativo-io/talon:latest
 ```
 
-Check that release notes link at least one share artifact (screenshot, GIF, or migration snippet).
+Check that release notes link at least one share artifact (screenshot, GIF, or migration snippet). To refresh Mission Control screenshots, see [docs/contributor/mission-control-screenshots.md](docs/contributor/mission-control-screenshots.md).
 
 ## Weekly Repo Quality Scorecard (maintainers)
 

diff --git a/LIMITATIONS.md b/LIMITATIONS.md
@@ -56,3 +56,4 @@ A valid signature proves that this evidence record was signed with the deploymen
 - [Evidence integrity specification](docs/reference/evidence-integrity-spec.md) — byte-exact fields, serialization, signing, and independent verification
 - [Threat model](docs/reference/threat-model.md) — attack surface, trust boundaries, and key-management assumptions
 - [Reproducible benchmarks](docs/reference/benchmarks.md) — run `make benchmarks` on your hardware; retry/fallback overhead not included until Epic #113 lands.
+- [Sample auditor pack](examples/auditor-pack/README.md) — example signed export and compliance report (`make auditor-pack`)
diff --git a/Makefile b/Makefile
@@ -16,7 +16,7 @@ ifeq ($(UNAME_S),Darwin)
   GO_ENV := env -u CC CC=/usr/bin/clang CGO_ENABLED=1
 endif
 
-.PHONY: help build install test test-integration test-e2e test-smoke test-all test-ssot-gate conformance benchmarks lint fmt clean vet mod-tidy check docker-build demo-gateway demo-full demo-clean verify-flow0 nosec-count
+.PHONY: help build install test test-integration test-e2e test-smoke test-all test-ssot-gate conformance benchmarks auditor-pack verify-newcomer lint fmt clean vet mod-tidy check docker-build demo-gateway demo-full demo-clean verify-flow0 nosec-count
 
 # Conformance suite: the evidence + policy paths whose passing test/subtest
 # count is published as Talon's honest conformance number. See
@@ -66,6 +66,12 @@ conformance: ## Run the evidence + policy conformance suite and print the passin
 benchmarks: ## Run reproducible micro-benchmarks (gateway overhead, PII scan, evidence write)
 	@bash scripts/run-benchmarks.sh
 
+auditor-pack: ## Generate sample auditor pack from docker-compose demo (examples/auditor-pack/)
+	@bash scripts/generate-auditor-pack.sh
+
+verify-newcomer: ## Smoke-test cold-start path (talon init + dry-run)
+	@bash scripts/verify-newcomer-path.sh
+
 lint: ## Run linter
 	@golangci-lint run ./...
 

diff --git a/README.md b/README.md
@@ -312,6 +312,20 @@ llm:
 
 ---
 
+## Proof Pack (trust & verification)
+
+Artifacts a skeptical reviewer can grep in one session:
+
+- [Limitations](LIMITATIONS.md) — what Talon does and does not prove
+- [Threat model](docs/reference/threat-model.md) — attack surface and trust boundaries
+- [Evidence integrity specification](docs/reference/evidence-integrity-spec.md) — byte-exact signing and verification
+- [Conformance suite](docs/reference/conformance.md) — `make conformance` (evidence + policy paths)
+- [Benchmarks](docs/reference/benchmarks.md) — `make benchmarks` on your hardware
+- [Sample auditor pack](examples/auditor-pack/README.md) — signed export + compliance report (`make auditor-pack`)
+- [Roadmap & focus](ROADMAP.md) — public anti-goals and EMEA SMB direction
+
+---
+
 ## Docs
 
 - [Documentation index](docs/README.md)

diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md
@@ -1,6 +1,6 @@
 # Talon Quick Start
 
-This page points you to the right doc for what you want to do.
+This page points you to the right doc for what you want to do. For the full documentation map, see [docs/README.md](README.md).
 
 ---
 
@@ -13,72 +13,69 @@ This page points you to the right doc for what you want to do.
 → [OpenAI proxy quickstart](tutorials/proxy-quickstart.md)
 
 **2.** I'm building something new and want controls from day one.  
-→ [Your first agent with Talon](tutorials/first-governed-agent.md)
+→ [Your first governed agent](tutorials/first-governed-agent.md)
 
-**3.** I want to understand how it works before touching anything.  
+**3.** I want to understand how it works before touching anything (no API key).  
 → [60-second demo (no API key)](tutorials/quickstart-demo.md)
 
+**4.** I need to review what an auditor handoff looks like.  
+→ [Sample auditor pack](../examples/auditor-pack/README.md)
+
+---
+
+## Install (native binary)
+
+See the [README install matrix](../README.md#install). Summary:
+
+| Platform | Recommended |
+|----------|-------------|
+| **macOS / arm64 Linux** | `git clone … && make install` or `go install github.com/dativo-io/talon/cmd/talon@latest` |
+| **linux/amd64 server** | Release tarball or `curl -sSL https://install.gettalon.dev \| sh` |
+| **No install** | [Docker Compose demo](../examples/docker-compose/README.md) |
+
+On macOS, if linking fails with `unsupported tapi file type`, use `make install` (sets system Clang) or `CC=/usr/bin/clang CGO_ENABLED=1 go install …`.
+
 ---
 
 ## Minimal commands (if you already know Talon)
 
 ```bash
 # Install (from repo)
-make build    # → bin/talon
+make install    # → $(go env GOPATH)/bin/talon
+
+# Secrets key (required for vault)
+export TALON_SECRETS_KEY="$(openssl rand -hex 32)"
+
+# New project
+mkdir my-agents && cd my-agents
+talon init --scaffold --name my-agent
 
-# New project (in a terminal: interactive wizard; in scripts/CI: use --scaffold or --pack)
-mkdir my-agents && cd my-agents && talon init
-# Non-interactive: talon init --scaffold   or   talon init --pack openclaw
+# Policy check without LLM spend
+talon run --dry-run "Your query here"
 
-# Set key and run
+# Live run (needs provider key)
 export OPENAI_API_KEY=sk-proj-...
-talon run "Your query here"   # Uses agent name from policy when --agent omitted
+talon run "Your query here"
 
 # Server (API + dashboard + optional gateway/proxy)
 export TALON_ADMIN_KEY="replace-with-strong-admin-key"
 talon serve --port 8080
-# OpenAI-compatible local drop-in (dev): OPENAI_BASE_URL=http://127.0.0.1:8080/v1
-talon serve --proxy-quickstart --port 8080
-# With LLM gateway: talon serve --gateway --gateway-config examples/gateway/talon.config.gateway.yaml
-# With MCP proxy:   talon serve --proxy-config path/to/proxy.yaml
 ```
 
-## Verify It Works (2-minute governance loop)
+Verify the cold-start path from repo root: `make verify-newcomer`.
 
-After running your first agent, prove the governance loop is working:
-
-```bash
-# 1. List the most recent governance evidence (audit trail)
-talon audit list --limit 1
-
-# 1a. Tail the live operational projection (same feed as dashboard recent activity)
-talon events tail --url http://localhost:8080
-
-# Expected output:
-# ┌──────┬──────────────────────────────────┬─────────┬──────────┐
-# │ ID   │ Timestamp                       │ Agent   │ Decision │
-# ├──────┼──────────────────────────────────┼─────────┼──────────┤
-# │ evt_1│ 2026-04-14T22:08:00Z             │ default │ approved │
-# └──────┴──────────────────────────────────┴─────────┴──────────┘
-
-# 2. Verify a specific evidence entry
-talon audit verify <evidence-id>
-
-# Expected output:
-# ✅ Evidence verified: policy=allow, reason=query matches allowlist rule #1
-```
-
-This confirms Talon is logging decisions and you can inspect the full audit trail at any time.
+---
 
-If evidence persistence degrades, `GET /v1/status` exposes:
-- `evidence_ok=false`
-- `last_good_write`
-- `evidence_error` and `evidence_error_at`
+## Trust artifacts (Proof Pack)
 
-For full configuration and options see [Configuration and environment](reference/configuration.md).
+- [LIMITATIONS.md](../LIMITATIONS.md)
+- [Threat model](reference/threat-model.md)
+- [Evidence integrity spec](reference/evidence-integrity-spec.md)
+- [Sample auditor pack](../examples/auditor-pack/README.md)
 
 ---
 
-## Documentation index
+## More
 
-All user-facing docs are listed by type (Tutorial, How-to, Reference, Explanation) in the **[documentation index](README.md)**. The project follows the [Diátaxis](https://diataxis.fr/) framework so you can find learning-oriented, task-oriented, or reference material quickly.
+- [Documentation index](README.md)
+- [Roadmap & focus](../ROADMAP.md)
diff --git a/docs/README.md b/docs/README.md
@@ -18,17 +18,38 @@ This documentation is organised around the [Diátaxis](https://diataxis.fr/) fra
 - [60-Second Demo](tutorials/quickstart-demo.md) — Docker Compose demo: `docker compose up`, send a curl request, see evidence immediately.
 - [QUICKSTART.md](QUICKSTART.md) — Short entry point for native Talon (requires Go).
 
+## New here?
+
+Pick the path that matches your goal. For what Talon is **not** building, read [Roadmap & focus](../ROADMAP.md) early.
+
+### Evaluator (no API key, ~15 minutes)
+
+1. [60-second demo](tutorials/quickstart-demo.md) — Docker Compose, mock provider, evidence in SQLite.
+2. [Evidence integrity 5-minute proof](tutorials/evidence-integrity-demo.md) — verify, export, tamper, fail verification.
+3. [Sample auditor pack](../examples/auditor-pack/README.md) — browse a signed export + compliance report; regenerate with `make auditor-pack`.
+
+### Builder (native binary, cold start)
+
+1. [Install matrix](../README.md#install) — `make install` or `go install` on macOS/arm64; linux/amd64 release tarball or install script.
+2. Set `TALON_SECRETS_KEY`, then `talon init --scaffold --name my-agent`, then `talon run --dry-run "hello"`.
+3. [Your first governed agent](tutorials/first-governed-agent.md) — live LLM run and audit trail.
+
+Smoke-check the builder path: `make verify-newcomer` (from repo root).
+
 ## Start Here (jobs-to-be-done)
 
 Choose the shortest path for your situation:
 
-1. **"I already have an app calling OpenAI/Anthropic and want controls fast."**
+1. **"I need to show an auditor or DPO what we can hand off."**
+   - Start: [Sample auditor pack](../examples/auditor-pack/README.md)
+   - Then: [How to export evidence for auditors](guides/compliance-export-runbook.md)
+2. **"I already have an app calling OpenAI/Anthropic and want controls fast."**
    - Start: [Add Talon to your existing app](guides/add-talon-to-existing-app.md)
    - Then: [How to export evidence for auditors](guides/compliance-export-runbook.md)
-2. **"I need to govern a third-party AI vendor."**
+3. **"I need to govern a third-party AI vendor."**
    - Start: [Vendor integration guide](VENDOR_INTEGRATION_GUIDE.md)
    - Then: [Architecture: MCP proxy](ARCHITECTURE_MCP_PROXY.md)
-3. **"I want to understand exactly what Talon enforces."**
+4. **"I want to understand exactly what Talon enforces."**
    - Start: [What Talon does to your request](explanation/what-talon-does-to-your-request.md)
    - Then: [Why not just a PII proxy?](explanation/why-not-a-pii-proxy.md)
 
@@ -102,6 +123,7 @@ Choose the shortest path for your situation:
 | [Conformance suite & count](reference/conformance.md) | Reproducible passing-test count for the evidence + policy paths (`make conformance`). |
 | [Reproducible benchmarks](reference/benchmarks.md) | `make benchmarks` — gateway overhead, PII scan, evidence write on your hardware. |
 | [Roadmap & focus](../ROADMAP.md) | Anti-goals and focus — answers "are you trying to be Portkey + AGT?" |
+| [Sample auditor pack](../examples/auditor-pack/README.md) | Generated signed export + compliance report for handoff review. |
 | [Evidence integrity 5-minute proof](tutorials/evidence-integrity-demo.md) | Fast proof moment for auditors/operators, including offline signed-export verification. |
 | [Threat model](reference/threat-model.md) | Attack surface, trust boundaries, and what the HMAC signature does and does not prove. |
 | [Security policy](../SECURITY.md) | Vulnerability reporting process and security scope. |

diff --git a/docs/contributor/mission-control-screenshots.md b/docs/contributor/mission-control-screenshots.md
@@ -0,0 +1,61 @@
+# Mission Control screenshot refresh
+
+Maintainer workflow for updating dashboard screenshots used in README, release notes, and docs.
+
+## When to refresh
+
+- Governance or Gateway Mission Control layout changes ([`web/dashboard.html`](../../web/dashboard.html), [`web/gateway_dashboard.html`](../../web/gateway_dashboard.html))
+- New evidence verify UX, compliance preview, or gateway widgets
+- Release notes that promise a visual share artifact (see [CONTRIBUTING.md](../../CONTRIBUTING.md))
+
+## Seed realistic data
+
+```bash
+cd examples/docker-compose
+docker compose up -d --build
+bash ../../scripts/demo-recorder.sh http://localhost:8080
+```
+
+This creates ~10 evidence rows (clean requests, PII variants, multiple models) suitable for screenshots.
+
+## URLs to capture
+
+| Surface | URL | What to show |
+|---------|-----|----------------|
+| Governance Mission Control | `http://localhost:8080/dashboard` | Evidence tab, verify action, signature/trust block |
+| Gateway Mission Control | Gateway dashboard route (see [gateway dashboard reference](../reference/gateway-dashboard.md)) | Posture, interventions, PII/cost signals |
+
+Open the **Evidence** tab first — that is the primary proof-bar surface for epic credibility work.
+
+## Suggested captures
+
+1. Evidence list with mixed allow/deny and PII flags visible.
+2. Single record detail with **Verified** integrity state.
+3. Compliance report preview panel (if enabled in your build).
+4. Gateway overview with at least one blocked or PII-detected row (optional).
+
+## Where to store assets
+
+Prefer **`docs/images/mission-control/`** for README and tutorial embeds:
+
+```
+docs/images/mission-control/
+  evidence-list.png
+  evidence-detail-verified.png
+  gateway-overview.png
+```
+
+Keep filenames stable; update references in docs when replacing files.
+
+Optional: copy highlights into `examples/auditor-pack/screenshots/` only when they illustrate auditor handoff (not required for `make auditor-pack`).
+
+## After capture
+
+1. Link new images from [README.md](../../README.md) or release notes as needed.
+2. Run `bash scripts/check-claim-discipline.sh` if doc text changed.
+3. Note the refresh in CHANGELOG under the release that ships the UX change.
+
+## Related scripts
+
+- [`scripts/demo-recorder.sh`](../../scripts/demo-recorder.sh) — seed evidence
+- [`scripts/generate-auditor-pack.sh`](../../scripts/generate-auditor-pack.sh) — export sample auditor pack (optional companion to screenshots)
diff --git a/examples/auditor-pack/README.md b/examples/auditor-pack/README.md
@@ -0,0 +1,45 @@
+# Sample auditor pack
+
+This folder contains a **generated sample** of what you might hand to a DPO, customer security reviewer, or internal audit — produced from the no-API-key [docker-compose demo](../docker-compose/README.md).
+
+It is **supporting controls and evidence** for review, not a completed legal filing or certification. See [LIMITATIONS.md](../../LIMITATIONS.md) and [ROADMAP.md](../../ROADMAP.md).
+
+## Contents
+
+| File | Purpose |
+|------|---------|
+| [manifest.json](manifest.json) | Generation metadata, verify commands, record count |
+| [evidence.signed.json](evidence.signed.json) | Full HMAC-signed evidence records (offline verification) |
+| [compliance-report.html](compliance-report.html) | Framework-mapped control summary (HTML) |
+| [compliance-report.json](compliance-report.json) | Same report as JSON |
+
+## Verify offline
+
+From a machine with the `talon` CLI and the same signing key context as the demo (or verify signature structure only):
+
+```bash
+talon audit verify --file examples/auditor-pack/evidence.signed.json
+```
+
+For a live regeneration path, see [Evidence integrity 5-minute proof](../../docs/tutorials/evidence-integrity-demo.md).
+
+## Regenerate
+
+Requires Docker. From the repo root:
+
+```bash
+make auditor-pack
+# or: scripts/generate-auditor-pack.sh
+```
+
+When Docker is available, the script starts `examples/docker-compose`, runs [demo-recorder.sh](../../scripts/demo-recorder.sh) to seed ~10 requests, then exports from the running container.
+
+When Docker is not available, `make auditor-pack` falls back to [auditorpackgen](../../scripts/auditorpackgen/main.go) (synthetic demo records with a fixed test signing key — see `manifest.json`).
+
+Commit updated artifacts when the evidence schema or compliance mapping changes.
+
+## Related docs
+
+- [How to export evidence for auditors](../../docs/guides/compliance-export-runbook.md)
+- [Evidence integrity specification](../../docs/reference/evidence-integrity-spec.md)
+- [Conformance suite & count](../../docs/reference/conformance.md)
diff --git a/examples/auditor-pack/compliance-report.html b/examples/auditor-pack/compliance-report.html
@@ -0,0 +1,32 @@
+<!DOCTYPE html>
+<html><head><meta charset="utf-8"><title>Talon Compliance Report</title>
+<style>
+body { font-family: ui-sans-serif, -apple-system, "Segoe UI", sans-serif; margin: 24px; color: #111; }
+h1, h2 { margin: 0 0 10px; }
+.meta { margin: 0 0 20px; color: #444; }
+table { border-collapse: collapse; width: 100%; margin: 12px 0 24px; }
+th, td { border: 1px solid #d9d9d9; padding: 8px; text-align: left; font-size: 14px; vertical-align: top; }
+th { background: #f4f4f4; }
+.cards { display: grid; grid-template-columns: repeat(4, minmax(120px, 1fr)); gap: 10px; margin: 16px 0; }
+.card { border: 1px solid #d9d9d9; padding: 10px; border-radius: 8px; }
+.label { color: #555; font-size: 12px; }
+.value { font-size: 20px; font-weight: 700; }
+code { background: #f5f5f5; padding: 1px 4px; border-radius: 4px; }
+</style></head><body>
+<h1>Talon Compliance Report</h1>
+<p class="meta">Generated: 2026-06-03 13:21:11.139991 &#43;0000 UTC | Framework: <b>all</b> | Tenant: <b>default</b> | Agent: <b>all</b></p>
+<div class="cards">
+  <div class="card"><div class="label">Evidence Records</div><div class="value">3</div></div>
+  <div class="card"><div class="label">Policy Denials</div><div class="value">1</div></div>
+  <div class="card"><div class="label">PII Records</div><div class="value">2</div></div>
+  <div class="card"><div class="label">Total Cost (EUR)</div><div class="value">0.0050</div></div>
+</div>
+<h2>Control Mappings</h2>
+<table><thead><tr><th>Framework</th><th>Article</th><th>Control</th><th>Source</th></tr></thead><tbody>
+<tr><td>gdpr</td><td>Art. 30</td><td>Processing records via signed evidence export</td><td><code>internal/evidence/store.go</code></td></tr><tr><td>gdpr</td><td>Art. 32</td><td>PII detection and model/data-tier routing</td><td><code>internal/classifier/pii.go</code></td></tr><tr><td>gdpr</td><td>Art. 44-50</td><td>EU data residency routing controls</td><td><code>internal/policy/rego/routing.rego</code></td></tr><tr><td>eu-ai-act</td><td>Art. 11</td><td>Technical documentation through execution plans and evidence</td><td><code>internal/agent/plan.go</code></td></tr><tr><td>eu-ai-act</td><td>Art. 13</td><td>Transparency via execution/model/cost traceability</td><td><code>internal/evidence/store.go</code></td></tr><tr><td>eu-ai-act</td><td>Art. 14</td><td>Human oversight via plan review gate</td><td><code>internal/agent/plan_review.go</code></td></tr><tr><td>nis2</td><td>Art. 21</td><td>Risk controls, policy enforcement, and monitoring</td><td><code>internal/policy/engine.go</code></td></tr><tr><td>dora</td><td>Art. 11</td><td>ICT incident traceability with signed audit trail</td><td><code>internal/evidence/store.go</code></td></tr><tr><td>iso-27001</td><td>A.8.15</td><td>Cryptographic integrity of logs (HMAC)</td><td><code>internal/evidence/signature.go</code></td></tr><tr><td>iso-27001</td><td>A.8.16</td><td>Monitoring and governance metrics</td><td><code>internal/gateway/metrics.go</code></td></tr>
+</tbody></table>
+<h2>Sample Evidence IDs</h2>
+<table><thead><tr><th>ID</th></tr></thead><tbody>
+<tr><td><code>req_5f880438</code></td></tr><tr><td><code>req_a928db90</code></td></tr><tr><td><code>req_b0a4da50</code></td></tr>
+</tbody></table>
+</body></html>