# Zoreva-UI host playbook

Contract for agents that call the Zoreva-UI MCP. No Cursor/Claude skill install required.
When a tool response conflicts with this document, **the tool response wins**.

## Product split

1. **Compositions** download as iPhone (SwiftUI/Xcode) or Android
   (Kotlin/Jetpack Compose) zips via `get_composition_download(id, artifact)`
   (short-lived ticket URL, same account session + weekly Free cupo as the
   website). `artifact` is `xcode` (default) or `android`. Each artifact
   spends its own Free credit. Call composition tools **only when the
   user explicitly asks** for an app/composition — never auto-suggest packs.
   There is **no** `get_download` tool. Never invent a public zip URL.
   Do **not** assemble apps from MCP recipes (`propose_assembly` /
   `get_app_recipe` / `get_component` are retired).
2. **Shaders** deliver as Metal + SwiftUI source, and as an Android AGSL zip
   (RuntimeShader API 33+, Canvas fallback below).
   `get_shader(id, artifact="xcode"|"android")`. Default artifact is xcode
   (inline Metal + SwiftUI). `android` returns a short-lived ticket URL and
   counts as its own free weekly download, separate from the Metal source.
   `customize_shader` edits the Metal source only. Do **not** auto-merge,
   compose, or wire a shader into an app. Putting a shader into an app happens
   **only when the user explicitly asks**.
   Never call retired `compose_screen_with_shader` / `propose_assembly`.
3. **Icons** live on MCP: `search_catalog(kinds=["icon"])` / `list_icons` /
   `resolve_icon` / `get_icon` / `customize_icon`. The `/icons` page is the
   same catalog in the browser (browse / filter only — delivery is via MCP).

## Before any work

1. Connect to `https://zoreva-ui.com/api/mcp` (OAuth).
2. Call Zoreva tools only for what the user asked: shaders, icons, and/or
   compositions. Never pull extras “to improve” the result.
3. If `needsClarification` is true → ask the user; do **not** guess an id.
4. Optional: call `get_host_playbook` or read `zoreva://host-playbook` once per session.

## Compositions

- `list_compositions` / `resolve_composition` — explore or resolve **when asked**.
  Filters: `domain`, `layoutPattern`, `tier` (free|pro), `zipReady`, `tag`, `query`.
- `get_composition_download(id, artifact="xcode"|"android")` — ticket URL;
  host fetches once and unzips. Default artifact is xcode.
- `get_composition_design_brief(id, focus?)` — layout / focusSlots / HIG only
  (no Swift or Kotlin sources, no component recipes). Use for extract-design
  (e.g. “pasa las cards de brew-lane a mi app de ropa”).
- Site buttons: `POST /api/swift-apps/{id}/download` and
  `POST /api/swift-apps/{id}/download?artifact=android`.
- Free: shared weekly app cupo with the site. Pro: unlimited.
- Pro-locked composition on Free → `{error: "pro_required", suggestions: [...Free]}`.
  Offer those Free alternatives — same pattern as shaders/icons.

## Shaders

- `get_shader(id, artifact="xcode"|"android")` — xcode is Metal + SwiftUI inline;
  android is the AGSL zip ticket. On Free, each counts as its own free weekly download.
- Site buttons: `POST /api/shaders/{id}/download` and
  `POST /api/shaders/{id}/download?artifact=android`.
- `list_shaders` for the plan-visible set. `resolve_shader` from free text.
- `customize_shader` is bounded (palette + speed) on the Metal source.
  artifact android is not applicable there. Never freehand-rewrite Metal.
- Do **not** silently drop a shader behind a downloaded composition, invent a
  merge, or call `compose_screen_with_shader`. If the user did not ask to put
  the shader in an app, stop at the source.
- Pro-locked on Free → `{error: "pro_required", suggestions: [...]}`. Offer the Free alternatives.

## Icons

- `search_catalog(kinds=["icon"])` or `list_icons` accept filters: `tier`
  (`free`/`pro`), `style` (`outline`/`filled`), `new`, `animated`.
  Do **not** call a separate list_animated tool.
- `resolve_icon` turns an intent / use-case into ranked **Free-first** candidates.
- `get_icon` for one card (`uid` like `tabler:home`, or a unique bare id).
- `customize_icon` exports SVG / JSX / TSX with stroke + color. Pro icons on a
  Free plan return `{error: "pro_required", suggestions: [...]}`.
- Never invent `Hugeicons.*` / `Tabler.*` / `Lucide.*` identifiers.

## After fetch

- Prefer SF Symbols + system Liquid Glass on iOS 26; keep an iOS 17+ compile path.
- Never hard-fail on Free/`pro_required` — offer Free suggestions from the error payload.
- After a composition zip: the user's IA reads the unzipped Xcode project and adapts
  what they asked into their own app — MCP does not write their project.
- When any tool returns `{error: ...}`, call `explain_last_error` with that payload
  before inventing a workaround. Respect Free/Pro and weekly cupos.