@maccesar/titools 2.5.1 → 2.6.0

package/skills/ti-branding/references/android-adaptive-icons.md

@@ -0,0 +1,85 @@
+# Android adaptive icons (API 26+)
+
+## Canvas and safe-zone
+
+Adaptive icons use a fixed 108×108 dp virtual canvas composed of two layers:
+
+- **Foreground**: the logo/glyph with transparency outside the safe-zone
+- **Background**: solid color, gradient, or pattern filling the full canvas
+
+The OS launcher applies a mask (circle, squircle, teardrop, rounded square — up to the OEM) and clips both layers to that shape. Only the central **66×66 dp safe-zone** is guaranteed to remain visible regardless of the mask.
+
+Translation to padding:
+
+```
+safe-zone:    66 / 108 = 61.1% of canvas
+min padding:  (108 - 66) / 2 / 108 = 19.44% per side
+```
+
+Anything beyond 66dp toward the edge is at the launcher's discretion — some masks (circle) hide more, some (squircle) hide less.
+
+## Density sizes
+
+One pixel unit equals `density_scale × 1 dp`:
+
+| Density  | Scale | Canvas size (108 dp) |
+|----------|-------|----------------------|
+| mdpi     | 1.0×  | 108 px               |
+| hdpi     | 1.5×  | 162 px               |
+| xhdpi    | 2.0×  | 216 px               |
+| xxhdpi   | 3.0×  | 324 px               |
+| xxxhdpi  | 4.0×  | 432 px               |
+
+Ship all five. The OS picks the closest match for the user's screen density.
+
+## Monochrome layer (API 31+)
+
+Android 13 introduced themed icons: the user can tell the launcher to re-color all app icons with the system accent color. The OS uses the `monochrome` drawable for this treatment.
+
+Rules for the monochrome drawable:
+
+- All non-transparent pixels become pure white at build time — the OS tint replaces white with the theme color at render time
+- Alpha channel must be preserved (same silhouette as foreground, transparency intact)
+- Do NOT include color information — it will be discarded
+
+The skill generates monochrome by taking the foreground and running ImageMagick's `-channel RGB -fill white -colorize 100 +channel` which replaces RGB with white while leaving the alpha untouched.
+
+## XML bind
+
+One file ties the three layers together. Ships to `mipmap-anydpi-v26/ic_launcher.xml`:
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
+  <background android:drawable="@mipmap/ic_launcher_background"/>
+  <foreground android:drawable="@mipmap/ic_launcher_foreground"/>
+  <monochrome android:drawable="@mipmap/ic_launcher_monochrome"/>
+</adaptive-icon>
+```
+
+The `v26` qualifier ensures only API 26+ devices use this file. Older devices fall through to the legacy `mipmap-*/ic_launcher.png` flat drawable.
+
+## Legacy flat icon
+
+For API 21–25 (~3% of active users in 2026) the launcher still uses a flat PNG:
+
+| Density  | Size |
+|----------|------|
+| mdpi     | 48   |
+| hdpi     | 72   |
+| xhdpi    | 96   |
+| xxhdpi   | 144  |
+| xxxhdpi  | 192  |
+
+Fill more of the canvas here — legacy launchers don't apply adaptive masking. The skill reduces the padding by 40% for this composite.
+
+## Verifying
+
+- Android Studio has a Resource Manager that previews adaptive icons with multiple masks. Point it at `app/platform/android/res/` to inspect.
+- On a device/emulator running API 26+, long-press the launcher icon and the animated wiggle reveals whether the adaptive layers are wired correctly.
+- On API 31+, toggle "Themed icons" in the launcher settings to verify the monochrome layer.
+
+## References
+
+- Android Developer: [Adaptive icons](https://developer.android.com/develop/ui/views/launch/icon_design_adaptive)
+- Android Developer: [Themed app icons](https://developer.android.com/about/versions/13/features#themed-app-icons)

package/skills/ti-branding/references/cleanup-legacy.md

@@ -0,0 +1,112 @@
+# `--cleanup-legacy` — removing obsolete branding artifacts
+
+Titanium project templates ship with a lot of legacy branding assets that made sense a decade ago and are dead weight today. The `--cleanup-legacy` flag scans the project and removes them, but only after verifying through `tiapp.xml` that they are genuinely unused.
+
+## Why cleanup matters
+
+Legacy branding assets bloat the project in three ways:
+
+1. **Repository size** — every `Default-XXXh@3x.png` (some 800 KB+ each) stays in git history forever unless actively deleted.
+2. **Build output size** — some legacy assets DO get copied into the APK/IPA even when modern alternatives make them unreachable at runtime. Extra MB mean slower downloads for end users and marginally longer store review times.
+3. **Cognitive load** — new contributors look at `res-long-port-hdpi/`, `Default-Landscape-2688h@3x.png`, `background.9.png`, and reasonably assume they matter. They don't, but nobody is willing to delete what they don't fully understand.
+
+## The three buckets
+
+The cleanup logic categorizes targets by how safe removal is:
+
+### SAFE — universally obsolete
+
+Removed without checking any project configuration. These artifacts are fossils from Android versions predating the current SDK's minimum target.
+
+| Artifact | Why it's dead |
+|---|---|
+| `app/assets/android/images/res-long-*/` | Android's `long` screen qualifier distinguished devices like the Motorola Droid (854×480) from the Nexus One (800×480) in 2009–2011. Since Android 3.0 the system uses dp-based layouts instead. No modern launcher or OS consults these folders. |
+| `app/assets/android/images/res-notlong-*/` | Inverse of `long` — same verdict. |
+
+These buckets are almost always empty in practice (Titanium templates create the folders but rarely populate them), so the cleanup is primarily about removing visual noise from the project tree.
+
+### CONDITIONAL — safe given the project's current configuration
+
+Removed only when `tiapp.xml` confirms the artifact is genuinely unused.
+
+| Artifact | Safety rule | Why |
+|---|---|---|
+| `app/assets/iphone/Default-*.png`, `Default@2x.png` | `<enable-launch-screen-storyboard>true</enable-launch-screen-storyboard>` | With the storyboard active, iOS adapts dynamically to any device resolution via Auto Layout. Apple mandated this in 2020. Without storyboard, these PNGs matter and must stay. |
+| `app/assets/android/images/res-*-land-*/`, `res-land-*/` | `tiapp.xml` declares portrait-only orientations | Landscape variants only load when the app can rotate to landscape. |
+| `app/assets/android/default.png` | `mipmap-anydpi-v26/ic_launcher.xml` exists (adaptive icons present) | The legacy Titanium Android splash PNG is shadowed by the modern SplashScreen API, which derives the splash from the launcher icon. Only deleted when the modern path is in place. |
+| `app/assets/android/appicon.png` | Same adaptive-icons condition | Legacy Android launcher PNG. When adaptive icons exist in `mipmap-*/`, this file is redundant. |
+
+If a safety rule is not satisfied, the artifact is preserved and the user sees a clear reason in the cleanup plan.
+
+### AGGRESSIVE — opt-in via `--aggressive`
+
+Defensible but off by default because there are edge cases.
+
+| Artifact | Reason it's usually safe |
+|---|---|
+| `app/assets/android/images/res-ldpi/`, `res-*-ldpi/` | ldpi (≤120 dpi, pre-2010 low-end devices) is below 1% of active Android devices globally. |
+| `app/platform/android/res/drawable-ldpi/`, `mipmap-ldpi/`, `values-ldpi/` | Same ldpi justification for platform-native resources. |
+
+Users targeting specific low-density markets (some IoT devices, kiosks) should leave `--aggressive` off.
+
+## Safety model
+
+The flag is opinionated about not trashing anybody's work:
+
+- `--dry-run` prints the full plan (paths, sizes, reasons) without deleting anything. Run it first.
+- The plan always shows which `tiapp.xml` flags drove each decision (storyboard on/off, orientation, adaptive-icons presence) so the user can verify the detection is correct.
+- The skill does not delete files outside the project's asset and platform resource directories.
+- It does not touch `tiapp.xml`, source code, `modules/`, `i18n/`, or any application code.
+- Conditional targets still require the safety rule to pass — even with `--cleanup-legacy`, nothing conditional deletes unless `tiapp.xml` justifies it.
+- Aggressive-bucket targets require the explicit `--aggressive` flag on top of `--cleanup-legacy`.
+
+## Real-world savings
+
+Measured on SNAP Gym, a mid-sized Titanium 13.1 Alloy project, immediately after a fresh `alloy new` template:
+
+| Bucket | Items removed | Disk freed |
+|---|---|---|
+| SAFE (`res-long-*` + `res-notlong-*`) | 11 folders | ~0 KB (empty templates) |
+| CONDITIONAL (`iphone/Default-*.png` × 15) | 15 files | ~5.4 MB |
+| CONDITIONAL (`android/default.png`, `appicon.png`) | 2 files | 52 KB |
+| **Total (default flags)** | **28 artifacts** | **~5.5 MB** |
+
+Running `--aggressive` on top would remove an additional ~40 KB of `ldpi` folders — small payoff per project, but compounds when applied across multiple apps.
+
+The 5.4 MB of iOS launch images is the largest single win: those PNGs exist in source but are not shipped in modern IPAs (storyboard-driven iOS builds ignore them). Removing them from source shrinks the repo and clears confusion for new contributors.
+
+## When NOT to run cleanup
+
+- **Classic Titanium apps pre-SDK 10**: rely on the legacy assets. Upgrading the SDK is a prerequisite to safely cleaning up.
+- **Apps with `<enable-launch-screen-storyboard>false</enable-launch-screen-storyboard>`**: the iOS PNGs are still consulted — the skill correctly skips them, but the user should enable the storyboard before running cleanup to get the savings.
+- **Apps that support landscape orientation**: the `res-*-land-*` folders are preserved, which is correct.
+
+## Usage
+
+```bash
+# Preview first — nothing deletes in dry-run mode
+bash scripts/ti-branding --cleanup-legacy --dry-run
+
+# Apply
+bash scripts/ti-branding --cleanup-legacy
+
+# Include ldpi
+bash scripts/ti-branding --cleanup-legacy --aggressive
+
+# Point at a specific project (default: current directory)
+bash scripts/ti-branding --cleanup-legacy --project /path/to/project
+
+# Combine with generation — brand the app and clean up in one pass
+bash scripts/ti-branding ./logo.svg --bg-color "#0B1326" --cleanup-legacy
+```
+
+## Verification checklist
+
+After applying cleanup, rebuild for each platform and visually confirm:
+
+- [ ] iOS app on a modern device (iPhone 11 or newer): splash reaches top and bottom (no letterboxing). The storyboard is doing its job; the deleted PNGs are confirmed unused.
+- [ ] Android app on API 31+ (Android 12 or newer): splash shows the launcher icon centered on the brand color, then transitions to the app normally.
+- [ ] Android app on API 21–30 if the minimum target is that low: app launches without the old `default.png`. Titanium's adaptive-icon fallback kicks in.
+- [ ] `git status` lists only the expected deletions. No source code changes.
+
+If any of those fail, the deletion can be reverted with `git checkout -- .` (before committing) or `git restore` (after).

package/skills/ti-branding/references/ios-appiconset.md

@@ -0,0 +1,62 @@
+# iOS appiconset (Xcode 14+)
+
+## One master, all sizes
+
+Since Xcode 14 (2022), Apple no longer requires the full matrix of 20+ icon sizes. A single 1024×1024 source is sufficient — Xcode generates the rest at build time.
+
+Titanium SDK 13.x embraces this:
+
+- Place `DefaultIcon-ios.png` (1024×1024, no alpha) at the project root
+- On `ti build`, Titanium writes the generated appiconset to `build/iphone/Assets.xcassets/AppIcon.appiconset/`
+- `build/` is regenerated on every build — you never commit the full set to the source tree
+
+If you manually place `app/assets/iphone/appicon-*.png` files, Titanium respects them and only fills in the missing sizes. This skill ignores that path — it only writes the single `DefaultIcon-ios.png` master.
+
+## Why no alpha channel
+
+Apple's review pipeline rejects icons with transparency:
+
+> Apps with app icons that include transparency will be rejected during app review.
+
+The skill flattens alpha by compositing the master over the `--bg-color` before writing `DefaultIcon-ios.png`. Same for `iTunesConnect.png` (App Store submission).
+
+## Relevant file paths
+
+At the project root:
+
+| File | Size | Purpose |
+|------|------|---------|
+| `DefaultIcon-ios.png` | 1024×1024 | Master for appiconset generation |
+| `DefaultIcon.png` | 1024×1024 | Fallback if `DefaultIcon-ios.png` missing (Android uses this too) |
+| `iTunesConnect.png` | 1024×1024 | Uploaded to App Store Connect |
+
+The skill generates the first and third; the second can be a copy of the first if the user wants a shared master.
+
+## Dark and tinted variants (iOS 18+)
+
+iOS 18 added dark-mode and tinted versions of app icons, configured via:
+
+- `DefaultIcon-Dark.png` — dark theme variant
+- `DefaultIcon-Tinted.png` — tinted grayscale variant for iOS's theme engine
+
+These are **out of scope** for this skill's v1. Users who want them can drop the files into the project root manually; Titanium SDK 13.1+ picks them up automatically.
+
+## Launch images — deliberately not generated
+
+The 30+ `Default-*@3x.png` launch image variants from Titanium documentation are legacy. Modern Titanium uses `LaunchScreen.storyboard`, configured in `tiapp.xml`:
+
+```xml
+<ios>
+  <enable-launch-screen-storyboard>true</enable-launch-screen-storyboard>
+  <default-background-color>#0B1326</default-background-color>
+</ios>
+```
+
+The storyboard adapts to any device resolution dynamically. Legacy PNG launch images were needed before iOS 14 — they are now dead weight in any app submitted to the App Store (Apple mandates storyboard-based launch as of 2020).
+
+If a user genuinely needs legacy launch images (maintaining a pre-2020 app), that's a separate tool job — this skill explicitly does not generate them.
+
+## References
+
+- Apple HIG: [App icons](https://developer.apple.com/design/human-interface-guidelines/app-icons)
+- Apple: [Configuring your project to use asset catalogs](https://developer.apple.com/documentation/xcode/configuring-your-project-to-use-asset-catalogs)

package/skills/ti-branding/references/master-input-guidelines.md

@@ -0,0 +1,84 @@
+# Master input guidelines
+
+## Preferred: SVG
+
+SVG is the best source because:
+
+- Vector: re-renders cleanly at any density, no upscaling artifacts
+- Preserves transparency natively
+- Small file size (~5–50 KB for typical logos vs 100+ KB for 1024² PNG)
+- Easy to edit by designers in Illustrator / Affinity / Figma / Inkscape
+
+**SVG requirements**:
+
+- Square viewBox (or content that's square within a rectangular viewBox)
+- Paths only — avoid `<script>`, `<foreignObject>`, web fonts
+- Solid fills or simple gradients — very complex gradients may rasterize inconsistently across densities
+- No external references (embedded images, fonts loaded by URL)
+
+The skill uses `rsvg-convert` to rasterize to 1024×1024 PNG before any further processing.
+
+## Acceptable: PNG ≥ 1024×1024 with transparency
+
+A PNG master works when SVG isn't available:
+
+- Minimum size: 1024×1024 (smaller input produces visibly soft xxxhdpi icons)
+- Square preferred — non-square inputs get center-cropped with a warning
+- Transparent background for best monochrome layer results
+
+## Accepted with warning: PNG with solid background
+
+PNGs that already have a non-transparent background still work, but:
+
+- The monochrome layer will be a solid square silhouette (every pixel is non-transparent, so "everything" becomes white)
+- You cannot change the adaptive background color — it's baked in
+- Recommend re-exporting from the source with transparency if possible
+
+## Padding and the "pegado" problem
+
+If the icon's content already fills the full canvas (logo touching the edges), every generated asset will show the same cramped look. The skill cannot add space that isn't there.
+
+Two ways to fix:
+
+1. **Prepare the master with transparent padding** — export the logo so there's ~15% empty space around it in the source
+2. **Increase the `--padding` flag** — the skill re-centers the logo inside the target canvas. Higher padding pushes the logo inward
+
+Recommended padding values:
+
+| Padding | Logo fill | When to use |
+|---------|-----------|-------------|
+| 19 (spec floor) | 62% | Intricate logos needing maximum detail; risky with aggressive launcher masks |
+| 22 (default) | 56% | Balanced, compliant with Android safe-zone spec + 3% buffer |
+| 25 | 50% | Logos with fine strokes or details near the edge |
+| 28–32 | 44–36% | Bold simple shapes, single-letter monograms |
+
+If the user sees the logo pegado after running the skill once, re-run with a higher `--padding`.
+
+## Alpha channel handling
+
+PNG inputs commonly have one of three alpha configurations:
+
+- **Straight alpha** (most common): `rgba(r, g, b, a)` — R/G/B hold true color, A holds coverage
+- **Premultiplied alpha**: `rgba(r × a, g × a, b × a, a)` — R/G/B are scaled by A
+- **No alpha channel**: opaque only
+
+ImageMagick handles straight alpha transparently. Premultiplied inputs may show dark halos at the edges when composited — if this happens, re-export from the source app with straight alpha.
+
+## Checking the master before running
+
+Quick sanity check:
+
+```bash
+# Dimensions and alpha info
+magick identify -format "%wx%h  alpha=%A\n" /path/to/logo.png
+
+# Visualize the alpha channel (useful for debugging halos)
+magick /path/to/logo.png -alpha extract /tmp/alpha.png && open /tmp/alpha.png
+```
+
+For SVG:
+
+```bash
+# Preview at output size
+rsvg-convert -w 1024 -h 1024 /path/to/logo.svg -o /tmp/preview.png && open /tmp/preview.png
+```

package/skills/ti-branding/references/notification-icons.md

@@ -0,0 +1,63 @@
+# Notification icons
+
+## The white-only rule
+
+Android notification icons, since API 21 (Lollipop), must be **white pixels on a transparent background**. The system applies a runtime tint based on the notification's `color` property — color in the source image is discarded.
+
+If the icon is not white+alpha, it renders as a blank white square on API 21+ (a common bug symptom when developers reuse their launcher icon as the notification icon).
+
+## Generation
+
+The skill's `gen-notification.sh`:
+
+1. Scales the foreground logo down to the notification size
+2. Runs ImageMagick's `-channel RGB -fill white -colorize 100 +channel` to force all RGB channels to 255 while preserving alpha
+3. Pads transparently to match the target canvas size
+
+## Sizes
+
+| Density  | Size |
+|----------|------|
+| mdpi     | 24   |
+| hdpi     | 36   |
+| xhdpi    | 48   |
+| xxhdpi   | 72   |
+| xxxhdpi  | 96   |
+
+## File naming
+
+Titanium has no hard convention, but the de-facto name is `ic_stat_notify.png`. The skill emits this name. To reference it:
+
+**In JavaScript (local notification)**:
+
+```js
+Ti.Android.NotificationManager.notify(1, Ti.Android.createNotification({
+  contentTitle: 'Hello',
+  contentText: 'Hi there',
+  icon: Ti.App.Android.R.drawable.ic_stat_notify  // white+alpha
+}))
+```
+
+**In `platform/android/AndroidManifest.xml` (Firebase default)**:
+
+```xml
+<meta-data
+  android:name="com.google.firebase.messaging.default_notification_icon"
+  android:resource="@drawable/ic_stat_notify"/>
+<meta-data
+  android:name="com.google.firebase.messaging.default_notification_color"
+  android:resource="@color/notification_tint"/>
+```
+
+With a matching `values/colors.xml`:
+
+```xml
+<color name="notification_tint">#FDD900</color>
+```
+
+The `default_notification_color` is the tint the runtime applies to the white pixels.
+
+## References
+
+- Android: [Notifications overview](https://developer.android.com/develop/ui/views/notifications)
+- Firebase: [Setting the default notification icon](https://firebase.google.com/docs/cloud-messaging/android/client#manifest)

package/skills/ti-branding/references/splash-screen-api.md

@@ -0,0 +1,81 @@
+# Splash screens (modern)
+
+## Two strategies by platform
+
+### iOS — storyboard-driven (iOS 14+)
+
+Modern iOS uses `LaunchScreen.storyboard`. Titanium enables this via `tiapp.xml`:
+
+```xml
+<ios>
+  <enable-launch-screen-storyboard>true</enable-launch-screen-storyboard>
+  <default-background-color>#0B1326</default-background-color>
+</ios>
+```
+
+The storyboard is a single layout that scales dynamically to any device. No per-device PNG launch images are needed. The `<default-background-color>` sets both the storyboard background AND the gap-color between the storyboard and the first view.
+
+This skill does NOT generate iOS launch images. It prints the `<default-background-color>` snippet for the user to paste.
+
+### Android 12+ — SplashScreen API (API 31+)
+
+Android 12 introduced a system-managed splash that replaces the old "put a PNG in drawable/background.png" approach. It's theme-driven:
+
+```xml
+<!-- platform/android/res/values-v31/splash_theme.xml -->
+<resources>
+  <style name="Theme.SnapGym.SplashScreen" parent="Theme.SplashScreen">
+    <item name="windowSplashScreenBackground">#0B1326</item>
+    <item name="windowSplashScreenAnimatedIcon">@drawable/splash_icon</item>
+    <item name="postSplashScreenTheme">@style/Theme.AppDerived</item>
+  </style>
+</resources>
+```
+
+With a matching `AndroidManifest.xml` entry (inside `<application>`):
+
+```xml
+<meta-data android:name="io.tidev.titanium.splash.theme"
+           android:value="@style/Theme.SnapGym.SplashScreen"/>
+```
+
+Critical: **do NOT apply this theme to `<application android:theme>` or to a specific `<activity>`** — it only affects the system SplashScreen via the manifest meta-data. Applying it to the application breaks the ActionBar / TitleBar in every subsequent screen (as SNAP Gym learned the hard way).
+
+### Android <12 — fallback to launcher icon
+
+On API <31, the system uses the launcher icon as the splash. No extra file needed. The `background.9.png` 9-patch pattern is obsolete in Titanium SDK 13+.
+
+## splash_icon.png canvas (Android 12+)
+
+The SplashScreen API spec:
+
+- Total canvas: **288 dp**
+- Icon safe-zone: **192 dp centered** (≈ 67% of canvas)
+- OS applies a circular mask automatically — keep content centered
+
+Density sizes:
+
+| Density  | Total canvas | Icon area |
+|----------|--------------|-----------|
+| mdpi     | 288          | 192       |
+| hdpi     | 432          | 288       |
+| xhdpi    | 576          | 384       |
+| xxhdpi   | 864          | 576       |
+| xxxhdpi  | 1152         | 768       |
+
+The skill's `gen-splash-icon.sh` places the logo at `192/288 ≈ 67%` of the canvas with transparent padding around it.
+
+## Why we don't generate `background.9.png`
+
+The old 9-patch splash pattern works like this:
+
+- PNG with 1px borders marked as stretchable regions
+- Titanium references it as `background.9.png` in `drawable-*dpi/`
+- SDK pre-13 used it as `windowBackground` for the root activity
+
+Titanium 13+ handles splash via the modern SplashScreen API on 12+ and via the launcher icon itself on older versions. `background.9.png` produces worse results on 12+ (competing with the SplashScreen API) and offers no benefit on older versions that the launcher fallback can't provide.
+
+## References
+
+- Android: [Splash screens](https://developer.android.com/develop/ui/views/launch/splash-screen)
+- Apple: [Configuring your app's launch screen](https://developer.apple.com/documentation/xcode/configuring-your-apps-launch-screen)

package/skills/ti-branding/references/ti-icon-paths.md

@@ -0,0 +1,84 @@
+# Canonical paths — Titanium SDK 13.x
+
+## Alloy layout (primary)
+
+```
+project-root/
+├── DefaultIcon-ios.png              # iOS master (1024² no alpha)
+├── DefaultIcon.png                  # Generic master (1024² no alpha) — fallback
+├── iTunesConnect.png                # 1024² App Store submission
+├── MarketplaceArtwork.png           # 512² Google Play submission
+├── tiapp.xml
+└── app/
+    ├── assets/
+    │   ├── iphone/                  # (optional) manual iOS appiconset — skill doesn't write here
+    │   └── android/
+    │       ├── appicon.png          # 128² legacy fallback (pre-adaptive)
+    │       └── images/              # density-scaled in-app image assets (NOT launcher)
+    └── platform/
+        └── android/
+            └── res/
+                ├── mipmap-mdpi/
+                │   ├── ic_launcher.png              # legacy 48²
+                │   ├── ic_launcher_foreground.png   # adaptive 108²
+                │   ├── ic_launcher_background.png   # adaptive 108²
+                │   └── ic_launcher_monochrome.png   # themed 108²
+                ├── mipmap-hdpi/    # 72 / 162 / 162 / 162
+                ├── mipmap-xhdpi/   # 96 / 216 / 216 / 216
+                ├── mipmap-xxhdpi/  # 144 / 324 / 324 / 324
+                ├── mipmap-xxxhdpi/ # 192 / 432 / 432 / 432
+                ├── mipmap-anydpi-v26/
+                │   └── ic_launcher.xml              # binds the 3 adaptive layers
+                ├── drawable-mdpi/
+                │   ├── ic_stat_notify.png           # (optional) 24² white+alpha
+                │   └── splash_icon.png              # (optional) 288² Android 12+ splash
+                ├── drawable-hdpi/  # 36 / 432
+                ├── drawable-xhdpi/ # 48 / 576
+                ├── drawable-xxhdpi/ # 72 / 864
+                └── drawable-xxxhdpi/ # 96 / 1152
+```
+
+## Classic layout
+
+Same structure, different roots. The skill detects `Resources/` and remaps:
+
+| Alloy path | Classic path |
+|---|---|
+| `app/assets/android/appicon.png` | `Resources/android/appicon.png` |
+| `app/platform/android/res/...` | `platform/android/res/...` |
+
+Root-level files (`DefaultIcon*.png`, `iTunesConnect.png`, `MarketplaceArtwork.png`) are identical in both layouts.
+
+## What Titanium does at build time
+
+- **iOS**: reads the root master → writes to `build/iphone/Assets.xcassets/AppIcon.appiconset/` (build directory, regenerated every build, never commited)
+- **Android**: copies `app/platform/android/res/*` verbatim to `build/android/app/src/main/res/`, plus copies `app/assets/android/appicon.png` to `build/.../res/drawable-*dpi/appicon.png` if the legacy path is used
+
+Result: anything the skill writes to `app/platform/android/res/` or `app/assets/` survives builds. Nothing the skill generates can be accidentally overwritten by `ti build`.
+
+## What the skill writes
+
+After confirming with the user, the skill copies from its staging directory to:
+
+| Target | Files |
+|---|---|
+| Project root | `DefaultIcon-ios.png`, `iTunesConnect.png`, `MarketplaceArtwork.png` |
+| `app/platform/android/res/mipmap-*/` | Launcher icons (adaptive triplet + legacy flat), 5 densities |
+| `app/platform/android/res/mipmap-anydpi-v26/` | `ic_launcher.xml` |
+| `app/platform/android/res/drawable-*/` (optional) | `ic_stat_notify.png`, `splash_icon.png` |
+
+The skill never touches `tiapp.xml`, `config.json`, source code, or anything outside the asset/resource paths above.
+
+## Required `tiapp.xml` entry
+
+For the adaptive icon to be picked up, `tiapp.xml` must reference it:
+
+```xml
+<android>
+  <manifest>
+    <application android:icon="@mipmap/ic_launcher"/>
+  </manifest>
+</android>
+```
+
+The skill checks for this and, if missing, prints the snippet — does not edit the file. See `tiapp-xml-snippets.md` for the full set.

package/skills/ti-branding/references/tiapp-xml-snippets.md

@@ -0,0 +1,92 @@
+# tiapp.xml snippets
+
+The skill prints these blocks after generating assets. The user reviews and pastes them manually — `tiapp.xml` often contains sensitive info (API keys, signing identities, staging URLs) and automated editing would be fragile.
+
+## Block 1 — iOS background color (for storyboard splash)
+
+Under the `<ios>` element:
+
+```xml
+<ios>
+  <enable-launch-screen-storyboard>true</enable-launch-screen-storyboard>
+  <default-background-color>#0B1326</default-background-color>
+</ios>
+```
+
+Replace `#0B1326` with the user's `--bg-color`.
+
+## Block 2 — Android application icon reference
+
+Under `<android><manifest><application>`:
+
+```xml
+<android>
+  <manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <application android:icon="@mipmap/ic_launcher"
+                 android:usesCleartextTraffic="false"/>
+  </manifest>
+</android>
+```
+
+The `android:icon="@mipmap/ic_launcher"` tells Android to use the adaptive icon XML (via `mipmap-anydpi-v26/ic_launcher.xml` on API 26+) with automatic fallback to the flat `mipmap-*dpi/ic_launcher.png` on older devices.
+
+## Block 3 — Android 12+ splash screen (optional, requires `--with-splash-icon`)
+
+Requires three changes:
+
+### 3a. Splash theme resource
+
+Create `app/platform/android/res/values-v31/splash_theme.xml`:
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+  <style name="Theme.App.SplashScreen" parent="Theme.SplashScreen">
+    <item name="windowSplashScreenBackground">#0B1326</item>
+    <item name="windowSplashScreenAnimatedIcon">@drawable/splash_icon</item>
+    <item name="postSplashScreenTheme">@style/Theme.AppDerived</item>
+  </style>
+</resources>
+```
+
+### 3b. Manifest meta-data (NOT a theme on `<application>` or `<activity>`)
+
+Under `<android><manifest><application>`:
+
+```xml
+<meta-data android:name="io.tidev.titanium.splash.theme"
+           android:value="@style/Theme.App.SplashScreen"/>
+```
+
+### 3c. DO NOT do this
+
+Setting `android:theme="@style/Theme.App.SplashScreen"` on `<application>` or `<activity>` will strip the ActionBar / TitleBar from every screen in the app because Titanium's `Theme.AppDerived` inherits from the application theme. The SplashScreen API is designed to work through the manifest meta-data entry above, not through activity theming.
+
+## Block 4 — Firebase Cloud Messaging notification icon (optional, requires `--with-notification`)
+
+Create `app/platform/android/res/values/colors.xml` (if it doesn't exist) with:
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+  <color name="notification_tint">#FDD900</color>
+</resources>
+```
+
+Then under `<android><manifest><application>`:
+
+```xml
+<meta-data android:name="com.google.firebase.messaging.default_notification_icon"
+           android:resource="@drawable/ic_stat_notify"/>
+<meta-data android:name="com.google.firebase.messaging.default_notification_color"
+           android:resource="@color/notification_tint"/>
+```
+
+## What the skill reports
+
+After generation, the skill prints only the blocks relevant to the flags used and the project's current state:
+
+- Always prints Block 2 if `android:icon="@mipmap/ic_launcher"` is missing from tiapp.xml
+- Always prints Block 1 if `<default-background-color>` is missing
+- Prints Block 3 only if `--with-splash-icon` was used
+- Prints Block 4 only if `--with-notification` was used