vydanne 0.5.0 → 0.7.0

package/GETTING_STARTED.md

@@ -20,10 +20,10 @@ submit anything for review.
 | vydanne does | You (or your developer) still do |
 |---|---|
 | Write/push the store text in every language | **Create the app record** in App Store Connect / Play Console |
-| Upload screenshots, app previews, Play graphics | **Build and upload the binary** (`.ipa` / `.aab`) |
-| Set age rating, App Review contact, IAP text | Answer **App Privacy** in Apple's web UI (see [step 9](#9-finish-in-the-browser-the-parts-no-api-can-do)) |
-| Generate the US export-compliance PDF | Play **Data Safety** + content-rating questionnaires |
-| Check everything is complete (`preflight`) | **Press Submit for Review** |
+| Upload screenshots, app previews, Play graphics | **Build and sign the binary** (`.ipa` / `.aab`) |
+| Upload that binary to testers (`prerelease`: TestFlight internal / a Play testing track) | Answer **App Privacy** in Apple's web UI (see [step 9](#9-finish-in-the-browser-the-parts-no-api-can-do)) |
+| Set age rating, App Review contact, IAP text | Play **Data Safety** + content-rating questionnaires |
+| Generate the US export-compliance PDF · check everything is complete (`preflight`) | **Press Submit for Review** |
 
 > **It never submits.** That's deliberate — a human should always be the one who ships.
 
@@ -220,14 +220,20 @@ export default {
 | `primaryLocale` | Your main App Store language. Any language you *don't* translate falls back to this, so it must be complete. |
 | `platforms` | `["IOS"]`, or `["IOS", "MAC_OS"]` if you ship a Mac app too. **Mac is a separate listing** — its text is not shared with iOS. |
 | `uiLocales` | Short language codes you publish in. vydanne converts them to Apple's codes (`de` → `de-DE`) and warns about any language the App Store doesn't offer. |
+| `localeMap` | Optional. Your code → Apple's code, for anything the built-in table doesn't cover (`{ "nb": "no" }`). Merged over the defaults, so list only your exceptions. |
 | `metadataDir` | Where your listing text lives. `fastlane/metadata` is the default. |
-| `rating` | Age rating, e.g. `"4+"`. |
+| `screenshots` | Optional. Where your screenshots live, per platform: `{ IOS: "…", MAC_OS: "…" }`. Defaults to `fastlane/screenshots` and `fastlane/screenshots-macos`. |
+| `rating` | Age rating, e.g. `"4+"`. Anything other than `"4+"` also needs `ageRating` below. |
+| `ageRating` | The content descriptors behind a rating above 4+, e.g. `{ violenceCartoonOrFantasy: "INFREQUENT_OR_MILD" }`. Merged over an all-NONE base — Apple computes the band from what you declare. |
+| `reviewContact` | Optional `{ demoAccountRequired }`. By default this is inferred from whether `review_information/demo_user.txt` exists. |
 | `asc` | Optional `{ keyId, issuerId }` — only if you'd rather not use environment variables. |
 | `privacy` | What data actually leaves the device, e.g. `{ collected: ["CRASH_DATA"], tracking: false }`. |
 | `iaps` | Your in-app purchases (name ≤30 chars, description ≤45). |
 | `previews` | App Preview videos — see step 7. |
-| `export` | Export-compliance details for the PDF: `{ encryption: "standard", appName, version, teamId }`. |
-| `google` | The Play block — `{ packageName, metadataDir, defaultLocale }`. Omit it if you're iOS-only. |
+| `export` | Export-compliance details for the PDF: `{ encryption, appName, version, teamId, algorithms, statement, filed }`. `algorithms` and `statement` are **required** when `encryption` is `"standard"` — the command will not invent your cryptography. |
+| `google` | The Play block — `{ packageName, metadataDir, defaultLocale, track, images, imageLocales }`. Omit it if you're iOS-only. |
+| `bridge` | Optional `{ out, apple, play }` — where zdymak wrote, and which of its output folders feed which store slot. Only needed when `dir:` in `zdymak.config.mjs` makes a folder name differ from its target name. |
+| `push` | Optional `{ skip: [...] }` — pipeline steps this app never runs. |
 
 Check your languages resolved correctly:
 
@@ -288,11 +294,16 @@ image is for. Anything after it is yours — but files upload in alphabetical or
 | `watch_` | Apple Watch Ultra |
 | `macos_` | Mac (in `screenshots-macos/`) |
 
-A file whose prefix isn't in that table is **silently skipped** — if a screenshot doesn't appear, check
-the name first.
+A file whose prefix isn't in that table is **not uploaded**, and `fill` says so by name — it lists every
+file it skipped and the prefixes it knows. Same for a folder that isn't an App Store locale code (`de`
+instead of `de-DE`, the classic one): named, not dropped in silence.
 
