vydanne 0.2.0

package/GETTING_STARTED.md

@@ -0,0 +1,434 @@
+# Getting started with vydanne
+
+A step-by-step setup for **your** app — written so you can follow it without being a developer. Every
+step is a command to paste or a button to click. Budget ~30 minutes the first time; after that a release
+is three commands.
+
+If you'd rather skim: [What vydanne does](#0-what-vydanne-does-and-what-stays-yours) →
+[Accounts](#1-what-you-need-before-you-start) → [Install](#2-install-vydanne) →
+[Apple key](#3-get-your-apple-credentials-once) → [Play key](#4-get-your-google-play-credentials-once-android-only) →
+[Config](#5-write-the-config-file) → [Folders](#6-put-your-text-and-images-where-vydanne-looks) →
+[Push it](#8-push-it-to-the-store).
+
+---
+
+## 0. What vydanne does, and what stays yours
+
+vydanne fills in **an app record that already exists**. It does not create apps, build software, or
+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** |
+
+> **It never submits.** That's deliberate — a human should always be the one who ships.
+
+---
+
+## 1. What you need before you start
+
+**For Apple (iPhone / iPad / Mac):**
+1. An **Apple Developer Program** membership (~$99/year) — [developer.apple.com/programs](https://developer.apple.com/programs/).
+2. An **app already created** in [App Store Connect](https://appstoreconnect.apple.com) → **My Apps → +**.
+   You need its **Bundle ID** (e.g. `com.example.myapp`).
+3. Permission to create API keys: your account must be **Account Holder** or **Admin**.
+
+**For Google Play (Android)** — skip if you're iOS-only:
+1. A **Play Console** developer account (one-time $25) — [play.google.com/console](https://play.google.com/console).
+2. An **app already created** in Play Console, with its **package name** (e.g. `com.example.myapp`).
+3. For a brand-new app, upload your first build through the Play Console web UI once. The API can edit a
+   listing, but a never-released app has nothing to attach a listing to.
+
+**On your computer:**
+- **Node.js 20.9 or newer.** Check with `node -v`. If it's missing or older, install the LTS build from
+  [nodejs.org](https://nodejs.org).
+- **macOS, Linux, or Windows** — vydanne runs on all three.
+
+> **Windows users:** every step below shows both versions. Use the **PowerShell** one (open *Terminal* or
+> *Windows PowerShell* from the Start menu). The commands are not interchangeable — `export` and
+> `VAR=1 command` are Unix-only syntax and will fail in PowerShell.
+
+---
+
+## 2. Install vydanne
+
+Open your terminal and go to your app's project folder (the top level — the folder you'd open in an editor):
+
+```sh
+# macOS / Linux
+cd /path/to/your-app
+```
+```powershell
+# Windows PowerShell
+cd C:\path\to\your-app
+```
+
+If there's no `package.json` there yet, create one (harmless — it just records your tools):
+
+```sh
+npm init -y
+```
+
+Install vydanne and confirm it runs:
+
+```sh
+npm i -D vydanne
+npx vydanne version
+```
+
+You should see something like `vydanne 0.1.0`.
+
+> **Always run vydanne from this folder.** It reads `vydanne.config.mjs` and every file path relative to
+> wherever you are. Running it from a subfolder will make it look in the wrong place.
+
+---
+
+## 3. Get your Apple credentials (once)
+
+vydanne talks to Apple with an **API key** — three pieces: a `.p8` file, a **Key ID**, and an **Issuer ID**.
+
+1. Go to [App Store Connect](https://appstoreconnect.apple.com) → **Users and Access**.
+2. Open the **Integrations** tab → **App Store Connect API** → **Team Keys**.
+3. Click **+**, name it `vydanne`, and set **Access** to **App Manager**. *(Admin also works. Anything
+   lower can't edit a listing.)*
+4. Click **Generate**, then **Download the key**. ⚠️ **Apple lets you download it exactly once.** If you
+   lose it, revoke the key and make a new one.
+5. On that same page, copy the **Key ID** (next to your new key) and the **Issuer ID** (at the top of the
+   list — one per team, looks like `57246542-96fe-1a63-e053-0824d011072a`).
+
+Now put the file where vydanne looks for it — inside a `.appstoreconnect\private_keys` folder in your
+home directory. vydanne finds your home folder automatically on every operating system.
+
+```sh
+# macOS / Linux
+mkdir -p ~/.appstoreconnect/private_keys
+mv ~/Downloads/AuthKey_*.p8 ~/.appstoreconnect/private_keys/
+```
+```powershell
+# Windows PowerShell
+New-Item -ItemType Directory -Force "$env:USERPROFILE\.appstoreconnect\private_keys"
+Move-Item "$env:USERPROFILE\Downloads\AuthKey_*.p8" "$env:USERPROFILE\.appstoreconnect\private_keys\"
+```
+
+Tell your terminal the two IDs (substitute your own values):
+
+```sh
+# macOS / Linux
+export ASC_KEY_ID=ABCD123456
+export ASC_ISSUER_ID=57246542-96fe-1a63-e053-0824d011072a
+```
+```powershell
+# Windows PowerShell
+$env:ASC_KEY_ID = "ABCD123456"
+$env:ASC_ISSUER_ID = "57246542-96fe-1a63-e053-0824d011072a"
+```
+
+**To avoid retyping these every time you open a terminal:**
+
+- **macOS / Linux** — append the same two `export` lines to `~/.zshrc` (or `~/.bashrc`), then run
+  `source ~/.zshrc`.
+- **Windows** — save them permanently for your user account (run once; then reopen the terminal):
+  ```powershell
+  [Environment]::SetEnvironmentVariable("ASC_KEY_ID", "ABCD123456", "User")
+  [Environment]::SetEnvironmentVariable("ASC_ISSUER_ID", "57246542-96fe-1a63-e053-0824d011072a", "User")
+  ```
+
+**Test it:**
+
+```sh
+npx vydanne inspect
+```
+
+If you see your app's current state, Apple is wired up. (Errors? See
+[Troubleshooting](#troubleshooting).)
+
+---
+
+## 4. Get your Google Play credentials (once, Android only)
+
+Play uses a **service account** — a robot Google account with a JSON key file.
+
+1. In [Play Console](https://play.google.com/console): **Setup → API access**. Link or create a Google
+   Cloud project if prompted.
+2. Click through to **Google Cloud → Service Accounts**, then **Create service account**. Name it
+   `vydanne`. You can skip the optional role/user steps.
+3. Open the new service account → **Keys → Add key → Create new key → JSON**. It downloads immediately —
+   this file is a password, keep it out of your project folder and out of git.
+4. Back in **Play Console → Users and permissions → Invite new user**. Paste the service account's email
+   (it looks like `vydanne@your-project.iam.gserviceaccount.com`).
+5. Give it access to **your app only**, with the **Edit store listing, pricing & distribution**
+   permission (and **Release** if you'll also push builds later). Send the invite — it's auto-accepted.
+
+Point vydanne at the key — use the **full path**, not a shortcut like `~` (vydanne does not expand it):
+
+```sh
+# macOS / Linux
+export PLAY_JSON_KEY_FILE="$HOME/keys/play-service-account.json"
+```
+```powershell
+# Windows PowerShell
+$env:PLAY_JSON_KEY_FILE = "$env:USERPROFILE\keys\play-service-account.json"
+```
+
+**Test it:**
+
+```sh
+npx vydanne inspect --store google
+```
+
+> vydanne is **scoped to the one `packageName`** in your config. Even a service-account key with wider
+> access can't touch another app through vydanne.
+
+---
+
+## 5. Write the config file
+
+Create a file named **`vydanne.config.mjs`** in your project folder. Start from the copy that ships
+inside the package:
+
+```sh
+# macOS / Linux
+cp node_modules/vydanne/vydanne.config.example.mjs vydanne.config.mjs
+```
+```powershell
+# Windows PowerShell
+Copy-Item node_modules\vydanne\vydanne.config.example.mjs vydanne.config.mjs
+```
+
+A minimal iPhone-only config looks like this — edit the values to match your app:
+
+```js
+export default {
+  bundleId: "com.example.myapp",   // exactly as registered with Apple
+  primaryLocale: "en-US",          // your main language — MUST be filled in
+  platforms: ["IOS"],              // add "MAC_OS" only if you also ship a Mac app
+  uiLocales: ["en", "de", "fr"],   // the languages you'll publish
+  metadataDir: "fastlane/metadata",
+  rating: "4+",
+};
+```
+
+**The fields, in plain terms:**
+
+| Field | What to put |
+|---|---|
+| `bundleId` | Your app's bundle identifier, exactly as Apple has it. |
+| `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. |
+| `metadataDir` | Where your listing text lives. `fastlane/metadata` is the default. |
+| `rating` | Age rating, e.g. `"4+"`. |
+| `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. |
+
+Check your languages resolved correctly:
+
+```sh
+npx vydanne locales
+```
+
+Anything listed as *unsupported* has no App Store language and will fall back to your primary locale —
+**don't** create a folder for it.
+
+---
+
+## 6. Put your text and images where vydanne looks
+
+This is the part that trips people up. vydanne reads **plain `.txt` files in named folders**. One folder
+per language, named with **Apple's** code (from `vydanne locales`).
+
+```
+your-app/
+├─ vydanne.config.mjs
+├─ fastlane/
+│  ├─ metadata/
+│  │  ├─ en-US/                    ← Apple's locale code, not "en"
+│  │  │  ├─ name.txt               (≤30)  your app's store name
+│  │  │  ├─ subtitle.txt           (≤30)  one benefit line
+│  │  │  ├─ description.txt        (≤4000)
+│  │  │  ├─ keywords.txt           (≤100) comma-separated, NO spaces
+│  │  │  ├─ promotional_text.txt   (≤170) editable anytime, no review
+│  │  │  ├─ release_notes.txt      what's new in this version
+│  │  │  ├─ marketing_url.txt      (optional)
+│  │  │  └─ support_url.txt        (optional)
+│  │  ├─ de-DE/  …same files…
+│  │  └─ review_information/       ← App Review contact. KEEP OUT OF GIT.
+│  │     ├─ first_name.txt
+│  │     ├─ last_name.txt
+│  │     ├─ phone_number.txt
+│  │     ├─ email_address.txt
+│  │     └─ notes.txt              how a reviewer tests your app
+│  ├─ screenshots/                 ← iPhone / iPad / Watch
+│  │  └─ en-US/
+│  │     ├─ iphone69_01.png
+│  │     ├─ iphone69_02.png
+│  │     └─ ipad13_01.png
+│  └─ screenshots-macos/           ← Mac only
+│     └─ en-US/
+│        └─ macos_01.png
+```
+
+**Screenshot file names matter.** The part **before the first underscore** tells vydanne which device the
+image is for. Anything after it is yours — but files upload in alphabetical order, so number them
+`_01`, `_02`, …
+
+| Prefix | Device slot |
+|---|---|
+| `iphone69_` | iPhone 6.9″ |
+| `iphone65_` | iPhone 6.5″ |
+| `ipad13_` | iPad Pro 12.9″ |
+| `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.
+
+> **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.
+
+**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:
+
+```
+fastlane/metadata/android/
+└─ en-US/
+   ├─ title.txt              (≤30)
+   ├─ short_description.txt  (≤80)
+   └─ 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 asset | Path vydanne reads |
+|---|---|
+| Store icon (512×512) | `brand/icons/play/icon-512.png` |
+| Feature graphic (1024×500) | `marketing/out/play-feature-graphic.png` |
+| Phone screenshots | `marketing/out/play-phone-plain/` |
+| 7″ tablet screenshots | `marketing/out/play-tablet7-plain/` |
+| 10″ tablet screenshots | `marketing/out/play-tablet-plain/` |
+
+*(These paths are not configurable yet — create the folders at those locations, or symlink them.)*
+
+---
+
+## 7. Optional extras
+
+**App Preview videos** — add them to your config, then `npx vydanne previews`:
+
+```js
+previews: [
+  { platform: "IOS", type: "IPHONE_67", file: "marketing/out/preview.mp4",
+    poster: "00:00:05:00", locales: ["en-US"] },
+],
+```
+
+`poster` is the still frame shown before playback, as `HH:MM:SS:FF`. A locale that already has a preview
+is skipped; set `VYDANNE_REPLACE=1` to swap in a new one.
+
+**In-app purchases** — list them under `iaps` and run `npx vydanne iap` to validate the character limits
+before you paste them into App Store Connect.
+
+**Export compliance** — `npx vydanne compliance` writes the US self-classification PDF to
+`export-compliance/`. Attach it in App Store Connect. If you set `france: true`, remember France needs a
+separate ANSSI declaration.
+
+---
+
+## 8. Push it to the store
+
+Always look before you leap:
+
+```sh
+npx vydanne preflight     # is anything missing or over a character limit?
+npx vydanne diff          # exactly what would change vs what's live now
+```
+
+`preflight` must be **green**. Then:
+
+```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
+```
+
+**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:
+
+```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
+```
+```powershell
+# Windows PowerShell — set the variable first; the `VAR=1 command` form does NOT work here
+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
+```
+
+Finally, run `npx vydanne diff` once more and eyeball one screenshot per platform in the web UI.
+
+---
+
+## 9. Finish in the browser (the parts no API can do)
+
+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.
+3. **Play Data Safety + content rating** — questionnaires in the Play Console.
+4. **Submit for Review** — yours to press.
+
+---
+
+## Troubleshooting
+
+| What you see | What it means | Fix |
+|---|---|---|
+| `config not found at …` | You're in the wrong folder, or the file is misnamed. | `cd` to your project root; the file must be `vydanne.config.mjs`. |
+| `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"). |
+| 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. |
+| `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`. |
+| `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`. |
+
+---
+
+## Reference: environment variables
+
+| Variable | Purpose |
+|---|---|
+| `ASC_KEY_ID`, `ASC_ISSUER_ID` | Apple API key identifiers (**required**). |
+| `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_FLATTEN=<png>` | `iap`: convert an image to RGB (removes transparency). |
+| `VYDANNE_A11Y_PUBLISH=1` | `accessibility`: publish the labels (only once the app is live). |
+
+Set them with `export NAME=value` on macOS/Linux, or `$env:NAME = "value"` in Windows PowerShell.
+
+Secrets — the `.p8`, the Play JSON, and `fastlane/metadata/review_information/` — should **never** be
+committed to git. Add them to your `.gitignore`.
+
+---
+
+Next: the [README](README.md) for the full command list and the store gotchas vydanne encodes.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vydanne contributors
+
+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.

package/README.md

@@ -0,0 +1,212 @@
+# vydanne
+
+**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
+description, keywords, screenshots… once per language, twice per store, again for the Mac version. Miss a
+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**.
+
+> *выданне* (Belarusian) — "publishing".
+
+<br>
+
+## Is this for me?
+
+**Yes, if** you have an app and you're tired of the store's web forms — especially in more than one
+language. You do not need to be a programmer: you write text files, and run three commands.
+
+**Probably not, if** you publish one app in one language and never change it. The web form is fine.
+
+**You'll still need** an Apple Developer account (and/or a Play Console account) and someone to build the
+actual app. vydanne handles the *listing*, not the software.
+
+<br>
+
+## The two halves of a release
+
+vydanne has a sibling — **[zdymak](https://www.npmjs.com/package/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.
+
+<br>
+
+## Install
+
+You need **Node.js 20.9 or newer** ([nodejs.org](https://nodejs.org) — the LTS build). Then, in your app's
+folder:
+
+```sh
+npm i -D vydanne
+npx vydanne version
+```
+
+Works on **macOS, Linux and Windows**. The examples below use macOS/Linux shell syntax; Windows
+PowerShell equivalents are in [GETTING_STARTED.md](GETTING_STARTED.md) (`$env:NAME = "value"` instead of
+`export`, and set variables on their own line — PowerShell has no `VAR=1 command` form).
+
+<br>
+
+## Quick start
+
+**→ First time? Follow [GETTING_STARTED.md](GETTING_STARTED.md).** It walks through every click:
+getting your Apple API key, setting up a Play service account, where each file goes, and what to do when
+something errors. This section is the short version for people who've done it before.
+
+**1. Get a key from Apple.** App Store Connect → Users and Access → Integrations → App Store Connect API.
+Download the `.p8` (once only!), then:
+
+```sh
+mkdir -p ~/.appstoreconnect/private_keys
+mv ~/Downloads/AuthKey_*.p8 ~/.appstoreconnect/private_keys/
+export ASC_KEY_ID=…  ASC_ISSUER_ID=…
+```
+```powershell
+# Windows PowerShell
+New-Item -ItemType Directory -Force "$env:USERPROFILE\.appstoreconnect\private_keys"
+Move-Item "$env:USERPROFILE\Downloads\AuthKey_*.p8" "$env:USERPROFILE\.appstoreconnect\private_keys\"
+$env:ASC_KEY_ID = "…"; $env:ASC_ISSUER_ID = "…"
+```
+
+**2. Describe your app** in a `vydanne.config.mjs` file next to your project:
+
+```js
+export default {
+  bundleId: "com.example.myapp",
+  primaryLocale: "en-US",
+  platforms: ["IOS"],
+  uiLocales: ["en", "de", "fr"],
+  metadataDir: "fastlane/metadata",
+  rating: "4+",
+};
+```
+
+**3. Write your listing** as plain text files, one folder per language:
+
+```
+fastlane/metadata/en-US/name.txt          ← "My App"
+fastlane/metadata/en-US/subtitle.txt      ← "The one-line pitch"
+fastlane/metadata/en-US/description.txt
+fastlane/metadata/en-US/keywords.txt
+```
+
+**4. Check, then push:**
+
+```sh
+npx vydanne preflight     # anything missing or too long?
+npx vydanne diff          # what exactly would change?
+npx vydanne fill          # do it
+```
+
+Run vydanne **from your project folder** — it finds everything relative to where you are.
+
+<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. |
+| `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. |
+| `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. |
+| `review-contact` | Fills in the App Review contact details (who Apple calls if there's a problem). |
+| `accessibility` | Saves Accessibility Nutrition Labels. Stays a draft until your app is live. |
+| `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. |
+| `version` | Prints the version of vydanne. |
+
+For **Google Play**, add `--store google` to `inspect`, `diff`, `preflight`, or `fill`.
+
+<br>
+
+## Google Play
+
+Add a `google` block to your config and point `PLAY_JSON_KEY_FILE` at a service-account key
+([how to get one](GETTING_STARTED.md#4-get-your-google-play-credentials-once-android-only)):
+
+```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
+```
+
+**Play is dry by default on purpose.** Nothing goes live until you add `VYDANNE_COMMIT=1`, 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.
+
+<br>
+
+## Your config, field by field
+
+`bundleId` · `primaryLocale` (your main language — everything else falls back to it, so it must be
+complete) · `asc` (Apple key IDs, if you'd rather not use environment variables) · `platforms` (iOS and
+macOS are **separate listings**) · `uiLocales` (your languages, auto-translated to Apple's codes) ·
+`metadataDir` (where your text lives) · `rating` · `privacy` (what data actually leaves the device) ·
+`iaps` (in-app purchases) · `previews` (App Preview videos) · `export` (encryption compliance details) ·
+`google` (the Play block).
+
+A commented example ships with the package: **[`vydanne.config.example.mjs`](vydanne.config.example.mjs)**.
+
+<br>
+
+## The mistakes it saves you from
+
+Every one of these has cost somebody a rejected build or a blank store page. vydanne handles them so you
+don't have to learn them the hard way.
+
+| The trap | What vydanne does |
+|---|---|
+| A wrongly-named language folder aborts the **entire** upload | Maps your codes to Apple's and flags any language the store doesn't support |
+| 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 |
+| 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 |
+| 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 |
+| Play's language codes differ from Apple's | Documented and validated separately |
+| A missing local screenshot folder deleting your live ones | Only uploads what exists — never deletes by omission |
+
+<br>
+
+## 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 doesn't create the app record — make that in App Store Connect / Play Console first.
+
+<br>
+
+## For developers & AI agents
+
+The package ships **[SKILL.md](SKILL.md)** — a precise, agent-facing operating guide (exact file layout,
+the store gotchas, the ASO rules) — plus TypeScript definitions
+([`types/index.d.ts`](types/index.d.ts), type `import('vydanne').VydanneConfig`).
+
+Two guards keep the docs honest: `npm run check:docs` (every config field and command is documented) and
+`npm run check:types` (every one is typed). Both run before publish, so the docs can't drift from the code.
+
+Technically: native Node, no fastlane, Ruby, or Python. ES256 JWT via `node:crypto`, the App Store Connect
+REST API over `fetch`, chunked uploads by hand, PDFs via `pdfkit`, image flattening via `sharp`. Android
+goes through the Google Play Developer **Edits** API.
+
+Releasing a new version: [RELEASING.md](RELEASING.md).
+
+MIT.