@maccesar/titools 2.5.1 → 2.6.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cesar Estrada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -8,7 +8,7 @@
 
 </div>
 
-TiTools is a CLI that installs Titanium SDK skills and a knowledge index for AI coding assistants. One command installs 8 skills, a research agent, and 100+ reference files for Titanium SDK, Alloy MVC, and PurgeTSS.
+TiTools is a Titanium SDK toolkit for AI coding assistants. It provides 9 skills, a research agent, and 100+ reference files for Titanium SDK, Alloy MVC, and PurgeTSS.
 
 The reference files are maintained against official documentation whenever an official source exists, so the assistant can retrieve current framework behavior instead of guessing from generic training data.
 
@@ -18,7 +18,41 @@ Vercel's AGENTS.md evaluation reports a 100% pass rate for the knowledge index a
 
 ---
 
-## Quick setup
+## Safety and disclaimer
+
+TiTools modifies files in your Titanium project. In particular, the `ti-branding` skill can write branding assets into `app/platform/android/res/` and, when invoked with the `--cleanup-legacy` flag, **delete** obsolete branding artifacts (iOS launch images, Android legacy splash, density fossil folders, etc.).
+
+Recommendations before running destructive operations:
+
+- **Commit your project with git** so you can `git restore` if anything looks wrong.
+- **Always run with `--dry-run` first** when using `--cleanup-legacy` or replacing icons. The skill prints every target and its safety reasoning before touching anything.
+- **Review the staging directory** (`.ti-branding/`) before copying generated assets into your project.
+
+The maintainers of TiTools accept no responsibility for data loss, build breakage, or any other damage caused by the use of the CLI, skills, or generated scripts. The tool is provided AS IS under the MIT License — see [`LICENSE`](./LICENSE) for the full terms. Use at your own risk.
+
+---
+
+## Installation
+
+### Option A: Plugin Marketplace (Claude Code only)
+
+The fastest way to get started with Claude Code. One command to add the marketplace, one to install:
+
+```bash
+/plugin marketplace add macCesar/titools
+/plugin install titools@maccesar-titools
+```
+
+What you get:
+- All 9 Titanium skills
+- ti-pro research agent
+- Session hook that auto-detects Titanium projects (`tiapp.xml`, Alloy, PurgeTSS)
+- Slash commands: `/ti-check`, `/ti-new-screen`, `/ti-audit`
+- Auto-updates via marketplace
+
+### Option B: CLI (Claude Code, Gemini CLI, Codex CLI)
+
+Cross-platform installation via npm. Works with all three AI coding assistants:
 
 ```bash
 # 1) Install the CLI
@@ -42,7 +76,7 @@ claude   # or gemini, or codex
 ```
 
 What gets installed:
-- All 8 titanium-related skills to `~/.agents/skills/`
+- All 9 titanium-related skills to `~/.agents/skills/`
 - ti-pro agent for Claude Code
 - Platform symlinks (Claude Code, Gemini CLI, Codex CLI)
 - Knowledge index in your project's `AGENTS.md`/`CLAUDE.md`/`GEMINI.md`
@@ -53,6 +87,20 @@ Why NPM?
 - No sudo required
 - Auto-updates via Claude Code hook (checks once per day)
 
+### Which option should I use?
+
+| | Plugin (Option A) | CLI (Option B) |
+|---|---|---|
+| **Claude Code** | Recommended | Supported |
+| **Gemini CLI** | Not available | Supported |
+| **Codex CLI** | Not available | Supported |
+| **Knowledge Index** | Not included | Included (`titools sync`) |
+| **Auto-updates** | Via marketplace | Via SessionStart hook |
+| **Slash commands** | `/ti-check`, `/ti-new-screen`, `/ti-audit` | Not available |
+| **Session hook** | Auto-detects Titanium projects | Auto-update only |
+
+Use **Option A** if you only use Claude Code. Use **Option B** if you use multiple AI assistants or want the Knowledge Index feature.
+
 ---
 
 ## Compatible platforms
@@ -134,6 +182,7 @@ The knowledge index is based on the latest Titanium SDK documentation. If your p
 | alloy-howtos | Alloy CLI and debugging         | Project setup, CLI commands, errors     |
 | purgetss     | Utility-first styling           | UI styling and animations               |
 | ti-api       | Complete API reference          | Properties, methods, events, constants  |
+| ti-branding  | Icon and splash generator       | App icons, adaptive icons, splash, notifications, store artwork, legacy cleanup |
 | ti-expert    | Architecture and implementation | Starting point for most tasks           |
 | ti-guides    | SDK fundamentals                | Hyperloop, distribution, configuration  |
 | ti-howtos    | Native feature integration      | Location, Push, Media, Platform APIs    |
@@ -149,14 +198,14 @@ In addition to skills, this repository includes sub-agents for Claude Code. Sub-
 
 ### ti-pro
 
-Deep-dive research specialist that preloads all 7 titanium-related skills.
+Deep-dive research specialist that preloads all 8 titanium-related documentation skills.
 
 | Aspect           | Details                                           |
 | ---------------- | ------------------------------------------------- |
 | Location         | `~/.claude/agents/ti-pro.md`                      |
 | Model            | Sonnet (comprehensive analysis)                   |
 | Tools            | Read-only (Read, Grep, Glob)                      |
-| Preloaded Skills | All 7 titanium-related skills injected at startup |
+| Preloaded Skills | All 8 Titanium documentation skills injected at startup |
 
 When to use the agent vs skills:
 
@@ -185,6 +234,35 @@ Key difference:
 
 ---
 
+## Slash Commands (Plugin only)
+
+When installed as a plugin, TiTools provides slash commands for common tasks:
+
+| Command | Description |
+|---|---|
+| `/ti-check` | Verify project setup: SDK version, Alloy structure, PurgeTSS config, common issues |
+| `/ti-new-screen <name>` | Create a new Alloy screen (controller + view + style) following project conventions |
+| `/ti-audit` | Audit project for anti-patterns, memory leaks, and best practice violations |
+
+These commands automatically invoke the relevant skills:
+- `/ti-check` reads `tiapp.xml` and reports project health
+- `/ti-new-screen` uses `alloy-guides` + `purgetss` to create properly structured files
+- `/ti-audit` uses `ti-expert` + `ti-ui` + `purgetss` + `alloy-guides` for comprehensive review
+
+---
+
+## Session Hook (Plugin only)
+
+The plugin includes a session start hook that auto-detects Titanium projects. When you open Claude Code in a directory with `tiapp.xml`, it automatically reports:
+
+```
+Titanium Alloy + PurgeTSS project detected. TiTools skills are available and MUST be used...
+```
+
+This ensures Claude knows it's a Titanium project from the first prompt, preventing it from writing generic code.
+
+---
+
 ## How skills work
 
 Skills are automatically activated based on your questions. Just ask naturally:

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.1",
+  "version": "2.6.1",
   "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>