-> **Screenshots must be RGB PNGs with no transparency.** Simulator captures often have an alpha channel
-> and Apple rejects those. `npx vydanne iap` with `VYDANNE_FLATTEN=path/to.png` converts one for you.
+PNG and JPEG are both accepted.
+
+> **Screenshots must have no transparency.** Simulator captures often carry an alpha channel and Apple
+> rejects those. `npx vydanne bridge` refuses before copying anything if it finds one, and tells you
+> which file; to fix a single image in place, `VYDANNE_FLATTEN=path/to.png npx vydanne iap` converts it
+> to RGB. Note that `fill` itself does **not** convert — flatten at the source.
 
 **Google Play** uses its **own** language codes (`de-DE`, `zh-CN`, `iw-IL`, `ar` — *not* Apple's
 `zh-Hans`/`he`), and only three text files:
@@ -305,8 +316,8 @@ fastlane/metadata/android/
    └─ full_description.txt   (≤4000)
 ```
 
-Play images are read from **fixed paths** (they're where [zdymak](https://www.npmjs.com/package/zdymak)
-writes them). Each is uploaded only if the file exists, so a missing set never wipes what's live:
+Play images are read from **fixed paths**. Each is uploaded only if the file exists, so a missing set
+never wipes what's live:
 
 | Play asset | Path vydanne reads |
 |---|---|
@@ -318,6 +329,12 @@ writes them). Each is uploaded only if the file exists, so a missing set never w
 
 *(These paths are not configurable yet — create the folders at those locations, or symlink them.)*
 
+> **Capturing with [zdymak](https://www.npmjs.com/package/zdymak)?** Its output layout is different
+> from all of the above (one `store-assets/` tree, short locale codes, numbered filenames). Run
+> **`npx vydanne bridge`** after every capture — it renames and files everything into the Apple and
+> Play layouts on this page, holds back screenshots for locales that have no listing text yet, and
+> refuses images with an alpha channel before Apple can. `--dry-run` shows what it would do.
+
 ---
 
 ## 7. Optional extras
@@ -345,40 +362,46 @@ separate ANSSI declaration.
 
 ## 8. Push it to the store
 
-Always look before you leap:
+**Every command that changes a store is a dry run until you add `--apply`** — it prints each write it
+would make and sends nothing. So the safe rhythm is always: run it, read the plan, run it again with
+`--apply`.
+
+The whole Apple release is one command, which runs the seven steps in the only order that works
+(`prepare` → `fill` → `previews` → `age-rating` → `review-contact` → `accessibility` → `preflight`) and
+stops at the first problem:
 
 ```sh
-npx vydanne preflight     # is anything missing or over a character limit?
 npx vydanne diff          # exactly what would change vs what's live now
+npx vydanne push          # DRY RUN of the whole pipeline — read it
+npx vydanne push --apply  # do it; ends at a green preflight
+npx vydanne privacy       # prints the answers to type into Apple's web UI
 ```
 
-`preflight` must be **green**. Then:
+Each step is also its own command (`npx vydanne fill --apply`, etc.) if you prefer to go one at a time.
+Two things worth knowing:
 
-```sh
-npx vydanne fill          # text + screenshots (iOS and Mac both)
-npx vydanne previews      # App Preview videos
-npx vydanne age-rating
-npx vydanne review-contact
-npx vydanne accessibility # saved as a draft; publishes only once your app is live
-npx vydanne privacy       # prints the answers to type into Apple's web UI
-```
+- **Updating an app that's already live?** The draft version to write into doesn't exist until
+  `prepare` creates it — `push` runs it first, or run `npx vydanne prepare --apply` yourself. Without
+  it, `fill` refuses rather than touching the listing your customers are reading.
+- **Replacing screenshots or previews that are already on the store** needs `VYDANNE_REPLACE=1` — by
+  default a populated slot is skipped (and says so), never overwritten.
 
-**For Google Play**, `fill` is a **dry run by default** — it validates and throws the change away so a
-half-finished local folder can't overwrite your live listing:
+**For Google Play**, the same `--apply` rule applies — a dry run validates against Google for real,
+then throws the change away, so a half-finished local folder can't overwrite your live listing:
 
 ```sh
 # macOS / Linux
