@makefully/adaptfully 3.16.1 → 4.1.0

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 All notable changes to this project are documented in this file.
 
+## 4.1.0 — 2026-09-04
+
+### Added
+
+- **`adaptfully android-keystore`** — Generate debug/release keystores with `keytool` and write `assets/meta/deployments/android/build.json`.
+- **`adaptfully apple-signing`** — Generate CSR/key (OpenSSL), export `.p12` from an Apple `.cer`, place provisioning profiles under `ios/apple/`, optional `apple.p12Password` in `build.json`.
+- **Credential setup guides** — First-time walkthroughs under [`docs/credentials/`](docs/credentials/README.md) for iOS, Android, and Steam (full manual steps + helper skip markers).
+
+## 4.0.0 — 2026-09-03
+
+### Removed
+
+- **Cordova / PhoneGap** — Dropped `CordovaPackager`, `packager: "cordova"`, and the `cordova` package keyword. Android/iOS prebuild and Wrapfully family resolution are Capacitor-only.
+- **`CordovaPackager` export** — No longer exported from `@makefully/adaptfully`.
+
+### Changed
+
+- **`resolveFamily(..., 'cordova')`** — Throws an explicit error directing clients to Capacitor.
+- **Major version** — Breaking for projects still configured with Cordova.
+
 ## 3.16.1 — 2026-09-03
 
 ### Fixed

package/README.md

@@ -29,6 +29,8 @@ adaptfully deploy steam                       # prebuild + POST to Wrapfully ste
 adaptfully steam-publish                      # one-time: log in with steamcmd → assets/meta/deployments/steam/steam.json
 adaptfully google-publish --from ./sa.json    # one-time: import Play service account → deployments/android/google.json
 adaptfully apple-publish                      # one-time: write App Store Connect creds → deployments/ios/apple.json
+adaptfully android-keystore                   # one-time: generate keystores + android build.json
+adaptfully apple-signing                      # one-time: CSR / .p12 / provisioning files under ios/apple/
 ```
 
 | Stage | What it does |
@@ -39,6 +41,10 @@ adaptfully apple-publish                      # one-time: write App Store Connec
 | `steam-publish` | One-time local setup: install steamcmd, interactive login, write the `steam` deployment's `steam.json` (also updates `.gitignore`) |
 | `google-publish` | One-time local setup: import a Play Console service-account JSON into the `android` deployment folder (also updates `.gitignore`) |
 | `apple-publish` | One-time local setup: write App Store Connect credentials into the `ios` deployment folder (also updates `.gitignore`) |
+| `android-keystore` | One-time local setup: generate debug/release keystores and write `android` `build.json` (also updates `.gitignore`) |
+| `apple-signing` | One-time local setup: CSR → Apple `.cer` → `.p12` / provisioning profiles under `ios/apple/` (also updates `.gitignore`) |
+
+First-time walkthroughs (manual steps + helper skip markers): [docs/credentials/](docs/credentials/README.md).
 
 `wrapfully-deploy` is a compatibility alias for `adaptfully deploy` when invoked with a Wrapfully builder name (`steam`, `win`, `android`, etc.).
 
@@ -159,16 +165,15 @@ Standard plugin keys load bundled Adaptfully runtime scripts and emit an inline
 
 Wrapfully builders (`steam`, `win`, `mac`, `android`, etc.) map to platform keys via defaults (`win` → `steam`) or an explicit `builders` array on the platform config.
 
-Each platform entry may set a **`packager`** (`web`, `electron`, `cordova`, or `capacitor`). Defaults to **`web`** — copy deploy and inject HTML only. Packagers are implemented as classes (`WebPackager`, `ElectronPackager`, `CordovaPackager`, `CapacitorPackager`) that handle prebuild output for their target platforms.
+Each platform entry may set a **`packager`** (`web`, `electron`, or `capacitor`). Defaults to **`web`** — copy deploy and inject HTML only. Packagers are implemented as classes (`WebPackager`, `ElectronPackager`, `CapacitorPackager`) that handle prebuild output for their target platforms.
 
 | Packager | Prebuild adds |
 |----------|---------------|
 | `web` | `game-config.js` for **`uwp`** platform prebuilds |
 | `electron` | `main.js` (Electron shell); `preload.js` when **`steam-auth`** is registered |
-| `cordova` | `cordova.js` stub, `game-config.js`, CSP/viewport HTML extras |
 | `capacitor` | `game-config.js`, Capacitor CSP/viewport; `social-login-config.js` when **`social-auth`** is registered |
 
-Android/iOS Wrapfully builds default to the **`capacitor`** builder family. Set `packager: "cordova"` on a platform to use Cordova for that target.
+Android/iOS Wrapfully builds use the **`capacitor`** builder family. Cordova/PhoneGap is no longer supported.
 
 **`steam-auth` requires `packager: "electron"`** and `platforms.<name>.steamId` (Steamworks app ID for the client preload). Steam **upload** app IDs live separately in each Steam deployment’s `manifest.json` — see Wrapfully docs.
 
@@ -461,10 +466,6 @@ Standard npm fields (`name`, `version`, `description`) are used directly. Add a
         }
       }
     },
-    "properties": [
-      { "tag": "plugin", "name": "cordova-plugin-inappbrowser" },
-      { "tag": "allow-navigation", "href": "*" }
-    ]
   }
 }
 ```
