shotops-mcp 0.5.0 → 0.7.0

package/LICENSE

@@ -0,0 +1,97 @@
+ShotOps CLI and Local MCP License
+Version 1.1 — 11 August 2026
+
+Copyright (c) 2026 Rasmus Gehrke. All rights reserved.
+
+This license governs the `shotops-mcp` software package, including the bundled
+ShotOps rendering engine (the "Software"). "You" means the individual or legal
+entity exercising the rights granted below. The Software is licensed, not sold.
+Third-party components and assets are excluded from the definition of Software
+and are governed by their own licenses and notices.
+
+GRANT
+
+Subject to this license, you are granted a free, worldwide, royalty-free,
+non-exclusive, non-transferable right to:
+
+1. install and run the Software, without limit, in computing environments you
+   own, control, or are authorized to use, including via `npx` and in CI;
+2. use the Software to render device mockups, screenshot strips, and store
+   bundles from content you are authorized to use; and
+3. use, publish, and commercialize the output the Software produces from that
+   content, subject to any rights in your content, third-party components,
+   assets, device designs, and trademarks.
+
+As between you and the copyright holder, the copyright holder claims no
+ownership in your content or in output created from it. This license does not
+grant rights in third-party content, assets, designs, or trademarks that may
+appear in the output.
+
+Use of ShotOps hosted services through the Software is additionally governed
+by the ShotOps Terms of Service at https://shotops.dev/terms.
+
+RESTRICTIONS
+
+You may not:
+
+1. redistribute, republish, sell, rent, sublicense, or otherwise provide the
+   Software or any part of it (including the bundled rendering engine) to a
+   third party;
+2. modify the Software or create derivative works from it;
+3. extract, copy, or reuse components of the Software — including the
+   rendering engine — in another product or service;
+4. offer the Software's functionality to third parties as a service, or use
+   it to build a product or service that competes with ShotOps; or
+5. reverse engineer, decompile, disassemble, or otherwise attempt to derive
+   the source code of the Software; or
+6. remove or obscure copyright, license, or attribution notices.
+
+These restrictions apply only to the extent permitted by law. Nothing in this
+license limits a right that cannot lawfully be waived or restricted. In
+particular, where Directive 2009/24/EC or equivalent national law applies, this
+license does not restrict the lawful user's rights to make a necessary backup
+copy, to observe, study, or test the functioning of the Software while
+performing authorized acts, or to reproduce or translate code where that is
+indispensable to achieve interoperability and all statutory conditions are met.
+
+THIRD-PARTY COMPONENTS
+
+The Software depends on and may bundle third-party components and assets.
+Their copyright notices and license terms are identified in the files,
+metadata, or THIRD_PARTY_NOTICES distributed with the package. Those terms,
+not this license, govern the relevant third-party material. Nothing in this
+license restricts rights granted under a third-party license.
+
+TERMINATION
+
+If you materially breach this license, your rights terminate if you do not cure
+the breach within 14 days after receiving notice. Rights terminate immediately
+for a breach that cannot be cured or that involves intentional unauthorized
+redistribution or provision of the Software as a service. On termination, you
+must stop using the Software and delete your copies. Provisions that by their
+nature should survive termination, including ownership, restrictions,
+warranty, and liability provisions, remain effective.
+
+NO WARRANTY; LIABILITY
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
+NON-INFRINGEMENT. TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE COPYRIGHT HOLDER
+IS NOT LIABLE FOR INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR PUNITIVE
+DAMAGES, OR FOR LOSS OF DATA, REVENUE, OR PROFITS, ARISING FROM OR IN CONNECTION
+WITH THE SOFTWARE OR ITS USE.
+
+NOTHING IN THIS LICENSE EXCLUDES OR LIMITS MANDATORY STATUTORY RIGHTS OR
+REMEDIES, INCLUDING CONSUMER RIGHTS RELATING TO CONFORMITY OF DIGITAL CONTENT,
+OR LIABILITY THAT CANNOT LAWFULLY BE EXCLUDED OR LIMITED.
+
+GOVERNING LAW
+
+This license is governed by the law of Denmark, without regard to conflict-of-
+laws rules. If you are a consumer, this choice does not deprive you of mandatory
+protections provided by the law that would apply without this choice, and
+jurisdiction is determined by mandatory consumer-jurisdiction rules. In all
+other cases, disputes are subject to the exclusive jurisdiction of the courts
+of Denmark.
+
+Contact: support@shotops.dev

package/README.md