-npx vydanne fill --store google                    # dry run: shows what would happen
-VYDANNE_COMMIT=1 npx vydanne fill --store google   # actually commit it
+npx vydanne fill --store google            # dry run: shows what would happen
+npx vydanne fill --store google --apply    # actually commit it
 ```
 ```powershell
-# Windows PowerShell — set the variable first; the `VAR=1 command` form does NOT work here
+# Windows PowerShell — same flag, no environment variables needed
 npx vydanne fill --store google
-$env:VYDANNE_COMMIT = "1"; npx vydanne fill --store google
-Remove-Item Env:\VYDANNE_COMMIT          # clear it so later runs stay dry
+npx vydanne fill --store google --apply
 ```
 
-Finally, run `npx vydanne diff` once more and eyeball one screenshot per platform in the web UI.
+Finally, run `npx vydanne diff` once more — it compares text *and* image content against the store —
+and eyeball one screenshot per platform in the web UI.
 
 ---
 
@@ -386,7 +409,9 @@ Finally, run `npx vydanne diff` once more and eyeball one screenshot per platfor
 
 1. **App Privacy** (Apple) — Apple's privacy API isn't reachable with an API key, so `vydanne privacy`
    prints the exact answers; you paste them into App Store Connect by hand.
-2. **Upload the binary** — Xcode, Transporter, or your CI. vydanne never touches your build.
+2. **Build the binary** — Xcode / Gradle, as usual. `npx vydanne prerelease --apply` can then upload it
+   for you (TestFlight internal groups, or a Play testing track). Shipping it to the *public* stays in
+   the consoles, always.
 3. **Play Data Safety + content rating** — questionnaires in the Play Console.
 4. **Submit for Review** — yours to press.
 
@@ -400,13 +425,13 @@ Finally, run `npx vydanne diff` once more and eyeball one screenshot per platfor
 | `ASC key not found at …` | The `.p8` isn't where vydanne looks. | The error prints the exact path it wants — move the file there. List it with `ls ~/.appstoreconnect/private_keys/` (macOS/Linux) or `dir "$env:USERPROFILE\.appstoreconnect\private_keys"` (Windows). |
 | `app '…' not found for this ASC key` | The bundle ID is wrong, or the key's team doesn't own the app. | Check `bundleId` matches App Store Connect exactly. |
 | `401` / `403` from Apple | Key lacks permission, or the IDs are swapped. | Key access must be **App Manager**+. Confirm `ASC_KEY_ID` vs `ASC_ISSUER_ID` aren't reversed. |
-| `no editable version` | There's no version in an editable state. | In App Store Connect, create the next version (e.g. "1.0 Prepare for Submission"). |
+| `no editable version` | The only version is live (read-only) and no draft exists yet. | `npx vydanne prepare --apply` creates the next version — that's its job. |
 | A locale was ignored | The folder name isn't an Apple code. | Run `npx vydanne locales` and rename the folder to the code shown. |
-| Screenshots didn't upload | Wrong filename prefix, or the slot already has images. | Use the prefix table above. vydanne never overwrites a set that already has screenshots. |
-| Apple rejects a screenshot | It has an alpha channel. | Flatten to RGB — macOS/Linux: `VYDANNE_FLATTEN=shot.png npx vydanne iap` · Windows: `$env:VYDANNE_FLATTEN="shot.png"; npx vydanne iap`. |
-| `VYDANNE_… =1` "does nothing" on Windows | PowerShell doesn't support the Unix `VAR=1 command` form. | Set it first: `$env:VYDANNE_COMMIT = "1"`, then run the command. |
+| Screenshots didn't upload | Wrong filename prefix, or the slot already has images. | `fill` now names both cases in its output. Use the prefix table above; to replace an already-populated slot, re-run with `VYDANNE_REPLACE=1`. |
+| Apple rejects a screenshot | It has an alpha channel. | Flatten to RGB — macOS/Linux: `VYDANNE_FLATTEN=shot.png npx vydanne iap` · Windows: `$env:VYDANNE_FLATTEN="shot.png"; npx vydanne iap`. (`bridge` checks this for you.) |
+| `VYDANNE_… =1` "does nothing" on Windows | PowerShell doesn't support the Unix `VAR=1 command` form. | Set it first: `$env:VYDANNE_REPLACE = "1"`, then run the command. |
 | `no google block in config` | Play isn't configured. | Add the `google` block and set `PLAY_JSON_KEY_FILE`. |
-| Play changes didn't stick | `fill --store google` is dry by default. | Re-run with `VYDANNE_COMMIT=1`. |
+| Play changes didn't stick | Store-changing commands are dry by default. | Re-run with `--apply`. |
 | `accessibility` returns 409 | Labels can't publish before the app is live. | Leave it as a draft; publish after launch with `VYDANNE_A11Y_PUBLISH=1`. |
 
 ---
@@ -419,10 +444,14 @@ Finally, run `npx vydanne diff` once more and eyeball one screenshot per platfor
 | `PLAY_JSON_KEY_FILE` | Path to the Play service-account JSON (**required for Play**). |
 | `VYDANNE_CONFIG` | Use a different config file (same as `--config`). |
 | `VYDANNE_SKIP_METADATA` / `VYDANNE_SKIP_SCREENSHOTS` | `fill`: push only one half. |
-| `VYDANNE_COMMIT=1` | `fill --store google`: actually commit (otherwise dry). |
-| `VYDANNE_REPLACE=1` | `previews`: delete the existing preview and upload a new one. |
+| `VYDANNE_REPLACE=1` | `fill` / `previews`: delete what's in an already-populated slot and upload yours. |
+| `VYDANNE_VERSION=<x>` | `prepare`: name the version when it's created before its build exists. |
+| `VYDANNE_IPA=<path>` / `VYDANNE_AAB=<path>` | `prerelease`: override where the binary is found. |
+| `VYDANNE_TRACK` / `VYDANNE_RELEASE_NAME` | `prerelease --store google`: testing track / release name. |
 | `VYDANNE_FLATTEN=<png>` | `iap`: convert an image to RGB (removes transparency). |
 | `VYDANNE_A11Y_PUBLISH=1` | `accessibility`: publish the labels (only once the app is live). |
+| `VYDANNE_ALLOW_CROSS_STORE=1` | Skip the other-store-mention check for one run. |
+| `VYDANNE_COMMIT=1` | Legacy alias for `--apply` — prefer the flag. |
 
 Set them with `export NAME=value` on macOS/Linux, or `$env:NAME = "value"` in Windows PowerShell.
 

package/README.md

@@ -1,5 +1,11 @@
 # vydanne
 
+[![npm version](https://img.shields.io/npm/v/vydanne.svg)](https://www.npmjs.com/package/vydanne)
+[![npm downloads](https://img.shields.io/npm/dm/vydanne.svg)](https://www.npmjs.com/package/vydanne)
+[![node](https://img.shields.io/node/v/vydanne.svg)](https://nodejs.org)
+[![license](https://img.shields.io/npm/l/vydanne.svg)](LICENSE)
+[![companion: zdymak](https://img.shields.io/badge/companion-zdymak-6e40c9?logo=github)](https://github.com/Lonli-Lokli/zdymak)
+
 **Fill in your app's App Store and Google Play listing — in every language — from files on your computer.**
 
 Publishing an app means typing the same things into a web form over and over: a name, a subtitle, a
@@ -7,7 +13,9 @@ description, keywords, screenshots… once per language, twice per store, again
 box and the store quietly shows a blank page to half the world. Get a folder name wrong and the whole
 upload fails.
 
-vydanne does that typing for you, then **checks your work before Apple or Google does**.
+vydanne does that typing for you, then **checks your work before Apple or Google does** — and puts
+your build in front of testers on both stores. It stops at the one step that should stay a human's:
+it never submits for review, and never ships to the public.
 
 > *выданне* (Belarusian) — "publishing".
 
@@ -27,15 +35,19 @@ actual app. vydanne handles the *listing*, not the software.
 
 ## The two halves of a release
 
-vydanne has a sibling — **[zdymak](https://www.npmjs.com/package/zdymak)**. They split the job cleanly:
+vydanne has a sibling — **[zdymak](https://github.com/Lonli-Lokli/zdymak)**. They split the job cleanly:
 
 | | [zdymak](https://github.com/Lonli-Lokli/zdymak) 📸 | **vydanne** 📝 |
 |---|---|---|
 | Makes | The **pictures** — screenshots, App Preview videos, the Play feature graphic | The **words and the paperwork** — listing text, ratings, contacts, privacy, compliance |
 | Ends with | Image and video files on disk | A listing filled in and verified, ready for a human to submit |
 
-Use them together: zdymak produces the assets, vydanne uploads them alongside your text. Use vydanne
-alone if you already have your screenshots.
+Use them together: zdymak produces the assets, **`npx vydanne bridge`** moves them to where vydanne
+reads (zdymak writes one `store-assets/` tree with short locale codes and numbered files; vydanne reads
+`fastlane/screenshots/<Apple-locale>/` with device-prefixed names, and fixed `marketing/out/` paths for
+Play), and `fill` uploads them alongside your text. Run `bridge` after every capture — skipping it means
+`fill` quietly re-uploads whatever was bridged last time. Use vydanne alone if you already have your
+screenshots in its layout.
 
 <br>
 
@@ -141,6 +153,19 @@ export default {
 };
 ```
 
