# Canonical Pilot Path

Use this path when a buyer, partner, or internal sponsor needs to see GrantFlow as an operating workflow, not as a feature tour.

## Pilot Objective

Prove that GrantFlow can move representative donor opportunities from raw program intent to a reviewable, traceable, export-ready package with less review chaos.

The pilot should measure:
- cycle time to first reviewable draft
- number of review loops before approval
- traceability confidence from reviewers
- export handoff readiness

## Default Scope

Run 3-6 representative cases with named reviewers and one accountable pilot owner.

Default strongest paths:
- `eu_digital_governance_moldova`
- `un_agencies_katch_evaluation_kyrgyzstan`

Conditional path:
- `usaid_gov_ai_kazakhstan`

Use other donors only when the buyer explicitly needs evaluation breadth rather than strongest proof.

## Before Day 1

Prepare:
- pilot owner and reviewer list
- baseline cycle-time and review-loop assumptions
- target donor paths
- source documents or seeded corpus
- success criteria and go/no-go thresholds
- access boundary for the demo or protected environment

Recommended companion docs:
- `pilot-kickoff-agenda.md`
- `pilot-evaluation-checklist.md`
- `pilot-success-metrics.md`
- `production-boundaries.md`

## Live Workflow

### 1. Readiness

Confirm the runtime is healthy:

```bash
curl -fsS http://127.0.0.1:8000/health
curl -fsS http://127.0.0.1:8000/ready
```

For production-oriented pilot environments, run:

```bash
make preflight-prod-api
make preflight-prod-worker
```

### 2. Corpus

Upload or seed the buyer-approved source set before claiming grounded output.

Check:
- `GET /ingest/readiness`
- `GET /ingest/inventory`
- `GET /ingest/recent`

Do not treat fallback-only generation as proof of grounded donor workflow quality.

### 3. Generate

Start from a representative preset:

```bash
POST /generate/from-preset
```

Then inspect:

```bash
GET /status/{job_id}
GET /status/{job_id}/quality
GET /status/{job_id}/grounding-gate
```

### 4. Review

Use the reviewer console or API endpoints to inspect:
- critic findings
- review comments
- SLA profile
- next primary action
- HITL checkpoint state

Relevant endpoints:

```bash
GET /demo
GET /status/{job_id}/critic/findings
GET /status/{job_id}/comments
GET /status/{job_id}/review/workflow
GET /hitl/pending
```

For HITL checkpoints, approve or reject and resume:

```bash
POST /hitl/approve
POST /resume/{job_id}
```

### 5. Traceability

Show that reviewers can inspect the work product, not just read generated text:

```bash
GET /status/{job_id}/citations
GET /status/{job_id}/versions
GET /status/{job_id}/diff
GET /status/{job_id}/events
```

Reviewers should be able to answer:
- which source supported this claim?
- what changed between draft versions?
- which findings remain open?
- who owns the next action?

### 6. Export

Generate the buyer-facing handoff:

```bash
GET /status/{job_id}/export-payload
POST /export
GET /status/{job_id}/pilot-quick-report
GET /status/{job_id}/pilot-evidence-pack/export
```

The export package is the handoff artifact for review, not a substitute for final human sign-off.

## Go/No-Go Decision

Use `pilot-conversion-decision-memo-template.md` after the representative cases are complete.

Default decision gates:
- first draft is reviewable without major structural rewrite
- reviewers can resolve or route findings without ad hoc coordination
- citations and versions are clear enough for trust review
- export package is usable for downstream proposal operations
- measured deltas justify paid pilot expansion or production hardening

## What To Avoid

Do not make these claims during the pilot:
- every donor path is equally mature
- the system replaces compliance sign-off
- API key auth is a full enterprise IAM layer
- generated exports are final submission packages
- grounded quality can be proven without source discipline

## Evidence To Keep

For each case, retain:
- preset or request payload
- readiness snapshot
- quality and grounding-gate response
- reviewer findings and comments
- versions, citations, and events
- export payload and generated artifacts
- final go/no-go notes

Customer-specific evidence should stay outside the public repository.
