@maccesar/titools 2.5.0 → 2.6.0

package/bin/titools.js

@@ -14,6 +14,7 @@ import { uninstallCommand } from '../lib/commands/uninstall.js';
 import { autoUpdateCommand } from '../lib/commands/auto-update.js';
 import { statusCommand } from '../lib/commands/status.js';
 import { doctorCommand } from '../lib/commands/doctor.js';
+import { listCommand } from '../lib/commands/list.js';
 
 const program = new Command();
 
@@ -73,6 +74,13 @@ program
   .description('Check installation health and diagnose issues')
   .action(doctorCommand);
 
+// List command
+program
+  .command('list')
+  .alias('ls')
+  .description('List available Titanium skills with short descriptions')
+  .action(listCommand);
+
 // Parse arguments
 program.parse();
 

package/lib/commands/list.js

@@ -0,0 +1,105 @@
+/**
+ * List command
+ * Enumerates available Titanium skills with a short description.
+ * Reads each skill's SKILL.md frontmatter — no hardcoded list.
+ */
+
+import chalk from 'chalk';
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import {
+  SKILLS,
+  PACKAGE_VERSION,
+  getAgentsSkillsDir,
+} from '../config.js';
+
+const CHECK = chalk.green('✓');
+const CROSS = chalk.red('✗');
+
+/**
+ * Extract the skill's human-readable name and short description from SKILL.md.
+ * Returns { description, installed } where description is the first sentence of
+ * the frontmatter description, trimmed for terminal display.
+ */
+function readSkillMetadata(skillDir) {
+  const skillMd = join(skillDir, 'SKILL.md');
+  if (!existsSync(skillMd)) {
+    return { description: null, installed: false };
+  }
+
+  try {
+    const content = readFileSync(skillMd, 'utf8');
+    const frontmatter = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!frontmatter) return { description: null, installed: true };
+
+    const descMatch = frontmatter[1].match(/description:\s*"([^"]+)"|description:\s*(.+)/);
+    if (!descMatch) return { description: null, installed: true };
+
+    const full = descMatch[1] || descMatch[2] || '';
+    // First sentence: period followed by whitespace (avoids breaking on "SDK 13."
+    // or other version-number periods). Falls back to a word-safe length cutoff.
+    let short;
+    const firstSentence = full.match(/^([^]*?\.)\s/);
+    if (firstSentence) {
+      short = firstSentence[1];
+    } else if (full.length > 80) {
+      const cut = full.slice(0, 80);
+      short = cut.slice(0, cut.lastIndexOf(' ')) + '…';
+    } else {
+      short = full;
+    }
+    return { description: short.trim(), installed: true };
+  } catch {
+    return { description: null, installed: true };
+  }
+}
+
+export async function listCommand() {
+  console.log('');
+  console.log(chalk.bold.blue(`Titanium skills (v${PACKAGE_VERSION})`));
+  console.log('');
+
+  const skillsDir = getAgentsSkillsDir();
+
+  if (!existsSync(skillsDir)) {
+    console.log(chalk.yellow('No skills installed yet.'));
+    console.log('Install with:');
+    console.log(chalk.cyan('  titools install'));
+    console.log('');
+    return;
+  }
+
+  const rows = [];
+  let installedCount = 0;
+  let maxNameLen = 0;
+
+  for (const name of SKILLS) {
+    const skillDir = join(skillsDir, name);
+    const { description, installed } = readSkillMetadata(skillDir);
+
+    if (installed) installedCount++;
+    if (name.length > maxNameLen) maxNameLen = name.length;
+
+    rows.push({ name, description, installed });
+  }
+
+  // Print aligned rows
+  for (const row of rows) {
+    const mark = row.installed ? CHECK : CROSS;
+    const paddedName = row.name.padEnd(maxNameLen + 2);
+    const desc = row.description
+      ? chalk.gray(row.description)
+      : chalk.gray(row.installed ? '(no description)' : 'not installed');
+
+    console.log(`  ${mark} ${chalk.cyan(paddedName)} ${desc}`);
+  }
+
+  console.log('');
+  console.log(chalk.gray(`${installedCount}/${SKILLS.length} installed at ${skillsDir}`));
+  console.log('');
+  console.log(chalk.gray('Run `titools status` for installation health.'));
+  console.log(chalk.gray('Run `titools doctor` to diagnose issues.'));
+  console.log('');
+}
+
+export default listCommand;