+Every field is optional except `bundleId` and `primaryLocale`. The ones you reach for next:
+
+| Field | What it's for |
+|---|---|
+| `screenshots` | Where your screenshots live, per platform. Defaults to `fastlane/screenshots` + `fastlane/screenshots-macos`. |
+| `localeMap` | Your language codes → Apple's, for anything the built-in table misses (`{ nb: "no" }`). |
+| `ageRating` | The content descriptors behind any rating above `4+`. Apple computes the band from them. |
+| `reviewContact` | `{ demoAccountRequired }` — otherwise inferred from whether `review_information/demo_user.txt` exists. |
+| `export` | Export-compliance details. `algorithms` + `statement` are required for `encryption: "standard"`. |
+| `bridge` | `{ out, apple, play }` — which zdymak output folder feeds which store slot, when `dir:` overrides make them differ. |
+| `push` | `{ skip: [...] }` — pipeline steps this app never runs. |
+| `google` | The Play block, including `track`, `images` and `imageLocales`. |
+
 **3. Write your listing** as plain text files, one folder per language:
 
 ```
@@ -155,33 +180,111 @@ fastlane/metadata/en-US/keywords.txt
 ```sh
 npx vydanne preflight     # anything missing or too long?
 npx vydanne diff          # what exactly would change?
