# Sparkel — full notes for agents

This expands `llms.txt`. Prefer the short file for discovery; use this when executing a golden job.

## Product model (minimal)

Project → Tables → Items
Items link to BIM elements and/or Shapes (including Autoshape outputs)
Quantities resolve from links (DYNAMIC / DERIVED / EXTRACT)
Export via Excel, sheet PDF, API, or MCP

Tribal concepts (breakdowns, predicate vocabulary, company DB) come **after** first trusted quantity.

## MCP tools (production)

Shared + host tools typically include:

- sparkel_credits
- sparkel_fetch / sparkel_create / sparkel_update / sparkel_delete / sparkel_search
- sparkel_search_elements / sparkel_get_element_properties
- sparkel_begin_upload / sparkel_complete_upload
- sparkel_render / sparkel_export

Auth: OAuth 2.1 style with dynamic client registration + PKCE. Unauthenticated tools/list should yield 401 with resource metadata.

## Scripted happy path (room areas)

1. sparkel_credits
2. sparkel_create type=project
3. sparkel_create type=table (+ items or template)
4. sparkel_begin_upload (sheet PDF) → PUT bytes → sparkel_complete_upload
5. sparkel_search sheet → sparkel_update calibration if needed
6. sparkel_create type=auto_shape (room_detection_2d)
7. sparkel_fetch type=auto_shape waitUntilComplete=true
8. Link / ensure items use shape query + DYNAMIC quantity
9. sparkel_search type=item resolve=true
10. sparkel_export exportType=sheet_pdf (or assemble activation payload)

### Quantity footgun (critical)

On 2D sheet polygons, `Quantities` / `Area` may return **0** with source `computed`.
Use **`Net Area`** or canonical **`Largest side area`** for room floor areas (aliases). Prefer keys from `sparkel_get_element_properties`. Bare `Area` also aliases to net area.

### Geometry footgun

Polygon create expects closed rings (first point equals last, ≥4 points) inside the multipolygon schema. Open rings → server error.

## Credits / commerce

- Before Autoshape: sparkel_credits
- If insufficient: surface upgrade URL https://www.sparkel.ai/get-started or in-app billing (MCP checkout tool may be absent — do not invent charges)
- On insufficient credits: structured `credits_exhausted` with `upgradeUrl`, `buyCreditsUrl`, `signupUrl` (HTTP 402 / MCP tool `isError`)

## Activation budgets (targets)

See job cards under product/agent-jobs/jobs/ for authoritative budgets. Typical room-areas targets:

- wall_clock_seconds ≤ 180
- tool_calls ≤ 40
- credits_spent ≤ 15
- room_shape_count ≥ 3 with areas matching gold fixture tolerance

## Human PLG mirror

Start free → create project → upload PDF → calibrate → Autoshapes → table → export.
Onboarding tips exist for free contractors in the web app (localStorage, not cross-device).