@maccesar/titools 4.4.2 → 4.6.1

package/skills/purgetss/references/app-branding.md

@@ -1,32 +1,38 @@
 # App Icons & Branding
 
-The `purgetss brand` command (introduced in PurgeTSS v7.6.0, restructured in v7.7.0, extended in v7.10.0 with the Google Play Feature Graphic) generates the complete Titanium branding set from a single SVG or PNG logo — with optional Android-specific overrides when you need them: launcher icons across every Android density, the adaptive-icon trio (foreground + background + monochrome), iOS 18+ Dark and Tinted variants, marketplace artwork (including the 1024×500 Feature Graphic for Google Play), and optional notification/splash icons. Alloy and Classic layouts are auto-detected.
+The `purgetss brand` command (introduced in v7.6.0, grouped config in v7.7.0, restructured into per-piece blocks in v7.13.0) regenerates **every image the Titanium template ships**, from one main SVG or PNG logo: launcher icons, adaptive icons, iOS 18+ Dark/Tinted variants, marketplace artwork, and both the iOS and Android splash sets. Per-piece overrides are there when you need them. Alloy and Classic layouts are auto-detected.
+
+The rule is simple: **if the template ships the file, `brand` updates it.** You should never have to know which API still reads which file to avoid shipping an app with the grey Alloy logo somewhere in it.
 
 For the terse flag reference, see the [`brand` command reference](./cli-commands.md#brand-command). For sibling UI assets, see [Multi-Density Images](./multi-density-images.md).
 
-> **INFO**
+> **WARNING**
 >
-> The `brand` command at a glance
-> `purgetss brand` turns one logo into every asset a Titanium app needs to ship — launcher icons, adaptive icons, iOS 18+ Dark/Tinted variants, marketplace artwork, and optional notification/splash icons. Works on both Alloy and Classic projects.
+> Breaking changes in v7.13.0
+> `--splash` → `--splash-icon`, `--notification` → `--notification-icon`, `--splash-logo` → `--splash-icon-logo`, `--feature-logo` → `--feature-graphic-logo`. `--icon-logo` now feeds the `icon` piece (the Android launcher source is `--adaptive-logo`). `--legacy-splash` is gone: the per-qualifier Android splashes belong to `android-splash` and are always generated. **No flag aliases were kept.** The `brand:` config block also changed shape, but that one updates itself — see [Older configs update themselves](#older-configs-update-themselves).
 
 <!-- TOC-START -->
 ## Contents
 
 - [Quick start](#quick-start)
 - [The `purgetss/brand/` convention](#the-purgetssbrand-convention)
-- [The `brand:` config section (v7.7.0 grouped structure)](#the-brand-config-section-v770-grouped-structure)
+- [The `brand:` config section](#the-brand-config-section)
+- [Brand config reference](#brand-config-reference)
 - [Overwrite confirmation](#overwrite-confirmation)
 - [What gets generated](#what-gets-generated)
+- [Shrinking the generated files](#shrinking-the-generated-files)
+- [Regenerating a single piece with `--only`](#regenerating-a-single-piece-with---only)
 - [Android dark mode](#android-dark-mode)
 - [Android 12+ splash artwork](#android-12-splash-artwork)
-- [Android legacy splash fallback](#android-legacy-splash-fallback)
+- [Android pre-12 splash](#android-pre-12-splash)
+- [The iOS launch screen and LaunchLogo.png](#the-ios-launch-screen-and-launchlogopng)
+- [iPhone launch images](#iphone-launch-images)
 - [iOS 18+ Dark and Tinted variants](#ios-18-dark-and-tinted-variants)
-- [Google Play Feature Graphic (v7.10.0)](#google-play-feature-graphic-v7100)
 - [Brand color](#brand-color)
 - [Padding guidance](#padding-guidance)
 - [Cleanup legacy branding artifacts](#cleanup-legacy-branding-artifacts)
 - [Troubleshooting](#troubleshooting)
-- [Full flag reference](#full-flag-reference)
+- [Flag reference](#flag-reference)
 - [Community-Discovered Patterns](#community-discovered-patterns)
 - [See also](#see-also)
 
@@ -34,7 +40,7 @@ For the terse flag reference, see the [`brand` command reference](./cli-commands
 
 ## Quick start
 
-Drop a logo file into `purgetss/brand/`, then run the command. That's the whole workflow.
+Drop a logo file into `purgetss/brand/`, then run the command.
 
 ```bash
 mkdir -p purgetss/brand            # if the folder doesn't exist yet
@@ -59,45 +65,48 @@ purgetss brand --dry-run
 
 `init` creates `purgetss/brand/` (alongside `fonts/` and `images/`) so the folder is already there the first time you look for it, even before you've dropped in a logo.
 
-PurgeTSS auto-discovers logo files under this folder, the same way `purgetss/fonts/` works for fonts. Drop files with these names and you're done — no flags, no config:
+PurgeTSS auto-discovers logo files under this folder, the same way `purgetss/fonts/` works for fonts. The naming rule is `logo-<piece>`, using the same piece names the CLI and the config use. Drop a file in and you're done:
 
 ```text
 purgetss/brand/
-├── logo.svg              required — main logo (or logo.png)
-├── logo-icon.svg         optional — square Android launcher mark
-├── logo-mono.svg         optional — monochrome layer + notifications
-├── logo-dark.svg         optional — iOS 18+ dark variant
-├── logo-splash.svg       optional — Android 12+ splash icon override
-├── logo-tinted.svg       optional — iOS 18+ tinted variant
-└── logo-feature.svg      optional — Google Play Feature Graphic (1024×500) override
+├── logo.svg                   required — main logo (or logo.png), source for every piece
+├── logo-mono.svg              optional — monochrome layer + notification icons
+├── logo-icon.svg              optional — DefaultIcon.png + DefaultIcon-ios.png
+├── logo-adaptive.svg          optional — square Android launcher mark
+├── logo-dark.svg              optional — iOS 18+ dark variant
+├── logo-tinted.svg            optional — iOS 18+ tinted variant
+├── logo-launch.svg            optional — iOS launch screen logotype (LaunchLogo.png)
+├── logo-splash-icon.svg       optional — Android 12+ splash icon override
+├── logo-android-splash.svg    optional — Android <12 splash artwork
+├── logo-ios-splash.svg        optional — iPhone launch images
+├── logo-marketplace.svg       optional — App Store / Play Store artwork
+├── logo-feature-graphic.svg   optional — Google Play Feature Graphic override
+├── logo-legacy-icon.svg       optional — legacy ic_launcher.png
+├── logo-appicon.svg           optional — appicon.png
+└── logo-notification-icon.svg optional — notification icons
 ```
 
-Only `logo.svg` (or `logo.png`) is required. Everything else is **opt-in refinement**:
-
-| File | Required? | What it's for | Fallback when omitted |
-| --- | --- | --- | --- |
-| `logo.svg` / `logo.png` | **Required** | Main colored logo. Feeds every density and variant. | — |
-| `logo-icon.svg` / `.png` | Optional | Square Android launcher mark — use when `logo.svg` is a wide wordmark or non-square lockup. | Main logo is reused for Android launcher icons. |
-| `logo-mono.svg` / `.png` | Optional | Android adaptive monochrome layer (themed icons on Android 13+) and notification icons. | Main logo is whitened automatically. |
-| `logo-splash.svg` / `.png` | Optional | Android 12+ `splash_icon.png` artwork (only used when `--splash` / `android.splash: true`). | Falls back to the launcher artwork. |
-| `logo-dark.svg` / `.png` | Optional | iOS 18+ Dark appearance variant. | Main logo on a transparent background (Apple HIG default). |
-| `logo-tinted.svg` / `.png` | Optional | iOS 18+ Tinted appearance variant. | Grayscale of the main logo on black. |
-| `logo-feature.svg` / `.png` | Optional | Google Play Feature Graphic (1024×500). Use when the Play Store banner should differ from the main app icon (e.g. logo + tagline lockup that fills the wider rectangular canvas). | Main logo is centered inside the banner with configured vertical padding. |
-
-Provide a dedicated `logo-icon` when the main logo is a horizontal wordmark, a vertical lockup, or anything else that looks fine in a 1024×1024 branding canvas but feels cramped inside an Android launcher mask.
+Only `logo.svg` (or `logo.png`) is required. Every other file is an override for one piece, and dropping it in is all it takes. There is no syntax to remember, and opening the folder shows what has been customized.
 
-Provide a dedicated `logo-mono` when the colored logo has detail that would collapse into a featureless blob under naive whitening (e.g. a painter's palette with colored dots — the monochrome variant should have cutouts instead).
+Every one of them has a CLI equivalent, `--<piece>-logo <path>`, and a config equivalent, `brand.<piece>.logo`, for artwork that lives outside `purgetss/brand/`.
 
-Provide a dedicated `logo-splash` when the Android 12+ splash should use a different composition than the launcher icon. PurgeTSS generates the file, but Titanium still needs a custom Android splash theme if you want the system splash to use it instead of `ic_launcher`.
+The ones worth knowing about:
 
-Provide a dedicated `logo-dark` when dark-mode brand guidelines use a different lockup or color treatment; provide `logo-tinted` when you want a pre-simplified silhouette that tints better than a naive grayscale of the colored version.
-
-Provide a dedicated `logo-feature` when the Google Play Feature Graphic (1024×500) should use a different composition than the main app icon — for example a logo-plus-tagline lockup or a wider artwork that takes advantage of the rectangular canvas instead of being constrained to the centered square.
+| File | What it's for | Fallback when omitted |
+| --- | --- | --- |
+| `logo-icon` | Alternate artwork for `DefaultIcon.png` / `DefaultIcon-ios.png`, when the universal icon should differ from the main logo. | Main logo. |
+| `logo-adaptive` | A separate **square** mark for Android launcher icons. Use it when the main logo is a horizontal wordmark, a vertical lockup, or anything else that looks fine on a 1024×1024 canvas but feels cramped inside an Android launcher mask. | Main logo. |
+| `logo-mono` | Silhouette for the Android adaptive monochrome layer (themed icons on Android 13+) and for notification icons. | Main logo, whitened automatically. |
+| `logo-dark` | iOS 18+ dark mode. Provide your own when dark-mode brand guidelines use a different lockup or color treatment. | Main logo on a transparent background (Apple's recommended approach). |
+| `logo-tinted` | iOS 18+ tinted mode. Provide your own when a simpler silhouette tints better than a grayscale of the colored version. | Grayscale of the main logo. |
+| `logo-launch` | The only file that also **activates** a piece. Drop it in and `brand` writes `LaunchLogo.png`, so the iOS launch screen shows your logotype instead of the app icon. See [The iOS launch screen and LaunchLogo.png](#the-ios-launch-screen-and-launchlogopng). | Piece is not generated. |
+| `logo-splash-icon` | Alternate artwork for Android 12+ `splash_icon.png`, when the splash should use a different composition than the launcher icon. | Launcher artwork. |
+| `logo-feature-graphic` | Alternate logo for the Google Play Feature Graphic (1024×500 banner) — a logo-plus-tagline lockup, say, or wider artwork that uses the rectangular canvas instead of staying inside the centered square. | Main logo, centered with the configured vertical padding. |
 
 > **INFO**
 >
 > Prefer SVG for the master
-> SVG scales losslessly to every density Sharp needs to emit. A single `logo.svg` rasterizes perfectly at every `res-*dpi` output. PNG masters should be at least **1024×1024** to avoid upscaling artifacts.
+> SVG scales cleanly to every density Sharp needs to emit. A single `logo.svg` can be rasterized at every `res-*dpi` output. PNG masters should be at least **1024×1024** to avoid upscaling artifacts.
 
 ### Overriding auto-discovery
 
@@ -107,143 +116,146 @@ You can also pass a path directly or point to a logo from the config. Useful whe
 purgetss brand ./docs/snap-logo.svg
 ```
 
-Or in `purgetss/config.cjs`:
+Or in `purgetss/config.cjs`, where each piece takes its own `logo`:
 
 ```javascript
 brand: {
-  logos: {
-    primary: './docs/snap-logo.svg',
-    androidLauncher: './docs/snap-app-icon.svg',
-    monochrome: './docs/snap-logo-mono.svg',
-    featureGraphic: './docs/snap-feature.svg'   // optional — Google Play Feature Graphic
-  }
+  adaptive: { logo: './docs/snap-app-icon.svg' },
+  featureGraphic: { logo: './docs/snap-feature.svg' },
+  monochromeLogo: './docs/snap-logo-mono.svg'
 }
 ```
 
 Precedence: **CLI flags win over config values, and config values win over auto-discovery.**
 
-## The `brand:` config section (v7.7.0 grouped structure)
+### How the work is divided between files and config
+
+- **Files decide the artwork.** Dropping `logo-dark.svg` next to `logo.svg` is enough; open the folder and you can see what has been customized. This is the main path.
+- **Config decides numbers, colors and activation**, none of which can be expressed with a filename.
+- `logo:` inside a piece is there for artwork that lives outside `purgetss/brand/`.
+
+## The `brand:` config section
 
-On the first run, `purgetss brand` injects a `brand:` block into your existing `purgetss/config.cjs` (between `purge:` and `theme:`) with these defaults. The structure is grouped by purpose:
+On the first run, `purgetss brand` adds a `brand:` block to your existing `purgetss/config.cjs`, between `purge:` and `theme:`. It has **one block per piece**:
 
 ```javascript
 brand: {
-  logos: {
-    // Optional overrides. If omitted, PurgeTSS auto-discovers files from purgetss/brand/:
-    // primary: './docs/logo.svg',
-    // androidLauncher: './docs/app-icon.svg',
-    // androidSplash: './docs/splash.svg',
-    // monochrome: './docs/logo-mono.svg',
-    // iosDark: './docs/logo-dark.svg',
-    // iosTinted: './docs/logo-tinted.svg'
-  },
-  padding: {
-    ios: '4%',              // iOS aesthetic padding. Range 2-8%. No launcher mask.
-    androidLegacy: '10%',   // legacy ic_launcher.png padding %
-    androidAdaptive: '19%', // adaptive icon safe-zone %. Spec floor 19.44%.
-    featureGraphic: '12%'   // vertical padding for MarketplaceArtworkFeature.png (1024×500)
-  },
-  android: {
-    splash: false,         // also generate splash_icon.png × 5
-    notification: false    // also generate ic_stat_notify.png × 5
-  },
-  colors: {
-    background: '#FFFFFF'  // Android adaptive bg + iOS/marketplace flatten
-  },
-  // Optional iOS overrides:
-  // ios: {
-  //   dark: false,           // skip DefaultIcon-Dark.png
-  //   tinted: false,         // skip DefaultIcon-Tinted.png
-  //   darkBackground: '#111' // opaque dark bg for DefaultIcon-Dark.png (null = transparent per Apple HIG)
-  // },
-  confirmOverwrites: true  // prompt before overwriting files (set false to skip)
+  background: '#FFFFFF',   // inherited by every piece that doesn't set its own
+  confirmOverwrites: true, // prompt before overwriting files (set false to skip)
+  optimize: false,         // true = quantize the generated PNGs to a palette (lossy, ~71% smaller)
+
+  // One block per piece. Artwork comes from purgetss/brand/logo-<piece>.{svg,png};
+  // these keys are for numbers, colors and activation. Padding is never inherited.
+  icon:             { padding: '4%' },    // DefaultIcon.png + DefaultIcon-ios.png
+  dark:             { background: null }, // DefaultIcon-Dark.png
+  tinted:           {},                   // DefaultIcon-Tinted.png
+  iosSplash:        { padding: '26%' },   // assets/iphone/Default*.png × 16
+  launchLogo:       { padding: '12%' },   // LaunchLogo.png (1024×1024)
+  marketplace:      {},                   // iTunesConnect.png + MarketplaceArtwork.png
+  featureGraphic:   { padding: '12%' },   // MarketplaceArtworkFeature.png (1024×500)
+  adaptive:         { padding: '18%' },   // ic_launcher_{foreground,background,monochrome}.png × 5 + ic_launcher.xml
+  legacyIcon:       { padding: '10%' },   // ic_launcher.png × 5
+  appicon:          {},                   // appicon.png (128×128)
+  androidSplash:    { padding: '26%' },   // assets/android/default.png + images/res-*/default.png × 11
+
+  // Opt-in: inert until you edit the Android theme / FCM meta-data by hand.
+  splashIcon:       { enabled: false },   // drawable-*/splash_icon.png × 5
+  notificationIcon: { enabled: false },   // drawable-*/ic_stat_notify.png × 5
+  ninePatch:        { enabled: false }    // background.9.png (not implemented yet)
 }
 ```
 
-The recommended workflow is convention-first: drop files in `purgetss/brand/`, let auto-discovery pick them up, and only set `brand.logos.*` when you have a persistent override. CLI flags still win for one-off runs.
+Change only what you want to keep as a project default. CLI flags still win for one-off runs.
 
-### `brand.logos`
+### Older configs update themselves
 
-All `logos.*` keys are optional path overrides. If you omit them, PurgeTSS auto-discovers files from `purgetss/brand/`.
+PurgeTSS keeps `config.cjs` current the same way it renamed `config.js` to `config.cjs`: **on the file, once**. When the `brand:` block uses a shape from an earlier version, the next run rewrites it to the per-piece structure and carries over everything that had been customized (paddings, colors, logo paths, enabled flags), then lists each value it moved:
 
-| Key | Auto-discovers | Purpose |
-| --- | --- | --- |
-| `logos.primary` | `purgetss/brand/logo.svg` | Main brand source. |
-| `logos.androidLauncher` | `purgetss/brand/logo-icon.svg` | Square Android launcher mark — use when the main logo is a wordmark. |
-| `logos.androidSplash` | `purgetss/brand/logo-splash.svg` | Android 12+ splash artwork. |
-| `logos.monochrome` | `purgetss/brand/logo-mono.svg` | Android themed icons + notification icons. |
-| `logos.iosDark` | `purgetss/brand/logo-dark.svg` | iOS dark variant. |
-| `logos.iosTinted` | `purgetss/brand/logo-tinted.svg` | iOS tinted variant. |
-| `logos.featureGraphic` | `purgetss/brand/logo-feature.svg` | Google Play Feature Graphic source (1024×500 rectangular canvas). |
-
-### `brand.padding`
-
-All padding values accept either numbers or percentage strings like `'19%'`.
+```text
+::PurgeTSS:: Updated the brand: structure in ./purgetss/config.cjs.
+  Your values were carried over:
+    • brand.logos.androidLauncher → brand.adaptive.logo
+    • brand.padding.androidAdaptive → brand.adaptive.padding
+    • brand.android.splash → brand.splashIcon.enabled
+    • brand.colors.background → brand.background
+```
 
-| Key | Default | Purpose |
-| --- | --- | --- |
-| `padding.ios` | `'4%'` | Visual inset for `DefaultIcon-ios.png`, `DefaultIcon-Dark.png`, `DefaultIcon-Tinted.png`, marketplace artwork. |
-| `padding.androidLegacy` | `'10%'` | Visual inset for legacy `ic_launcher.png`. |
-| `padding.androidAdaptive` | `'19%'` | Visual inset for adaptive Android foreground (`ic_launcher_foreground.png`). Adjust this first when icons look cropped inside launcher masks. |
-| `padding.featureGraphic` | `'12%'` | Vertical padding (top + bottom) for `MarketplaceArtworkFeature.png` (1024×500 Google Play banner). The logo is rendered as a square block of side `500 - 2 × pad` centered horizontally and vertically. Lower it for a more impactful banner; raise it if the logo looks cramped against the top or bottom edge on smaller Play Store crops. |
+This happens on `purgetss brand`, and on any command that goes through the config: `build`, `watch`, `purge`, `shades`. Values that already matched a default are not written, so a block that was never customized comes out clean rather than cluttered with redundant keys.
 
-### `brand.android`
+Both earlier shapes are recognized: the original flat keys (`brand.padding` as a number, `brand.iosPadding`, `brand.bgColor`, `brand.darkBgColor`, top-level `brand.notification` / `brand.splash`) and the grouped sections from v7.7.0 (`logos` / `padding` / `android` / `ios` / `colors`). One key is dropped rather than moved: `brand.android.legacySplash`, because the per-qualifier splashes belong to `androidSplash` now and are always generated. The run says so when it happens.
 
-| Key | Default | Purpose |
-| --- | --- | --- |
-| `android.splash` | `false` | When `true`, also generates `drawable-*/splash_icon.png`. |
-| `android.notification` | `false` | When `true`, also generates `drawable-*/ic_stat_notify.png`. |
+The command itself understands exactly one structure. Nothing translates on the fly, so the day this migration is removed, nothing else changes.
 
-### `brand.ios` (optional)
+> **INFO**
+>
+> This replaced the in-memory translation that ran from v7.10.2 to v7.12.1. Back then `normalizeLegacyBrand()` re-translated the old shape on **every** config read — every purge, watch and build, forever. Now the file is fixed once and every command afterwards reads one shape.
 
-If omitted, PurgeTSS behaves as if `ios.dark = true`, `ios.tinted = true`, `ios.darkBackground = null`.
+### Unknown keys are an error
 
-| Key | Default | Purpose |
-| --- | --- | --- |
-| `ios.dark` | `true` | Set to `false` to skip `DefaultIcon-Dark.png`. |
-| `ios.tinted` | `true` | Set to `false` to skip `DefaultIcon-Tinted.png`. |
-| `ios.darkBackground` | `null` | When `null`, `DefaultIcon-Dark.png` stays transparent per Apple HIG. Set a hex to bake in an opaque dark background. |
+A key `brand:` does not define stops the run before a single file is written, at both levels:
 
-### `brand.colors`
+```text
+Unknown key(s) in the brand: section of purgetss/config.cjs:
+  • brand.adaptive.paddig
 
-| Key | Default | Purpose |
-| --- | --- | --- |
-| `colors.background` | `'#FFFFFF'` | Triple-purpose: Android adaptive background layer, iOS alpha flatten for `DefaultIcon-ios.png`, marketplace flatten for `iTunesConnect.png` / `MarketplaceArtwork.png` when overridden. |
+  Top-level keys: background, confirmOverwrites, logo, monochromeLogo
+  Piece blocks:   icon, dark, tinted, iosSplash, launchLogo, marketplace, featureGraphic,
+                  adaptive, legacyIcon, appicon, androidSplash, splashIcon,
+                  notificationIcon, ninePatch
+  Inside a piece: logo, padding, background, enabled
 
-### `brand.confirmOverwrites`
+  Check the spelling. Nothing was written.
+```
 
-| Key | Default | Purpose |
-| --- | --- | --- |
-| `confirmOverwrites` | `true` | When `false`, the `[y/N/a]` prompt is skipped. |
+A typo is deliberately **not** treated as an old structure: rewriting the block would drop it silently. And ignoring a misspelled `paddig` would be worse than stopping — the whole icon set would render at the wrong size and look perfectly plausible.
 
-### Upgrading from pre-7.7.0 configs
+## Brand config reference
 
-In v7.7.0, the `brand:` block was reorganized into grouped subsections (`logos`, `padding`, `android`, `ios`, `colors`). Since **v7.10.2**, if your `config.cjs` still uses the original flat layout, PurgeTSS auto-migrates it **in memory on every run** — your old config keeps working without any change on disk.
+Every piece accepts the same four keys, where they apply:
 
-| Pre-7.7.0 flat key | Current grouped key |
+| Key | What it does |
 | --- | --- |
-| `brand.padding: <number\|string>` (single value) | `brand.padding.androidLegacy` **and** `brand.padding.androidAdaptive` (same value applied to both) |
-| `brand.iosPadding` | `brand.padding.ios` |
-| `brand.bgColor` | `brand.colors.background` |
-| `brand.darkBgColor` | `brand.ios.darkBackground` |
-| `brand.notification` | `brand.android.notification` |
-| `brand.splash` | `brand.android.splash` |
-
-If both legacy and grouped keys are present for the same property, the **grouped key wins**.
+| `logo` | Path to this piece's artwork, when it lives outside `purgetss/brand/`. |
+| `padding` | Inset per side, as a number or a percentage string like `'19%'`. **Never inherited.** |
+| `background` | Hex color, or `null` for transparent. Inherited from `brand.background`. |
+| `enabled` | `false` turns a default piece off; `true` turns an opt-in piece on. |
 
-On first encounter per session, PurgeTSS prints a one-time deprecation notice listing the legacy keys it migrated:
+And these live at the top level:
 
-```text
-::PurgeTSS:: Legacy brand: schema detected in purgetss/config.cjs — auto-migrated in memory:
-     • brand.padding: 15 → brand.padding.androidLegacy + brand.padding.androidAdaptive
-     • brand.iosPadding → brand.padding.ios
-     • brand.bgColor → brand.colors.background
-     Update purgetss/config.cjs to the new grouped schema to silence this warning.
-```
-
-The notice is suppressed once you update the file to the grouped layout. Auto-migration is purely transitional and may be removed in a future major version, so a one-time update to your `config.cjs` is recommended.
-
-Prior to v7.10.2, projects on the flat layout crashed auto-purge with `TypeError: Cannot create property 'ios' on number '15'` because `brand.padding` was a number rather than an object. v7.10.2 normalizes the shape before defaults are applied.
+| Key | Default | Purpose |
+| --- | --- | --- |
+| `background` | `'#FFFFFF'` | The background every piece inherits unless it declares its own: the Android adaptive background layer, the `DefaultIcon-ios.png` flatten, the splash canvases, and the marketplace flatten when a background is explicitly configured. |
+| `confirmOverwrites` | `true` | Whether `brand` asks before overwriting project files in place. |
+| `optimize` | `false` | Quantize the generated PNGs to a palette. Lossy — see [Shrinking the generated files](#shrinking-the-generated-files). |
+| `logo` | — | Path override for the main logo. |
+| `monochromeLogo` | — | Path override for the silhouette shared by the adaptive monochrome layer and the notification icons. |
+
+### The pieces
+
+| Piece | Config key | Generates | Default padding | On by default |
+| --- | --- | --- | --- | --- |
+| `icon` | `icon` | `DefaultIcon.png` + `DefaultIcon-ios.png` | `4%` | yes |
+| `dark` | `dark` | `DefaultIcon-Dark.png` | `4%` | yes |
+| `tinted` | `tinted` | `DefaultIcon-Tinted.png` | `4%` | yes |
+| `ios-splash` | `iosSplash` | `assets/iphone/Default*.png` × 16 | `26%` | yes |
+| `launch-logo` | `launchLogo` | `LaunchLogo.png` (1024×1024) | `12%` | when `logo-launch.*` exists |
+| `marketplace` | `marketplace` | `iTunesConnect.png` + `MarketplaceArtwork.png` | `4%` | yes |
+| `feature-graphic` | `featureGraphic` | `MarketplaceArtworkFeature.png` (1024×500) | `12%` | yes |
+| `adaptive` | `adaptive` | `ic_launcher_{foreground,background,monochrome}.png` × 5 + `ic_launcher.xml` | `18%` | yes |
+| `legacy-icon` | `legacyIcon` | `ic_launcher.png` × 5 | `10%` | yes |
+| `appicon` | `appicon` | `appicon.png` (128×128) | `10%` | yes |
+| `android-splash` | `androidSplash` | `assets/android/default.png` + `images/res-*/default.png` × 11 | `26%` | yes |
+| `splash-icon` | `splashIcon` | `drawable-*/splash_icon.png` × 5 | — | `--splash-icon` |
+| `notification-icon` | `notificationIcon` | `drawable-*/ic_stat_notify.png` × 5 | — | `--notification-icon` |
+| `nine-patch` | `ninePatch` | `background.9.png` | — | `--nine-patch` (not implemented yet) |
+
+`ic_launcher.xml` always travels inside `adaptive`; it is never generated on its own.
+
+Only three pieces are opt-in, and for one reason: they produce nothing useful until you edit XML by hand. `splash_icon.png` is inert without `windowSplashScreenAnimatedIcon` in the theme, and `ic_stat_notify.png` is inert without the FCM `meta-data` entry.
+
+### `background` is inherited, `padding` is not
+
+Set `brand.background` once and every piece picks it up. Padding works the other way on purpose: the defaults answer to different constraints. The adaptive `18%` answers to the Android launcher mask, while the iOS `4%` is an aesthetic choice with no mask behind it. A single inherited number would let `8%` quietly break the launcher mask, so padding is set per piece or not at all.
 
 ## Overwrite confirmation
 
@@ -279,24 +291,29 @@ The output is automatically routed to the right directory for your project layou
 ```text
 <project>/
 ├── DefaultIcon.png                 ← 1024×1024, universal fallback (Android-safe padding)
-├── DefaultIcon-ios.png             ← 1024×1024, iOS flattened on bgColor
+├── DefaultIcon-ios.png             ← 1024×1024, iOS flattened on brand.background
 ├── DefaultIcon-Dark.png            ← 1024×1024, iOS 18+ dark (transparent per Apple HIG)
 ├── DefaultIcon-Tinted.png          ← 1024×1024, iOS 18+ tinted (grayscale on black)
 ├── iTunesConnect.png               ← 1024×1024, App Store submission
 ├── MarketplaceArtwork.png          ← 512×512, Google Play submission
-├── MarketplaceArtworkFeature.png   ← 1024×500, Google Play Feature Graphic (v7.10.0)
+├── MarketplaceArtworkFeature.png   ← 1024×500, Google Play Feature Graphic
 └── app/
-    └── assets/android/
-        ├── default.png             ← legacy Titanium Android splash fallback (v7.7.0)
-        └── res/
-            ├── mipmap-mdpi/        ← 108×108 foreground + background + monochrome + legacy
-            ├── mipmap-hdpi/        ← 162×162
-            ├── mipmap-xhdpi/       ← 216×216
-            ├── mipmap-xxhdpi/      ← 324×324
-            ├── mipmap-xxxhdpi/     ← 432×432
-            ├── drawable-*/         ← optional splash_icon.png when --splash is enabled
-            └── mipmap-anydpi-v26/
-                └── ic_launcher.xml ← adaptive-icon binder
+    ├── assets/iphone/
+    │   ├── Default*.png            ← the 16 launch images the template ships
+    │   └── LaunchLogo.png          ← 1024×1024, only when logo-launch.* exists
+    ├── assets/android/
+    │   ├── appicon.png             ← 128×128
+    │   ├── default.png             ← Android <12 splash
+    │   └── images/res-*/default.png ← the 11 per-qualifier splashes
+    └── platform/android/res/
+        ├── mipmap-mdpi/            ← 108×108 foreground + background + monochrome + legacy
+        ├── mipmap-hdpi/            ← 162×162
+        ├── mipmap-xhdpi/           ← 216×216
+        ├── mipmap-xxhdpi/          ← 324×324
+        ├── mipmap-xxxhdpi/         ← 432×432
+        ├── drawable-*/             ← optional splash_icon.png with --splash-icon
+        └── mipmap-anydpi-v26/
+            └── ic_launcher.xml     ← adaptive-icon binder
 ```
 
 **Classic layout:**
@@ -304,21 +321,102 @@ The output is automatically routed to the right directory for your project layou
 ```text
 <project>/
 ├── DefaultIcon.png  DefaultIcon-ios.png  ...     ← same root-level files as Alloy
-├── MarketplaceArtworkFeature.png   ← 1024×500, Google Play Feature Graphic (v7.10.0)
+├── MarketplaceArtworkFeature.png   ← 1024×500, Google Play Feature Graphic
 ├── Resources/
-│   └── android/default.png         ← legacy Titanium Android splash fallback (v7.7.0)
+│   ├── iphone/Default*.png         ← the launch images the template ships
+│   └── android/
+│       ├── appicon.png             ← 128×128
+│       └── default.png             ← Android <12 splash
 └── platform/
     └── android/res/
         ├── mipmap-*/               ← same 5 densities as Alloy
-        ├── drawable-*/             ← optional splash_icon.png when --splash is enabled
+        ├── drawable-*/             ← optional splash_icon.png with --splash-icon
         └── mipmap-anydpi-v26/ic_launcher.xml
 ```
 
+A Classic project has no `images/res-*` folders, so the per-qualifier splashes are simply skipped there.
+
 The Android outputs are related, but they are not interchangeable:
 
-- `ic_launcher*` drives the app icon, and by default also feeds the Android 12+ system splash
-- `splash_icon.png` is only generated when you ask for it with `--splash`
-- `default.png` is the older Titanium Android splash fallback (regenerated since v7.7.0)
+- `ic_launcher*` drives the app icon, and by default it also feeds the Android 12+ system splash
+- `splash_icon.png` is only generated when you ask for it with `--splash-icon`
+- `default.png` and `images/res-*/default.png` are the Android <12 splash path
+- `appicon.png` is the fallback Titanium uses for `tiapp.xml`'s `<icon>` when the manifest declares no `android:icon`
+
+### Why files that "no longer matter" are regenerated
+
+Several of these are read by nothing in a modern build. With `<enable-launch-screen-storyboard>` enabled — the default since Titanium 8 — iOS draws the storyboard and never opens the 16 `Default*.png`. `appicon.png` only comes into play when the Android manifest declares no `android:icon`.
+
+They are regenerated anyway, because the alternative is worse: the template ships them with the grey Alloy logo, and deciding which ones to skip would mean asking you to keep track of which Titanium and OS version reads which file. If it is in the project tree, it carries your logo.
+
+To skip the ones you know you don't need, use [`--only`](#regenerating-a-single-piece-with---only). To delete them outright, see [Cleanup legacy branding artifacts](#cleanup-legacy-branding-artifacts).
+
+## Shrinking the generated files
+
+`brand` writes truecolor PNGs. Logos are flat artwork with few distinct colors, which is exactly the case where a 256-color palette is indistinguishable from truecolor at a fraction of the size — the same trick TinyPNG and pngquant use.
+
+It is off by default because it is lossy. Turn it on per run or for the project:
+
+```bash
+purgetss brand --optimize
+```
+
+```javascript
+brand: {
+  optimize: true
+}
+```
+
+`--no-optimize` skips the pass on a single run even when the config asks for it.
+
+On the reference project, the full set of 56 PNGs goes from **1.6 MB to 476 KB, 71% smaller**. Measured on the visible pixels of the generated icons, the difference against the truecolor version averages 0.08–0.19 out of 255, with no channel exceeding 16/255: indistinguishable in practice on flat artwork. Transparency survives too — `DefaultIcon-Dark.png` keeps its alpha channel and the same 67% transparent pixels.
+
+### What "lossy" means here, in numbers
+
+The loss is real: the generated icons carry between 950 and 4,300 distinct visible colors, not because the logo has that many, but because every curved edge and every letter of small text produces hundreds of intermediate tones through antialiasing. Quantization reduces all of that to at most 256.
+
+Those intermediate tones are gradations between two or three base colors, which is exactly what a palette approximates well, and Sharp dithers the result. Measured on the visible pixels:
+
+| Source | Colors | Average difference | Channels over 16/255 |
+| --- | --- | --- | --- |
+| Flat logo (the usual case) | 950–4,300 | 0.08–0.19 / 255 | 0% |
+| Three-stop gradient (stress test) | 1,215 | 0.74 / 255 | 0.01% |
+
+Even a full-circle gradient does not band measurably. Still, quantization is lossy by definition, so if your mark leans on wide, smooth gradients, compare a generated file before turning it on for the whole project. A file is only ever rewritten when the palette version comes out smaller.
+
+> **WARNING**
+>
+> This is tuned for logo artwork. It is not meant for photographic sources.
+
+For context on what the platforms already do: iOS re-encodes every PNG in the bundle with `pngcrush -iphone` when it packages the app, but that is **lossless**, so this saving is not something the SDK would have done for you. On Android, nothing in Titanium touches these files.
+
+## Regenerating a single piece with `--only`
+
+A full run rewrites every branding file. That is what you want the first time, and it is exactly what you don't want when only one piece changed and the others were tweaked by hand.
+
+`--only` takes a comma-separated list of pieces, groups, or both:
+
+```bash
+purgetss brand                          # everything
+purgetss brand --only icon              # just the DefaultIcon pair
+purgetss brand --only ios               # icon, dark, tinted, ios-splash
+purgetss brand --only ios,notification-icon
+```
+
+Groups are shorthand for the obvious sets:
+
+| Group | Expands to |
+| --- | --- |
+| `ios` | `icon`, `dark`, `tinted`, `ios-splash` |
+| `store` | `marketplace`, `feature-graphic` |
+| `android` | `adaptive`, `legacy-icon`, `appicon`, `android-splash` |
+
+Details worth knowing:
+
+- Naming a piece generates it **even when its opt-in flag is absent**: `--only notification-icon` is enough on its own.
+- A name that doesn't exist aborts the run before anything is written, printing the valid pieces and groups.
+- `--dry-run` honors the same filter, so you can check the plan first.
+- The order you type doesn't matter; generation always follows the pipeline order.
 
 ## Android dark mode
 
@@ -340,49 +438,80 @@ The monochrome layer is pure white (`RGB 255,255,255`) with alpha preserved. And
 
 ## Android 12+ splash artwork
 
-If you pass `--splash`, PurgeTSS generates `drawable-*/splash_icon.png` across Android densities.
+If you pass `--splash-icon`, PurgeTSS generates `drawable-*/splash_icon.png` across Android densities.
 
 ```bash
-purgetss brand --splash
+purgetss brand --splash-icon
 ```
 
-If you want that artwork to differ from the launcher icon, provide `logo-splash.svg` or set `brand.logos.androidSplash`:
+If you want that artwork to differ from the launcher icon, provide `logo-splash-icon.svg` or set `brand.splashIcon.logo`:
 
 ```javascript
 brand: {
-  android: {
-    splash: true
-  },
-  logos: {
-    androidSplash: './docs/snap-splash-mark.svg'
+  splashIcon: {
+    enabled: true,
+    logo: './docs/snap-splash-mark.svg'
   }
 }
 ```
 
 > **INFO**
 >
-> Generating `splash_icon.png` does not automatically switch Titanium to use it for the Android 12+ system splash. Titanium still needs a custom splash theme that points `android:windowSplashScreenAnimatedIcon` to `@drawable/splash_icon`. If you do nothing, Android keeps using `ic_launcher`.
+> Generating `splash_icon.png` does not automatically switch Titanium to use it for the Android 12+ system splash. Titanium still needs a custom splash theme that points `android:windowSplashScreenAnimatedIcon` to `@drawable/splash_icon`. If you do nothing, Android keeps using `ic_launcher`. That inertness is exactly why the piece is opt-in.
+
+Keep the theme already assigned to `<application>`. Define a launcher-only theme that inherits from `Theme.Titanium`, then assign it to Titanium's generated launcher Activity. The complete setup is in [Matching the launch background](#matching-the-launch-background).
 
 > **WARNING**
 >
-> Merge splash settings into the existing Android theme
-> If your app already has a custom Android theme block in `tiapp.xml`, **merge** the new splash settings (the `android:windowSplashScreenAnimatedIcon` entry and any sibling theme attributes) into that existing theme. Do **not** append a second `<application>` element or a duplicate theme block — Titanium will only honor one theme definition, and the duplicate silently shadows or overrides the original, leading to "my settings were ignored" debugging sessions. Always edit the existing `<application>` / theme block in place.
+> Android masks this icon into a circle
+> The Android 12+ splash icon is drawn inside a circular mask. A wide wordmark that fills the canvas loses its corners. Use a square mark for `logo-splash-icon`, the same advice that applies to launcher icons.
 
-> **INFO**
->
-> A brief flash on splash exit is usually the system, not your PNGs
-> If you still see a brief flash or abrupt exit transition during splash dismissal even with correct assets in place, **do not assume the PNGs PurgeTSS generates are wrong**. That artifact commonly comes from Android 12+'s system splash exit transition (or from Titanium's splash theme handoff to your first window), not from the splash icon files themselves. Regenerating `splash_icon.png` will not change it — the fix lives in the splash theme animation, not in the icon assets.
+Also, if you still see a brief flash during splash exit even with correct assets, do not assume the PNGs are wrong. That artifact can come from Titanium's splash theme or the system splash transition itself.
+
+## Android pre-12 splash
+
+Below Android 12 there is no system splash: the launch screen comes from the image Titanium maps into `drawable-*/background.png`, and that image comes from the project's own splash artwork.
 
-## Android legacy splash fallback
+`brand` regenerates the whole set on every run. It is the `android-splash` piece, on by default:
 
-Since v7.7.0, PurgeTSS regenerates `app/assets/android/default.png` in Alloy projects and `Resources/android/default.png` in Classic projects.
+- `app/assets/android/default.png` (`Resources/android/default.png` in Classic)
+- `app/assets/android/images/res-*/default.png` — the 11 per-qualifier images the Alloy template ships
 
-That file still matters as a fallback on older Titanium Android splash paths, which is why `cleanup-legacy` no longer removes it.
+Earlier versions regenerated only the first file and hid the other 11 behind a `--legacy-splash` flag, which is why a freshly branded project could still flash the grey Alloy logo on an older phone. That flag is gone: its output is part of `android-splash` and always generated.
 
 > **INFO**
 >
-> Older Android splash theme assets are left out on purpose
-> The older Android splash **theme** assets `background.png` / `background.9.png` are intentionally **not** part of the normal `brand` flow. `brand` targets the modern Titanium icon pipeline (iOS app icons, Android adaptive icons, optional Android 12+ splash artwork), so if a project still depends on those legacy nine-patch theme assets, manage them manually. (Source: upstream `app-assets/1-app-icons-and-branding.md` ~lines 334, 386.)
+> A solid `windowBackground` wins
+> If the launch theme sets `android:windowBackground` to a plain color — which is what [Matching the launch background](#matching-the-launch-background) recommends — that color takes precedence over this artwork on Android <12. Drop the `windowBackground` item if you want the image to show instead.
+
+## The iOS launch screen and LaunchLogo.png
+
+Titanium builds `LaunchLogo.imageset` itself on every iOS build, resizing one source into the five sizes it needs. It looks for `LaunchLogo.png` first and falls back to `DefaultIcon.png`.
+
+So there is nothing for PurgeTSS to generate there, but there is something to choose. With only `DefaultIcon.png` around, the launch screen shows your app icon, safe-zone padding and all. Dropping a `logo-launch.svg` (or `.png`) into `purgetss/brand/` makes `brand` write a `LaunchLogo.png`, and the launch screen shows the full logotype instead:
+
+```bash
+cp docs/my-wordmark.svg purgetss/brand/logo-launch.svg
+purgetss brand
+```
+
+The file is written at exactly **1024×1024**. That is not a style choice: the SDK validates the size and discards the file with a warning when it does not match.
+
+The piece activates by convention (the presence of `logo-launch.*`) rather than through a flag, because `--<piece>-logo` already means "the source for this piece" everywhere else in the command. To generate it from a path without adding the file:
+
+```bash
+purgetss brand --launch-logo docs/my-wordmark.svg
+purgetss brand --only launch-logo
+purgetss brand --launch-logo-padding 18   # more breathing room around the logotype
+```
+
+The output keeps its alpha, so the storyboard's `<default-background-color>` shows through.
+
+## iPhone launch images
+
+The Alloy and Classic templates ship 16 `Default*.png` launch images under `assets/iphone/`, from the 320×480 original iPhone size up to 2688×1242. `brand` regenerates all of them, scaling the logo against the **shorter side** of each canvas so portrait and landscape carry the same visual weight.
+
+With `<enable-launch-screen-storyboard>` enabled (the default), iOS never reads these files. They are regenerated because they are in your project, they ship with the Alloy logo, and no one should have to audit their `tiapp.xml` to know whether that matters. If you are sure your project doesn't need them, [`--cleanup-legacy`](#cleanup-legacy-branding-artifacts) deletes them instead.
 
 ## iOS 18+ Dark and Tinted variants
 
@@ -410,99 +539,109 @@ purgetss brand --no-dark --no-tinted
 >
 > Until that PR lands, after your first iOS build you may need to add the two PNGs manually into `build/iphone/Assets.xcassets/AppIcon.appiconset/` in Xcode (via the "Appearance" column in the asset catalog editor). Once #14122 merges, the command becomes fully end-to-end.
 
-## Google Play Feature Graphic (v7.10.0)
-
-Since v7.10.0, `purgetss brand` also generates `MarketplaceArtworkFeature.png` — the **1024×500** banner that Google Play shows above the app description on the Play Store listing. It's submission artwork only: the file is written to the project root for upload via Play Console; it is **not** bundled into the APK.
-
-### How the source is chosen
+## Brand color
 
-PurgeTSS resolves the Feature Graphic source in this order (first match wins):
+The `--bg-color` flag (or `brand.background` in config) controls the background across the generated branding assets:
 
-1. CLI `--feature-logo <path>` for the current run.
-2. `brand.logos.featureGraphic` in `config.cjs`.
-3. Auto-discovered `purgetss/brand/logo-feature.{svg,png}`.
-4. The main logo (centered inside the 1024×500 canvas with the configured vertical padding).
+1. The **Android adaptive background layer**: a solid color that fills the full 108dp canvas behind your logo.
+2. The **iOS alpha flatten** for `DefaultIcon-ios.png`. Apple rejects transparent App Store icons, so the logo is flattened on this color.
+3. The **marketplace flatten** for `iTunesConnect.png`, `MarketplaceArtwork.png`, and `MarketplaceArtworkFeature.png`.
+4. **Every splash canvas**: `default.png`, the 11 `res-*/default.png`, and the 16 iPhone launch images.
+5. `appicon.png`.
 
 ```bash
-purgetss brand --feature-logo ./docs/feature.svg
+purgetss brand --bg-color "#0B1326"
 ```
 
-Drop a dedicated logo when you want a logo + tagline lockup or a wider artwork that takes advantage of the rectangular canvas. Otherwise the main `logo.svg` is centered as a square block — fine for most apps.
+Any piece can opt out with its own `background`. That is what `dark: { background: null }` does in the default config, which keeps `DefaultIcon-Dark.png` transparent per Apple HIG.
 
-### Padding
+If you never pass the flag, background stays `#FFFFFF`. `iTunesConnect.png` and `MarketplaceArtwork.png` keep their alpha channel to match Titanium's default; `MarketplaceArtworkFeature.png` is always flattened for Google Play.
 
-The default vertical padding is `12%` (top + bottom). Override per run with `--feature-graphic-padding <n>` (integer `0-40`), or persist it in `brand.padding.featureGraphic`:
+### Matching the launch background
 
-```bash
-purgetss brand --feature-graphic-padding 8
-```
+`brand.background` bakes into the generated image pixels. It does **not** edit `tiapp.xml` or an Android theme. Carrying the same color into the native launch surfaces takes an iOS `<default-background-color>` entry plus a launcher-only Android theme — the complete, copy-ready setup is in [Matching the Launch Background](./launch-background.md).
 
-```javascript
-brand: {
-  padding: {
-    featureGraphic: '8%'
-  }
-}
-```
+`purgetss brand --notes` prints that setup with the project's current `brand.background` already filled in.
 
-The logo is rendered as a square block of side `500 - 2 × pad` and centered horizontally on the 1024-wide canvas. Lower the padding for a more impactful banner; raise it if the logo looks cramped against the top or bottom edge on smaller Play Store crops.
 
-## Brand color
+## Padding guidance
 
-The `--bg-color` flag (or `brand.colors.background` in config) controls three things at once:
+Padding belongs to the piece, not to the project. Each piece has its own key and its own flag:
 
-1. The **Android adaptive background layer**: a solid color that fills the full 108dp canvas behind your logo.
-2. The **iOS alpha flatten** for `DefaultIcon-ios.png`. Apple rejects transparent App Store icons, so the logo is flattened on this color.
-3. The **marketplace flatten** for `iTunesConnect.png` and `MarketplaceArtwork.png` when you pass a non-default value explicitly.
+| Piece | Config | Flag | Default |
+| --- | --- | --- | --- |
+| `adaptive` | `brand.adaptive.padding` | `--android-adaptive-padding` | `18%` |
+| `legacy-icon` | `brand.legacyIcon.padding` | `--android-legacy-padding` | `10%` |
+| `icon` | `brand.icon.padding` | `--ios-padding` | `4%` |
+| `feature-graphic` | `brand.featureGraphic.padding` | `--feature-graphic-padding` | `12%` |
+| `launch-logo` | `brand.launchLogo.padding` | `--launch-logo-padding` | `12%` |
+| `android-splash` | `brand.androidSplash.padding` | `--android-splash-padding` | `26%` |
+| `ios-splash` | `brand.iosSplash.padding` | `--ios-splash-padding` | `26%` |
 
-```bash
-purgetss brand --bg-color "#0B1326"
+`--padding` is a shortcut for the two Android launcher paddings in a single run, and `--splash-padding` for the two splash paddings. `--ios-padding` moves the four square iOS/marketplace pieces together (`icon`, `dark`, `tinted`, `marketplace`); in config each of them has its own key.
+
+There is deliberately **no global padding value that cascades down**. The defaults answer to different constraints: `18%` answers to the Android launcher mask, while `4%` is an aesthetic choice for a canvas with no mask behind it. One inherited number would let a reasonable-looking `8%` silently break the launcher mask. `background`, which has no such trap, is inherited from `brand.background`.
+
+### How the source is read, and how sharp the output is
+
+Two things are worth knowing about what happens to your `logo.svg` or `logo.png` before any padding is applied.
+
+**The container is what counts, not the artwork's bounding box.** An SVG is read at its `viewBox`, a raster at its full canvas, and neither is trimmed to where the pixels actually are. So whatever margin a designer baked into the file **adds** to the padding configured per piece. A round logo exported inside a 2048×2048 PNG with 25% of its own air, generated at `adaptive: { padding: '18%' }`, ends up covering about 32% of the icon canvas, not 64%. If a mark comes out smaller than the numbers suggest, that is almost always why: crop the source or lower the padding.
+
+**The masters are sized to the run.** The source is rasterized once into two intermediate masters, and every piece scales down from them, so their resolution is the ceiling on output sharpness. Rather than a fixed size, `brand` measures the largest number of pixels any selected piece will ask for and builds the masters at exactly that. A default run reports it:
+
+```text
+  • Masters at 942 px — the largest any selected piece asks for
 ```
 
-If you never pass the flag, background stays `#FFFFFF` and the marketplace artwork keeps its alpha channel (matches Titanium's default).
+Lower a padding and the figure rises with it (`--splash-padding 4` needs 1413 px), so output never goes soft against a fixed ceiling. Every destination is a reduction, never an upscale.
 
-## Padding guidance
+The one case this cannot fix is a raster source that is simply too small: a 512-px PNG cannot produce a sharp 942-px icon. Prefer SVG, or a PNG of at least 1024×1024.
 
-Since v7.7.0, PurgeTSS treats Android adaptive and Android legacy launcher icons as two related but different cases:
+### Splash padding
 
-- `brand.padding.androidAdaptive` or `--android-adaptive-padding` for the adaptive foreground
-- `brand.padding.androidLegacy` or `--android-legacy-padding` for `ic_launcher.png`
-- `--padding` is a one-shot **shortcut** that sets both Android paddings to the same value for one run
+The 28 splash images (`default.png`, the 11 `res-*`, and the 16 iPhone launch images) share one rule: the logo is fitted into a square whose side is a share of the canvas's **shorter** side.
 
-The adaptive default is `19%`, which stays close to the Android safe-zone. The legacy default is `10%`, so the flat `ic_launcher.png` can keep a little more visual weight.
+Measuring against the shorter side is what lets a single number work across canvases as different as 1440×2560 and 800×480: at 800×480 the limit comes from the height, at 240×400 from the width, and the logo keeps the same visual weight in portrait and in landscape.
 
-### Adaptive icon padding
+| `androidSplash.padding` / `iosSplash.padding` | Logo | `default.png` (1440×2560) | `res-notlong-port-mdpi` (320×480) |
+| --- | --- | --- | --- |
+| `20%` | 60% of the shorter side | 864 px | 192 px |
+| `26%` (default) | 48% | 691 px | 153 px |
+| `30%` | 40% | 576 px | 128 px |
+| `35%` | 30% | 432 px | 96 px |
 
-| Padding | Logo fill | When to use                                                                                            |
-| ------- | --------- | ------------------------------------------------------------------------------------------------------ |
-| `15%`   | 70%       | Aggressive. Better for square symbols with lots of built-in breathing room.                            |
-| `18%`   | 64%       | Defensive: for intricate logos, fine serifs, multi-element designs.                                    |
-| `19%`   | 62%       | **Default**. Close to the Android safe-zone and safer for adaptive masks.                              |
-| `20%`   | 60%       | Conservative, spec-compliant. Safe on every launcher, including aggressive masks.                      |
+The `26%` default is calibrated against the Titanium template itself: the Alloy logo in the stock `default.png` measures 665×488 px on a 1440×2560 canvas, so `26%` lands within 4% of the size Titanium ships.
 
-A useful visual check is the "corners" heuristic: imagine a circle inscribed in your 1024×1024 canvas with the given padding. If your logo's outermost corners fit inside that circle, you're safe on circular launchers (Pixel default, Oppo Android 15). If they poke out, they'll be clipped.
+Before v7.13.0 none of this was configurable: `default.png` used a hardcoded box of 72% × 26% of its own canvas, and the `res-*` set a separate hardcoded 60%. Two rules for the same piece, neither adjustable.
 
-The official Android spec floor is `19.44%` (108dp canvas, 66dp inscribed safe-zone circle). That is the theoretical worst-case for aggressive adaptive masks, which is why the adaptive default now sits close to it.
+### Adaptive icon padding
 
-### Legacy icon padding
+Android's adaptive canvas is 108 dp. The mask leaves roughly 72 dp visible, and the **guaranteed** safe area is a 66 dp circle inscribed in it. What each padding means in those terms:
+
+| Padding | Logo | vs. the 66 dp safe circle | vs. the ~72 dp the mask shows |
+| --- | --- | --- | --- |
+| `15%` | 75.6 dp | outside | **outside** — clipped on any launcher |
+| `16%` | 73.4 dp | outside | **outside** |
+| `18%` | 69.1 dp | corners outside | inside — **the default** |
+| `19.44%` | 66.0 dp | exactly on it | inside |
+| `20%` | 64.8 dp | inside | inside — most conservative |
 
-Legacy `ic_launcher.png` does not go through the same adaptive mask, so it can usually run tighter. That is why the default for `brand.padding.androidLegacy` is `10%`.
+`18%` sits between the guaranteed circle and the mask edge: a logo that carries its own margin never reaches those corners, which is why it is a safe default in practice. Drop to `20%` if your mark runs edge to edge and you see clipping on a circular launcher.
 
-### iOS padding
+A useful visual check is the "corners" heuristic: imagine a circle inscribed in your 1024×1024 canvas with the given padding. If your logo's outermost corners fit inside that circle, you're safe on circular launchers (Pixel default, Oppo Android 15). If they poke out, they'll be clipped.
 
-`--ios-padding` is a separate lever — iOS has no launcher mask, so the range is different:
+The official Android spec floor is `19.44%` (108dp canvas, 66dp inscribed safe-zone circle). That is the theoretical worst-case for aggressive adaptive masks, which is why the adaptive default sits close to it.
 
-| iOS padding | When to use |
-| --- | --- |
-| `2%` | Bold, edge-to-edge logos. |
-| `4%` | **Default**. Balanced aesthetic. |
-| `8%` | Conservative, generous whitespace around the mark. |
+### Legacy icon padding
+
+Legacy `ic_launcher.png` does not go through the same adaptive mask, so it can usually run tighter. That is why the default for `brand.legacyIcon.padding` is `10%`.
 
 ## Cleanup legacy branding artifacts
 
-Projects that predate Android adaptive icons (API 26+) or modern iOS launch storyboards often accumulate obsolete assets: `res-long-*/res-notlong-*` qualifiers dead since Android 3.0, legacy `Default-*.png` launch images ignored when the storyboard is enabled, pre-adaptive `appicon.png`, and so on.
+Projects that predate Android adaptive icons (API 26+) or modern iOS launch storyboards often accumulate obsolete assets: `res-long-*/res-notlong-*` qualifiers dead since Android 3.0, legacy `Default-*.png` launch images ignored when the storyboard is enabled, pre-adaptive `appicon.png`, and similar files.
 
-The `--cleanup-legacy` flag removes them with context-aware safety rules: it reads `tiapp.xml` to decide what's safe to delete based on your project's configuration. Always preview first:
+The `--cleanup-legacy` flag removes them with context-aware safety rules: it reads `tiapp.xml` to decide what is actually safe to delete for your project. Always preview first:
 
 ```bash
 purgetss brand --cleanup-legacy --dry-run
@@ -525,15 +664,23 @@ purgetss brand --cleanup-legacy --aggressive
 > Commit first
 > `--cleanup-legacy` deletes files permanently. Commit your project to git before running without `--dry-run` so `git restore` is available as a rollback.
 
+Files kept on purpose:
+
+- `app/assets/android/default.png` in Alloy projects
+- `Resources/android/default.png` in Classic projects
+
+Those files are still valid Android <12 splash artwork.
+
 > **INFO**
 >
-> Files kept on purpose
-> `--cleanup-legacy` intentionally does **not** remove the following files, even when modern adaptive launcher icons and splash assets are already in place:
+> `--cleanup-legacy` never deletes what the same run just generated
+> Three cleanup rules target files `brand` now regenerates by default: the `res-long-*`/`res-notlong-*` folders (`android-splash`), the iPhone `Default*.png` images (`ios-splash`) and `appicon.png` (`appicon`). When `--cleanup-legacy` runs as part of a generating pass, those paths are skipped and the run reports how many it spared:
 >
-> - `app/assets/android/default.png` (Alloy projects)
-> - `Resources/android/default.png` (Classic projects)
+> ```text
+> Keeping 28 path(s) this run just regenerated with your artwork.
+> ```
 >
-> These remain because they are still required by Titanium framework defaults — older Android splash code paths fall back to `default.png`, and removing it can cause build warnings or a missing-asset error on certain Titanium SDK versions even when modern splash assets exist. Treat them as part of the baseline asset set, not as legacy clutter.
+> To actually delete them, exclude the piece that writes them. For example, `purgetss brand --only android --cleanup-legacy` regenerates the Android icons while letting cleanup remove the iPhone launch images.
 
 ## Troubleshooting
 
@@ -549,9 +696,7 @@ Or set it in the config:
 
 ```javascript
 brand: {
-  padding: {
-    androidAdaptive: '20%'
-  }
+  adaptive: { padding: '20%' }
 }
 ```
 
@@ -565,7 +710,7 @@ purgetss brand --android-adaptive-padding 17
 
 ### The monochrome version looks like a white blob
 
-Your colored logo likely has multi-color detail that doesn't survive a naive whitening. Provide a dedicated silhouette:
+Your colored logo likely has multi-color detail that does not survive automatic whitening. Provide a dedicated silhouette:
 
 ```bash
 cp docs/my-logo-mono.svg purgetss/brand/logo-mono.svg
@@ -574,7 +719,7 @@ purgetss brand
 
 ### iOS rejects the app icon upload ("contains transparency")
 
-That's Apple's rule: App Store icons must have no alpha channel. `DefaultIcon-ios.png` is always flattened on `bgColor` for that reason. If you edited the file manually and reintroduced alpha, re-run `purgetss brand` to regenerate.
+Apple requires App Store icons to have no alpha channel. `DefaultIcon-ios.png` is always flattened on `brand.background` for that reason. If you edited the file manually and reintroduced alpha, re-run `purgetss brand`.
 
 ### The dark variant doesn't show on my iPhone
 
@@ -582,101 +727,39 @@ Dark variants require iOS 18+ and Titanium SDK automatic wiring (tracked upstrea
 
 ### I get "Input image exceeds pixel limit" on an SVG from Affinity / Illustrator
 
-Affinity Designer and Adobe Illustrator often bake transforms into the exported SVG's `viewBox`, so the intrinsic dimensions end up at something absurd like `29559×13542 pt`. Rasterized at 1× density, that blows past Sharp's pixel limit and the command crashes.
+Affinity Designer and Adobe Illustrator often bake transforms into the exported SVG's `viewBox`, so the intrinsic dimensions can end up at something like `29559×13542 pt`. Rasterized at 1× density, that exceeds Sharp's pixel limit and the command crashes.
 
 PurgeTSS checks the `viewBox` on every SVG. When either side is over `4096 pt`, it prints a warning with the actual dimensions and switches to an adaptive density that caps the output pixel count regardless of input size. The warning tells you the source is oversized; the command still finishes.
 
 If you want to clean up the source, re-export from the vector editor with a canvas-sized viewBox (`0 0 1024 1024`, for example). The rasterized output is identical either way, but a normalized viewBox keeps the SVG portable for other tools.
 
+### A key in `brand:` aborts the run
+
+`brand` rejects unknown keys instead of ignoring them. Check the spelling against the piece table above — see [Unknown keys are an error](#unknown-keys-are-an-error).
+
 ### I changed my bg color — do I need to regenerate the Android densities too?
 
-Yes. `bgColor` bakes into every Android background layer and the iOS flatten. Re-run:
+Yes. `brand.background` bakes into every Android background layer, every splash canvas, and the iOS flatten. Re-run:
 
 ```bash
 purgetss brand --bg-color "#NEW_COLOR"
 ```
 
-All 5 Android densities, marketplace artwork, and iOS variants regenerate in one pass.
-
-## Full flag reference
-
-**Project & output**
-
-| Flag | Purpose |
-| --- | --- |
-| `--project <path>` | Project root (defaults to cwd). |
-| `--dry-run` | Preview what would be generated without writing any files. |
-| `--output <dir>` | Stage into `<dir>` instead of writing in place. |
-| `-y`, `--yes` | Skip the overwrite confirmation prompt for this invocation. |
-
-**Visual customization**
-
-| Flag | Purpose |
-| --- | --- |
-| `--bg-color <hex>` | Background color for Android adaptive + iOS/marketplace flatten. |
-| `--padding <n>` | Shortcut: sets BOTH Android paddings to the same value for one run. Fixed in v7.10.0 — previously only fed `androidAdaptivePadding`, leaving `androidLegacyPadding` at its own config value. |
-| `--android-adaptive-padding <n>` | Adaptive icon safe-zone % (default `19`). |
-| `--android-legacy-padding <n>` | Legacy `ic_launcher.png` padding % (default `10`). |
-| `--ios-padding <n>` | iOS aesthetic padding % (range `2–8`, default `4`). |
-| `--feature-graphic-padding <n>` | (v7.10.0) Vertical padding for `MarketplaceArtworkFeature.png` (range `0-40`, default `12`). |
-
-**Optional asset types**
-
-| Flag | Purpose |
-| --- | --- |
-| `--notification` | Also emit `ic_stat_notify.png × 5`. |
-| `--splash` | Also emit `splash_icon.png × 5`. |
-
-**Logo variants & overrides**
-
-| Flag | Purpose |
-| --- | --- |
-| `--icon-logo <path>` | Override `purgetss/brand/logo-icon.{svg,png}` for Android launcher icons. |
-| `--monochrome-logo <path>` | Override `purgetss/brand/logo-mono.{svg,png}`. |
-| `--dark-logo <path>` | Override `purgetss/brand/logo-dark.{svg,png}`. |
-| `--dark-bg-color <hex>` | Opaque dark bg for `DefaultIcon-Dark.png` (default: transparent per Apple HIG). |
-| `--splash-logo <path>` | Override `purgetss/brand/logo-splash.{svg,png}` for Android 12+ splash artwork. |
-| `--tinted-logo <path>` | Override `purgetss/brand/logo-tinted.{svg,png}`. |
-| `--feature-logo <path>` | (v7.10.0) Override `purgetss/brand/logo-feature.{svg,png}` for the Google Play Feature Graphic. |
-| `--no-dark` | Skip `DefaultIcon-Dark.png`. |
-| `--no-tinted` | Skip `DefaultIcon-Tinted.png`. |
-
-**Legacy cleanup**
-
-| Flag | Purpose |
-| --- | --- |
-| `--cleanup-legacy` | Remove obsolete branding artifacts (reads `tiapp.xml` for safety rules). Keeps `default.png` on purpose. |
-| `--aggressive` | With `--cleanup-legacy`, also remove `ldpi` density folders. |
+All 5 Android densities, marketplace artwork, splash canvases, and iOS variants regenerate in one pass.
 
-**Diagnostics**
+## Flag reference
 
-| Flag | Purpose |
-| --- | --- |
-| `--notes` | Print full `tiapp.xml` snippets + padding tuning guide. |
-| `--debug` | Print extra diagnostics. |
-
-### Examples
-
-```bash
-purgetss brand                                            # uses purgetss/brand/logo.svg + config
-purgetss brand --bg-color "#0B1326"                       # override bg color
-purgetss brand --icon-logo ./docs/app-icon.svg            # dedicated square Android launcher mark
-purgetss brand --splash --splash-logo ./docs/splash.svg   # custom Android 12+ splash artwork
-purgetss brand --feature-logo ./docs/feature.svg          # custom Google Play Feature Graphic (v7.10.0)
-purgetss brand --feature-graphic-padding 8                # tighter Feature Graphic padding (v7.10.0)
-purgetss brand --notification --splash                    # add notification + splash
-purgetss brand --no-tinted                                # skip iOS 18+ tinted variant
-purgetss brand --dry-run                                  # preview without writing
-purgetss brand --cleanup-legacy --dry-run                 # preview legacy cleanup
-```
+Every flag lives in the terse reference: [`brand` command](./cli-commands.md#brand-command) — project & output, `--only`, padding, optional asset types, the `--<piece>-logo` overrides, `--optimize`, appearance, legacy cleanup and diagnostics, with examples.
 
 ## Community-Discovered Patterns
 
-- **Titanium SDK wiring lag for iOS 18+ variants.** Titanium SDK currently wires `DefaultIcon-ios.png` into the generated appiconset automatically, but `DefaultIcon-Dark.png` and `DefaultIcon-Tinted.png` are not picked up yet. Until [tidev/titanium-sdk#14122](https://github.com/tidev/titanium-sdk/issues/14122) merges, the practical workaround is: run `ti build -p ios` once, then open `build/iphone/Assets.xcassets/AppIcon.appiconset/` in Xcode and drag the two PNGs into the "Appearance" column of the asset catalog editor. The generated PNGs are already named and sized correctly — no resizing needed.
-- **Wordmark logos need a separate launcher mark.** When `logo.svg` is a wide wordmark or vertical lockup, it tends to look cramped inside Android launcher masks. Drop a square `logo-icon.svg` (or set `brand.logos.androidLauncher`) and the launcher icons get the dedicated mark while the rest of the brand set still uses the main logo. Same idea applies to Android 12+ splash with `logo-splash.svg`.
-- **Three Android assets, three different jobs.** `ic_launcher*` drives the app icon and the default Android 12+ splash; `splash_icon.png` is generated only when you pass `--splash` and Titanium needs an explicit splash theme to actually use it; `default.png` is the older Titanium Android splash fallback (regenerated since v7.7.0, intentionally kept by `cleanup-legacy`). Knowing which file does what saves a lot of "but the icon didn't change" debugging.
+- **Wordmark logos need a separate launcher mark.** When `logo.svg` is a wide wordmark or vertical lockup, it tends to look cramped inside Android launcher masks. Drop a square `logo-adaptive.svg` (or set `brand.adaptive.logo`) and the launcher icons get the dedicated mark while the rest of the brand set still uses the main logo. The same idea applies to the Android 12+ splash with `logo-splash-icon.svg`, which Android additionally masks into a circle. **Note the v7.13.0 rename:** the file that used to do this was `logo-icon.svg`; that name now feeds `DefaultIcon.png` instead.
+- **Verify with `--dry-run` before a real run on a project with hand-tweaked assets.** A full `brand` run rewrites every branding file, so any icon touched by hand outside PurgeTSS is overwritten. Since v7.13.0 the surgical alternative is `--only <piece>`, which honors `--dry-run` too. Before v7.13.0 the only options were a full run or nothing.
+- **The `[y/N/a]` prompt disappears in non-TTY contexts, including the `alloy.jmk` hook.** That is by design, but it means a `brand` invocation wired into the build pipeline silently overwrites without asking. Keep the project committed before wiring `brand` into `alloy.jmk`.
 
 ## See also
 
 - [`brand` command reference](./cli-commands.md#brand-command) — terse flag list.
 - [Multi-Density Images](./multi-density-images.md) — sibling `images` command for UI assets.
+- [Customization Deep Dive](./customization-deep-dive.md) — the full `config.cjs` structure.
+- [Version History](./version-history.md) — what changed in each release.