-npx vydanne fill          # do it
+npx vydanne fill          # DRY RUN — prints every write it would make
+npx vydanne fill --apply  # do it
 ```
 
 Run vydanne **from your project folder** — it finds everything relative to where you are.
 
 <br>
 
+## `--apply`, or nothing happens
+
+**Every command that can change a store is a dry run unless you pass `--apply`.** It reads the store,
+prints each write it would make, and sends nothing:
+
+```
+DRY RUN — 'fill' will not change App Store Connect. Add --apply to write.
+      would PATCH /v1/appStoreVersionLocalizations/ad2f… — description, keywords, whatsNew
+      …
+DRY RUN — 40 store write(s) withheld. Re-run with --apply to perform them.
+```
+
+The commands this applies to are marked `✎` in the usage text (`vydanne` with no arguments): `prepare`, `push`, `fill`, `previews`,
+`age-rating`, `review-contact`, `accessibility`, `prerelease`. Everything else only reads, and ignores
+the flag.
+
+Two details worth knowing:
+
+- **A dry run walks the whole plan.** It does not stop at the first locale — the count at the end is the
+  number to compare against `diff`. "Nothing to write" and "nothing happened" are different sentences, and
+  only the first one means your local files already match the store.
+- **The two stores enforce it differently, deliberately.** Play builds the Edit and *validates it against
+  Google* for real, then discards it — so a dry run catches everything a commit would have caught. Apple
+  has no transaction to roll back, so there the block is at the HTTP layer: no `POST`/`PATCH`/`PUT`/
+  `DELETE` leaves the process at all. `prerelease` also refuses the `altool` upload, after validating the
+  archive.
+
+> Upgrading from ≤ 0.5? The Apple half used to write immediately — `vydanne fill` now needs `--apply`.
+> `VYDANNE_COMMIT=1` still works as an alias so existing Play scripts keep running, but prefer the flag.
+
+<br>
+
 ## What each command does
 
 | Command | In plain English |
 |---|---|
-| `preflight` | **Run this first.** Checks the listing is complete and nothing is over a character limit. Green means submittable. |
+| `preflight` | **Run this first.** Checks the listing is complete, nothing is over a character limit, no locale mentions the other app store — and that the screenshots on the store are your *current* ones, not a stale set. Green means submittable. |
+| `prepare` | Starts the next release: creates the App Store version you're preparing and attaches your newest build to it. **Needed before `fill` on an app that already has a version on sale** — until a draft exists there is nothing for the listing text to go into. Reuses the draft if it's already there, so it's safe to re-run. It does *not* submit. |
+| `push` | **The whole release, one command**: runs `prepare` → `fill` → `previews` → `age-rating` → `review-contact` → `accessibility` → `preflight`, in that order, stopping at the first failure. Dry run without `--apply`, like everything else. Ends at a green preflight — it never submits. |
 | `diff` | Shows exactly what's different between your files and what's live. Nothing is changed — a safe preview. |
-| `fill` | Uploads your listing text and screenshots. Handles iPhone, iPad and Mac. |
+| `fill` | Uploads your listing text and screenshots. Handles iPhone, iPad and Mac. Refuses to upload text that names the other mobile platform. |
 | `previews` | Uploads App Preview videos. |
 | `inspect` | Shows the app's current state in the store. Read-only. |
 | `locales` | Lists your languages and Apple's code for each — and warns about any language the App Store doesn't offer. |
-| `age-rating` | Sets the age rating. |
+| `age-rating` | Sets the age rating. `rating: "4+"` needs nothing else; any higher rating is described feature-by-feature in `ageRating` and Apple computes the band from it. |
 | `review-contact` | Fills in the App Review contact details (who Apple calls if there's a problem). |
 | `accessibility` | Saves Accessibility Nutrition Labels from the `accessibility` block in your config. Stays a draft until your app is live. Refuses to run if you have not declared one — see below. |
 | `privacy` | Prints the privacy answers to paste into Apple's website (Apple's privacy section has no API). |
 | `iap` | Checks your in-app purchase text fits, and can strip transparency from an image. |
 | `compliance` | Generates the US encryption self-classification PDF that Apple asks for. |
+| `bridge` | Moves [zdymak](https://github.com/Lonli-Lokli/zdymak)'s captured screenshots into the folders `fill` reads — renaming locales to the stores' codes and files to the device-slot convention. Local files only; `--dry-run` previews. Run it after every capture. |
 | `version` | Prints the version of vydanne. |
 
 For **Google Play**, add `--store google` to `inspect`, `diff`, `preflight`, `fill`, or `prerelease`.
 
+`prepare`, `push`, `fill`, `previews`, `age-rating`, `review-contact`, `accessibility` and `prerelease`
+change the store, so they need [`--apply`](#--apply-or-nothing-happens); without it they report and exit.
+
+## The release pipeline — the order matters
+
+A release is the same seven steps in the same order, every time. `prepare` must come first (until the
+draft version exists, nothing has anywhere to write) and `preflight` must come last (green has to be
+measured *after* the writes it blesses, or it blesses nothing). That ordering is exactly the kind of
+thing that lives in someone's head until the day it doesn't — so `push` runs it for you, stopping at the
+first failure, and each step's own refusals still apply:
+
+```sh
+npx vydanne prerelease --apply    # whenever the build is ready — before or after push is fine
+npx vydanne push                  # DRY RUN of the whole pipeline: read the plan
+npx vydanne push --apply          # do it: prepare → fill → previews → age-rating
+                                  #        → review-contact → accessibility → preflight
+# then, in App Store Connect: Add to Review -> Submit  (always you, never vydanne)
+```
+
+The two flows differ only at the first step, and `push` absorbs the difference:
+
+- **First release.** Creating the app record in App Store Connect already gave you a version in *Prepare
+  for Submission*, so `prepare` finds it and reuses it — a no-op that simply reports what's there.
+- **An update to a live app.** A version on sale is read-only and there is no draft until someone makes
+  one. Here `prepare` is the step that matters: it creates the next version (numbered from the newest
+  build's own `CFBundleShortVersionString`, so it can't drift from the binary) and attaches that build.
+
+Skip `prepare` on a live app and `fill` has nowhere valid to aim — it refuses, rather than falling back
+to the version **on sale** and rewriting the listing your customers are reading.
+
+One wrinkle worth knowing: on a live app, a *dry run* of `push` stops at `fill`, because the draft the
+later steps write into doesn't exist until `prepare` is applied. `push` says so up front. Creating the
+draft is safe — it isn't a submission — so `vydanne prepare --apply` first, then a dry `push`, previews
+the whole plan. Preparing a version before its build exists is the one case that needs telling:
+
+```sh
+VYDANNE_VERSION=1.2 npx vydanne prepare --apply
+```
+
+Prefer doing it step by step? Every step is its own command (the table above), and `push` is nothing
+more than those commands in the right order.
+
 <br>
 
 ## Google Play
@@ -191,9 +294,8 @@ Add a `google` block to your config and point `PLAY_JSON_KEY_FILE` at a service-
 
 ```sh
 npx vydanne preflight --store google
