# Pilot Report PDF API

Endpoints:

- `/api/memo-pdf`
- `/api/audit-pdf`
- Legacy alias: `/api/pilot-report-pdf`

## Methods

- `GET`
- `POST`

## Purpose

Generate a server-side decision report PDF from intake/report payload fields.

## Query parameters / body fields

All fields are optional. Missing fields fall back to sample defaults.

- `intakeId`
- `company`
- `owner`
- `kpiBriefCount`
- `decisionQuestion`
- `recommendedCall`
- `confidence`
- `expectedImpact`
- `riskChecks`
- `runtimeProvider`
- `requestId`
- `generatedAt` (ISO datetime)

Phase A decision-brief fields (optional, now supported):

- `verdict` (`ship|defer|no_go`)
- `decision_margin_points`
- `forecast` object (`metric_name`, `window_days`, `p10`, `p50`, `p90`, `unit`)
- `next_action` object (`action`, `owner`, `due_date`)
- `why_now` array
- `guardrails` array
- `rollback_triggers` array
- `uncertainties` array
- `why_alternatives_lose` array
- `uncertainty_drivers` array
- `decision_stakes` object (`revenue_impact_range`, `customer_risk`, `strategic_importance`)
- `decision_confidence` object (`percent`, `label`, `drivers[]`)
- `execution_status` object (`status`, `detail`)
- `outcome_tracking` object (`status`, `owner`, `due_date`, `metric`, `note`)

Control fields:

- `format` (`pdf` or `json`, default `pdf`)
- `renderer` (`auto`, `playwright`, `lightweight`)
- `persist` (`true/false`, default `false`)
- `strictPlaywright` (`true/false`, default `false`)
- `live` (`true/false`, default `false`) -> when `true`, resolves payload from latest live case snapshot
- `snapshotId` (optional) -> resolve a specific live case snapshot by ID when `live=true`

## Examples

### Get a sample memo PDF

`GET /api/memo-pdf`

### Get report metadata as JSON

`GET /api/memo-pdf?format=json`

`report` now includes:

- `decisionId`
- `verdict`
- `recommendedCall`
- `recommendedOptionId`
- `decisionMarginPoints`
- `forecast`
- `nextAction`
- `whyNow`
- `guardrails`
- `rollbackTriggers`
- `assumptions`
- `uncertainties`
- `whyAlternativesLose`
- `uncertaintyDrivers`
- `decisionStakes`
- `decisionConfidence`
- `executionStatus`
- `outcomeTracking`
- `decisionGates` (`shipIf[]`, `deferIf[]`, `noGoIf[]`, `resultLabel`, `checks`)
- `evidenceDiversity` (`total`, `counts`, `summary`)
- `evidenceClaims` (`claim`, `source_title`, `source_url`, `quote`, `evidence_tier`)
- `sourceDigests` now include source transparency fields (`sourceType`, `sourceCategory`, `sourceOrigin`, tier/type labels)
- `memoValidation`

### Get latest live snapshot PDF

- Memo: `GET /memo-pdf?live=1`
- Audit: `GET /audit-pdf?live=1`
- Snapshot-specific memo: `GET /memo-pdf=<reportId>`
- Snapshot-specific audit: `GET /audit-pdf=<reportId>`

`/api/site-case` and `/api/generate-live-case` now expose:

- `latestPdfUrl` -> best available client-safe artifact (`memo` when published, otherwise `audit`)
- `latestMemoPdfUrl` -> executive memo URL only when the memo is actually published
- `latestAuditPdfUrl` -> audit packet URL
- `latestPdfKind` -> `memo` or `audit`
- `memoPublished` -> `true` only when the executive memo is published

### Generate and persist report (if storage configured)

`POST /api/memo-pdf` with JSON body:

```json
{
  "intakeId": "kh-2026-0301-001",
  "company": "Acme Inc",
  "owner": "Product Lead",
  "kpiBriefCount": 1,
  "decisionQuestion": "Should we use automatic overage billing or burst packs for extra API usage?",
  "recommendedCall": "Ship hybrid usage policy (burst default + capped overage opt-in).",
  "confidence": "74%",
  "expectedImpact": "+$3.3k expansion MRR in 45 days",
  "riskChecks": "No-surprise billing checks passed, churn ceiling intact, support SLA intact",
  "runtimeProvider": "decidefyi",
  "requestId": "req_usage_9k2m4",
  "format": "json",
  "persist": true
}
```

## Environment variables

Renderer:

- `KRAFTHAUS_PDF_RENDERER` = `auto` | `playwright` | `lightweight`
- `KRAFTHAUS_PDF_RENDERER_STRICT` = `true` to fail hard if Playwright cannot render

Storage (for `persist=true`):

- `KRAFTHAUS_SUPABASE_URL` (or `SUPABASE_URL`)
- `KRAFTHAUS_SUPABASE_SERVICE_ROLE_KEY` (or `SUPABASE_SERVICE_ROLE_KEY`)
- `KRAFTHAUS_REPORT_BUCKET` (optional, default `pilot-reports`)

## Readiness endpoint fields

`/api/readiness` now reports:

- `pilotReportPdf`
- `pilotReportRenderer`
- `pilotReportPlaywrightAvailable`
- `pilotReportPlaywrightExecutableExists`
- `pilotReportStorage`
- `pilotReportStoragePartial`