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

# Generating an Evidence Pack

> Build a pack from the dashboard, the API, or the CLI. The Lambda-backed builder, progress reporting, and typical generation times.

# Generating an Evidence Pack

There are three entry points. They all enqueue the same builder pipeline and produce the same artefact in all three [formats](/evidence/formats).

## From the dashboard

The path most users take.

<Steps>
  <Step title="Open the release">
    **Releases → choose a release → Overview**. The release must be in state `verified` or `shipped` (see [Release scoping](/evidence/release-scoping)). A `draft` or `verifying` release cannot produce a pack.
  </Step>

  <Step title="Click Generate Evidence Pack">
    A modal asks for the formats to render (PDF, ZIP, ReqIF — ReqIF is gated to Team and Enterprise) and any [customization](/evidence/customization) overrides (Enterprise only).
  </Step>

  <Step title="Watch the progress">
    The builder reports phase-by-phase progress via a websocket. Typical phases: snapshot requirements → collect JUnit XMLs → resolve MCAP references → assemble coverage → fetch SBOM → render PDF → assemble ZIP → sign manifest → upload to S3.
  </Step>

  <Step title="Download or share">
    When the pack is ready, the release page shows a download link for each format and a read-only share link for handing to an external party. Share links are signed, time-bounded, and revocable.
  </Step>
</Steps>

<Check>
  The release page now shows a green **Pack generated** badge with the SHA-256 of the manifest and a link to verify the [hash chain](/evidence/hash-chain).
</Check>

## From the API

For programmatic generation — release-gate scripts, custom CI jobs, integration with a release-train tool.

```bash theme={null}
curl -X POST https://api.roboticks.io/api/v1/organizations/{org_slug}/projects/{project_slug}/releases/{release_id}/evidence-pack \
  -H "Authorization: Bearer $RBTK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "formats": ["pdf", "zip", "reqif"],
    "include_screenshots": true
  }'
```

The response returns a `job_id` immediately. Poll `GET /evidence-pack-jobs/{job_id}` or subscribe to the websocket for progress. On success the body returns three signed download URLs (one per format) valid for 7 days.

## From the CLI

The fastest path inside a CI pipeline or a developer shell.

```bash theme={null}
# By release
rbtk test evidence-pack --release v1.4.0 --format pdf

# By release, multiple formats
rbtk test evidence-pack --release v1.4.0 --format pdf,zip,reqif

# Ad-hoc, by branch + commit set
rbtk test evidence-pack \
  --branch main \
  --commit-set abc123,def456 \
  --format zip
```

The CLI blocks on the job by default, streams progress to stdout, and writes the resulting file(s) into `./evidence-packs/`. Add `--no-wait` to get just the `job_id` back.

See [CLI commands](/cli/commands) for the full flag list.

## The builder pipeline

```mermaid theme={null}
%%{init: {"theme": "neutral", "themeVariables": {"primaryColor": "#4040ff"}} }%%
flowchart LR
    Trig["Trigger<br/>(dashboard / API / CLI)"] --> Q["SQS queue"]
    Q --> L["Lambda builder<br/>(15 min budget)"]
    L --> Snap["Snapshot requirements"]
    L --> Junit["Collect JUnit XMLs"]
    L --> Mcap["Resolve MCAP refs"]
    L --> Cov["Assemble coverage"]
    L --> Sbom["Fetch SBOM"]
    L --> Sa["Collect SARIF"]
    Snap & Junit & Mcap & Cov & Sbom & Sa --> Render["Render PDF / ZIP / ReqIF"]
    Render --> Sign["Sign manifest<br/>(Ed25519, AWS KMS)"]
    Sign --> S3["Upload to S3"]
    S3 --> Chain["Append to hash chain"]
```

The builder is a single AWS Lambda with a 15-minute budget. Packs that exceed the budget — typically very large repos with multi-gigabyte MCAP indexes — automatically fall back to an ECS Fargate task with a 6-hour budget. The fallback is transparent; the API and CLI behaviour does not change.

## Typical generation times

| Project size                               | Format    | Time      |
| ------------------------------------------ | --------- | --------- |
| Small (50 reqs, 200 tests, 1 GB MCAPs)     | PDF only  | 15–30 s   |
| Small                                      | All three | 30–60 s   |
| Medium (500 reqs, 2 k tests, 20 GB MCAPs)  | All three | 2–5 min   |
| Large (5 k reqs, 20 k tests, 200 GB MCAPs) | All three | 8–15 min  |
| Very large (Lambda → Fargate fallback)     | All three | 20–90 min |

MCAP size dominates. The builder never copies MCAPs into the pack — it references them by presigned URL — but it still verifies integrity by computing SHA-256s in parallel.

## Errors and partial packs

A pack with any unresolved dependency (a missing MCAP, an unreachable connector, a corrupt SARIF) fails the job rather than producing a partial pack. The error is surfaced with the specific artefact at fault, and you can re-run after fixing the upstream. **The platform never produces a silent best-effort pack.** Auditors rely on completeness.

For triage workflows where a partial view is useful, use `rbtk test evidence-pack --allow-partial`. The resulting pack is marked `partial: true` in its manifest, refuses to enter the hash chain, and is watermarked **NOT FOR AUDIT** in the PDF.

## Next steps

<CardGroup cols={2}>
  <Card title="Formats deep dive" icon="layer-group" href="/evidence/formats">
    What the PDF, ZIP, and ReqIF deliverables look like.
  </Card>

  <Card title="Customise the pack" icon="palette" href="/evidence/customization">
    Cover pages, branding, custom sections. Enterprise.
  </Card>

  <Card title="Hand off to an auditor" icon="user-shield" href="/evidence/customer-handoff">
    Recommended cover letter and disclaimer.
  </Card>

  <Card title="Verify the chain" icon="link" href="/evidence/hash-chain">
    Prove a historical pack has not been altered.
  </Card>
</CardGroup>