vydanne 0.6.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
@@ -29,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>
 
@@ -143,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:
 
 ```
@@ -177,8 +200,9 @@ DRY RUN — 'fill' will not change App Store Connect. Add --apply to write.
 DRY RUN — 40 store write(s) withheld. Re-run with --apply to perform them.
 ```
 
-The commands this applies to are marked `✎` in `vydanne help`: `fill`, `previews`, `age-rating`,
-`review-contact`, `accessibility`, `prerelease`. Everything else only reads, and ignores the flag.
+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:
 
@@ -200,24 +224,66 @@ Two details worth knowing:
 
 | Command | In plain English |
 |---|---|
-| `preflight` | **Run this first.** Checks the listing is complete, nothing is over a character limit, and no locale mentions the other app store. 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. 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`.
 
-`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.
+`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>
 
@@ -299,11 +365,20 @@ 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 `--apply`, so a
 half-finished folder can never overwrite a good listing. Play also uses its **own** language codes
@@ -336,9 +411,9 @@ 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 |

package/SKILL.md

@@ -11,8 +11,12 @@ fastlane/Ruby/Python. Two jobs: **(A) write the listing well (ASO)**, **(B) push
 **Companion tool — [zdymak](https://www.npmjs.com/package/zdymak)** makes the *media* (screenshots, App
 Preview videos, Play feature graphic); vydanne pushes that media plus all the *text and paperwork*. If the
 user needs screenshots or a preview video produced, that's zdymak's job, not vydanne's — vydanne only
-uploads files that already exist. zdymak's default output paths are exactly the paths vydanne reads for
-Play images (below), so the two line up with no glue.
+uploads files that already exist. **The two do NOT line up on disk** (they did before zdymak 0.15):
+zdymak writes one root shaped `store-assets/<locale>/<target>/NN-name.png`, while vydanne reads several
+hardcoded roots, with Apple's locale codes and a device-prefix filename convention. **`vydanne bridge`
+is the glue** — run it after `zdymak screenshots`/`zdymak build` and before `fill`, every time.
+Skipping it is silent and dangerous: zdymak reports success, vydanne re-uploads whatever was bridged
+LAST time, and the store quietly keeps stale art.
 
 **Never submits for review; never ships to the public.** It *does* upload builds — `prerelease` sends
 the `.ipa` to TestFlight (internal groups) or the `.aab` to a Play closed track, and points the version
@@ -51,8 +55,30 @@ which user file was used, and whether the `.p8` is on disk.
 
 **Config fields:** `bundleId` · `primaryLocale` (the fallback — must be populated) · `asc` (optional
 `{profile}` — selection only, never secrets) · `platforms` (iOS and macOS are SEPARATE) · `uiLocales`
-(auto-mapped to ASC codes) · `metadataDir` · `rating` · `privacy` · `iaps` · `previews` · `export` ·
-`google` (Google Play).
+(auto-mapped to ASC codes) · `localeMap` · `metadataDir` · `screenshots` · `rating` · `ageRating` ·
+`privacy` · `iaps` · `previews` · `export` · `accessibility` · `ios` · `google` (Google Play) ·
+`bridge` · `push` · `reviewContact` · `allowCrossStoreTerms`.
+
+**Paths are defaults, not laws.** `metadataDir` (default `fastlane/metadata`), `screenshots`
+(`{IOS, MAC_OS}`, default `fastlane/screenshots` + `-macos`) and `google.images` (Play image type →
+local path) all follow fastlane's supply convention out of the box and are all overridable. Point them
+at the repo you have rather than reshaping the repo around the tool.
+
+**Four blocks the tool will NOT fill in for you.** Each publishes a CLAIM rather than a fact, so silence
+is refused instead of defaulted — that is deliberate, and re-adding a default is the bug, not the fix:
+
+- **`accessibility`** — Accessibility Nutrition Labels. Declare every feature true/false from what was
+  actually verified. No block → the command errors.
+- **`export.algorithms` + `export.statement`** — the cryptography inventory and statement in the US
+  export-compliance PDF (`compliance`). Required when `export.encryption` is `"standard"`. Never invent
+  these; ask what the app actually ships. `export.filed` stays **false** until the report has really
+  been emailed to BIS and the NSA, and while it is false the PDF does not claim it was submitted.
+- **`ageRating`** — needed for any `rating` above `"4+"`. Describe the CONTENT
+  (`{ violenceCartoonOrFantasy: "INFREQUENT_OR_MILD" }`, merged over an all-NONE base); Apple computes
+  the band. `"4+"` alone needs nothing else.
+- **`reviewContact` / demo account** — whether App Review needs a login is inferred from
+  `<metadataDir>/review_information/demo_user.txt` + `demo_password.txt` (both gitignored). An app with
+  a sign-in wall and no demo account is a guaranteed rejection.
 
 For a non-technical user asking how to set this up from scratch, walk them through
 **`GETTING_STARTED.md`** (accounts → API key → config → folders → push) rather than improvising.
@@ -94,17 +120,38 @@ before the **first underscore** selects the device slot; files upload in sorted
 | `watch_` | `APP_WATCH_ULTRA` |
 | `macos_` | `APP_DESKTOP` (in `screenshots-macos/`) |
 
-An unknown prefix is silently ignored. A set that **already has screenshots is skipped**, never
-duplicated — to replace shots, delete them in ASC first. PNGs must be **RGB with no alpha**.
+A file with an unknown prefix is not uploaded, and `fill` names it. A set that **already has
+screenshots is skipped** (and says so), never duplicated — `VYDANNE_REPLACE=1` deletes the store's set
+and uploads yours, the same flag `previews` uses. PNGs must be **RGB with no alpha**.
 
 **Play listing text** — `<google.metadataDir>/<PLAY-locale>/{title,short_description,full_description}.txt`
 (30 / 80 / 4000). Play uses its **own** codes (`de-DE`, `zh-CN`, `iw-IL`, `ar`, `be`) — *not* Apple's
 `zh-Hans`/`he`/`ar-SA`.
 
-**Play images** — hardcoded source paths (zdymak's output), each pushed only when the file exists, so a
-missing local set never deletes the live one: `brand/icons/play/icon-512.png` (512²) ·
-`marketing/out/play-feature-graphic.png` (1024×500) · `marketing/out/play-phone-plain/` ·
-`marketing/out/play-tablet7-plain/` (7″) · `marketing/out/play-tablet-plain/` (10″).
+**Play images** — DEFAULT source paths (override any of them with `google.images`), each pushed only
+when the file exists, so a missing local set never deletes the live one:
+`brand/icons/play/icon-512.png` (512², from znachok) · `marketing/out/play-feature-graphic.png`
+(1024×500) · `marketing/out/play-phone-plain/` · `marketing/out/play-tablet7-plain/` (7″) ·
+`marketing/out/play-tablet-plain/` (10″) · `marketing/out/play-wear/`. `wearScreenshots`, `tvScreenshots`
+and `tvBanner` are also understood, so a Wear OS or Android TV release is a config line, not a code
+change. An image dir that exists but is EMPTY is reported (by `fill` and `diff`) as a live set only
+Play Console can remove.
+
+Play holds graphics **per language**. The default uploads one untranslated set at
+`google.defaultLocale`; `google.imageLocales` (a list, or `"*"` for every local listing folder) opts
+into localized art, and a `<source>/<lang>/` subdirectory overrides the shared source for that language.
+`diff --store google` compares exactly the locales `fill` would write, so the two never disagree.
+
+**`bridge` populates both screenshot layouts from zdymak's output.** It maps
+`store-assets/<locale>/<dir>/NN-name.png` onto the Apple and Play paths above: locale codes via the
+same `toAsc` table `fill` uses (`de` → `de-DE`; a code with no App Store language is skipped and falls
+back to the primary listing), the device-slot prefix prepended (`iphone69_01-fresh.png`), and the Play
+sets into their configured destinations. A locale with screenshots but NO listing text is held back
+(uploading pictures alone would create the localization and break its fallback to the primary
+language), and every bridged image is checked for an alpha channel — which Apple rejects — on the
+SOURCE, before anything is copied, so a refusal leaves the destinations untouched and `--dry-run`
+catches it too. Local files only; `--dry-run` previews what would be written *and removed*. See the
+directory-vs-target note under Commands for why the source folder name is the thing that matters.
 
 ## A. Writing the listing (the ASO craft — the durable value)
 
@@ -165,8 +212,20 @@ who it's for → honest close. Keep it scannable; lead each bullet with the payo
 `fill` (metadata + screenshots, native PATCH/chunked upload — works even at READY_FOR_REVIEW) ·
 `previews` (App Preview videos) · `age-rating` · `review-contact` · `accessibility` (draft; publish once
 live) · `privacy` (prints answers for the UI — the API can't reach Apple's iris host) · `iap` (validate +
-RGB flatten) · `compliance` (US self-classification PDF) · `diff` (what differs vs live) · `preflight`
-(completeness gate + cross-store lint) · `inspect` · `auth` (what credentials resolved, and from where) · `locales` · `version`.
+RGB flatten) · `compliance` (US self-classification PDF) · `bridge` (zdymak's output → the folders
+`fill` reads) · `diff` (what differs vs live, text AND media by checksum) · `preflight`
+(completeness gate + cross-store lint + stale-screenshot check) · `inspect` · `auth` (what credentials
+resolved, and from where) · `locales` · `version`.
+
+**`bridge` maps by DIRECTORY, not by target.** zdymak writes each shot to `<dir || target>`, so a
+`dir:` override makes the folder name differ from the target name — and Play's 7" slot can *only* exist
+that way (`{ target: 'play-tablet', dir: 'play-tablet7-plain' }`; there is no `play-tablet7` target).
+Defaults prefer the `-plain` convention Google asks for on listings and fall back to the bare target
+name; `bridge.apple` / `bridge.play` override per slot. It **owns its destinations per store**: any
+Apple output means both Apple roots are rebuilt (so art dropped upstream stops being uploaded), while
+an app that bridges only Play never has its hand-managed Apple screenshots touched. It plans before it
+writes — a failure (alpha channel, empty source) leaves every destination untouched, and `--dry-run`
+reports exactly what a real run would write *and remove*.
 
 **Cross-store lint.** `preflight` and `fill` refuse listing text that names the other mobile platform
 — App Review 2.3.10 for Apple, the Store Listing and Promotion policy for Google — scanning every
@@ -176,6 +235,43 @@ blocking; `allowCrossStoreTerms: [...]` in the config silences a specific one, a
 `VYDANNE_ALLOW_CROSS_STORE=1` overrides a single run. This is a rejection that surfaces days later in
 one locale out of twenty, so it is checked where it is free to fix.
 
+**The pipeline has ONE working order** — `prepare` → `fill` → `previews` → `age-rating` →
+`review-contact` → `accessibility` → `preflight` → **a human submits**. `prepare` must be first (until
+the draft version exists, nothing has anywhere to write) and `preflight` last (green must be measured
+after the writes it blesses). `push` runs exactly that sequence — each step the same `run` as the
+standalone command, on the same client, stopping at the first failure — so prefer `vydanne push` over
+re-deriving the order; the near-miss that motivated it was `fill` pointed at a live-only app out of
+order. The two flows differ only at step one and `push` absorbs it: a FIRST release already has a
+PREPARE_FOR_SUBMISSION version (creating the app record made it), so `prepare` is a find-and-reuse
+no-op; an UPDATE has only the read-only live version until `prepare` creates the next one. On a live
+app a DRY `push` stops at `fill` — the draft the later steps target doesn't exist until `prepare` is
+applied — and says so up front; `prepare --apply` (a draft, not a submission) then a dry `push`
+previews the whole plan. `prepare` creates a version for EVERY declared platform, so an iOS+macOS app
+gets both drafts. `prerelease` is deliberately not a step (macOS-only, shells out to altool); run it
+whenever the build is ready — `prepare` attaches the newest build either way.
+
+**`push --skip <step>[,<step>]`** (or `push: { skip: [...] }`) drops a step that doesn't apply — the
+usual case being an app with no audited `accessibility` block, which the command correctly refuses to
+guess. `prepare` and `preflight` cannot be skipped. Every skip is reported on its own line AND again
+after the final green, because the whole value of that last line is that green means green: never let
+a skipped run read like a complete one.
+
+`prepare` creates the version to write INTO, and is REQUIRED as the first push step on any app that
+already has a version on sale. Every other Apple command finds its target through
+`client.editVersion()`, which returns the first version Apple has not marked dead; when the only
+version is live it has no editable record to return and falls back to the live one — so `fill` aims
+its `description`/`whatsNew` PATCHes at the listing customers are reading, and `prerelease` declines
+to attach the build it just uploaded. `prepare` POSTs `/v1/appStoreVersions` with `releaseType:
+MANUAL` (so approval still doesn't release), sets `copyright` from `<metadataDir>/copyright.txt`
+(nothing else in vydanne writes that version-level field), and attaches the newest build. The version
+number is read off that build's `preReleaseVersion` — the archive's own
+`CFBundleShortVersionString`, so it cannot drift from the binary — or `VYDANNE_VERSION=<x>` when the
+version is being prepared before its build exists. It is find-or-create, so re-running is safe; a
+version Apple has locked (`IN_REVIEW`, `READY_FOR_SALE`, …) is refused rather than edited, because
+withdrawing a submission is the operator's call. It pre-checks the number against the version on sale,
+turning Apple's 409 into a sentence. **Creating a draft is not submitting** — Add to Review and Submit
+stay manual.
+
 `prerelease` uploads the BUILD. On Apple it validates and uploads the `.ipa` to **TestFlight** via
 `xcrun altool` — the one command that shells out, because the ASC REST API has never carried a binary,
 which also makes it macOS-only. `.ipa` comes from `ios.ipa` / `VYDANNE_IPA` (a directory takes its
@@ -191,10 +287,14 @@ edit transaction. `production` is REFUSED — not flag-gated — so no argument
 public; promoting the tested build stays a human's job, mirroring the Apple side never submitting. Track
 comes from `google.track` / `VYDANNE_TRACK`, default `internal`; the bundle from `google.aab` /
 `VYDANNE_AAB` (a directory takes its newest `.aab`). **For a PAID app use `internal`** — it's the only
-track where testers install without buying. Notes follow supply's layout:
-`<google.metadataDir>/<play-locale>/changelogs/<versionCode>.txt`, falling back to `default.txt`, capped
-at Play's 500 chars. DRY by default; `--apply` publishes. The versionCode comes from the bundle itself,
-so re-uploading one fails loudly instead of silently replacing.
+track where testers install without buying. Notes follow supply's layout, per locale, first match wins:
+`<google.metadataDir>/<play-locale>/changelogs/<versionCode>.txt` → `next.txt` → `default.txt`, capped
+at Play's 500 chars. **Write the upcoming release's notes as `next.txt`** when the versionCode is not
+knowable in advance (derived from the commit count, say): after a real publish vydanne renames it to
+`<versionCode>.txt` so the next release can't inherit it, and a `default.txt` fallback is WARNED rather
+than silent. The versionCode is read out of the `.aab` locally and the changelog resolution reported
+BEFORE the upload; re-uploading a used code fails loudly instead of silently replacing. DRY by default;
+`--apply` publishes.
 
 `--store google` routes `inspect` · `diff` · `preflight` · `fill` · `prerelease` to the Play Developer **Edits** API
 (OAuth2 service account; **scoped to the config's `packageName`** — a shared key can't touch another app).
@@ -202,9 +302,10 @@ The AAB binary and the (YouTube-URL) promo video stay outside vydanne.
 
 ## `--apply` — writes are opt-in
 
-**Every store-mutating command is a DRY RUN without `--apply`**: `fill` · `previews` · `age-rating` ·
-`review-contact` · `accessibility` · `prerelease` (marked `✎` in `vydanne help`). They read the store,
-print each write they would make, and send nothing. Read-only commands ignore the flag.
+**Every store-mutating command is a DRY RUN without `--apply`**: `prepare` · `push` · `fill` ·
+`previews` · `age-rating` · `review-contact` · `accessibility` · `prerelease` (marked `✎` in
+the usage text, printed by `vydanne` with no arguments). They read the store, print each write they would make, and send nothing. Read-only
+commands ignore the flag.
 
 Never reach for `--apply` to "check whether it works" — the dry run IS the check, and it walks the whole
 plan rather than stopping at the first locale. Its closing count is what you compare against `diff`.
@@ -217,14 +318,18 @@ through that client. **A new command that touches the store must be marked `writ
 `src/registry.mjs`** — that flag is the whole opt-in, not a label.
 
 **Env toggles:** `VYDANNE_CONFIG` · `VYDANNE_SKIP_METADATA` / `VYDANNE_SKIP_SCREENSHOTS` (fill) ·