@@ -1,15 +1,21 @@
 # shotops-mcp
 
-A hosted-ready **MCP server** that turns app screenshots into styled 3D App Store mockups,
-emits a `fastlane deliver`-ready bundle, and reads your saved ShotOps look — 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).
+A hosted-ready **MCP server** that makes the marketing screenshots an app store listing needs.
+Give it the raw screen captures from an app and it composites each one into a styled 3D device
+mockup, lays them out as a screenshot strip, sets your headlines over them, and hands back the
+panels as PNGs plus a `fastlane deliver`-ready bundle. Captions are held per locale, so one strip
+ships in every language you list in. It renders at App Store panel sizes and bundles for fastlane
+deliver, so a Google Play listing reuses the designs rather than the exact files. Designs save as
+reusable **looks** and editable **projects**, so the next release matches the last one.
+
+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 Fly.io with an account, saved looks, and share links (see
-[Hosted (Fly.io)](#hosted-flyio) below, or the public
-[`/connect`](https://storeframe-studio.vercel.app/connect) page in the studio app).
+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).
 
 ## Zero-custody
 
@@ -24,37 +30,66 @@ share links) — nothing that could reach a store on your behalf.
 
 | Tool | What it does | Key inputs |
 |------|--------------|------------|
-| `render_strip` | Render screenshots into mocked-up per-panel PNGs | `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 }`) + a `fastlane deliver` zip (+ optional share link) | `screenshots` or `panels`, `bundleId`, `clip?`, `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); returns `projectId` + an `openUrl` | `screenshots`, `project?` (update in place; omit to create), `projectName?`, `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, and the `versions` history | `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. Answers *"what did the designer change?"* (remember `updatedAt`, re-read later) | `project?` (default: your most recently edited project) |
-| `render_project` | Re-render a SAVED project with your OWN raw screenshots, matched to its shots **by filename** — the project supplies frame order, captions + styling, so the result reproduces the designer's strip | `project?`, `screenshots` (a FLAT list, each with its original filename as `name`), `locale?`, `preview?`, `output?` |
+| `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?`, `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 | `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?` |
 | `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` | The styling field catalog + defaults, for authoring from scratch | *(none)* |
-| `request_screenshot_upload` | Mint signed upload slots for real screenshots | `count` (1–10), `names?`, `locale?` (a per-locale batch tag) |
-| `import_screenshot` | Import a PNG attached in ChatGPT and return a render-ready ref | `file`, `name?`, `locale?` |
+| `describe_look` | Five named design presets, two 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?` |
 | `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`,
-  `ipad13`, `ipad129`. This enum is a hand-kept copy of `mockup-engine/appstore.ts`'s
-  `PANEL_PRESETS` (see `shotops-mcp/src/schemas.ts`'s `PANEL_PRESET_IDS`/`PANEL_DIMENSIONS`)
-  — when Apple revises required sizes, add the preset in the engine first, then mirror it
-  here.
+- **`panelPresetId`** — App Store size: `r69` (default, 6.9″ iPhone 1290×2796), `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/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):
-  `{ 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 above the device so they never collide with the phone.
+  `{ 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
+  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").
+  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 panel its **own** device (`shots[]`, tint/tilt/size per panel),
-  which `style.shotLook` can't. **Validated** — unknown keys are rejected (a typo won't silently
-  render wrong). Omit for default styling.
+  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
-  panel AND captions, so pass them **together**: the `look` supplies the per-panel devices +
+  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`.
@@ -93,8 +128,11 @@ variants** instead of one image:
   `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, locale })` tags a batch of upload slots with the
-  locale it's for (echoed back — bookkeeping only; refs are locale-agnostic).
+- `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,
@@ -154,25 +192,50 @@ context budget (or get silently truncated by a file-read tool) long before rende
 
 **Upload out-of-band instead:**
 
-In ChatGPT, attach the PNG and call `import_screenshot` once per file. ChatGPT supplies the
-temporary file parameter; ShotOps downloads and stores it server-to-server, then returns
-the same `{ ref }` used by the render tools. In other hosted MCP clients, use the signed-slot
-flow below:
+**`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:
+
+```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
+] }
+```
+
+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.
 
-1. Call `request_screenshot_upload({ count: N })` — returns `N` `{ ref, uploadUrl }` slots
+`{ url }` and `{ file }` need the hosted server (it stores the fetched 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.
+   `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 ~8MB decoded, pointing
+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),
 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