package/lib/config.js

@@ -38,6 +38,7 @@ export const SKILLS = [
   'ti-guides',
   'alloy-guides',
   'alloy-howtos',
+  'ti-branding',
 ];
 // Legacy skills to remove during updates/uninstall
 export const LEGACY_SKILLS = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maccesar/titools",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Titanium SDK skills and agents for AI coding assistants (Claude Code, Gemini CLI, Codex CLI)",
   "main": "lib/index.js",
   "type": "module",

package/skills/alloy-guides/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: alloy-guides
-description: "Titanium Alloy MVC official framework reference. Use when working with, reviewing, analyzing, or examining Alloy models, views, controllers, Backbone.js data binding, TSS styling, widgets, Alloy CLI, sync adapters, migrations, or MVC compilation. Explains how Backbone.js models and collections work in Alloy."
+description: "Titanium Alloy MVC official framework reference. Use when working with, reviewing, analyzing, or examining Alloy models, views, controllers, Backbone.js data binding, TSS styling, widgets, Alloy CLI, sync adapters, migrations, or MVC compilation. AUTO-DETECT: If the project has an app/views/ + app/controllers/ + app/styles/ folder structure, it is an Alloy project — invoke this skill BEFORE editing XML views, JS controllers, or TSS styles. Alloy XML is NOT HTML; TSS is NOT CSS; controllers follow Alloy-specific patterns, not web MVC."
 argument-hint: "[concept]"
 allowed-tools: Read, Grep, Glob, Edit, Write, Bash(node *)
 ---

package/skills/alloy-howtos/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: alloy-howtos
-description: "Titanium Alloy CLI and configuration guide. Use when creating, reviewing, analyzing, or examining Alloy projects, running alloy commands (new, generate, compile), configuring alloy.jmk or config.json, debugging compilation errors, creating conditional views, using Backbone.Events for communication, or writing custom XML tags."
+description: "Titanium Alloy CLI and configuration guide. Use when creating, reviewing, analyzing, or examining Alloy projects, running alloy commands (new, generate, compile), configuring alloy.jmk or config.json, debugging compilation errors, creating conditional views, using Backbone.Events for communication, or writing custom XML tags. AUTO-DETECT: If the project has app/views/ + app/controllers/ structure and the task involves Alloy CLI commands, project configuration, or build issues, invoke this skill first."
 argument-hint: "[task]"
 allowed-tools: Read, Grep, Glob, Edit, Write, Bash(alloy *), Bash(node *)
 ---

package/skills/purgetss/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: purgetss
-description: "Titanium PurgeTSS utility-first styling toolkit. Use when styling, reviewing, analyzing, or examining Titanium UI with utility classes, configuring config.cjs, creating dynamic components with $.UI.create(), building animations, using grid layouts, setting up icon fonts, or working with TSS styles. Never suggest other CSS framework classes - verify in class-index.md first."
+description: "Titanium PurgeTSS utility-first styling toolkit. Use when styling, reviewing, analyzing, or examining Titanium UI with utility classes, configuring config.cjs, creating dynamic components with $.UI.create(), building animations, using grid layouts, setting up icon fonts, or working with TSS styles. AUTO-DETECT: If purgetss/ folder or purgetss/config.cjs exists, this project uses PurgeTSS — invoke this skill BEFORE writing ANY styling code. All styling MUST use PurgeTSS utility classes in XML, NOT custom TSS. PurgeTSS classes look like Tailwind but are NOT Tailwind — verify every class exists before using it. Never use padding on Views (use margins on children), never use flexbox classes, never write manual TSS when a utility class exists."
 argument-hint: "[class-name]"
 allowed-tools: Read, Grep, Glob, Edit, Write, Bash(purgetss *), Bash(node *)
 ---

