> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zespan.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Evidence Packs — audit-ready compliance documents

> Generate hash-addressed, re-verifiable audit documents — a per-agent Compliance Card or a SOC 2 control evidence report — from your existing Zespan data.

An evidence pack is a generated document that cites the Zespan records backing either a single agent's operational history or a compliance framework's controls, for a stated period. Every fact in the document links back to the record it came from — a guardrail config, an evaluation run, an approval request, an audit log entry — so an auditor (or you) can click through to the source, or later re-check that the source still exists and the document hasn't been altered. See [Verification](/compliance/verification) for how that re-check works.

Every pack is:

* **Scoped** to a project and a `periodStart`/`periodEnd` window (400 days maximum)
* **Hash-addressed** — content-addressed by its own SHA-256, computed over the exact bytes stored, not over a re-serialized copy
* **Immutable once generated** — nothing about a completed pack is edited in place; generate a new one for a new period
* **Never a compliance certification** — see the honesty constraint below

## The honesty constraint

Every generated document — Compliance Card or SOC 2 control evidence, in every format — carries this exact disclaimer, printed at both the top and the bottom of the document:

> "This document reports controls and evidence observed by Zespan for the stated scope and period. It is not a certification of compliance and does not constitute legal advice."

This isn't boilerplate — it's the feature's design premise. A section with no matching records for a period renders the literal text "No evidence available for this period." — never a suppressed section, never a silently-passing control. See [Frameworks and controls](/compliance/frameworks#coverage) for how an uncovered control is surfaced before you even generate a document.

## The two document kinds

<CardGroup cols={2}>
  <Card title="Compliance Card" icon="user-check">
    Everything Zespan recorded about **one agent** (or all agents, if you leave the agent unset) for the period: profile, models used, guardrails in force, guardrail change history and outcomes, evaluation results with sample sizes, human approvals, known limitations, and change history.
  </Card>

  <Card title="SOC 2 control evidence" icon="list-checks">
    The same underlying facts, reorganized and namespaced under the three SOC 2 controls Zespan maps today — CC6.1, CC7.2, CC8.1. See [Frameworks and controls](/compliance/frameworks) for what each control draws on.
  </Card>
</CardGroup>

## Generating a pack

<Steps>
  <Step title="Open Compliance">
    From the project sidebar, go to **Monitor → Compliance**. Requires the Pro plan.
  </Step>

  <Step title="Choose a document type">
    **Compliance Card** for one agent (or all agents), or **SOC 2 control evidence** for the framework mapping. Control evidence requires picking a framework — SOC 2 is the only one available today; see [Not yet available](/compliance/frameworks#not-yet-available).
  </Step>

  <Step title="Set the period">
    Pick `periodStart` and `periodEnd`. The form defaults to the last full calendar month. Maximum period length is 400 days.
  </Step>

  <Step title="Pick a format">
    **HTML** (default) or **JSON** — see [Formats](#formats) below.
  </Step>

  <Step title="Generate">
    Click **Generate evidence pack**. This returns immediately with the pack in `pending` status — generation runs on a background worker, and the row updates to `processing` then `completed` (or `failed`) as it runs. The Compliance page polls automatically while any pack is in flight.
  </Step>

  <Step title="Download or verify">
    Once `completed`, use **Download** to get the document, or **Verify** to re-check it — see [Verification](/compliance/verification).
  </Step>
</Steps>

<Tip>
  Before you generate, the **Coverage for this period** panel shows which controls have evidence for your chosen period and framework — so you find a gap before you generate (and possibly hand off) a document, not after. It runs the same evidence-collection logic the document itself would use, without rendering or storing anything.
</Tip>

## Formats

| Format | What it is                                                                                             | Use it for                                                 |
| ------ | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------- |
| `html` | A single self-contained HTML file — inline CSS, no external requests, a real `@media print` stylesheet | Printable to PDF from your browser; human review           |
| `json` | The structured evidence document — every section, record, and source citation as data                  | Machine ingestion, archival, feeding into your own tooling |

<Warning>
  PDF is not yet an available format. There's no headless-browser rendering path in Zespan today, and adding one is genuine new infrastructure — a browser runtime, a memory cap, a timeout, a fallback — rather than a config change, so a request for `format: "pdf"` is rejected at the API rather than silently downgraded to HTML. The HTML document is designed to print cleanly straight from your browser's own print-to-PDF, which is the interim path.
</Warning>

## Downloading

`GET /v1/projects/:id/evidence-packs/:packId?download=true` returns a presigned download URL when packs are stored in object storage (Cloudflare R2), or the raw document content directly when running on local-disk storage (typically self-hosted or local dev). The dashboard's **Download** button handles either case for you.

## Permissions

| Role                    | List / download / verify / coverage (`compliance:read`) | Generate (`compliance:generate`) |
| ----------------------- | ------------------------------------------------------- | -------------------------------- |
| Owner, Admin            | Yes                                                     | Yes                              |
| Editor, Viewer, Billing | Yes                                                     | No                               |

A role without `compliance:generate` can still list, download, and verify existing packs — it just can't start a new generation.

## Next steps

* [Frameworks and controls](/compliance/frameworks) — the SOC 2 CC6.1/CC7.2/CC8.1 mapping and what evidence each control draws on
* [Verification](/compliance/verification) — what `/verify` re-checks, and what it can't
* [Compliance evidence limitations](/reference/compliance-limitations) — the permanent data gaps this feature reports about itself
* [Audit log](/platform/audit) — the record source behind access-control and change-history evidence