+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
@@ -224,7 +287,7 @@ is entered in the Platform dashboard. Set it on the hosted server as
 `OPENAI_APPS_CHALLENGE_TOKEN`; the server then returns that exact value from
 `/.well-known/openai-apps-challenge`. With no token configured, the route returns 404.
 The server also exposes a synthetic, non-user PNG at
-`/review-fixtures/sample-app-screen.png` so reviewers can reproduce attachment and URL-input
+`/review-fixtures/sample-app-screen-v2.png` so reviewers can reproduce attachment and URL-input
 tests without private fixture data or third-party hosting.
 
 ## Connect Claude Code
@@ -254,23 +317,23 @@ unzip shotops-appstore-upload.zip -d upload && cd upload
 fastlane deliver        # signs in as YOU, previews, uploads screenshots to a draft — never submits
 ```
 
-## Hosted (Fly.io)
+## Hosted
 
 The server also runs hosted, 24/7-reachable (scale-to-zero when idle), at:
 
 ```
-https://shotops-mcp.fly.dev/mcp
+https://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-mcp.fly.dev/mcp \
+claude mcp add --transport http shotops https://shotops.dev/mcp \
   --header "Authorization: Bearer shotops_…"
 ```
 
-The public [`/connect`](https://storeframe-studio.vercel.app/connect) page in the studio
+The public [`/connect`](https://shotops.dev/connect) page in the studio
 app has the same instructions for Cursor/CI, plus a link to where to create a token — it's
 the one place an external agent user (not a repo collaborator) can find the connect story,
 since this repo is private.
@@ -288,7 +351,7 @@ since this repo is private.
 - **Verify after any deploy** — a green `flyctl deploy` isn't proof the server answers MCP
   calls:
   ```bash
-  node verify-mcp.mjs https://shotops-mcp.fly.dev/mcp <a-real-shotops_-token>
+  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`.
@@ -299,11 +362,19 @@ since this repo is private.
   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` (2 vCPU / 2GB), not `shared-cpu-1x`** (found live, Phase 10):
-  Chromium's software WebGL render (no GPU on Fly's shared tier) is CPU-heavy enough that on
+- **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 Fly force-kills the VM ("Virtual machine exited abruptly")
-  mid-render. On 2 vCPUs the same 3-panel real-screenshot render completes in ~8s. Don't
+  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
@@ -314,7 +385,7 @@ since this repo is private.
 ## Local (free tier) — `npx shotops-mcp`
 
 The SAME server also runs as a **local stdio MCP**, entirely on your own machine — no URL, no