-`VYDANNE_REPLACE` (previews) · `VYDANNE_FLATTEN=<png>` (iap) · `VYDANNE_A11Y_PUBLISH` (accessibility) ·
-`VYDANNE_COMMIT=1` (legacy alias for `--apply`; prefer the flag).
+`VYDANNE_REPLACE` (fill screenshots + previews: replace populated slots) · `VYDANNE_VERSION` (prepare) ·
+`VYDANNE_IPA` / `VYDANNE_AAB` / `VYDANNE_TRACK` / `VYDANNE_RELEASE_NAME` (prerelease) ·
+`VYDANNE_FLATTEN=<png>` (iap) · `VYDANNE_A11Y_PUBLISH` (accessibility) · `VYDANNE_ALLOW_CROSS_STORE`
+(one run past the cross-store lint) · `VYDANNE_COMMIT=1` (legacy alias for `--apply`; prefer the flag).
 
 ## Flow
 
-config → **write the English master listing (ASO, research-grounded)** → `preflight` (char limits) → fan
-out one copywriter agent per locale → media from zdymak → `fill` + `previews` + declarations (read the
-dry run, then re-run with `--apply`) → `diff` → `preflight` (must be green) → **a human submits**.
+config → **write the English master listing (ASO, research-grounded)** → fan out one copywriter agent
+per locale → media from zdymak → **`bridge`** (zdymak's output into vydanne's folders — every time) →
+build via `prerelease --apply` whenever it is ready → `push` (read the dry run, then re-run with
+`--apply` — it is prepare → fill → previews → age-rating → review-contact → accessibility → preflight,
+stopping at the first failure) → `diff` to confirm → **a human submits**.
 
 ## Gotchas it encodes (don't re-derive)