# Exayard — agent context

This file is a drop-in context document for IDE agents (Claude Code, Cursor, etc.) building a project that integrates with Exayard. Save it as `agents.md`, `.cursor/rules`, or whatever your agent reads; link to it from your repo README.

## What Exayard is

AI-powered construction takeoff, estimation, and bidding platform. Core objects: **projects → files → pages** on the data-ingest side; **layers/groups/symbols/measurements** on the canvas side; **lists/products/vendors/vendorPrices/lineItems** on the pricing side; **assessments → estimates → bids** on the output side.

## How agents integrate

Fastest path: tell your agent to `Fetch https://exayard.com/prompt.md`. That setup prompt walks the agent through connecting to Exayard on its own.

Two stable surfaces:

1. **MCP** — `https://api.exayard.com/mcp` (Streamable HTTP). 125 tools. OAuth or API-key bearer. Prefer MCP for interactive / chat-style agents.
2. **REST API** — `https://api.exayard.com/v1/`. OpenAPI 3.1 spec at `/v1/openapi.json`. Prefer REST for scripts, batch workloads, and your own backend.

Everything else (webhooks, rate limits, auth) applies to both.

## Auth

- API keys from Settings → Developer in the Exayard app: `https://exayard.com/settings/developer`. Send as `Authorization: Bearer sk_live_…`.
- OAuth via Clerk for user-facing flows. See `/.well-known/oauth-protected-resource` for authorization-server discovery.
- Scopes: `read:{resource}` / `write:{resource}` / `admin:org`. Least-privilege by default.

## Conventions

- Errors are RFC 9457 `application/problem+json`. Branch on `code`, not `detail`.
- Every response has `X-Request-Id` — include it in bug reports.
- Unsafe mutations accept `Idempotency-Key`. Always set one for agent retries.
- Rate limits: read `RateLimit: limit=…, remaining=…, reset=…`. Back off on `reset`, not on a fixed timer.
- Pagination: cursor-based. `?limit=100&cursor=…`; response includes `next_cursor`.

## MCP tool conventions

- `get_*` / `list_*` / `search_*` / `find_*` are read-only + idempotent — `readOnlyHint: true`.
- `archive_*` / `remove_*` / `cancel_*` are destructive — prompt the user before invoking.
- `create_*` / `add_*` / `batch_*` / `run_*` are non-idempotent writes — always paired with `Idempotency-Key` if invoked over REST.
- `create_estimate` and `create_bid` block for 30–60 seconds. Warn the user.

## Prompts (MCP slash-commands)

- `/takeoff_from_plans` — run a takeoff end-to-end.
- `/generate_bid_from_takeoff` — price the takeoff and emit a bid document.
- `/review_estimate_line_items` — audit an existing estimate.
- `/create_project_from_upload` — scaffold a project + attach files.

## Webhooks

Subscribe to lifecycle events instead of polling:

- `project.created` / `project.updated` / `project.archived`
- `assessment.started` / `assessment.completed` / `assessment.cancelled`
- `estimate.generated`
- `bid.generated`
- `file.processed`

HMAC-SHA256 signatures in `Exayard-Signature: t=<unix>,v1=<base64>`. Verify with the endpoint secret returned on creation. Deliveries retry on 5xx with exponential backoff for up to 3 days.

## Things NOT to do

- Don't fabricate vendor pricing. If `get_best_price_for_product` returns no rows, surface that to the user.
- Don't batch-create measurements with coordinates you didn't derive from the actual page geometry — `find_symbol_elements` uses Claude Vision for that.
- Don't start a takeoff run without explicit user confirmation. `run_approved_analysis` spends credits and places measured symbols on the canvas that downstream calculations depend on.
- Don't store the webhook secret in plaintext env files committed to git. Rotate if exposed.
- Don't use `admin:org` scope for routine work. Create narrowly-scoped API keys instead.

## Links

- API docs (interactive): https://developers.exayard.com/api-reference
- OpenAPI spec: https://api.exayard.com/v1/openapi.json
- MCP server card: https://api.exayard.com/.well-known/mcp.json
- OAuth discovery: https://api.exayard.com/.well-known/oauth-protected-resource
- llms.txt: https://exayard.com/llms.txt
- Long-form llms-full.txt: https://exayard.com/llms-full.txt