-account, no Fly cost, and no render-timeout ceiling (the hosted server's one real limit — see
+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.
 
@@ -347,32 +418,54 @@ produce `output: "urls"` refs. After rendering, pass the on-disk PNGs straight t
 { "bundleId": "com.acme.app", "panels": [{ "path": "/abs/panel-01.png" }, { "path": "/abs/panel-02.png" }] }
 ```
 
-**What's different locally, and why:** every tool that needs an ACCOUNT to read or persist to —
-`read_look` / `save_look` / `save_project` / `read_project` / `render_project` / share links —
-has nothing to talk to in local mode by default, so they cleanly no-op with a "sign in" message.
-`render_strip` / `emit_bundle` are otherwise **fully functional** — you lose nothing on rendering
-itself, only on persistence, which is exactly the free/paid line:
+**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
+`projectId` yet. Give the `openUrl` to the user: after one Google sign-in they own the project,
+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.
 
-| | Local (free, `npx shotops-mcp`) | Hosted (Fly, `shotops_…` token) |
+Ordinary `render_strip` / `emit_bundle` calls still upload **nothing** and work fully. 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) |
 |---|---|---|
-| Render compute | **your machine** ($0, no timeout) | our Fly machine |
+| 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 |
-| Saved looks / editable projects / project read+re-render / share links | opt-in via a token (below) — share links still need a direct hosted connection | ✅ |
+| 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
 
-Pass a personal ShotOps API token (Studio → account menu → **API tokens** — the same
-`shotops_…` token the hosted server takes as a bearer) and `save_project` / `read_look` /
-`save_look` / `read_project` / `render_project` start working too — **rendering still happens
-locally and for free; only the small saved-project JSON (structure + look, never screenshot
-bytes) goes to your 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
+deliberate save also uploads its local source PNGs privately so the project reopens with
+screenshots on another device; normal renders and exports never upload.
+
+Sign in through your browser, once per machine:
+
+```bash
+npx shotops-mcp login     # opens ShotOps in your browser, saves the token it gets back
+npx shotops-mcp whoami    # which account is connected, and its plan
+npx shotops-mcp logout    # revokes that token and removes it from this machine
+```
+
+The token lands in `~/.shotops/credentials.json`, readable only by you, and every later
+`npx shotops-mcp` picks it up — nothing to paste into a client config. It is an ordinary
+ShotOps API token: revoke it any time from Studio → account menu → **API tokens**.
+
+For CI, or to point one client at a different account, pass the token explicitly instead:
 
 ```bash
 SHOTOPS_TOKEN=shotops_… claude mcp add shotops -- npx -y shotops-mcp
 # or: npx shotops-mcp --token shotops_…
 ```
 
+`--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.
+
 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
@@ -411,7 +504,7 @@ 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 (scale-to-zero, /health check) — deploy from repo root
+  fly.toml          Fly app config — ROLLBACK ONLY since the Vercel cutover; see #68
   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

@@ -0,0 +1,156 @@
+Third-Party Notices for shotops-mcp
+
+This file identifies third-party software, font files and 3D models bundled
+directly in the shotops-mcp package. Dependencies installed as separate npm
+packages carry their own license files.
+
+-------------------------------------------------------------------------------
+iPhone 17 Pro 3D model
+-------------------------------------------------------------------------------
+
+"iPhone 17 Pro" by Ranguel (https://sketchfab.com/Ranguel)
+Source: https://sketchfab.com/3d-models/iphone-17-pro-4541aa8a28324b33a2baaf81d263aaec
+Licensed under Creative Commons Attribution 4.0 International (CC BY 4.0):
+https://creativecommons.org/licenses/by/4.0/
+
+The model file bundled here (dist/harness assets) is a converted and optimized
+derivative of that work, produced with glTF-Transform. CC BY 4.0 permits both
+commercial use and redistribution of the model, including in modified form,
+provided the author is credited — which is what this notice is for. Keep it in
+any redistribution of this package.
+
+Apple and iPhone are trademarks of Apple Inc. Google and Pixel are trademarks
+of Google LLC. Neither company sponsors or endorses ShotOps.
+
+-------------------------------------------------------------------------------
+Three.js
+-------------------------------------------------------------------------------
+
+Copyright (c) 2010-2024 three.js authors
+
+The MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+-------------------------------------------------------------------------------
+Bundled caption fonts
+-------------------------------------------------------------------------------
+
+The package includes unmodified, Latin-subset WOFF2 files from these font
+families:
+
+Inter
+Copyright 2020 The Inter Project Authors (https://github.com/rsms/inter)
+
+Manrope
+Copyright 2018 The Manrope Project Authors (https://github.com/sharanda/manrope)
+
+Poppins
+Copyright 2020 The Poppins Project Authors (https://github.com/itfoundry/Poppins)
+
+Fraunces
+Copyright 2018 The Fraunces Project Authors (https://github.com/undercasetype/Fraunces)
+
+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:
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The fonts,
+including any derivative works, can be bundled, embedded, redistributed
+and/or sold with any software provided that any reserved names are not used
+by derivative works. The fonts and derivatives, however, cannot be released
+under any other type of license. The requirement for fonts to remain under
+this license does not apply to any document created using the fonts or their
+derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may include
+source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical writer or
+other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of the Font Software, to use, study, copy, merge, embed, modify, redistribute,
+and sell modified and unmodified copies of the Font Software, subject to the
+following conditions:
+
+1) Neither the Font Software nor any of its individual components, in
+Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy contains
+the above copyright notice and this license. These can be included either as
+stand-alone text files, human-readable headers or in the appropriate
+machine-readable metadata fields within text or binary files as long as those
+fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font Name(s)
+unless explicit written permission is granted by the corresponding Copyright
+Holder. This restriction only applies to the primary font name as presented
+to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any Modified
+Version, except to acknowledge the contribution(s) of the Copyright Holder(s)
+and the Author(s) or with their explicit written permission.
+
+5) The Font Software, modified or unmodified, in part or in whole, must be
+distributed entirely under this license, and must not be distributed under
+any other license. The requirement for fonts to remain under this license
+does not apply to any document created using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF COPYRIGHT, PATENT,
+TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR
+ANY CLAIM, DAMAGES OR OTHER LIABILITY, INCLUDING ANY GENERAL, SPECIAL,
+INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, WHETHER IN AN ACTION OF
+CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF THE USE OR INABILITY TO USE
+THE FONT SOFTWARE OR FROM OTHER DEALINGS IN THE FONT SOFTWARE.