@@ -472,13 +473,13 @@ Standard npm fields (`name`, `version`, `description`) are used directly. Add a
 | Field | Used by | Description |
 |-------|---------|-------------|
 | `title` | All | Display name shown in stores and app shells |
-| `packageName` | Cordova, Capacitor, Electron, UWP, Play upload | Reverse-DNS identifier (`com.company.game`) |
-| `publisherDisplayName` | Cordova, Electron, web | Short publisher name |
+| `packageName` | Capacitor, Electron, UWP, Play upload | Reverse-DNS identifier (`com.company.game`) |
+| `publisherDisplayName` | Electron, web | Short publisher name |
 | `publisherFullName` | Electron | Legal entity name for copyright |
-| `publisherWebsite` | Cordova, web | Company URL |
-| `publisherEmailAddress` | Cordova | Contact email |
+| `publisherWebsite` | Web | Company URL |
+| `publisherEmailAddress` | Optional | Contact email |
 | `scope` | Web/PWA | Base URL scope for the web app |
-| `themeColor` | Cordova, Capacitor, Electron, UWP, web | Loading screen / theme color |
+| `themeColor` | Capacitor, Electron, UWP, web | Loading screen / theme color |
 | `twitterId` | Web | Twitter handle for meta tags |
 | `deployFolder` | Client | Neutral deploy directory staged before prebuild (default: `deploy`) |
 | `htmlInjections` | Prebuild | Deploy-relative HTML paths to inject (default: `["index.html"]`) |