package/skills/ti-api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ti-api
-description: "Titanium SDK complete API reference. Use when looking up properties, methods, events, constants, or type signatures for any Ti.* or Modules.* API. Covers Ti.UI, Ti.Android, Ti.App, Ti.Media, Ti.Network, Ti.Database, Ti.Filesystem, Ti.Geolocation, Ti.Contacts, Ti.Calendar, Global, and third-party modules (Map, BLE, NFC, Facebook, Identity, CoreMotion)."
+description: "Titanium SDK complete API reference. Use when looking up properties, methods, events, constants, or type signatures for any Ti.* or Modules.* API. Covers Ti.UI, Ti.Android, Ti.App, Ti.Media, Ti.Network, Ti.Database, Ti.Filesystem, Ti.Geolocation, Ti.Contacts, Ti.Calendar, Global, and third-party modules (Map, BLE, NFC, Facebook, Identity, CoreMotion). AUTO-DETECT: If tiapp.xml exists in the project, this is a Titanium project — invoke this skill BEFORE writing any code that uses Ti.* APIs. Do NOT rely on training data for Titanium APIs; always check the reference files in this skill first."
 argument-hint: "[Ti.UI.Window | Ti.Network.HTTPClient | Modules.Map.View | ...]"
 allowed-tools: Read, Grep, Glob
 ---

