shotops-mcp 0.6.1 → 0.8.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

@@ -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)* |
 | `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,7 +76,9 @@ 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
@@ -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`,
@@ -256,7 +284,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.
@@ -294,7 +322,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 +350,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_…"
 ```
 
@@ -351,7 +379,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.dev/mcp <a-real-shotops_-token>
+  node verify-mcp.mjs https://mcp.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`.
@@ -382,12 +410,12 @@ since this repo is private.
   can take 60-110s before the CPU fix, and network/Supabase round trips add more on `urls`
   output.
 
-## Local (free tier) — `npx shotops-mcp`
+## 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 +438,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,31 +458,160 @@ 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 |
-| 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
 
-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.** 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:
+Connect your account and `save_project` / `read_look` / `save_look` / `read_project` /
+`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.
+
+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.
+
+### 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 create, update, clear,
+replacement, upload, attachment, and no-op, plus a portable `release-review.zip` containing that
+exact canonical plan and its content-addressed screenshot bytes. The plan expires after 15 minutes
+and hash-binds the project revision, desired bytes, normalized Fastlane inputs, Apple setup identity,
+policy version, and the complete remote snapshot so later approval cannot drift onto different state.
+
+`release-plan-envelope.json` is the separate redacted form safe for a later ShotOps coordination
+step: it carries identifiers and value hashes, never metadata values, review credentials, local
+paths, Apple credentials, or asset bytes. 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 unexpired 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, expiry, complete or partial scope, every before/after/clear,
+build, review, rating, compliance, preview, screenshot order/replacement/omission, no-op, 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; expired, 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
@@ -480,7 +642,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)

package/THIRD_PARTY_NOTICES

@@ -0,0 +1,157 @@
+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:
+https://openfontlicense.org/open-font-license-official-text/
+
+-----------------------------------------------------------
+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.