shotops-mcp 0.9.9 → 0.10.0

package/README.md

@@ -20,29 +20,25 @@ below, or the public [MCP docs](https://shotops.dev/docs/mcp)).
 
 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.
+Pro:** a `render` with `output: "panels"` (full resolution) or `output: "bundle"`. 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 cloud credit is reserved, a screenshot is read or a file is
-  written — a refused call costs nothing and leaves nothing behind.
+  for Studio, hosted and local alike. Free and anonymous callers are refused before a cloud credit
+  is reserved, a screenshot is read or a file is written — a refused call costs nothing.
 - **Cloud credits** price compute ShotOps supplies: 1 per hosted preview panel, 4 per hosted
-  full-resolution panel, plus AI. Rendering on your own machine spends none, on any plan. More
-  cloud credits never unlock store-ready output on Free.
+  full-resolution panel. Rendering on your own machine spends none, on any plan.
 
 Free accounts get 80 cloud 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 cloud credits and none of that anonymous
-allowance.
+exactly where this connection stands — it spends nothing.
 
 ## Zero-custody
 
-The hosted server and every MCP tool **never touch a store-signing credential.** `emit_bundle`
+The hosted server and every MCP tool **never touch a store-signing credential.** A bundle render
 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**.
 
@@ -54,240 +50,102 @@ The key is never copied, printed, or sent to ShotOps, and no release tool is ins
 
 | Tool | What it does | Key inputs |
 |------|--------------|------------|
-| `render_strip` | Preferred focused render: turn raw screenshots into mocked-up per-panel PNGs without creating or updating a project | `screenshots`, `panelPresetId?`, `clip?`, `style?` **+** `look?` (they compose) / `useSavedLook?`, `project?`, `version?`, `locale?`, `preview?`, `output?` |
-| `emit_bundle` | `render_strip` (or pre-rendered `panels` — refs or local `{ path }`, or a saved `project`'s own screenshots) + a `fastlane deliver` zip (+ optional share link) | `screenshots` or `panels` or `project` (bundles what that project holds), `bundleId`, `clip?`, `outputs?` (target devices — one bundle for several sizes; omit and a `project`'s saved outputs are used), `locale?`, `locales?` (multi-locale bundle), `projectName?`, `share?`, `output?` (+ the same styling params) |
-| `save_project` | Save the strip as an editable Studio project (structure + look only — does NOT render, so it never hits the render timeout); always returns an `openUrl`. Authenticated saves also return `projectId`; unsigned local saves return a seven-day pending claim the user owns after opening the link and signing in | `screenshots`, `project?` (update in place only when explicitly targeted and authenticated; omit to create a new project or pending claim), `projectName?`, `appListing?` (an App Store URL, numeric app ID or bundle ID — the project takes the real app's name, bundle ID, languages and devices), `outputs?`, `panelPresetId?`, `style?` / `look?` / `useSavedLook?`, `version?`, `locale?`, `sourceDir?` |
-| `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. `linkedApp` names the App Store app the project is linked to, when it has one | `project?` (default: your most recently edited project) |
-| `search_app_listing` | Find the user's app on the App Store so a save can carry its real identity: each result carries the app's name, seller, icon, bundle ID and numeric app ID, plus the App Store Connect languages and iPhone devices ShotOps would apply. Free, renders nothing, writes nothing; needs an account. Finding a public listing proves nothing about who owns the app | `term`, `country?` (two-letter storefront, default `us`) |
-| `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, 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 cloud 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 cloud 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 1320×2868), `r65`, `r55`.
-  **iPhone sizes only** — the iPad presets are deliberately not offered, because no iPad device
-  model exists yet and rendering one would put an iPhone body in an iPad-shaped canvas. The
-  accepted set is `RENDERABLE_PANEL_PRESET_IDS` in `shotops-mcp/src/render/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. 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"`, `"bleed"`, `"top-bleed"`,
-  `"lean-right"`, `"lean-left"`, `"swipe"` or `"corner-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 last four run it off a
-  SIDE edge instead, into the neighbouring screenshot, so the set reads as one continuous swipe —
-  pick one for **every** panel or none, and never mirror `lean-right` against `lean-left`, which
-  puts two devices into the same seam. 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
-  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
-  it can never go stale the way a stored id would. When a template was nudged, it reports the near
-  miss instead of just failing to match:
-
-  ```jsonc
-  { "layout": "bleed" }                                    // every panel agrees
-  { "layout": null, "closestLayout": "bleed",              // on Bleed, with one adjustment
-    "differs": { "vOffset": { "is": "45", "template": "38" } } }
-  { "layout": null, "closestLayout": null }                // nothing close
-  ```
-
-  It also answers per panel (`layout.panels["panel-1"]`), because a strip may mix compositions and a
-  multi-device panel whose devices were dragged apart is honestly on no template at all. If you set
-  placement by hand with no `layout`, the response `note` names the template that would have produced
-  it — templates are the main road, raw fields are how you nudge one.
-- **`look`** — a ShotOps look JSON exactly as `read_look` returns it, but you can also
-  hand-author one: it gives each screenshot/device its **own** styling through `shots[]`, including
-  two differently coloured devices in one panel. `shots[]` is flattened in panel order; repeat the
-  same `panelId` for devices sharing a panel. This is what `style.shotLook` can't do. **Validated**
-  — unknown keys are rejected (a typo won't silently render wrong). Omit for default styling.
-- **`style` + `look` compose** — every real App Store strip needs BOTH a different device per
-  shot AND captions, so pass them **together**: the `look` supplies the per-device styling +
-  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`.
-- **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`,
-  `fastlane/screenshots/<locale>/NN_shotops.png`) as `zipBase64` or `zipUrl`/`zipRef` (see
-  Output below), plus `shareLink` when `share: true`.
-- **`locale`** — an App Store locale code, e.g. `de-DE` (default `en-US`). Labels the render,
-  picks which `{ "locales": … }` screenshot variants render (see
-  [Per-locale screenshots](#per-locale-screenshots--multi-locale-bundles)), and, for
-  `emit_bundle`, picks the `fastlane/screenshots/<locale>/` folder. **It does not
-  select caption text** — this server never stores or looks up Studio-typed copy (repo owns
-  the words). Pass the right words for that locale yourself in `style.captions[].text` /
-  `subtitle`.
-
-### Per-locale screenshots & multi-locale bundles
-
-Any `screenshots` entry (and any `emit_bundle` `panels` entry) can carry **per-locale
-variants** instead of one image:
-
-```json
-{ "locales": { "en-US": { "ref": "…en…" }, "de-DE": { "ref": "…de…" } } }
-```
-
-- `render_strip({ locale: "de-DE", … })` renders the `de-DE` variant of each such entry. A
-  locale with **no variant of its own falls back** to the `en-US` variant (else the first
-  declared) — so you can ship German captions over English screenshots today and upgrade the
-  pixels later. Plain (non-`locales`) entries serve every locale. The response echoes the
-  declared locales as `screenshotLocales`.
-- `emit_bundle({ locales: ["en-US", "de-DE"], … })` emits **ONE zip** with a
-  `fastlane/screenshots/<locale>/` folder per listed locale — `fastlane deliver` uploads every
-  locale in a single run. A single-entry list behaves exactly like `locale`; omitting `locales`
-  is the unchanged single-locale bundle.
-- `request_screenshot_upload({ count, names, family?, locale? })` returns each slot as
-  `{ ref, uploadUrl, name?, variant }`. For `render_project`, pass that `variant` through beside
-  the ref: it is the device-family + locale cell the screenshot overrides, not a bookkeeping tag.
-  Each `name` must exactly match the saved shot's original filename (`frameName`); the filename
-  chooses the shot while `variant` chooses that shot's device-family + locale cell.
-
-**Recommended multi-locale flow — render per locale, then compose once.** Caption text is
-per-render input, so this is also the only way to get per-locale *captions* into one bundle,
-and it keeps each call fast (see "Cheap preview, then compose" below):
-
-1. Per locale `L`: `render_strip({ locale: L, output: "urls", style: { captions: [<L's words>] },
-   screenshots: […] })` → per-panel refs for `L`.
-2. One `emit_bundle({ locales: […], bundleId, panels: [ { "locales": { "en-US": { "ref": "p1-en" },
-   "de-DE": { "ref": "p1-de" } } }, … ] })` — zips every locale **without re-rendering**.
-
-The one-call form (`emit_bundle` with `screenshots` + `locales`) works too, but renders once
-per locale with the *same* captions for every locale, and multiplies the slow full-res render
-by the locale count.
-
-### The `captions.<locale>.json` convention
-
-The canonical source of shipping caption copy is a file **in your own repo**, one per locale,
-keyed by **panel ordinal** (0-based, in strip order — not panel id, so the file stays stable
-across re-renders):
-
-A panel's entry is EITHER a single caption (`{ headline, subtitle? }`) OR an **array of layers**
-(each `{ text, … }`, stacked in order) — use the array when you want more than a headline + one
-subtitle, e.g. an eyebrow over a headline over a caption:
-
-```json
-// captions.de-DE.json
-{
-  "0": { "headline": "Alles im Blick", "subtitle": "Deine Tage, übersichtlich." },
-  "1": [ { "text": "NEU" }, { "text": "Schneller planen" } ]
-}
-```
-
-To render a locale: read that file, map it onto `style.captions[]` in the same order (index
-`i` → panel `i`, `null` for a panel with no caption), and pass `locale` alongside so the
-render/bundle is labeled and routed consistently. A single caption maps to one object; a layer
-array maps straight through as an array:
+| `render` | Render store screenshots from a saved project (it holds its screenshots, captions and look) or from supplied screenshots. Preview panels, full-resolution panels or a `fastlane deliver` zip. Never saves a project | `project?` or `screenshots?`, `output?` (`preview` default, `panels`, `bundle`), `outputs?`, `locale?`, `locales?` (bundle), `style?`/`look?` (supplied screenshots), `bundleId` (bundle), `share?`, `delivery?` |
+| `save_project` | Save screenshots and styling as an editable project. Returns an `openUrl`; authenticated saves also return `projectId`, unsigned local saves return a seven-day pending claim the user owns after opening the link and signing in | `screenshots`, `project?`, `projectName?`, `style?`/`look?`, `outputs?`, `locale?`, `appListing?` |
+| `edit_project` | Apply concrete changes to a saved project and save it: caption words per frame and locale, frame order, layout, preset, caption style, background, device pose. Deterministic — no AI, no credits | `project`, `captions?`, `order?`, `layout?`, `preset?`, `captionStyle?`, `background?`, `frames?`, `devices?` |
+| `read_project` | A project's full current state: frame order, per-locale caption words, locales, styling, the derived `layout`, and a `screenshots` report of which pixels the project holds | `project?` |
+| `read_look` | A project's saved look (styling only) with its version history | `project?` |
+| `save_look` | Save a look on a project as a new version | `look`, `project?`, `sourceName?` |
+| `describe_look` | Design presets, layout templates, the intake script, every styling field with its default, the devices, and `edit_project`'s vocabulary | *(none)* |
+| `search_app_listing` | Find the user's app on the App Store so a save carries its real identity. Free | `term`, `country?` |
+| `import_screenshot` | Store screenshots from a URL, a ChatGPT attachment or (local) a path, returning a ref per entry | `screenshots`, `file?`, `name?` |
+| `request_screenshot_upload` | Signed upload slots for screenshots on the user's machine | `count`, `names?`, `family?`, `locale?` |
+| `delete_assets` | Permanently delete private uploads, panels or bundles this account holds | `assetIds?`, `refs?` |
+| `account_status` | Whether this connection may render full resolution and bundles, the plan and the credit balance. Free | *(none)* |
+| `production_operation` | Follow a queued full-resolution render or bundle: progress, result, cancel | `action`, `operationId` |
+
+### Rendering
+
+- **A saved project** — `render({ project })` renders the screenshots, frame order, captions and
+  look the project holds, with nothing uploaded. `project` takes an id or the exact name. Pass
+  `screenshots` with `name` (and optional `variant: { family?, locale? }`) to replace the project's
+  file of that name for this render.
+- **Supplied screenshots** — `render({ screenshots: [{ ref }, …], style })`, one panel per entry
+  (nest entries in an array to put several phones in one panel). A render never saves;
+  `save_project` does, when the user wants to keep the work.
+- **`output`** — `"preview"` (default) renders at about a quarter resolution for iterating;
+  `"panels"` renders full resolution; `"bundle"` builds a zip (`README.md`, `fastlane/Deliverfile`,
+  `fastlane/screenshots/<locale>/NN_shotops.png`) and needs `bundleId`. `locales: [...]` puts one
+  folder per locale in one zip; a project bundle takes each locale's own caption words from the
+  project.
+- **`outputs`** — the devices to render (`iphone-6-9`, `iphone-6-5`). Default: the project's saved
+  devices, else `iphone-6-9`.
+- **`delivery`** — `"inline"` image blocks or short-lived `"urls"`; omitted, it picks inline for
+  small results.
+
+### Styling
+
+Call `describe_look` for the authoritative complete field catalog on both the hosted MCP and the
+local `npx shotops-mcp` stdio server. In short:
+
+- **`style`** — `{ layout?, shotLook?, background?, captions? }`. `layout` is the panel composition
+  in one word (`standard`, `bleed`, `top-bleed`, `lean-right`, `lean-left`, `swipe`,
+  `corner-bleed`): it reserves the headline region and places the device, and any field you pass
+  explicitly overrides it. `shotLook` styles every phone alike. `captions` has one entry per panel,
+  a caption object or an array of stacked layers. Caption words are per-render input and never
+  stored in a look.
+- **`look`** — a look exactly as `read_look` returns it; `shots[]` gives every device its own
+  styling. Pass `look` for the devices and `style.captions` for the words in one render. Set
+  `look.shots[].look.clipToFrame: true` to clip one device to its own panel.
+- Every render grades itself: an optional `layout` block names captions sitting on devices and
+  colliding captions, and `layout.correctedLook` is a repaired look to pass straight back.
+
+### Editing a saved project
+
+`edit_project` takes the change itself. Frames and devices are numbered from 1, as the user counts
+them:
 
-```json
+```jsonc
 {
-  "locale": "de-DE",
-  "style": { "captions": [
-    { "text": "Alles im Blick", "subtitle": "Deine Tage, übersichtlich." },
-    [ { "text": "NEU", "sizePt": 28 }, { "text": "Schneller planen" } ]
-  ] }
+  "project": "Darts Tracker",
+  "captions": [
+    { "frame": 1, "text": "Track every throw" },
+    { "frame": 1, "text": "Jeden Wurf im Blick", "locale": "de-DE" }  // adds de-DE if missing
+  ],
+  "order": [2, 1, 3],
+  "layout": "bleed",
+  "devices": [{ "frame": 2, "roll": 8, "colorway": "blue" }]
 }
 ```
 
-There is no MCP tool to read Studio-typed caption text back — Studio's per-locale captions
-are for *visual preview* only; your repo's `captions.<locale>.json` is what actually ships.
+A bad value is refused with the exact field and what it accepts, and nothing is written. The edit
+is saved against the version it read, so a concurrent Studio save is never overwritten.
 
-### Agents: don't inline large images
+### Getting screenshots in
 
-A real marketing screenshot is easily 1–2MB as a PNG — 30–40% bigger again as base64 — and
-that base64 string flows through your OWN tool-call arguments, in YOUR context window, before
-it ever reaches this server. Passing full-resolution screenshots inline can blow past your
-context budget (or get silently truncated by a file-read tool) long before rendering happens.
+Don't inline full-resolution screenshots: base64 flows through your own context first, and inline
+entries are capped at 3MB. Instead:
 
-**Upload out-of-band instead:**
+- **`import_screenshot`** takes several sources in one call — `{ "url" }` (PNG or JPEG, fetched
+  server-side), `{ "file" }` (a ChatGPT attachment, which arrives as the top-level `file`
+  parameter, one per call) or `{ "path" }` (local stdio only) — and returns one ref per entry, in
+  order.
+- **`request_screenshot_upload({ count, names?, family?, locale? })`** returns signed slots;
+  `curl -T screenshot.png "<uploadUrl>"` each one, then pass `{ "ref" }`. With a project, pass the
+  slot's `name` and `variant` too.
 
-**`import_screenshot` moves them all in one call.** Each entry of `screenshots` names exactly
-one source, and you get one result per entry, in the order you sent them:
+Every raw PNG is palette-optimized before rendering, with dimensions and transparency preserved.
+Private uploads and generated files expire after the retention window unless a project keeps them;
+`delete_assets` removes them sooner when the user asks.
 
-```jsonc
-{ "screenshots": [
-  { "url": "https://example.com/01_home.png", "name": "01_home.png" },  // this server fetches it
-  { "path": "/abs/02_stats.png" },                                       // local stdio server ONLY
-  { "file": { "download_url": "…", "file_id": "…" } }                    // a ChatGPT attachment
-] }
-```
+### Per-locale captions
 
-Two sources in one entry is rejected (split them into two entries). A failed entry reports its
-own `error` and never cancels the others — re-import just that one. In ChatGPT the attachment
-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 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
-is no URL to give, so use the signed-slot flow below:
-
-1. Call `request_screenshot_upload({ count: N, names?, family?, locale? })` — returns `N`
-   `{ ref, uploadUrl, name?, variant }` slots
-   under your own private prefix, plus a copy-paste `curl -T` example.
-2. `curl -T screenshot.png "<uploadUrl>"` each screenshot directly (bytes never touch this
-   conversation).
-3. Pass `{ "ref": "<ref>" }` — not inline base64 — as that screenshot's entry in
-   `render_strip`/`emit_bundle`'s `screenshots` array. For `render_project`, also pass the slot's
-   `name` and `variant`; `name` must exactly match the saved shot's original filename, and legacy
-   entries without a variant remain the base/fallback cell.
-
-`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: 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. 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`/`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,
-re-render without `preview` (or call `emit_bundle` directly) once the look is right. Once
-you have full-resolution panel refs from a `render_strip({ output: "urls" })` call,
-`emit_bundle({ panels: [{ ref }, ...] })` packages them into a bundle WITHOUT rendering again
-— skip `screenshots` entirely in that call.
-
-Private uploaded screenshots and generated files are retained until deleted. Treat refs as
-short-lived and single-use, then call `delete_assets({ refs: [...] })` when the files are no
-longer needed. Deleting a ref is irreversible and can make a saved project's referenced
-screenshot unavailable; public privacy disclosures must accurately state this retention model.
+The canonical source of shipping caption copy is a `captions.<locale>.json` file **in your own
+repo**, keyed by panel ordinal (0-based). To render a locale, map it onto `style.captions[]` in the
+same order and pass `locale`. For a saved project, write the words into the project with
+`edit_project` instead, and `render({ project, locales: [...], output: "bundle" })` ships them all.
+A screenshot entry may carry per-locale variants — `{ "locales": { "en-US": { "ref" }, "de-DE":
+{ "ref" } } }` — and a locale with no variant falls back to `en-US`.
 
 ## Prerequisites
 
@@ -307,7 +165,7 @@ npm install
 npm run dev            # boots on http://localhost:8788/mcp  (override with MCP_PORT)
 ```
 
-Chromium boots lazily on the first `render_strip` / `emit_bundle` call, so startup is fast — and
+Chromium boots lazily on the first `render` call, so startup is fast — and
 that first render also installs Chromium if it isn't cached yet, adding ~20-25s to that one call.
 `GET /health` is an unauthenticated liveness probe.
 
@@ -349,7 +207,7 @@ before any tool runs.
 ## After you get a bundle
 
 ```bash
-# decode zipBase64 from emit_bundle's result to a file, then:
+# decode zipBase64 from a bundle render's result to a file, then:
 unzip shotops-appstore-upload.zip -d upload && cd upload
 fastlane deliver        # signs in as YOU, previews, uploads screenshots to a draft — never submits
 ```
@@ -405,13 +263,13 @@ agent user (not a repo collaborator) can find the connect story, since this repo
   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
+- **Hosted render capacity is load-bearing and history-rich.** A `render` 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`.
+  generous per-call timeout (≥180s) for `render`.
 
 ## Local — `npx shotops-mcp`
 
@@ -448,22 +306,13 @@ Chromium, which the first render downloads once as described above.
 instead of `{ ref }`/`{ url }`:
 
 ```json
-{ "screenshots": [[{ "path": "/Users/you/screens/01_home.png" }]] }
+{ "screenshots": [{ "path": "/Users/you/screens/01_home.png" }] }
 ```
 
 (`{ "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** — 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 cloud 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
+Bundles 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
 cloud credits. `account_status` reports which side of the line this process is on.
 
@@ -474,27 +323,27 @@ 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** — pixels and zips are written
+Ordinary `render` 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
+account reads/writes (`read_project`, `edit_project`, the look tools, rendering a saved `project`,
+share links) still need a token or hosted connection. A token-backed local project render reads the cloud
 manifest through the Studio control plane, downloads only the resolved cells, and renders locally:
 
 | | Local (`npx shotops-mcp`) | Hosted (`shotops_…` token) |
 |---|---|---|
 | Render compute | **your machine** ($0, no timeout, no cloud credits on any plan) | our servers — spends your ShotOps cloud credits: 1 per preview panel, 4 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 cloud credits) | trial or Pro, and spends cloud credits |
+| Full-resolution render or bundle | trial or Pro (costs no cloud credits) | trial or Pro, and spends cloud 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 spends no cloud
+Connect your account and `save_project` / `edit_project` / `read_project` / the look tools /
+`render({ project })` start working too — **rendering still happens locally and spends no cloud
 credits**, and
-a trial or Pro account unlocks full-resolution output and `emit_bundle` on this machine. A
+a trial or Pro account unlocks full-resolution output and bundles 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.