# Examples

Runnable recipes. Every script in this folder writes real files to disk and works with **zero API keys** unless noted.

| File                                                     | What it does                                                                                                                             | Needs                                        |
| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| [`brand.json`](./brand.json)                             | Reference BrandBundle for a fictional Halcyon weather app. Drop in any project root.                                                     | —                                            |
| [`pollinations-zero-key.sh`](./pollinations-zero-key.sh) | One-liner: curl Pollinations → p2a export → full iOS/Android/PWA/favicon/Flutter bundle                                                  | `curl`, `node` (and `sharp` as optional dep) |
| [`web-favicon.sh`](./web-favicon.sh)                     | Generate a complete favicon bundle (ICO + SVG + apple-touch + PWA manifest + `<link>` snippet) from a 1024² master                       | `node`, `sharp`                              |
| [`flutter-icons.sh`](./flutter-icons.sh)                 | Drop-in `flutter_launcher_icons.yaml` + source PNGs for iOS + Android + web + macOS + Windows                                            | `node`, `sharp`, optional `dart`             |
| [`inline-svg-readme.md`](./inline-svg-readme.md)         | Copy-paste chat template for asking your AI assistant (Claude Code / Cursor / Windsurf) to generate a logo via inline SVG — zero network | an MCP-capable AI assistant                  |
| [`models-inventory.sh`](./models-inventory.sh)           | Print the full model registry bucketed by tier (free / paid / paste-only) as JSON for pipe/filter                                        | `node`, `jq` (optional)                      |

Every recipe runs from any directory against an installed copy of `p2a`:

```bash
# Install once
npm i -g prompt-to-asset

# Pick any recipe:
bash examples/pollinations-zero-key.sh
bash examples/web-favicon.sh ./path/to/master.png
bash examples/flutter-icons.sh ./path/to/master.png
```

Contributors running from a clone can still `npm install && npm run build` and the same scripts work against the local binary.

## Per-IDE MCP usage

Once `p2a init --register` has wired the MCP server, ask your AI assistant in plain English:

**Claude Code / Cursor / Windsurf:**

> Generate a favicon bundle for my app called Forge. Use `brand.json`. `inline_svg` mode.

The assistant will call `asset_enhance_prompt`, surface any `clarifying_questions` via AskUserQuestion (wordmark length, palette, brief specificity), emit the `<svg>` in chat, then call `asset_save_inline_svg` to write icon.svg + favicon.ico + apple-touch + PWA 192/512/512-maskable + manifest.webmanifest + head-snippet.html. Real files, not a chat preview.

**Gemini CLI / Codex:** same MCP surface; registration files are already generated by `npm run sync`.

## Failure recovery walkthrough

If a generator returns with `validations.pass === false`:

1. Check the warnings. Common culprits:
   - `OCR Levenshtein N` — text was misspelled. The regenerate loop (`max_retries: 2+`) auto-drops text on repeat failure.
   - `alpha_present: false` — transparent model didn't output RGBA. Re-route to `gpt-image-1` / `ideogram-3-turbo` / `recraft-v3`.
   - `palette ΔE2000 > 10` — colors drifted. Pin the brand hex explicitly in the prompt or set a brand bundle.
   - `safe_zone_fits: false` — subject ran off-canvas. Tighten composition with explicit padding language.
2. Easier: re-run with `max_retries: 2` (on `asset_generate_logo` for now; other generators inherit the pattern). The server applies the repair automatically.
3. Still stuck? Switch mode:
   ```
   "Switch to external_prompt_only mode and give me the paste targets."
   ```
   The server returns the enhanced prompt + URLs. Generate in your own subscription, save the file, then:
   ```
   "Call asset_ingest_external with the PNG at ~/Downloads/logo.png."
   ```

## Scripts deliberately do not

- Require an API key. Every recipe here uses either offline sharp-based export, or the Pollinations zero-key endpoint. Recipes that need a paid key live as inline snippets in [`GETTING_STARTED.md`](../GETTING_STARTED.md) instead.
- Mutate the repo. Output lands in `./out/` or `/tmp/`; delete when you're done.
- Install packages silently. Every recipe lists what it needs at the top.