@@ -486,11 +487,10 @@ Standard npm fields (`name`, `version`, `description`) are used directly. Add a
 | `platforms` | Prebuild | Per-platform registration maps (see [Adaptfully runtime](#adaptfully-runtime)) |
 | `platforms.<name>.builder` | Build/deploy | Override Wrapfully builder for a platform (default: `web` → `webapp`, others match platform key) |
 | `platforms.<name>.builders` | wrapfully-deploy | Map additional Wrapfully builder names to a platform |
-| `platforms.<name>.packager` | Prebuild | `web` (default), `electron`, `cordova`, or `capacitor` — selects the packager class that adds platform-specific files during prebuild |
+| `platforms.<name>.packager` | Prebuild | `web` (default), `electron`, or `capacitor` — selects the packager class that adds platform-specific files during prebuild |
 | `platforms.<name>.steamId` | Electron + steam-auth | Steamworks app ID baked into `preload.js` (client). Upload app IDs belong in the Steam deployment `manifest.json` |
 | `platforms.<name>.socialLogin` | Capacitor + social-auth | Capgo provider config (`providers`, `google.webClientId`, `apple.clientId`, optional `defaultProvider`) |
 | `platforms.<name>.<configField>` | Build/deploy | Overrides the matching top-level `config.*` default for that platform only (e.g. `platforms.android.packageName`, `platforms.ios.title`). Does not apply to control fields: `packager`, `registrations`, `builder`, `builders`, `deployments`, `steamId`, `socialLogin`, `steamworks` |
-| `properties` | Cordova | Cordova config.xml entries (plugins, allow-navigation, etc.) |
 
 Top-level `config.*` values are **defaults**. Any non-control field on `config.platforms.<name>` overrides the default when that platform is built or deployed. Example:
 
@@ -553,10 +553,14 @@ For a single platform, pass the specific builder name.
 
 ### Platform package requirements
 
+**First-time setup:** see [docs/credentials/](docs/credentials/README.md) for iOS, Android, and Steam walkthroughs (CLI helpers + full manual steps).
+
 Signing keys, provisioning profiles, and store credentials go in the deployment folder `./assets/meta/deployments/<deployment>/` on disk (the selected deployment is sent as `meta/publish/` in the zip). The examples below use `<deployment>` as a placeholder for the target key (e.g. `steam`, `web-prod`). **These files contain secrets** — add them to `.gitignore` and never commit them to a public repository. (Projects that have not adopted the `deployments/` layout may still place these under the legacy `./assets/meta/publish/`.)
 
 #### Android (`android`, `android-dev`)
 
+First-time setup: [docs/credentials/android.md](docs/credentials/android.md) (`android-keystore`, `google-publish`).
+
 Place keystore files in `assets/meta/deployments/<deployment>/android/`. Include `assets/meta/deployments/<deployment>/build.json`:
 
 ```json
@@ -608,7 +612,9 @@ The file looks like:
 
 #### Apple (`ios`, `ios-dev`, `ios-sim`, `mac`)
 
-**Capacitor iOS** signing is file-based under the deployment folder (not the Cordova-style `build.json` `ios.*` identity fields):
+First-time setup: [docs/credentials/ios.md](docs/credentials/ios.md) (`apple-signing`, `apple-publish`).
+
+**Capacitor iOS** signing is file-based under the deployment folder:
 
 ```
 assets/meta/deployments/<deployment>/
@@ -617,11 +623,10 @@ assets/meta/deployments/<deployment>/
   apple/app-store.mobileprovision     # release
   apple/development.p12               # ios-dev device
   apple/development.mobileprovision   # ios-dev device
+  build.json                          # optional: { "apple": { "p12Password": "..." } }
 ```
 
-`adaptfully build` (zip-only) still packages this deployment folder for Capacitor/Cordova so device debug builds can sign. The `.p12` passphrase must match `MAC_KEYCHAIN_PASSWORD` on the Mac Wrapfully host. Team ID and profile UUID are read from the `.mobileprovision`. Enable **Sign in with Apple** on the App ID when using Capgo Apple auth.
-
-Optional `build.json` may still be present for tooling compatibility; Capacitor does not require its `ios.*` code-sign fields.
+`adaptfully build` (zip-only) still packages this deployment folder for Capacitor so device debug builds can sign. Optional `build.json` may set `apple.p12Password` for the `.p12` passphrase (defaults to empty when omitted). Team ID and profile UUID are read from the `.mobileprovision`. Enable **Sign in with Apple** on the App ID when using Capgo Apple auth.
 
 To deploy to the App Store, include `assets/meta/deployments/<deployment>/apple.json`. The easiest path is:
 
@@ -642,12 +647,11 @@ The file looks like:
 ```
 
 iOS IPA upload uses `username` + `password` via `xcrun altool --upload-app`. `category` / `identity` matter more for macOS Electron signing/notarization.
-#### Cordova
-
-Set `packager: "cordova"` on an `android` or `ios` platform to use Cordova instead of Capacitor. Requires the Android and Apple package requirements above.
 
 #### Steam (`steam`, `steam-dev`)
 
+First-time setup: [docs/credentials/steam.md](docs/credentials/steam.md) (`steam-publish`).
+
 `steam-dev` builds debug Electron binaries for Windows, Mac, and Linux without uploading to Steam. No `steam.json` credentials are required.
 
 For release uploads, run **`adaptfully steam-publish`** once on your machine. It installs steamcmd if needed, logs you in interactively (enter a Steam Guard code if prompted), and writes `assets/meta/deployments/steam/steam.json`:

package/docs/credentials/README.md

@@ -0,0 +1,50 @@
+# Credential setup guides
+
+One-time local setup for signing and store-upload credentials under
+`assets/meta/deployments/<deployment>/`.
+
+These guides stay focused on **files in your game repo** and Adaptfully CLI helpers.
+They do not cover which OS builds the artifact.
+
+## Guides
+
+| Platform | Guide | Typical deployment folder |
+|----------|--------|---------------------------|
+| iOS | [ios.md](./ios.md) | `assets/meta/deployments/ios/` |
+| Android | [android.md](./android.md) | `assets/meta/deployments/android/` |
+| Steam | [steam.md](./steam.md) | `assets/meta/deployments/steam/` |
+
+## Helpers
+
+| Command | Writes |
+|---------|--------|
+| `npx adaptfully android-keystore` | `android/*.keystore` + `build.json` |
+| `npx adaptfully google-publish --from <sa.json>` | `google.json` |
+| `npx adaptfully apple-signing` | CSR/key work files, `apple/*.p12`, optional `.mobileprovision` + `build.json` `apple.p12Password` |
+| `npx adaptfully apple-publish` | `apple.json` (App Store Connect upload login) |
+| `npx adaptfully steam-publish` | `steam.json` |
+
+Each guide lists the **full manual process** and marks **Helper** steps with **skip to step N** when you use a command instead.
+
+## Debug vs release
+
+| Goal | Credentials needed? |
+|------|---------------------|
+| `android-dev` / local debug APK | Project debug keystore (recommended) or host default |
+| `android` Play release | Release keystore + `google.json` |
+| `ios-dev` device IPA | `development.p12` + `development.mobileprovision` |
+| `ios` App Store | `distribution.p12` + `app-store.mobileprovision` + `apple.json` |
+| `ios-sim` | No device signing files |
+| `steam-dev` | None |
+| `steam` upload | `steam.json` |
+
+## Secrets
+
+Do not commit credential files. Helpers update `.gitignore` with Adaptfully patterns such as:
+
+- `assets/meta/deployments/**/build.json`
+- `assets/meta/deployments/**/google.json`
+- `assets/meta/deployments/**/apple.json`
+- `assets/meta/deployments/**/steam.json`
+- `assets/meta/deployments/**/android/`
+- `assets/meta/deployments/**/apple/`

package/docs/credentials/android.md

@@ -0,0 +1,124 @@
+# Android credentials
+
+Set up signing keystores and (for Play uploads) a Google Play service account.
+
+**Default folder:** `assets/meta/deployments/android/`
+
+## Recommended path
+
+1. **Helper:** `npx adaptfully android-keystore` — creates debug + release keystores and `build.json`.
+2. In Google Play Console, create a service account and download its JSON key (manual).
+3. **Helper:** `npx adaptfully google-publish --from ./path/to/sa.json` — writes `google.json`.
+
+Debug-only: `npx adaptfully android-keystore --debug-only`.
+
+## What you need
+
+| Goal | Files |
+|------|--------|
+| Debug / `android-dev` | `android/debug.keystore` + `build.json` `android.debug` block |
+| Play release / `android` | `android/release.keystore` + `build.json` `android.release` + `google.json` |
+
+`build.json` keystore paths are relative to the deployment folder (the directory that contains `build.json`).
+
+## Full steps
+
+### 1. Prerequisites
+
+- JDK on PATH so `keytool` works (`keytool -help`).
+- A Play Console app (for release uploads).
+
+### 2. Helper: generate keystores
+
+**Helper:** `npx adaptfully android-keystore [--deployment android] [--debug-only] [--yes]`
+
+If you run this, **skip to step 5** (Play service account). For debug-only, you can stop after this step.
+
+Flags:
+
+- `--debug-only` — only the debug keystore + `build.json` debug block
+- `--yes` — overwrite existing `build.json` without prompting
+- `--alias`, `--store-password`, `--key-password`, `--cn` — non-interactive release keystore fields
+
+### 3. Manual alternative: create keystores with keytool
+
+Skip this if you used step 2.
+
+```bash
+mkdir -p assets/meta/deployments/android/android
+
+keytool -genkeypair -v \
+  -keystore assets/meta/deployments/android/android/debug.keystore \
+  -alias androiddebugkey -keyalg RSA -keysize 2048 -validity 10000 \
+  -storepass android -keypass android \
+  -dname "CN=Android Debug,O=Android,C=US"
+
+keytool -genkeypair -v \
+  -keystore assets/meta/deployments/android/android/release.keystore \
+  -alias upload -keyalg RSA -keysize 2048 -validity 10000 \
+  -storepass "(your store password)" -keypass "(your key password)" \
+  -dname "CN=Your Studio,O=Your Studio,C=US"
+```
+
+### 4. Manual alternative: write `build.json`
+
+Skip this if you used step 2.
+
+Create `assets/meta/deployments/android/build.json`:
+
+```json
+{
+  "android": {
+    "debug": {
+      "keystore": "./android/debug.keystore",
+      "packageType": "apk",
+      "storePassword": "android",
+      "alias": "androiddebugkey",
+      "password": "android",
+      "keystoreType": ""
+    },
+    "release": {
+      "keystore": "./android/release.keystore",
+      "packageType": "bundle",
+      "storePassword": "(your store password)",
+      "alias": "upload",
+      "password": "(your key password)",
+      "keystoreType": ""
+    }
+  }
+}
+```
+
+### 5. Create a Play Console service account (manual)
+
+Required only for Play uploads (`adaptfully release android` / deploy to Google).
+
+1. Open [Google Play Console](https://play.google.com/console/) → **Setup** → **API access** (or Google Cloud IAM linked to the Play developer account).
+2. Create or select a service account with permission to manage releases.
+3. Download a JSON key for that service account.
+4. Invite the service account email in Play Console with the right app permissions.
+
+### 6. Helper: import `google.json`
+
+**Helper:** `npx adaptfully google-publish --from ./path/to/service-account.json [--deployment android]`
+
+If you run this, **skip to step 8**.
+
+### 7. Manual alternative: copy the service account JSON
+
+Skip this if you used step 6.
+
+Copy the downloaded key to `assets/meta/deployments/android/google.json`. Ensure `manifest.json` includes `"type": "google"` (helpers write this for you).
+
+### 8. Done when
+
+- [ ] `build.json` exists with debug (and release, if shipping)
+- [ ] Keystore files exist at the paths listed in `build.json`
+- [ ] For Play uploads: `google.json` is present and the service account can access the app
+- [ ] Credential paths are gitignored
+
+## Notes
+
+- Prefer **project-owned** keystores so debug installs stay reproducible across machines.
+- Some build hosts supply a default debug keystore when `build.json` is missing; do not rely on that for shared projects.
+- Keep release keystore passwords offline; losing the release keystore can block Play updates for that signing key.

package/docs/credentials/ios.md

@@ -0,0 +1,182 @@
+# iOS credentials
+
+Set up Apple signing files and (for App Store uploads) App Store Connect login credentials.
+
+**Default folder:** `assets/meta/deployments/ios/`
+
+You can create signing material on **macOS or Windows**. The sections below branch where the local tools differ.
+
+## Recommended path
+
+1. **Helper:** `npx adaptfully apple-signing --kind development` (and/or `--kind distribution`) — generates a CSR, walks portal checklist, exports `.p12`, optionally copies the provisioning profile.
+2. Complete the Apple Developer portal steps the helper prints (upload CSR, download `.cer` / `.mobileprovision`).
+3. For App Store uploads only — **Helper:** `npx adaptfully apple-publish` — writes `apple.json`.
+
+Simulator builds (`ios-sim`) need no device signing files.
+
+## What you need
+
+| Goal | Files |
+|------|--------|
+| Device debug (`ios-dev`) | `apple/development.p12`, `apple/development.mobileprovision` |
+| App Store (`ios` release) | `apple/distribution.p12`, `apple/app-store.mobileprovision`, `apple.json` |
+| Simulator (`ios-sim`) | None |
+
+Optional `build.json` next to `apple/`:
+
+```json
+{
+  "apple": {
+    "p12Password": "(passphrase used when exporting the .p12)"
+  }
+}
+```
+
+If omitted, the build pipeline treats the passphrase as empty.
+
+## Prerequisites
+
+- Apple Developer Program membership.
+- An App ID matching your platform `packageName`.
+- If you use Capgo Apple social login: enable **Sign in with Apple** on that App ID.
+- For development profiles: registered device UDIDs.
+- OpenSSL on PATH for the helper / Windows manual path (`openssl version`). macOS Keychain users can still use the helper if OpenSSL is available (e.g. via Homebrew or Xcode CLT tooling).
+
+## Full steps
+
+### 1. Helper: CSR, `.p12`, and profile placement
+
+**Helper:** `npx adaptfully apple-signing [--kind development|distribution] [--csr-only] [--from-cer path] [--provision path] [--p12-password secret]`
+
+If you run the full interactive helper (not `--csr-only`), **skip to step 7** after it finishes (or step 8 for App Store Connect login).
+
+Useful flags:
+
+- `--csr-only` — stop after writing the CSR; later continue with `--from-cer`
+- `--from-cer ./Certificates.cer` — skip CSR generation when `apple/.work/private.key` already exists
+- `--provision ./Profile.mobileprovision` — copy/rename into `apple/`
+- `--kind development` or `--kind distribution`
+
+Work files live under `assets/meta/deployments/ios/apple/.work/` by default (`private.key` + CSR).
+
+### 2. Create a Certificate Signing Request (manual)
+
+Skip this if you used step 1 (or will use `--from-cer` with an existing key from step 1).
+
+#### macOS (Keychain Access)
+
+1. Open **Keychain Access** → **Certificate Assistant** → **Request a Certificate From a Certificate Authority…**
+2. Enter your email and common name; choose **Saved to disk**.
+3. Save the `.certSigningRequest` file.
+
+#### Windows / OpenSSL (any OS)
+
+```bash
+mkdir -p assets/meta/deployments/ios/apple/.work
+cd assets/meta/deployments/ios/apple/.work
+
+openssl genrsa -out private.key 2048
+openssl req -new -key private.key -out CertificateSigningRequest.certSigningRequest -subj "/emailAddress=you@example.com/CN=Your Name/C=US"
+```
+
+### 3. Create the certificate on the Apple Developer site (manual)
+
+Always required — Apple must issue the certificate.
+
+1. Open [Certificates](https://developer.apple.com/account/resources/certificates/list).
+2. Create **Apple Development** (device debug) and/or **Apple Distribution** (App Store).
+3. Upload the CSR from step 1 or 2.
+4. Download the `.cer` file.
+
+### 4. Export a `.p12` (manual)
+
+Skip this if step 1 already exported `development.p12` / `distribution.p12`.
+
+#### macOS (Keychain Access)
+
+1. Double-click the `.cer` to import it into Keychain Access.
+2. Find the certificate (and its private key) → **Export…** → `.p12`.
+3. Choose a passphrase; remember it for `build.json` `apple.p12Password`.
+4. Save as `assets/meta/deployments/ios/apple/development.p12` or `distribution.p12`.
+
+#### Windows / OpenSSL
+
+```bash
+# From the folder that has private.key and the downloaded .cer
+openssl x509 -in Certificates.cer -inform DER -out cert.pem -outform PEM
+openssl pkcs12 -export -inkey private.key -in cert.pem -out development.p12
+# or distribution.p12 — use the matching kind
+```
+
+Move the `.p12` to `assets/meta/deployments/ios/apple/`.
+
+If DER conversion fails, try importing the `.cer` as PEM directly in the `pkcs12 -export` `-in` argument.
+
+### 5. Create and download a provisioning profile (manual)
+
+Always required for device / App Store signing.
+
+1. Register devices (development) under [Devices](https://developer.apple.com/account/resources/devices/list).
+2. Open [Profiles](https://developer.apple.com/account/resources/profiles/list).
+3. Create a **Development** profile or **App Store** profile for your App ID and certificate.
+4. Download the `.mobileprovision`.
+
+### 6. Place the provisioning profile (manual)
+
+Skip this if step 1 copied it with `--provision`.
+
+Rename/copy to:
+
+- Development → `assets/meta/deployments/ios/apple/development.mobileprovision`
+- App Store → `assets/meta/deployments/ios/apple/app-store.mobileprovision`
+
+### 7. Optional: record the `.p12` passphrase
+
+Skip this if `apple-signing` already wrote `build.json`.
+
+Create or merge `assets/meta/deployments/ios/build.json`:
+
+```json
+{
+  "apple": {
+    "p12Password": "(your .p12 passphrase)"
+  }
+}
+```
+
+### 8. Helper: App Store Connect login (`apple.json`)
+
+Required only for App Store uploads.
+
+**Helper:** `npx adaptfully apple-publish [--deployment ios]`
+
+If you run this, **skip to step 10**.
+
+You need an [app-specific password](https://appleid.apple.com/) for your Apple ID.
+
+### 9. Manual alternative: write `apple.json`
+
+Skip this if you used step 8.
+
+```json
+{
+  "category": "public.app-category.games",
+  "identity": "(your team id)",
+  "username": "(Apple ID email)",
+  "password": "(app-specific password)"
+}
+```
+
+### 10. Done when
+
+- [ ] For `ios-dev`: `apple/development.p12` + `apple/development.mobileprovision`
+- [ ] For App Store: `apple/distribution.p12` + `apple/app-store.mobileprovision` + `apple.json`
+- [ ] `apple.p12Password` matches the `.p12` passphrase when the passphrase is non-empty
+- [ ] App ID matches `packageName`; Sign in with Apple enabled if you use Capgo Apple auth
+- [ ] Credential paths are gitignored
+
+## Notes
+
+- Filenames under `apple/` must match the table above.
+- You can create credentials on Windows even if the IPA is built elsewhere.
+- Re-run `apple-signing --kind …` separately for development and distribution when you need both.

package/docs/credentials/steam.md

@@ -0,0 +1,99 @@
+# Steam credentials
+
+Set up Steamworks upload login for release deploys. Debug Steam builds need no upload credentials.
+
+**Default folder:** `assets/meta/deployments/steam/`
+
+## Recommended path
+
+1. Create or choose a Steamworks **build account** (manual; prefer a dedicated publisher account).
+2. **Helper:** `npx adaptfully steam-publish` — installs steamcmd if needed, logs in interactively, writes `steam.json`.
+3. Set upload `steamId` on the deployment `manifest.json` (and client `platforms.*.steamId` if you use Steamworks auth).
+
+## What you need
+
+| Goal | Files |
+|------|--------|
+| `steam-dev` (local Electron debug) | None |
+| `steam` release upload | `steam.json` (+ `manifest.json` with upload `steamId`) |
+
+## Full steps
+
+### 1. Prerequisites
+
+- A Steamworks partner app.
+- A Steam account allowed to upload builds (Steam Guard may be enabled).
+
+### 2. Helper: write `steam.json`
+
+**Helper:** `npx adaptfully steam-publish [--username U] [--password P] [--deployment steam]`
+
+If you run this, **skip to step 6**.
+
+The helper installs steamcmd under `~/.adaptfully/steamcmd` when needed, logs in (enter a Steam Guard code if prompted), and writes `assets/meta/deployments/steam/steam.json`.
+
+### 3. Manual alternative: install steamcmd
+
+Skip this if you used step 2.
+
+Download steamcmd for your OS from Valve and unpack it somewhere durable.
+
+### 4. Manual alternative: log in once
+
+Skip this if you used step 2.
+
+```bash
+steamcmd +login YOUR_USER YOUR_PASSWORD +quit
+```
+
+Complete Steam Guard if prompted. After a successful login, steamcmd stores session files under its install directory (`config/config.vdf`, and an `ssfn*` sentry file when Guard is enabled).
+
+### 5. Manual alternative: assemble `steam.json`
+
+Skip this if you used step 2.
+
+Create `assets/meta/deployments/steam/steam.json`:
+
+```json
+{
+  "username": "(your Steam build account)",
+  "password": "(your password)",
+  "configVdf": "(base64 of config/config.vdf)",
+  "sentryFileName": "(ssfn filename — only with Steam Guard)",
+  "sentryFile": "(base64 of the ssfn file — only with Steam Guard)"
+}
+```
+
+Accounts **without** Steam Guard only need `username`, `password`, and `configVdf`.
+
+### 6. App IDs (client vs upload)
+
+These are independent:
+
+| Setting | Purpose |
+|---------|---------|
+| `config.platforms.<name>.steamId` | Client Steamworks / `steam-auth` |
+| `assets/meta/deployments/steam/manifest.json` → `steamId` | Depot upload target |
+
+You can ship with Steam auth and no upload credentials, or upload without client Steamworks.
+
+Example `manifest.json`:
+
+```json
+{
+  "type": "steam",
+  "steamId": 480
+}
+```
+
+### 7. Done when
+
+- [ ] For uploads: `steam.json` exists and login tokens are valid
+- [ ] Upload `steamId` is set on the deployment manifest
+- [ ] Client `steamId` is set on the platform if you use Steamworks auth
+- [ ] Credential files are gitignored
+
+## Notes
+
+- Re-run `adaptfully steam-publish` when Steam invalidates the token (new machine, password change, or expired Guard).
+- `steam-dev` never requires `steam.json`.