---
name: storeframe-agent
description: >-
  Operates StoreFrame for Pro/Max members via Bearer API keys using the full
  Agent API reference: check membership/quota/export history, smart catalog
  search (keywords → AI rank → show preview links → use template), author YAML
  packs, import/re-import into cloud projects, list/update projects, and request
  export sessions. Use when the user pastes the StoreFrame AI Connect prompt or
  wants conversational template find/use or create → edit → re-import →
  preview/export, or asks about plan balance / export consumption.
---

# StoreFrame agent

Drive StoreFrame from chat for members who pasted the **AI Connect** prompt.

**Read [API.md](API.md) before calling any endpoint.**
It contains full request/response contracts. Do not guess body shapes.

## Prerequisites

1. User has a Pro/Max plan and an API key (`sf_...`).
2. This skill pack is installed under `.claude/skills/storeframe-agent/` and/or `~/.codex/skills/storeframe-agent/`.
3. Use `storeframe-template-from-brief` (bundled beside this skill) to author packs.

## Install (for the user)

Prefer the **AI Connect** prompt copied from the StoreFrame site. Equivalent terminal install:

```bash
ZIP=/tmp/storeframe-agent.zip
curl -fsSL "https://aistoreframe.shop/skills/storeframe-agent.zip" -o "$ZIP"
mkdir -p .claude/skills ~/.codex/skills
unzip -o "$ZIP" -d .claude/skills
unzip -o "$ZIP" -d ~/.codex/skills
rm "$ZIP"
```

## Auth

- Base: `https://api.slidemint.shop/api/v1/storeframe/`
- Header: `Authorization: Bearer sf_...`
- Errors: JSON `{ "detail": "..." }`

## Path A — Find a catalog template and use it

1. `GET agent/me` — stop on 401/402.
2. From the user brief, invent **3–8 keywords** (category, features, mood).
3. `POST agent/templates/search` with `prompt` + `keywords` (+ optional `platform`).
4. Show the user the top picks: name, reason, **`preview_url` / `catalog_url`**, and `preview_frames` titles.
   There is no static PNG thumbnail API yet — the preview link is the visual.
5. After they pick one: `POST agent/templates/:slug/projects` → return `editor_url`.
6. Optionally continue editing in the browser, or adapt into YAML and use Path B.

## Path B — YAML is the source of truth (custom pack)

1. `GET agent/me` — stop on 401/402.
2. Author a local pack with `storeframe-template-from-brief` (include `trustLabel`).
3. Convert YAML → JSON if needed.
4. **Create:** `POST agent/template-packs` with `{ "pack": { ... } }`.
5. Save `public_id` + keep the local YAML file.
6. User feedback → **edit the YAML** (titles, colors, trust badge, linked frames).
7. **Re-import:** `POST agent/template-packs` with `{ "project_id": "<public_id>", "pack": { ... } }`.
8. Preview: give the user `editor_url` from the response (optional).
9. Repeat 6–8 until satisfied.
10. **Upload screens:** `POST agent/projects/:id/screenshots` with local images as base64/data_url by page index.
11. **Render in chat:** `POST agent/projects/:id/exports` → paste response `markdown` into Codex so frames display inline.
12. Optional: open `editor_url` for browser PNG ZIP if pixel-perfect Custom Studio export is required.

## Membership / quota / history

When the user asks about plan status, remaining exports, or consumption history:

1. `GET agent/account/usage` (optional `?page=1&per_page=20`)
2. Summarize `membership` (plan + expiry + active/expired), `quota` (used / remaining / bonus), and recent `exports.items`.
3. Paginate if `exports.pages > 1`.

`GET agent/me` is only a lightweight key check — prefer `account/usage` for balances.

## Endpoint map

| Method | Path | Purpose |
|--------|------|---------|
| GET | `agent/me` | Verify key + plan |
| GET | `agent/account/usage` | Membership, remaining quota, export history |
| GET | `agent/projects` | List projects |
| GET | `agent/projects/:id` | Get project + `editor_url` |
| POST | `agent/projects` | Create from raw project JSON |
| PUT | `agent/projects/:id` | Replace raw project JSON |
| POST | `agent/template-packs` | Create or re-import pack (`project_id` optional) |
| POST | `agent/projects/:id/screenshots` | Upload screenshots onto frames |
| POST | `agent/projects/:id/exports` | Render store frames (SVG URLs + markdown) |
| POST | `agent/templates/search` | Keywords + AI ranked catalog search |
| GET | `agent/templates` | Simple paginated `q` search |
| GET | `agent/templates/:slug` | Full catalog template JSON + preview links |
| POST | `agent/templates/:slug/projects` | Clone catalog template into a cloud project |

Full schemas: [API.md](API.md)

## Safety

- Never log or echo the full API key.
- Confirm before re-importing over an existing `project_id`.
- Confirm before `POST .../projects` clones a catalog template.
- Respect export quotas; check `402` responses.

## Companion docs

- Pack schema: `../storeframe-template-from-brief/references/schema.md`
- Example pack: `../storeframe-template-from-brief/examples/habit-glow.yaml`