# Impact Suite — Agents playbook

Give this URL to any AI assistant (Claude, Cursor, Codex, ChatGPT, Gemini, local tools).
This is a skill-as-a-web-page: human-readable instructions plus a thin JSON API so an agent
can draft a **Proposal JSON** document and have Impact Suite validate it and compute a
transparent, sourced feasibility score — without clicking the UI.

## When to use

- The user wants a feasibility proposal built or scored for a place, modelled on a proven
  global precedent (the "global-to-local" pattern).
- You can produce or edit a **Proposal JSON** (`ProposalDocument`) and need the engine to
  validate it and return a scored breakdown.
- The user asks you to "use Impact Suite", "score this proposal", or "run the feasibility engine".

## Do not

- Do not invent a parallel schema. Use the existing **Proposal JSON** contract (same as the
  Studio editor).
- Do not compute the feasibility score yourself. The engine computes every number from your
  sourced `scoringInputs`; your job is to draft **sourced, cited inputs**, not to estimate scores.
- Do not cite a source you have not verified. Every scored number needs a real citation id.
- Do not treat the output as a bankable study — it is a desk-research feasibility signal over
  public, cited data.

## What the engine does

Four sourced sub-scores (0–25 each → raw max 100), multiplied by a confidence factor derived
from the number of **disclosed data gaps** (each gap −0.05, floored at 0.75). No sub-score is
LLM-estimated. See `https://sundaypyjamas.org/agents` for the human page.

- Land & site readiness, Capital mobilization, Regulatory/institutional readiness, Demand & strategic fit.

## Proposal JSON contract

Required top-level keys: ["meta","scoringInputs","disclosedGaps"]; optional ["datasetRows","citations","localConditions","problem","globalModelSection","tradeoffs","whatWouldNeedToBeTrue","limitations","changelog"].
A scored number is `{ value: number, confidence: 'official'|'press'|'proxy', citationIds: number[] }`.
Citation rule: Every scored input, and every official/press dataset row, must reference at least one citation id that exists in `citations`. The engine will not score uncited numbers.

Fetch the live template and a runnable example:

- `GET https://sundaypyjamas.org/api/proposal/example?variant=empty` — structural skeleton
- `GET https://sundaypyjamas.org/api/proposal/example?variant=runnable` — a filled example that scores 56.0/100
- `GET https://sundaypyjamas.org/api/proposal/schema` — field notes + empty template

## Agent loop

1. **GET instructions** — `https://sundaypyjamas.org/agents.md` or `GET https://sundaypyjamas.org/api/agents`
2. **GET example / schema** — `GET https://sundaypyjamas.org/api/proposal/example?variant=runnable`
3. **Draft Proposal JSON** — fill `scoringInputs` with real, cited numbers and list `disclosedGaps`
4. **POST validate** — `POST https://sundaypyjamas.org/api/proposal/validate` → structural + citation check
5. **POST run** — `POST https://sundaypyjamas.org/api/proposal/run` → `score` (components + rationale + adjusted score)
6. **Human review** — return the Proposal JSON to the user to load in the Studio at `https://sundaypyjamas.org/studio`

## Persistence

The API is **stateless** — nothing is stored server-side. To save, export the Proposal JSON
from the Studio (`https://sundaypyjamas.org/studio`).

## API reference

Base: same origin as this app. `Content-Type: application/json`.

| Method | Path | Purpose |
|--------|------|---------|
| GET | https://sundaypyjamas.org/agents | Human playbook UI |
| GET | https://sundaypyjamas.org/agents.md | Raw markdown |
| GET | https://sundaypyjamas.org/api/agents | Instructions JSON or markdown (`?format=markdown`) |
| GET | https://sundaypyjamas.org/api/proposal/example | Empty or runnable Proposal JSON (`?variant=empty|runnable`) |
| GET | https://sundaypyjamas.org/api/proposal/schema | Schema notes + empty template |
| POST | https://sundaypyjamas.org/api/proposal/validate | Structural + citation validation → `{ ok, errors }` |
| POST | https://sundaypyjamas.org/api/proposal/run | Stateless validate + score → `{ ok, score, ... }` |

Estimates over public, cited data only — not a bankable feasibility study.