-npx vydanne fill --store google                    # dry run — shows what would change
-VYDANNE_COMMIT=1 npx vydanne fill --store google   # actually do it
-#   Windows PowerShell:  $env:VYDANNE_COMMIT = "1"; npx vydanne fill --store google
+npx vydanne fill --store google           # dry run — shows what would change
+npx vydanne fill --store google --apply   # actually do it
 ```
 
 ### `prerelease` — the build, to testers
@@ -244,8 +346,8 @@ a paid app they are the testers who install without buying it.
 **Google Play — a closed track**
 
 ```sh
-npx vydanne prerelease --store google                    # dry run
-VYDANNE_COMMIT=1 npx vydanne prerelease --store google   # publish to the track
+npx vydanne prerelease --store google           # dry run
+npx vydanne prerelease --store google --apply   # publish to the track
 ```
 
 ```js
@@ -263,13 +365,22 @@ the same line the Apple side draws by never submitting.
 **Paid app? Use `internal`.** It is the only track where testers install without buying; closed and open
 testers pay like everyone else.
 
-Release notes follow supply's layout, so an existing repo needs no migration —
-`<metadataDir>/<play-locale>/changelogs/<versionCode>.txt`, falling back to `default.txt`, truncated to
-Play's 500-char cap with a warning. The versionCode comes from the bundle's own manifest, so build
-numbering stays with the build and re-uploading a used code fails loudly instead of silently replacing a
-binary. Overrides: `VYDANNE_AAB`, `VYDANNE_TRACK`, `VYDANNE_RELEASE_NAME`.
+Release notes follow supply's layout, so an existing repo needs no migration — per locale, first match
+wins:
+
+| File in `<metadataDir>/<play-locale>/changelogs/` | When to use it |
+|---|---|
+| `<versionCode>.txt` | You know the exact code (supply's own convention). |
+| `next.txt` | **The notes for the release you're about to cut** — for when the versionCode isn't knowable in advance (e.g. it's derived from the git commit count, so every commit moves it). After a real (`--apply`) publish, vydanne renames it to `<versionCode>.txt`, so the *next* release can't inherit this one's notes by accident. |
+| `default.txt` | Evergreen fallback ("bug fixes and improvements"). Falling back to it is **warned**, because notes written for one release quietly serving every later one is how a listing shows last release's news. |
+
+Notes are truncated to Play's 500-char cap with a warning. The versionCode comes from the bundle's own
+manifest — vydanne reads it out of the `.aab` locally and reports which changelog file each locale
+resolves to *before* the upload, so a wrong file costs a re-run, not a re-release. Re-uploading a used
+code fails loudly instead of silently replacing a binary. Overrides: `VYDANNE_AAB`, `VYDANNE_TRACK`,
+`VYDANNE_RELEASE_NAME`.
 
-**Play is dry by default on purpose.** Nothing goes live until you add `VYDANNE_COMMIT=1`, so a
+**Play is dry by default on purpose.** Nothing goes live until you add `--apply`, so a
 half-finished folder can never overwrite a good listing. Play also uses its **own** language codes
 (`zh-CN`, `iw-IL`) which are *not* Apple's — `vydanne locales` and the
 [layout guide](GETTING_STARTED.md#6-put-your-text-and-images-where-vydanne-looks) keep them straight.
@@ -300,9 +411,10 @@ don't have to learn them the hard way.
 | Your main language is left empty → most of the world sees a blank page | `preflight` refuses to pass |
 | macOS is a **separate** listing; its text is not shared with iOS | Fills each platform independently |
 | Apple's list endpoints return blank text, so tools "see" an empty listing | Reads each language individually |
-| Screenshots with transparency get rejected | Converts them to RGB |
+| Screenshots with transparency get rejected | `bridge` refuses before copying and names the files; `VYDANNE_FLATTEN` converts one |
 | Once a version is *Ready for Review*, most tools can no longer edit it | Uses a method that still works |
-| Character limits (30 / 30 / 100 / 170; purchases 30 / 45) | Checked before upload, not after rejection |
+| Character limits (name/subtitle 30, keywords 100, promo 170; purchases 30 / 45) | All checked by `preflight` before upload, not after rejection |
+| One translation says "also on Google Play" → rejected under guideline 2.3.10 | Every locale is scanned before upload; `preflight` and `fill` both refuse |
 | Apple's privacy section can't be reached by any API key | Prints the exact answers to paste in |
 | Accessibility labels can't publish before launch | Saved as a draft automatically |
 | In-app purchases need **two** different images, easily confused | Labels both slots |
@@ -313,8 +425,12 @@ don't have to learn them the hard way.
 
 ## What vydanne will never do
 
-- **It never submits your app.** A human attaches the build and presses Submit. That's on purpose.
-- It doesn't build, sign, or upload your app binary.
+- **It never submits for review, and never ships to the public.** It *will* put a build in front of
+  your testers — TestFlight internal, or a Play closed track — and point the version you are
+  preparing at it. Pressing Submit, promoting to Play production, and distributing to external
+  TestFlight (which needs Beta App Review) all stay yours. Those are refusals, not flags: there is
+  no argument combination that reaches the public.
+- It doesn't build or sign your binary. It uploads the `.ipa` / `.aab` you already produced.
 - It doesn't create the app record — make that in App Store Connect / Play Console first.
 
 <br>
@@ -337,6 +453,28 @@ Releasing a new version: [RELEASING.md](RELEASING.md).
 MIT.
 
 
+### One store never mentions the other
+
+Both stores reject a listing that advertises the competing platform — Apple under App Review
+guideline **2.3.10** ("no names, icons, or imagery of other mobile platforms"), Google under its
+Store Listing and Promotion policy. It is an easy mistake to make and an expensive one to find: the
+two listings come from the same source copy, so a single translator writing "auch für Android"
+costs a review cycle, in one locale out of twenty, days later.
+
+`preflight` and `fill` both scan the local metadata before anything is uploaded, per locale, per
+field — store names, store URLs, and the other platform's device names, in Latin script and in the
+localized forms (安卓, Андроид, アンドロイド, …). A store's OWN platform is never flagged: "Android"
+belongs in a Play listing. Neither does the bare word "Play", which every game listing uses.
+
+Ambiguous words ("apple" in a game about fruit) are reported as warnings and never block. If one
+genuinely belongs in your copy:
+
+```js
+allowCrossStoreTerms: ["Apple"],
+```
+
+`VYDANNE_ALLOW_CROSS_STORE=1` overrides the whole check for one run.
+
 ### Accessibility Nutrition Labels
 
 Every other thing vydanne writes is a *fact* about your app. This one is a **claim about its