package/skills/ti-branding/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: ti-branding
+description: "Generate complete app branding assets for modern Titanium SDK 13.x projects — launcher icons, adaptive icons, splash-screen icons, notification icons, and marketplace artwork — from a single SVG or PNG master. Use when the user asks to brand their app, update the app icon, set up splash screens, prepare store assets, fix generic/placeholder icons, add a notification icon, generate a launcher for Android 8+/13+, replace the TiTools default icon, or anything related to visual identity of a Titanium app (Alloy or Classic). Auto-detects Alloy vs Classic layout. Outputs iOS `DefaultIcon-ios.png` (flattened), Android adaptive triplet (foreground + background + monochrome) across 5 densities, Android legacy launcher × 5, marketplace artwork (1024² + 512²), and optionally notification icons and Android 12+ splash icons. Targets SDK 13.0–13.2 minimums without legacy cruft (post-Xcode 14 iOS minimums, no 9-patch splash, no pre-adaptive Android icons). Delegates raster work to ImageMagick + librsvg (system tools) — zero npm/pip dependencies. Invoke this skill whenever the user mentions icons, splash screens, branding, launcher, adaptive icon, mipmap, appiconset, DefaultIcon, iTunesConnect, Play Store artwork, or any visual asset for a Titanium app."
+argument-hint: "[master-path] [--bg-color <hex>] [--padding <pct>] [--with-notification] [--with-splash-icon] [--cleanup-legacy] [--aggressive] [--dry-run]"
+allowed-tools: Read, Glob, Bash, Write, Edit
+---
+
+# Titanium branding — icons and splash screens
+
+Generate the full set of launcher icons, adaptive icons, splash icons, notification icons, and marketplace artwork for a Titanium SDK 13.x project from ONE master input. Non-destructive by default (dry-run first, confirm before overwriting).
+
+## When to invoke this skill
+
+Invoke proactively whenever the user's work touches any of:
+
+- Replacing the generic/placeholder icon that ships with new Titanium projects
+- Adding brand identity (logo-based launcher) to an app
+- Fixing "my icon looks pixelated / pegado / cut-off on Android"
+- Setting up the Android 12+ splash screen with a custom background color
+- Generating notification icons for Firebase Cloud Messaging / local reminders
+- Preparing App Store / Google Play artwork for a release build
+- Updating icons after a rebrand or logo refresh
+- Generating adaptive icon foreground / background / monochrome layers
+- Migrating a legacy project to modern Android adaptive icons
+
+## What gets generated
+
+Every invocation produces (in a staging directory, reviewed before copy):
+
+| Asset | Path in project | Why |
+|---|---|---|
+| `DefaultIcon-ios.png` (1024×1024, no alpha) | Project root | iOS SDK generates the full appiconset from this at build time. Flattened because Apple rejects alpha channels. |
+| `iTunesConnect.png` (1024×1024, no alpha) | Project root | App Store submission requirement. |
+| `MarketplaceArtwork.png` (512×512, no alpha) | Project root | Google Play submission requirement. |
+| `ic_launcher_foreground.png` × 5 densities | `app/platform/android/res/mipmap-{m,h,x,xx,xxx}hdpi/` | Adaptive icon foreground layer. Logo centered in 108dp canvas with configurable padding (default 22% ≈ 66dp safe-zone). |
+| `ic_launcher_background.png` × 5 densities | idem | Adaptive icon background layer — solid `--bg-color`. |
+| `ic_launcher_monochrome.png` × 5 densities | idem | Android 13+ themed icons (all non-transparent pixels → white). |
+| `ic_launcher.png` × 5 densities (legacy) | idem | Fallback for Android < 8 (~3% of users in 2026). |
+| `ic_launcher.xml` | `app/platform/android/res/mipmap-anydpi-v26/` | Adaptive icon definition that binds the 3 layers. |
+
+Optional (flags):
+
+| Asset | Flag | Path |
+|---|---|---|
+| `ic_stat_notify.png` × 5 densities (white + alpha) | `--with-notification` | `app/platform/android/res/drawable-{m,h,x,xx,xxx}hdpi/` |
+| `splash_icon.png` × 5 densities | `--with-splash-icon` | idem (drawable-*) — for Android 12+ `windowSplashScreenAnimatedIcon` |
+
+For Classic projects (Resources/ layout), paths resolve to `Resources/android/...` instead of `app/platform/android/...`.
+
+## Dependencies
+
+- **ImageMagick 7.x** (required) — raster ops. `brew install imagemagick` / `apt install imagemagick`
+- **librsvg** (optional, only if input is SVG) — SVG → PNG rasterization. `brew install librsvg` / `apt install librsvg2-bin`
+- **Python 3** (optional, only for `--with-notification` alpha-mask extraction) — stdlib only, no pip install needed
+
+The skill's `scripts/lib/deps.sh` detects missing tools and prints OS-specific install instructions. Do not attempt to auto-install.
+
+## Invocation
+
+Main entry point: `scripts/ti-branding`. The skill runs it via Bash and then handles the review/copy workflow in Claude.
+
+```bash
+bash scripts/ti-branding <master> [options]
+```
+
+Options:
+
+| Flag | Default | Purpose |
+|---|---|---|
+| `--bg-color <hex>` | `#FFFFFF` | Solid color for adaptive background layer. Also used for iOS alpha flatten. |
+| `--padding <pct>` | `22` | Safe-zone padding per side (Android official minimum is 19.44% — 22% adds a small buffer against launcher masking). Range 0–40. |
+| `--with-notification` | off | Emit `ic_stat_notify.png` × 5 densities. |
+| `--with-splash-icon` | off | Emit `splash_icon.png` × 5 densities (Android 12+ SplashScreen API). |
+| `--cleanup-legacy` | off | After generating (or standalone), scan the project for legacy branding artifacts — iOS launch image PNGs, Android `default.png`, `appicon.png`, `res-long-*/res-notlong-*`, etc. — and remove them. Context-aware: reads `tiapp.xml` to decide what's safe. See `references/cleanup-legacy.md`. |
+| `--aggressive` | off | With `--cleanup-legacy`, also remove `ldpi` density folders (<1% of active devices globally in 2026). Off by default to be conservative. |
+| `--output <dir>` | `<project>/.ti-branding/` | Staging directory. Review before copying to `app/`. |
+| `--dry-run` | off | Print what would be generated/removed without writing or deleting. Works with both generation and `--cleanup-legacy`. |
+
+## Safety reminders
+
+This skill writes PNGs and an XML file into the project's `app/platform/android/res/` and `app/assets/iphone/` paths, and with `--cleanup-legacy` it deletes obsolete branding artifacts. The flow is designed to be safe (staging → review → copy, dry-run first, `tiapp.xml`-driven safety rules), but the user should commit the project before running destructive operations so that `git restore` is available as a rollback. The tool is provided AS IS under the MIT License. No warranty, no liability — see the repository's `LICENSE`.
+
+## Workflow
+
+1. **Detect project layout** — look for `app/` (Alloy) or `Resources/` (Classic). If neither, error.
+2. **Validate master** — run `scripts/lib/validate.sh` to confirm dimensions ≥ 1024×1024, square, and check for alpha-bleed at edges.
+3. **Check dependencies** — `scripts/lib/deps.sh` verifies `magick` + (if SVG) `rsvg-convert`.
+4. **Prepare master** — `scripts/lib/prepare-master.sh` converts SVG → 1024×1024 PNG with transparency preserved, or normalizes PNG input. Auto-crops transparent padding already in the source.
+5. **Generate assets** — call `gen-ios.sh`, `gen-android-adaptive.sh`, `gen-android-legacy.sh`, `gen-marketplace.sh` (and optionally `gen-notification.sh`, `gen-splash-icon.sh`). All outputs land in the staging directory.
+6. **Review with user** — show a diff of what will be overwritten in the project. Ask for explicit confirmation.
+
+   When opening generated PNGs for visual review, use the OS-native **lightweight previewer** — not whatever app the user has configured as the default PNG handler. Otherwise heavy editors like Affinity, Photoshop, or GIMP launch for a simple 3-file preview, which is annoying. Commands by OS:
+
+   - **macOS**: `open -a Preview <file>...` — Preview.app ships with every Mac, lightweight, always available.
+   - **Linux**: `xdg-open <file>` — desktop-agnostic, honors the user's registered image viewer. If you need something specific, `eog` (GNOME) / `gwenview` (KDE) / `feh` are common lightweight viewers. Prefer `xdg-open` as the portable default.
+   - **Windows**: `start "" <file>` (cmd) or `Invoke-Item <file>` (PowerShell). Windows doesn't ship a universal lightweight viewer equivalent to Preview — it uses whatever the user set (Photos app by default on Windows 10/11). Live with that.
+
+   Only preview 2–3 representative assets (e.g. `DefaultIcon-ios.png`, the highest-density `ic_launcher_foreground.png`, and — if generated — `splash_icon.png`). Do not open all 20+ PNGs.
+7. **Copy to project** — after confirmation, copy staging → target paths. Keep the staging directory for rollback.
+8. **Print tiapp.xml snippets** — do NOT edit `tiapp.xml` automatically. Print exact XML blocks for the user to review and paste manually. See `references/tiapp-xml-snippets.md` for the blocks.
+9. **Suggest verification build** — `ti clean && ti build -p android -T emulator` / `-p ios -T simulator`.
+
+## Padding guidance (important)
+
+The Android adaptive icon spec defines a 108dp canvas with a 66dp safe-zone. Expressed as padding: `(108-66)/2/108 ≈ 19.44%` per side. Anything inside the safe-zone is guaranteed to be visible regardless of the launcher's mask (circle, squircle, teardrop).
+
+Defaults and recommendations:
+
+| Padding | Logo fill | When to use |
+|---|---|---|
+| `19` (spec minimum) | 62% | Intricate logos needing maximum visible detail. Risky — leaves no buffer for aggressive launcher masks. |
+| `22` (default) | 56% | Balanced: compliant with spec + 3% buffer. Recommended for most apps. |
+| `25` | 50% | Logos with fine details near edges (wordmarks, thin strokes). |
+| `28`–`32` | 44%–36% | Simple icons, single-letter monograms, bold shapes. Gives visual breathing room. |
+
+If the user reports "my logo looks pegado / cramped / cut off on edges", increase padding. If the user reports "my logo looks tiny / lost in the middle", decrease padding.
+
+## iOS notes (modern)
+
+- iOS 13+ only. Targets Titanium SDK 13.0+.
+- `DefaultIcon-ios.png` is 1024×1024 with **no alpha channel** — Apple rejects transparency. The skill flattens alpha over `--bg-color`.
+- Xcode 14+ no longer requires the full 20-size appiconset. Titanium generates all required sizes from `DefaultIcon-ios.png` at build time into `build/iphone/Assets.xcassets/AppIcon.appiconset/` — the source project only needs the master.
+- `DefaultIcon-Dark.png` and `DefaultIcon-Tinted.png` (iOS 18+) are out of scope for this skill's v1. The user can add them manually later.
+- Launch images (`Default-*@3x.png`) are intentionally NOT generated. Modern Titanium uses `<enable-launch-screen-storyboard>true</enable-launch-screen-storyboard>` which adapts to any resolution via the storyboard + `<default-background-color>`. Legacy PNG launch images are dead weight.
+
+See `references/ios-appiconset.md` for full details.
+
+## Android notes (modern)
+
+- Minimum API: 21 (Lollipop). Target: API 34 (Android 14).
+- Adaptive icons (API 26+) are the primary launcher icon. Legacy `ic_launcher.png` (flat) is included only as fallback for API 21–25.
+- Monochrome layer (API 31+) is required for themed icons. The skill generates it by tinting all non-transparent foreground pixels to pure white (`RGB 255,255,255`, alpha preserved).
+- Splash screen (API 31+) uses `windowSplashScreenBackground` + `windowSplashScreenAnimatedIcon` in the app theme. Pre-12 Android falls back to the launcher icon automatically. 9-patch `background.9.png` is obsolete — not generated.
+- Notification icons (if `--with-notification`) must be white-on-transparent. Android applies a tint at runtime based on the notification's `color` property.
+
+See `references/android-adaptive-icons.md` and `references/splash-screen-api.md` for depth.
+
+## Reference files
+
+Load these on-demand when implementing specific parts of the workflow:
+
+- `references/ti-icon-paths.md` — Canonical paths for Alloy vs Classic layouts, per Titanium SDK version.
+- `references/android-adaptive-icons.md` — Safe-zone math, densities, XML bind format, monochrome rules.
+- `references/ios-appiconset.md` — Xcode 14+ minimums, DefaultIcon pipeline, alpha flattening.
+- `references/notification-icons.md` — White-only rule, runtime tinting, size table.
+- `references/splash-screen-api.md` — Android 12+ SplashScreen vs pre-12 legacy, iOS storyboard.
+- `references/master-input-guidelines.md` — SVG best practices, PNG alpha handling, bbox auto-detection, padding ergonomics.
+- `references/tiapp-xml-snippets.md` — Copy-paste blocks for `<default-background-color>`, splash theme overrides, adaptive icon manifest entries.
+- `references/cleanup-legacy.md` — What `--cleanup-legacy` removes, why each artifact is obsolete, the `tiapp.xml`-driven safety rules, and real-world space savings from dogfooding on SNAP Gym.
+
+## Non-goals
+
+- Does not generate iOS launch image PNGs (`Default-*@3x.png`) — storyboard-driven, no longer needed.
+- Does not generate Android `background.9.png` 9-patch splash — obsolete since Ti SDK 10+.
+- Does not edit `tiapp.xml` — prints snippets only. User decides what to paste.
+- **Does not create `values-v31/splash_theme.xml`, `values/colors.xml`, or any other resource XML file that depends on project-specific config (Gradle dependencies, existing themes, etc.).** Prints snippets for the user to paste after review. The only XML file the skill does write is `mipmap-anydpi-v26/ic_launcher.xml` — that one is pure adaptive-icon binding with no external library requirements.
+- Does not install ImageMagick or librsvg — detects and instructs.
+- Does not handle `DefaultIcon-Dark.png` / `DefaultIcon-Tinted.png` in v1. Leave for a future flag if users request it.
+- Does not handle tab bar / toolbar icons. Those are in-app assets, not branding.
+
+## Known limitations
+
+### `--with-splash-icon` is "PNG-only" — wire-up is user's responsibility
+
+Titanium SDK 13.x already generates a reasonable Android 12+ splash screen automatically, using the launcher icon you just created plus the `<default-background-color>` from `tiapp.xml`. For most apps this default is good enough and requires zero extra configuration.
+
+The `--with-splash-icon` flag generates `splash_icon.png × 5 densities` for advanced users who want a splash icon visually distinct from the launcher icon. Wiring it up requires a custom theme, which has TWO flavors (both printed in the post-generation notes):
+
+- **Native platform theme** (API 31+ only, no library): uses `parent="@android:style/Theme.DeviceDefault.NoActionBar"` with `android:windowSplashScreen*` attributes. Compiles out of the box. Pre-12 devices fall back to Titanium's default splash.
+- **androidx.core:core-splashscreen library** (API 21+ backward-compat): uses `parent="Theme.SplashScreen"` with unqualified attributes. Requires adding `implementation 'androidx.core:core-splashscreen:1.0.1'` to `app/platform/android/build.gradle`.
+
+The skill does NOT auto-pick or auto-create these resource files because:
+1. The user may already have custom themes that conflict
+2. The library flavor requires modifying Gradle config (can't be reversed cleanly)
+3. `tiapp.xml` meta-data registration requires opening a possibly self-closing `<application>` tag
+
+Print both options, explain the tradeoffs, let the user decide.
+
+### Do NOT set the splash theme on `<application android:theme>` or on any `<activity>`
+
+Tempting but wrong. Titanium's `Theme.AppDerived` inherits from the `<application>` theme. Setting a NoActionBar splash theme there propagates NoActionBar to every `TiActivity` in the app, stripping the ActionBar / TitleBar from every screen globally. The only correct registration is via `<meta-data android:name="io.tidev.titanium.splash.theme">`.
+
+### `<application>` in `tiapp.xml` may be self-closing
+
+When the project's `<application>` tag is self-closing (e.g. `<application android:icon="@mipmap/ic_launcher"/>`), users must expand it before adding `<meta-data>` children:
+
+```xml
+<!-- Before (self-closing) -->
+<application android:icon="@mipmap/ic_launcher"/>
+
+<!-- After (expanded) -->
+<application android:icon="@mipmap/ic_launcher">
+  <meta-data .../>
+</application>
+```
+
+The skill's post-generation notes remind the user of this.
+
+## Example invocations
+
+```bash
+# Minimal: PNG master, white background, default 22% padding
+bash scripts/ti-branding ./logo.png
+
+# SNAP Gym full kit: SVG master, navy background, notification + splash
+bash scripts/ti-branding ./docs/snap-logo.svg \
+    --bg-color "#0B1326" \
+    --padding 22 \
+    --with-notification \
+    --with-splash-icon
+
+# Tight padding for a detailed wordmark
+bash scripts/ti-branding ./logo.svg --padding 19 --bg-color "#000000"
+
+# Preview only (no files written)
+bash scripts/ti-branding ./logo.svg --bg-color "#FF6600" --dry-run
+
+# Cleanup-only mode — no master image needed, removes legacy artifacts
+bash scripts/ti-branding --cleanup-legacy --dry-run
+bash scripts/ti-branding --cleanup-legacy                # apply
+bash scripts/ti-branding --cleanup-legacy --aggressive   # also ldpi
+
+# One-shot: generate branding AND clean up legacy in a single invocation
+bash scripts/ti-branding ./logo.svg --bg-color "#0B1326" --cleanup-legacy
+```

package/skills/ti-branding/assets/ic_launcher.xml

@@ -0,0 +1,6 @@
+<?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>

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).