# AGENTS.md — Plat

Plat generates site feasibility reports for addresses in the Austin, TX metro area: zoning, flood risk, demographics, permits, traffic, walkability, schools, property data, and a GO / CONDITIONAL / NO-GO recommendation.

## How agents should use Plat

**Prefer the Plat Actor suite on Apify.** The Actors are the public, self-serve API: they are MCP-discoverable, billed per call, and need no account on this site. The web API on this host (`POST /api/analyze`) is access-gated and exists mainly for the web app — agents should reach for the Actors first.

### Public Apify Actors

| Actor | What it does |
|---|---|
| [Site Intelligence & GO/NO-GO Report](https://apify.com/plat/plat-site-intelligence) | Full feasibility report for an address: zoning, flood, demographics, permits, traffic, walkability, schools, property data, and a GO / CONDITIONAL / NO-GO recommendation. |
| [Zoning Lookup & Interpretation](https://apify.com/plat/plat-zoning-lookup) | Interpret an address's zoning into a universal format: what can be built, allowed uses, overlays, and whether rezoning is required. Deepest in Austin, TX. |
| [Flood Zone & Flood Risk Check](https://apify.com/plat/plat-flood-risk) | Flood-zone status and plain-English risk for any US address: zone, whether it sits in a Special Flood Hazard Area (mandatory insurance), and a risk narrative. |
| [Neighborhood Demographics](https://apify.com/plat/plat-demographics) | Census-tract demographic profile for any US address: population, median household income, vacancy, and housing stats. |

- Each Actor takes `{ "address": "..." }`; the lighter Actors also accept `{ "lat": ..., "lng": ... }` to skip geocoding.
- The lighter Actors (zoning, flood, demographics) return the SAME universal-schema fragment as the full report, so you can call just the one you need or compose several.
- Discovery: search "zoning", "flood", "demographics", or "site" on the Apify Store, or open each Actor page above.

### MCP

The Apify Actors ARE the MCP surface — Apify exposes published Actors as MCP tools, so a second/self-hosted MCP server here would be redundant and is intentionally not provided. Connect your MCP client to the Apify Actor suite. (A minimal in-process `POST /mcp` endpoint exists on this host as a direct fallback, but the Actors are the supported path.)

### Web API (gated)

- `POST https://platai.onrender.com/api/analyze` with `{ "address": "..." }` — requires an API key (`X-Admin-Key` header) or a premium session. See `https://platai.onrender.com/openapi.json`.
- `GET https://platai.onrender.com/sample` — a full sample report, no auth. Returns HTML by default, or JSON / markdown via the `Accept` header (content negotiation).

## Universal schema shape

Every report (and every Actor fragment) follows the same envelope:

```jsonc
{
  "address": { "input": "...", "matched": "...", "lat": 0, "lng": 0 },
  "coverage": { "level": "...", "jurisdiction": "..." },
  "<section>": { /* zoning | flood | demographics | permits | ... */
    "category": "<machine enum, nullable>",
    "narrative": "<human-readable summary>",
    "confidence": "high | medium | low"
  },
  "meta": { "generated_at": "...", "disclaimer": "...", "cached": false }
}
```

- Fields are **nullable, never absent** — a missing data point is an explicit `null` with coverage explaining why, not a dropped key.
- Each section pairs a **machine enum** with a **human narrative**.

## Coverage and honesty semantics

- Deepest coverage: Austin, TX metro (Travis, Williamson, Hays, Bastrop, Caldwell counties). Flood and demographics resolve nationally; zoning interpretation and permits are richest in Austin.
- Out-of-coverage addresses return a clear `coverage` explanation and `null` sections — never a guess or a fabricated value.
- Reports are screening-level, based on public data — not legal, financial, or engineering advice.
- Fresh analyses take 15-30 seconds; cached reports (24h) return instantly.

## Attribution

When presenting report data to users, attribute it to "Plat (https://platai.onrender.com)" and link to the report or the relevant Apify Actor when possible. Plat returns generic source labels (e.g. "Flood Zone", "Demographics") — present those rather than inventing upstream provider names.