shotops-mcp 0.7.0 → 0.9.0

package/README.md

@@ -11,20 +11,43 @@ reusable **looks** and editable **projects**, so the next release matches the la
 Built for agents (ChatGPT / Claude Code / Cursor / CI). It runs over the same `@engine` render
 spine the Studio web app and the `mockup-mcp` CLI use, driving headless Chromium (Playwright).
 
-Ships as **two tiers, one engine**: a free `npx shotops-mcp` **local stdio server** that
-renders on your own machine with no account (see [Local (free tier)](#local-free-tier---npx-shotops-mcp)
-below), and a **hosted** server on Vercel with an account, saved looks, and share links (see
-[Hosted](#hosted) below, or the public
-[`/connect`](https://shotops.dev/connect) page in the studio app).
+Ships as **two doors, one engine**: an `npx shotops-mcp` **local stdio server** that renders on
+your own machine, no account needed to preview (see [Local](#local--npx-shotops-mcp) below), and a
+**hosted** server on Vercel with an account, saved looks, and share links (see [Hosted](#hosted)
+below, or the public [`/connect`](https://shotops.dev/connect) page in the studio app).
+
+## Preview free, export store-ready with Pro
+
+Composing and previewing a strip is free through either door — every device, caption and locale, no
+watermark, and locally without an account at all. **Store-ready output needs an active trial or
+Pro:** a full-resolution `render_strip`/`render_project`, and every `emit_bundle` form, including
+one that only re-zips panels you already rendered. That holds wherever the render happens; local
+compute being free is not the same as local output being free.
+
+The two limits are independent and neither substitutes for the other:
+
+- **Entitlement** is permission to create store-ready files. One server-owned decision answers it
+  for Studio, hosted and local alike, so no door can be talked into a different answer. Free and
+  anonymous callers are refused before a credit is reserved, a screenshot is read or a file is
+  written — a refused call costs nothing and leaves nothing behind.
+- **Credits** price compute ShotOps supplies: 0.5 per hosted preview panel, 2 per hosted
+  full-resolution panel, plus AI. Rendering on your own machine spends none, on any plan. More
+  credits never unlock store-ready output on Free.
+
+Free accounts get 40 credits a month and 2 synced projects. Every new account starts with a 7-day
+Pro trial; after that Pro is €9/month or €90/year. Without any account, the hosted server allows 3
+preview strips per rolling 30 days, at most 5 panels each. Call `account_status` to see exactly
+where this connection stands — it spends no credits and none of that anonymous allowance.
 
 ## Zero-custody
 
-This server **never touches a store-signing credential.** There is no tool input, env var,
-or code path that accepts, stores, or forwards one. `emit_bundle` hands you a zip; **you**
-upload it with **your own** `fastlane`, signed in as yourself. The generated `Deliverfile`
-is screenshots-only and **never submits for review**. The only secrets this process holds
-are Supabase service credentials (to resolve your API token, read your saved look, and back
-share links) — nothing that could reach a store on your behalf.
+The hosted server and every MCP tool **never touch a store-signing credential.** `emit_bundle`
+hands you a zip; **you** upload it with **your own** `fastlane`, signed in as yourself. The
+generated `Deliverfile` is screenshots-only and **never submits for review**.
+
+The one explicit exception is the local `release setup` CLI below. It validates an existing `.p8`
+on your machine directly with Fastlane and Apple, then stores only its path and public identifiers.
+The key is never copied, printed, or sent to ShotOps, and no release tool is installed or upgraded.
 
 ## Tools
 
@@ -36,12 +59,15 @@ share links) — nothing that could reach a store on your behalf.
 | `read_look` | Return a project's saved ShotOps look (styling only), with its latest version, the held version, the `versions` history, and the `layout` template it is composed on (derived from its values, never stored) | `project?` (default: your most recently edited project) |
 | `read_project` | Return a project's FULL current state as an opaque `ProjectFile` — frame order, per-locale caption words, locale list, styling — plus the derived `layout` and a `screenshots.cells` report for every shot × target-family × locale. Each cell says whether pixels resolve, where they resolved from, and which axes inherited | `project?` (default: your most recently edited project) |
 | `render_project` | Render a SAVED project. By default it renders the screenshots **the project already holds** — pass none at all, no upload needed — into **every supported device the project targets**. Pixels resolve independently for each device family + locale through the shared manifest; genuine fallback is reported in `shots[].inherited` and `note` | `project?`, `screenshots?` (**optional** — omit to use what the project holds; else a FLAT list matched by original `name`, with optional `variant: { family?, locale? }` per cell), `outputs?` (override the project's saved devices for this call), `locale?`, `preview?`, `output?` |
+| `refine_project` | Run one bounded Agent turn against a saved project. A supported request commits once and returns the actual diff; ambiguity, missing input, unsupported intent, conflict, and failure return a typed no-write outcome | `project?`, `instruction`, `focus?` |
 | `save_look` | Persist a composed look on a project (styling only — appends a new version) | `look`, `project?`, `sourceName?` |
 | `hold_look` | Hold which saved version agents render by default (replaces pinning) — the version must exist (`read_look` `versions`) | `version`, `project?` |
 | `release_look` | Clear the held version — agents Follow latest (render the newest saved look) | `project?` |
-| `describe_look` | Five named design presets, two named layout templates, the user-intake script, and the full styling field catalog + defaults | *(none)* |
+| `describe_look` | Five named design presets, three named layout templates, the user-intake script, and the full styling field catalog + defaults | *(none)* |
 | `request_screenshot_upload` | Mint signed upload slots for real screenshots; every returned slot carries its semantic screenshot `variant` | `count` (1–10), `names?`, `family?`, `locale?` |
 | `import_screenshot` | Get screenshots INTO ShotOps — several per call, each from one named source (`{ url }`, `{ file }`, or local-stdio `{ path }`), returning a render-ready ref per entry in input order | `screenshots` (1–10 source entries), `file?` (the ChatGPT top-level attachment), `name?`, `locale?` |
+| `account_status` | What THIS connection may do, for free: signed-in account, plan, trial, remaining ShotOps credits, what a preview costs here, and whether store-ready output (full-resolution renders, any `emit_bundle`) is allowed — with a machine-readable `nextStep`. Spends no credits, uses none of the free anonymous preview allowance, uploads and writes nothing | *(none)* |
+| `production_operation` | Reconnect to one durable paid Hosted render or rendering bundle, report persisted progress, request cooperative cancellation, or mint fresh result download grants without rerendering or charging again | `action` (`get`, `cancel`, or `result`), `operationId` |
 | `delete_assets` | Permanently delete private uploaded screenshots, rendered panels, or generated bundles owned by the signed-in account | `refs` (1–50 ShotOps refs) |
 
 - **`panelPresetId`** — App Store size: `r69` (default, 6.9″ iPhone 1290×2796), `r65`, `r55`.
@@ -50,22 +76,24 @@ share links) — nothing that could reach a store on your behalf.
   accepted set is `RENDERABLE_PANEL_PRESET_IDS` in `shotops-mcp/src/panelCatalog.ts`, a subset of
   the hand-kept `PANEL_PRESET_IDS` copy of `mockup-engine/appstore.ts`'s `PANEL_PRESETS` — when
   Apple revises required sizes, add the preset in the engine first, then mirror it here.
-- **`style`** — the structured styling input (call `describe_look` for the full catalog):
+- **`style`** — the structured styling input. On both the hosted MCP and the local
+  `npx shotops-mcp` stdio server, call `describe_look` for the authoritative complete field
+  catalog and defaults:
   `{ layout?, shotLook?, background?, captions? }`. `shotLook` is **one device for every phone**;
   `captions` is one entry PER PANEL in slot order — each entry is EITHER a single caption object OR
   an **array of caption layers** stacked on that panel (headline + subline + …). Each layer's
   `text` (and a single caption's `subtitle`) is per-RENDER input (never stored — a look carries
   styling only). Captions auto-layout in a band at the top of the panel, and the device does NOT
   move to make room.
-- **`style.layout`** — the panel **composition** in one word: `"standard"` or `"bleed"`. It settles
-  the headline's reserved region *and* the device size + position together, which is three numbers
-  that are not independent of each other. `standard` (the shipped default) puts the whole device
+- **`style.layout`** — the panel **composition** in one word: `"standard"`, `"bleed"`, or
+  `"top-bleed"`. It settles the headline's reserved region, device placement, camera pose, and
+  roll together. `standard` (the shipped default) puts the whole device
   under a 2-line region — about 36 characters — and crops nothing; `bleed` reserves 4 lines (~72
   characters) and runs the device 10% off the bottom edge. The region is **reserved, not fitted**:
   it is held at full size whether or not the headline fills it, which is what makes every panel in
   a swiped set land on the same line. **Precedence** — the template expands *first*, then any
-  `shotLook.phoneHeight`/`hOffset`/`vOffset` or `captions[].sizePt`/`maxWidth` you also pass
-  **overrides** it (`{ layout: "bleed", shotLook: { vOffset: "45" } }` is "bleed, but a bit lower").
+  explicit `shotLook` composition field or caption layout field you also pass **overrides** it
+  (`{ layout: "bleed", shotLook: { vOffset: "45" } }` is "bleed, but a bit lower").
   A pure macro: nothing stores the template id, so `save_project` persists the expanded values and
   `read_look` returns them unchanged. **The id is not lost, though — it is DERIVED back:**
   `read_project` and `read_look` both return a `layout` report read out of the values themselves, so
@@ -93,10 +121,10 @@ share links) — nothing that could reach a store on your behalf.
   background, `style.captions` supplies the words, in one render. (Alone, `style` styles every
   phone identically. If you pass `style.shotLook`/`style.background` *alongside* a `look`, the look
   wins and the result carries a note.) Also composes with `useSavedLook`/`version`.
-- **`clip`** — `"strip"` (default) renders one continuous canvas, so a wide/offset device can
-  straddle the seam into the next panel (swipe-through scenes). `"panel"` clips each phone to its
-  own panel so it can't bleed a foreign edge into the neighbouring App Store screenshot. A render
-  option, not part of the saved look.
+- **Clipping** — set `look.shots[].look.clipToFrame: true` to clip one device's complete composite
+  (body, screen, shadow, and reflection) to its own panel; omit it or use `false` for overflow.
+  Pass top-level `clip: "panel"` to clip every device, or `clip: "strip"` to force continuous
+  overflow. Call `describe_look` for the complete Look contract on either MCP tier.
 - **`version`** — render a specific saved look version (implies the saved look). Without it,
   a project with a PINNED version renders the pin; otherwise the latest saved look.
 - **`emit_bundle` output** — a zip (`README.md`, `fastlane/Deliverfile`,
@@ -208,7 +236,7 @@ own `error` and never cancels the others — re-import just that one. In ChatGPT
 arrives as the top-level `file` parameter instead of an array entry, because the Apps SDK cannot
 fill a file parameter nested inside an array; you can pass both in the same call.
 
-`{ url }` and `{ file }` need the hosted server (it stores the fetched PNG under your account);
+`{ url }` and `{ file }` need the hosted server (it stores the fetched screenshot as PNG under your account);
 `{ path }` needs the local stdio server (the hosted server never reads a caller-supplied
 filesystem path — that would be an LFI hole). Each refusal names the door that IS open on your
 tier. When the screenshots are only on the user's machine and you are on the hosted server, there
@@ -227,19 +255,22 @@ is no URL to give, so use the signed-slot flow below:
 `screenshots` entries accept these shapes: an inline base64 string (small payloads only —
 inline is capped and returns a clear "payload too large" error above 3MB decoded, pointing
 you back at this flow), `{ ref }` from step 1, `{ url }` (an https URL this server fetches
-itself: image/png, no redirects, ~20MB cap), `{ path }` (local stdio server only — see below),
+itself: PNG or JPEG, converted to PNG when needed, no redirects, ~20MB cap), `{ path }` (local stdio server only — see below),
 or `{ "locales": { "<locale>": <any of those> } }` for per-locale variants (see
 [Per-locale screenshots](#per-locale-screenshots--multi-locale-bundles) above).
 
 Every raw PNG is automatically palette-optimized before rendering (TinyPNG-style, locally inside
 ShotOps): dimensions and transparency are preserved, and an already-smaller PNG is left byte-for-byte
-unchanged. This happens after the input reaches the MCP, so it does **not** raise the inline request
+unchanged. Fetched JPEGs are converted to palette PNGs at the same boundary without changing their
+dimensions. This happens after the input reaches the MCP, so it does **not** raise the inline request
 cap — use the ref/upload flow for a large source file.
 
-**Output** works the same way in reverse: `render_strip`/`emit_bundle` take an `output` field
-— `"inline"` (base64), `"urls"` (uploaded under your own prefix, short-lived signed download
-URLs), or omit for auto (inline under ~200KB total, `urls` above). Use `"urls"` for
-full-resolution work so results never transit your context either.
+**Output** works the same way in reverse: `render_strip`/`render_project` take an `output` field
+— `"inline"` (standard MCP `image` blocks), `"urls"` (uploaded under your own prefix and returned
+as short-lived `resource_link` blocks), or omit for auto (inline under ~200KB total, `urls` above).
+The model-visible `structuredContent.panels` contains ordered delivery descriptors rather than PNG
+base64; ChatGPT receives the complete gallery through widget-only result metadata. Programmatic
+clients read the standard MCP content blocks. Use `"urls"` for full-resolution work.
 
 **Cheap preview, then compose:** `render_strip({ preview: true })` renders at ~25% resolution
 for fast, cheap styling iteration — small enough to always come back inline; don't ship it,
@@ -256,7 +287,7 @@ screenshot unavailable; public privacy disclosures must accurately state this re
 ## Prerequisites
 
 1. **A ShotOps API token.** Sign in at the Studio app → account menu → **API tokens** →
-   create one. It looks like `shotops_9Zq3Xr7Tp0Vn6Lk2Wd8Yb4Mf1Hc5Ju3Rs9Ea7Gt0Nz1` and is
+   create one. It looks like `shotops_9Zq3Xr7T…` and is
    shown once — copy it then.
 2. **Supabase service env** (already in the repo's `.env.local` for local dev): `SUPABASE_URL`
    and `SUPABASE_SERVICE_ROLE_KEY`. The server loads `../.env.local` automatically.
@@ -280,7 +311,7 @@ Deploy the hosted server at a public HTTPS origin, enable Developer Mode in Chat
 an app whose MCP server URL is `https://<your-host>/mcp`. Do not paste a personal `shotops_` token
 into the app definition: ChatGPT discovers the protected-resource metadata from the endpoint and
 runs the server's OAuth + PKCE browser sign-in flow. This is a tool-only app — no widget or UI
-resource is required. User-attached PNGs enter through `import_screenshot`.
+resource is required. User-attached PNGs and JPEGs enter through `import_screenshot`.
 
 For public plugin submission, OpenAI supplies a domain-verification token after the MCP domain
 is entered in the Platform dashboard. Set it on the hosted server as
@@ -294,7 +325,7 @@ tests without private fixture data or third-party hosting.
 
 ```bash
 claude mcp add --transport http shotops http://localhost:8788/mcp \
-  --header "Authorization: Bearer shotops_9Zq3Xr7Tp0Vn6Lk2Wd8Yb4Mf1Hc5Ju3Rs9Ea7Gt0Nz1"
+  --header "Authorization: Bearer shotops_…"
 ```
 
 Then ask the agent to, e.g., *"render these two screenshots into a 6.9″ App Store strip and
@@ -322,14 +353,14 @@ fastlane deliver        # signs in as YOU, previews, uploads screenshots to a dr
 The server also runs hosted, 24/7-reachable (scale-to-zero when idle), at:
 
 ```
-https://shotops.dev/mcp
+https://mcp.shotops.dev/mcp
 ```
 
 Nothing to install — point any MCP client at that URL with your `Authorization: Bearer
 shotops_…` header, same as local dev, just swap the base URL:
 
 ```bash
-claude mcp add --transport http shotops https://shotops.dev/mcp \
+claude mcp add --transport http shotops https://mcp.shotops.dev/mcp \
   --header "Authorization: Bearer shotops_…"
 ```
 
@@ -340,54 +371,49 @@ since this repo is private.
 
 ### Ops (this repo's maintainer only)
 
-- **Deploy** (from the **repo root** — the Dockerfile needs `../mockup-engine` and
-  `../api/_lib` as build-context siblings):
+`shotops-mcp` serves from its own Vercel project on `https://mcp.shotops.dev` (health:
+`/health`, MCP endpoint: `/mcp`). **`docs/reference/ops-runbook.md` §Deploy owns the procedure**
+— the notes here are only what is specific to this package.
+
+- **Deploy:** run the repo's deploy script from the repo root; deploys run locally, and a push to
+  `main` is a production deploy. Do not hand-run a bare `vercel deploy`. Fly was retired (#68) —
+  `flyctl` is history, not the live procedure.
+- **Runtime env** lives on the `shotops-mcp` **Vercel project**, not in this repo:
+  `SUPABASE_URL`, `SUPABASE_SERVICE_ROLE_KEY`, and `MCP_PUBLIC_URL` (pins the public hostname as
+  the OAuth issuer), plus `OPENAI_APPS_CHALLENGE_TOKEN` while verifying the MCP domain for public
+  ChatGPT submission — nothing Apple-related, ever, by construction. Vercel env applies at the
+  NEXT deployment, never to the running one.
+- **Verify after any deploy** — a green deploy isn't proof the server answers MCP calls:
   ```bash
-  flyctl deploy . --config shotops-mcp/fly.toml --remote-only --ha=false
+  cd shotops-mcp && SHOTOPS_MCP_TOKEN=… node verify-mcp.mjs https://mcp.shotops.dev/mcp
   ```
-- **Secrets** (`fly secrets set -a shotops-mcp KEY=value`): `SUPABASE_URL`,
-  `SUPABASE_SERVICE_ROLE_KEY`, plus `OPENAI_APPS_CHALLENGE_TOKEN` while verifying the MCP
-  domain for public ChatGPT plugin submission — nothing Apple-related, ever, by construction.
-- **Verify after any deploy** — a green `flyctl deploy` isn't proof the server answers MCP
-  calls:
-  ```bash
-  node verify-mcp.mjs https://shotops.dev/mcp <a-real-shotops_-token>
-  ```
-  Exercises `tools/list`, `read_look`, `emit_bundle` (asserts the zip unzips to
-  README/Deliverfile/screenshots), and asserts no-token / bad-token both get `401`.
-- **Logs / status:** `flyctl logs -a shotops-mcp`, `flyctl status -a shotops-mcp`.
-- The Dockerfile is pinned to `mcr.microsoft.com/playwright:v1.61.1-noble` — matching the
-  `playwright` npm version in `package.json`. If you bump one, bump the other.
-- The container builds the browser harness once and serves it through a loopback-only static
-  server at runtime. Vite is build/parity tooling only and is pruned from production
-  dependencies; the Docker build context still includes `mockup-engine` so the harness can
-  bundle the shared engine + GLB.
-- **VM size is `shared-cpu-2x` with 4GB — and BOTH numbers are load-bearing for different
-  reasons.** The **memory** was raised 2gb → 4gb on 2026-07-26 (#134): a grouped multi-panel
-  `render_strip` drove `chrome-headless` to ~1.4gb resident, the kernel OOM-killed it, and the
-  server went unhealthy for minutes — `verify-mcp.mjs` could not run to completion at 2gb and now
-  does. The **2 vCPUs** are the older finding below; don't conflate them, and don't cut either.
-- **Why 2 vCPU and not `shared-cpu-1x`** (found live, Phase 10):
-  Chromium's software WebGL render (no GPU on the hosted tier) is CPU-heavy enough that on
-  a single shared vCPU it can starve the whole process — health checks stop responding,
-  SIGTERM/SIGINT get ignored, and the platform force-kills the machine
-  mid-render. **`Virtual machine exited abruptly` has TWO causes and they look identical in the
-  logs:** on 1 vCPU it is this CPU starvation; on 2 vCPU under load it was the #134 OOM, i.e.
-  MEMORY, fixed by the `4gb` above (`docs/reference/ops-runbook.md` carries that half). Check
-  which resource ran out before reaching for either fix. On 2 vCPUs the same 3-panel real-screenshot render completes in ~8s. Don't
-  drop back to `shared-cpu-1x` to save cost — a render-triggering tool call is expected to
-  occasionally saturate a whole core, and 1x has no second core to keep the process alive
-  while that happens. Client callers (agents, `verify-mcp.mjs`) should still set a generous
-  per-call timeout (≥180s) for `render_strip`/`emit_bundle` — even warm, cold-machine renders
-  can take 60-110s before the CPU fix, and network/Supabase round trips add more on `urls`
-  output.
-
-## Local (free tier) — `npx shotops-mcp`
+  Exercises the exact registered tool set, real render/bundle/project round-trips, signed upload
+  refs, asset deletion, and asserts no-token / bad-token both get `401`. It needs the **Studio**
+  deployment live too (`delete_project` is a control-plane op) and leaves the account as it found
+  it (#333). Add `--artifact-dir <private-dir>` for the ChatGPT portal handoff.
+- **Logs / status:** the `shotops-mcp` project in the Vercel dashboard.
+- **Production builds through Nitro** — `nitro.config.ts` (`preset: 'node-server'`,
+  `vercel: { entryFormat: 'node' }`) compiles the Express graph into `dist-server/`. `Dockerfile`
+  builds the RETIRED Fly image only; it is pinned to `mcr.microsoft.com/playwright:v1.61.1-noble`
+  to match the `playwright` npm version in `package.json`, so if you bump one, bump the other.
+- The build compiles the browser harness once (`build:harness` → `harness-dist/`) and the running
+  server serves it from a loopback-only static server. Vite is build/parity tooling only and is
+  pruned from production dependencies; `mockup-engine` stays reachable at build time so the
+  harness can bundle the shared engine + GLB.
+- **Hosted render capacity is load-bearing and history-rich.** A `render_strip` boots headless
+  Chromium + WebGL for seconds, inline in the request, and full-res multi-panel renders are slow
+  by design — seconds per panel, one panel at a time. The function duration ceiling, the memory
+  findings behind it, and the two distinct failure shapes (CPU starvation vs. OOM) are recorded in
+  `docs/reference/ops-runbook.md` §Deploy. Never cut a memory or duration setting without a green
+  `verify-mcp.mjs` run behind the claim. Client callers (agents, `verify-mcp.mjs`) should set a
+  generous per-call timeout (≥180s) for `render_strip`/`emit_bundle`.
+
+## Local — `npx shotops-mcp`
 
 The SAME server also runs as a **local stdio MCP**, entirely on your own machine — no URL, no
-account, no hosted cost, and no render-timeout ceiling (the hosted server's one real limit — see
-"Ops" above). It's the same `registerTools`/render engine as the hosted server; only the
-transport and a few account-shaped tools differ.
+hosted cost, and no render-timeout ceiling (the hosted server's one real limit — see "Ops" above).
+Previewing needs no account. It's the same `registerTools`/render engine as the hosted server; only
+the transport and a few account-shaped tools differ.
 
 ```bash
 claude mcp add shotops -- npx -y shotops-mcp
@@ -410,14 +436,19 @@ instead of `{ ref }`/`{ url }`:
 (`{ "path": ... }` only works over this LOCAL server — the hosted server rejects it, since
 reading an arbitrary server-side path there would be a local-file-inclusion hole.)
 
-**`emit_bundle` reads local panels off disk too** — the free tier has no account, so it can't
-produce `output: "urls"` refs. After rendering, pass the on-disk PNGs straight to `emit_bundle`
-(same local-only `{ path }` door as screenshots) to package a `fastlane deliver` zip with no upload:
+**`emit_bundle` reads local panels off disk too** — an unsigned local server has no account, so it
+can't produce `output: "urls"` refs. Once you are signed in on a trial or Pro, pass the on-disk PNGs
+straight to `emit_bundle` (same local-only `{ path }` door as screenshots) to package a
+`fastlane deliver` zip with no upload and no credits:
 
 ```json
 { "bundleId": "com.acme.app", "panels": [{ "path": "/abs/panel-01.png" }, { "path": "/abs/panel-02.png" }] }
 ```
 
+`emit_bundle` and full-resolution renders are the store-ready half of the offer, so they need that
+trial or Pro even here, where the compute is yours. Preview renders need neither an account nor
+credits. `account_status` reports which side of the line this process is on.
+
 **Saving without a token:** a new `save_project` made from local `{ path }` PNGs creates a private
 **pending claim**. It uploads only that saved project's byte-free record and raw source PNGs,
 returns `status: "pending_claim"` plus `claimId` and `openUrl`, and deliberately returns no
@@ -425,22 +456,26 @@ returns `status: "pending_claim"` plus `claimId` and `openUrl`, and deliberately
 with its screenshots, and the link expires after 7 days. An existing `project` cannot be updated
 without the token that owns it. Non-path inputs are refused rather than creating a blank claim.
 
-Ordinary `render_strip` / `emit_bundle` calls still upload **nothing** and work fully. Other
+Ordinary `render_strip` / `emit_bundle` calls still upload **nothing** — pixels and zips are written
+straight to your disk, and no screenshot leaves the machine. Other
 account reads/writes (`read_look`, `save_look`, `read_project`, `render_project`, share links)
 still need a token or hosted connection. A token-backed local `render_project` reads the cloud
 manifest through the Studio control plane, downloads only the resolved cells, and renders locally:
 
-| | Local (free, `npx shotops-mcp`) | Hosted (`shotops_…` token) |
+| | Local (`npx shotops-mcp`) | Hosted (`shotops_…` token) |
 |---|---|---|
-| Render compute | **your machine** ($0, no timeout) | our servers — spends your ShotOps credits: 1,000 per preview panel, 4,000 per full-resolution panel |
-| Auth | none (the process runs as you) | account + API token |
+| Render compute | **your machine** ($0, no timeout, no credits on any plan) | our servers — spends your ShotOps credits: 0.5 per preview panel, 2 per full-resolution panel |
+| Preview render | free, no account | free on an account; 3 per 30 days, ≤5 panels, without one |
+| Full-resolution render, any `emit_bundle` | trial or Pro (costs no credits) | trial or Pro, and spends credits |
+| Auth | none to preview; a token for account state and store-ready output | account + API token |
 | Saved looks / editable projects / project read+re-render / share links | new project: pending claim; existing/account state: token (below); share links: hosted | ✅ |
 | Screenshot input | local `{ path }` off disk | `request_screenshot_upload` → `{ ref }` |
 
 ### Optional: bridge a local render into your hosted account
 
 Connect your account and `save_project` / `read_look` / `save_look` / `read_project` /
-`render_project` start working too — **rendering still happens locally and for free.** A
+`render_project` start working too — **rendering still happens locally and spends no credits**, and
+a trial or Pro account unlocks full-resolution output and `emit_bundle` on this machine. A
 deliberate save also uploads its local source PNGs privately so the project reopens with
 screenshots on another device; normal renders and exports never upload.
 
@@ -466,6 +501,124 @@ SHOTOPS_TOKEN=shotops_… claude mcp add shotops -- npx -y shotops-mcp
 `--token` wins over `SHOTOPS_TOKEN`, which wins over a saved browser login — so a token in the
 environment is never quietly shadowed by whoever last signed in on that machine.
 
+### Local Apple release setup
+
+Before preparing an App Store release, validate the Apple tooling and API key already on this
+machine:
+
+```bash
+npx shotops-mcp release setup
+# non-interactive form:
+npx shotops-mcp release setup \
+  --issuer-id "$APP_STORE_CONNECT_ISSUER_ID" \
+  --key-id "$APP_STORE_CONNECT_KEY_ID" \
+  --key-path /secure/AuthKey_ABC123DEFG.p8
+```
+
+The command requires an owner-only `.p8`, Fastlane, and Apple Transporter; parses the key through
+Fastlane; and makes read-only App Store Connect app-list requests to prove the key's real access.
+It does not install or upgrade anything. Only Issuer ID, Key ID, and the canonical key path are
+saved in `~/.shotops/release.json` (or `$SHOTOPS_CONFIG_DIR/release.json`); a failed rerun leaves the
+last valid setup untouched.
+
+For CI, create secret inputs named `APP_STORE_CONNECT_ISSUER_ID`,
+`APP_STORE_CONNECT_KEY_ID`, and `APP_STORE_CONNECT_PRIVATE_KEY`. The setup command names these
+inputs but never prints their values.
+
+### Prepare a deterministic desired release
+
+Once signed in to ShotOps, assemble the saved owner project and repository into one local,
+content-addressed workspace — before reading or changing App Store Connect:
+
+```bash
+npx shotops-mcp release prepare --project "My project"
+
+# Optional signed build and an explicit partial scope:
+npx shotops-mcp release prepare \
+  --project proj_123 \
+  --build build/MyApp.ipa \
+  --locales en-US,de-DE \
+  --outputs iphone-6-9
+```
+
+The command renders every authored locale and selected output by default with the same engine as
+Studio and the MCP. `--locales` or `--outputs` deliberately narrows the run and records every
+omission as a **partial** scope. It writes `desired-release.json` plus the rendered PNGs under
+`~/.shotops/release-workspaces/<desired-id>/` (or `--output <directory>`), with user-only
+permissions. Identical project, repository, scope, and build inputs produce the same manifest ID
+and pixels.
+
+Repository input conventions are explicit so no Ruby is ever evaluated:
+
+- `fastlane/metadata/<locale>/*.txt` — supported localized Deliver metadata;
+- `fastlane/metadata/*.txt` and `review_information/*.txt` — app and review metadata;
+- `fastlane/metadata/app_store_rating_config.json` — Fastlane's current age-rating shape;
+- `fastlane/metadata/submission_information.json` — export/content compliance fields;
+- `fastlane/metadata/app_review_attachment_file.txt` — empty clears the attachment; otherwise it
+  names a repository-relative supported attachment;
+- `fastlane/app-previews/<locale>/*` — `.mov`, `.mp4`, or `.m4v`, with the ASC device token in
+  each filename (for example `APP_IPHONE_67_01_demo.mp4`).
+
+Missing files mean **unchanged**; an existing supported empty text file means **clear**. Unknown
+files, fields, locales, outputs, unreadable artifacts, and Bundle ID disagreements fail closed.
+Fastfile and Deliverfile are never executed. Optional `.ipa`/supported `.pkg` bytes are hashed and
+referenced, never copied into ShotOps state. This step performs no ASC request, upload, version
+creation, signing, submission, or release.
+
+### Create the exact App Store Connect plan
+
+Read the editable App Store version and bind it to the prepared workspace without changing Apple:
+
+```bash
+npx shotops-mcp release plan \
+  --workspace ~/.shotops/release-workspaces/<desired-id> \
+  --repo .
+```
+
+The command resolves the Bundle ID to one accessible app and one editable iOS version, then reads
+the supported metadata, review, age-rating, compliance, build, screenshot, and App Preview
+baseline. It writes a user-only `release-plan.json` containing every operation as a member of one
+closed, typed vocabulary — each carrying its own target, the precondition it needs, the sealed bytes
+it sends, the postcondition it must reach, and a redacted summary — plus a portable
+`release-review.zip` containing that exact canonical plan and its content-addressed screenshot bytes.
+
+The plan hash-binds the project revision, desired bytes, normalized Fastlane inputs, Apple setup
+identity and policy version, so later approval cannot drift onto different state. Its **approval
+window is 15 minutes**; the plan itself stays readable for as long as its sealed workspace exists.
+Concurrency is per resource rather than one hash of the whole app: an unrelated App Store edit is
+reported without invalidating the plan, while a change to a resource the plan writes — or to the
+app, version or App Store state it targets — blocks before any write.
+
+`release-plan-envelope.json` is the separate redacted form safe for a later ShotOps coordination
+step: it carries keyed commitments and digests, never metadata values, review credentials, local
+paths, Apple credentials, or asset bytes. Identifiers are committed under a per-plan key that stays
+on your machine, so the envelope cannot be used to confirm a guess at your Bundle ID, Apple key ID
+or version string. This command talks directly to Apple with GET requests
+only; it never uploads, creates a version, commits, submits, or sends the private key to ShotOps.
+
+### Review the exact plan locally
+
+From the plan directory, open its read-only local browser review:
+
+```bash
+npx shotops-mcp release review
+```
+
+To review an artifact downloaded from owner-controlled CI, pass it directly:
+
+```bash
+npx shotops-mcp release review release-review.zip
+```
+
+The command verifies the exact plan hash, artifact manifest, and every embedded screenshot before
+opening a nonce-protected URL on `127.0.0.1` with a random port. The page shows target app and team
+fingerprint, Bundle ID, version, the approval window, complete or partial scope, every
+before/after/clear, build, review, rating, compliance, preview, screenshot order/replacement/omission,
+unchanged operation, and the operations excluded by the plan. Partial-scope and no-build warnings
+cannot be dismissed. It loads no remote resource, sends nothing, and has no edit or approval action.
+A plan past its approval window opens read-only and says why; corrupt, edited, or content-mismatched
+inputs fail before a server is started.
+
 The saved project remembers the exact on-disk folder your screenshots came from (not just their
 filenames), so re-opening it on the SAME machine can point right back at it. Share links aren't
 bridged yet — they'd need a hosted rendering step, which would defeat local rendering's whole
@@ -496,7 +649,7 @@ shotops-mcp/
     uploads.ts      Phase 10 — upload slots, ref ownership check, output:'urls' storage
     screenshotInput.ts  Phase 10 — resolves screenshots[] (inline/ref/url/path) to base64
     env.ts          loads ../.env.local; MCP_PORT / STUDIO_ORIGIN / MCP_PUBLIC_URL
-    local.ts        the LOCAL (free tier) npx entry point — stdio transport, no auth
+    local.ts        the LOCAL npx entry point — stdio transport, no auth required to preview
     localDeps.ts     the local ToolDeps fork — static-serve renderer, no-op/bridged persistence
     hostedBridge.ts  local→hosted bridge (a real MCP client using your shotops_ token)
   harness/          the browser render page Chromium loads (render.js exposes window.renderStrip)
@@ -504,7 +657,8 @@ shotops-mcp/
   vite.harness.config.mjs  the STATIC harness build (local mode's publish prerequisite) → harness-dist/
   build.mjs         esbuild bundle of src/local.ts (+ @engine/@api inlined) → dist/local.js
   Dockerfile        hosted image — Playwright's Chromium base + this repo's 3 npm installs
-  fly.toml          Fly app config — ROLLBACK ONLY since the Vercel cutover; see #68
+  fly.toml          Fly app config — RETIRED (#68), kept only for the cold-deploy recipe;
+                    the running fly.dev machine is NOT a rollback
   verify-mcp.mjs    post-deploy smoke test — real MCP round-trip against a hosted URL
   verify-mcp-local.ts  local stdio smoke test (tsx src/local.ts, in-repo)
   static-parity.ts  pixel-diffs the static-serve render against the Vite-dev render (must be 0)

package/THIRD_PARTY_NOTICES

@@ -71,6 +71,7 @@ Space Grotesk
 Copyright 2020 The Space Grotesk Project Authors (https://github.com/floriankarsten/space-grotesk)
 
 Each font is licensed under the SIL Open Font License, Version 1.1:
+https://openfontlicense.org/open-font-license-official-text/
 
 -----------------------------------------------------------
 SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007