@maccesar/titools 2.6.1 → 2.7.0

package/README.md

@@ -48,7 +48,9 @@ What you get:
 - 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
+- Auto-updates via marketplace (opt-in — see note below)
+
+> **Note on auto-updates:** Claude Code disables auto-updates by default for third-party marketplaces like this one. To receive new versions automatically, open `/plugin` → **Marketplaces** tab and enable auto-update for `maccesar-titools`. When an update is applied, Claude Code prompts you to run `/reload-plugins` to activate the new code.
 
 ### Option B: CLI (Claude Code, Gemini CLI, Codex CLI)
 
@@ -89,15 +91,15 @@ Why NPM?
 
 ### 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 |
+|                     | 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**    | Marketplace (opt-in, enable in `/plugin`)  | SessionStart hook (daily) |
+| **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.
 
@@ -176,17 +178,17 @@ The knowledge index is based on the latest Titanium SDK documentation. If your p
 
 ## Skills overview
 
-| Skill        | Purpose                         | Best For                                |
-| ------------ | ------------------------------- | --------------------------------------- |
-| alloy-guides | Alloy MVC reference             | Models, Views, Controllers, Widgets     |
-| 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  |
+| Skill        | Purpose                         | Best For                                                                        |
+| ------------ | ------------------------------- | ------------------------------------------------------------------------------- |
+| alloy-guides | Alloy MVC reference             | Models, Views, Controllers, Widgets                                             |
+| 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    |
-| ti-ui        | UI/UX patterns                  | Complex layouts, ListViews, platform UI |
+| 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                                            |
+| ti-ui        | UI/UX patterns                  | Complex layouts, ListViews, platform UI                                         |
 
 Note: `ti-guides`, `ti-howtos`, `ti-ui`, `alloy-guides`, and `alloy-howtos` are based on official Titanium SDK and Alloy documentation. `purgetss` is opinionated in workflow and conventions, but its reference files are audited against the official PurgeTSS documentation for verifiable classes and behavior. `ti-expert` and `purgetss` reflect personal coding conventions (biased toward PurgeTSS).
 
@@ -200,11 +202,11 @@ In addition to skills, this repository includes sub-agents for Claude Code. Sub-
 
 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)                      |
+| Aspect           | Details                                                 |
+| ---------------- | ------------------------------------------------------- |
+| Location         | `~/.claude/agents/ti-pro.md`                            |
+| Model            | Sonnet (comprehensive analysis)                         |
+| Tools            | Read-only (Read, Grep, Glob)                            |
 | Preloaded Skills | All 8 Titanium documentation skills injected at startup |
 
 When to use the agent vs skills:
@@ -238,11 +240,11 @@ Key difference:
 
 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 |
+| 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 |
+| `/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
@@ -660,8 +662,8 @@ titools auto-update --silent   # No output (for hooks)
 ```
 
 Options:
-| Option         | Description                        |
-| -------------- | ---------------------------------- |
+| Option         | Description                       |
+| -------------- | --------------------------------- |
 | `-s, --silent` | Suppress all output except errors |
 
 What it does:
@@ -798,11 +800,11 @@ The TiTools skills include **Community-Discovered Patterns** — verified iOS be
 
 When using Large Titles with a ScrollView inside NavigationWindow or TabGroup, three Window properties must be set together. Without all three, the ScrollView content overlaps behind the navigation bar — or the large title renders with a visible delay.
 
-| Class | Property | Purpose |
-|---|---|---|
-| `auto-adjust-scroll-view-insets` | `autoAdjustScrollViewInsets` | Adjusts ScrollView insets to prevent content overlap |
-| `extend-edges-all` | `extendEdges` | Content extends behind bars (blur/translucent effect) |
-| `large-title-enabled` | `largeTitleEnabled` | Large title that collapses on scroll |
+| Class                            | Property                     | Purpose                                               |
+| -------------------------------- | ---------------------------- | ----------------------------------------------------- |
+| `auto-adjust-scroll-view-insets` | `autoAdjustScrollViewInsets` | Adjusts ScrollView insets to prevent content overlap  |
+| `extend-edges-all`               | `extendEdges`                | Content extends behind bars (blur/translucent effect) |
+| `large-title-enabled`            | `largeTitleEnabled`          | Large title that collapses on scroll                  |
 
 **Recommended:** set the base properties as global Window defaults in `config.cjs`:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maccesar/titools",
-  "version": "2.6.1",
+  "version": "2.7.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/ti-branding/SKILL.md

@@ -1,7 +1,7 @@
 ---
 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]"
+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.png` (alpha-preserved source) + `DefaultIcon-ios.png` (alpha-flattened for Apple), Android adaptive triplet (foreground + background + monochrome) across 5 densities, Android legacy launcher × 5, marketplace artwork (1024² + 512², alpha-preserved), 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] [--in-place] [--monochrome-master <path>] [--notes] [--dry-run]"
 allowed-tools: Read, Glob, Bash, Write, Edit
 ---
 
@@ -29,9 +29,10 @@ 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. |
+| `DefaultIcon.png` (1024×1024, alpha preserved) | Project root | Universal source — Titanium's `ti create` template ships this with alpha. Used for Android / Alloy references and as the alpha-intact source of truth. |
+| `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 on App Store icon uploads. |
+| `iTunesConnect.png` (1024×1024, alpha preserved) | Project root | App Store artwork template. Matches `ti create` default — alpha preserved so the developer can composite over any background before upload. |
+| `MarketplaceArtwork.png` (512×512, alpha preserved) | Project root | Google Play feature graphic template. Matches `ti create` default — alpha preserved. |
 | `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). |
@@ -68,12 +69,15 @@ 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. |
+| `--padding <pct>` | `20` | Safe-zone padding per side. Material spec floor is 19.44% — default of 20 gives a tiny buffer while keeping the logo visibly prominent across launcher masks. 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/`. |
+| `--in-place` | off | Skip the staging directory and write files directly into the project root. **Overwrites existing icons.** Ideal right after `ti create` when you want to replace the default Titanium/Alloy icons in one command. `--output` takes precedence if both are passed. |
+| `--monochrome-master <path>` | — | Optional dedicated silhouette master for `ic_launcher_monochrome.png` + `ic_stat_notify.png`. Use this when your colored logo has multi-color detail that would collapse into a featureless blob when naively whitened (e.g. a painter's palette with 4 color dots — provide a monochrome variant with cutout holes instead so the detail survives in themed icons and notification status bar). Falls back to whitening the main master when not provided. |
+| `--notes` | off | Print the full tiapp.xml snippets (iOS launch storyboard, Android launcher wiring, Android 12+ splash theme with Option A/B, FCM notification tint) and the padding tuning guide. Default output is a compact summary (~15 lines). |
 | `--dry-run` | off | Print what would be generated/removed without writing or deleting. Works with both generation and `--cleanup-legacy`. |
 
 ## Safety reminders

package/skills/ti-branding/scripts/lib/gen-android-adaptive.sh

@@ -13,8 +13,9 @@
 gen_android_adaptive() {
   local master="$1"
   local bg="$2"
-  local padding="$3"      # percent per side
-  local res_root="$4"     # e.g. /path/app/platform/android/res
+  local padding="$3"        # percent per side
+  local res_root="$4"       # e.g. /path/app/platform/android/res
+  local mono_master="${5:-}" # optional dedicated silhouette master
 
   local densities=(mdpi hdpi xhdpi xxhdpi xxxhdpi)
   local sizes=(108 162 216 324 432)
@@ -38,11 +39,22 @@ gen_android_adaptive() {
       -strip \
       "$dir/ic_launcher_background.png"
 
-    # Monochrome: foreground tinted to pure white, alpha preserved
-    magick "$dir/ic_launcher_foreground.png" \
-      -channel RGB -fill white -colorize 100 +channel \
-      -strip \
-      "$dir/ic_launcher_monochrome.png"
+    # Monochrome: white silhouette with alpha. If a dedicated mono master was
+    # provided, render it fresh with the same padding. Otherwise derive from
+    # the colored foreground (naive whitening — may flatten complex logos).
+    if [[ -n "$mono_master" ]]; then
+      magick "$mono_master" \
+        -resize "${inner}x${inner}" \
+        -background none -gravity center -extent "${size}x${size}" \
+        -channel RGB -fill white -colorize 100 +channel \
+        -strip \
+        "$dir/ic_launcher_monochrome.png"
+    else
+      magick "$dir/ic_launcher_foreground.png" \
+        -channel RGB -fill white -colorize 100 +channel \
+        -strip \
+        "$dir/ic_launcher_monochrome.png"
+    fi
   done
 
   # anydpi-v26 binder directory (XML copied by caller from assets/ic_launcher.xml)

package/skills/ti-branding/scripts/lib/gen-ios.sh

@@ -1,12 +1,17 @@
 #!/usr/bin/env bash
-# gen-ios.sh — produce DefaultIcon-ios.png (1024×1024, alpha flattened over bg-color).
+# gen-ios.sh — produce Titanium's two root-level iOS/Android icons:
 #
-# Unlike Android adaptive icons, iOS app icons have no "safe zone" — the launcher
-# doesn't mask them. What you see is what ships. So padding is purely visual
-# breathing room around the logo. Default 8% per side (logo fills 84% of the
-# canvas), which matches Apple's HIG aesthetic for branded wordmarks.
+#   DefaultIcon.png       1024×1024, alpha preserved (universal / Android source)
+#   DefaultIcon-ios.png   1024×1024, alpha flattened over bg-color (iOS)
 #
-# iOS rejects icons with alpha, so the final output is flattened over bg-color.
+# This matches what `titanium` / `alloy new` ships out of the box: a fresh
+# Alloy project contains both files in the project root, with DefaultIcon.png
+# keeping transparency and DefaultIcon-ios.png flattened (Apple rejects alpha
+# on App Store icon uploads).
+#
+# Padding is purely visual breathing room — iOS app icons have no launcher
+# mask. Default 8% per side (logo fills 84% of the canvas), which matches
+# Apple's HIG aesthetic for branded wordmarks.
 
 gen_ios() {
   local tight="$1"        # tight master (aspect-preserved, transparent bg)
@@ -19,6 +24,16 @@ gen_ios() {
   local size=1024
   local inner=$(( size * (100 - 2 * padding) / 100 ))
 
+  # DefaultIcon.png — alpha preserved (matches `ti create` default for the
+  # universal icon source; Alloy/Android use this directly).
+  magick "$tight" \
+    -resize "${inner}x${inner}" \
+    -background none -gravity center -extent "${size}x${size}" \
+    -strip \
+    "$out_root/DefaultIcon.png"
+
+  # DefaultIcon-ios.png — flattened over bg-color. This is the file iOS
+  # actually ships; Apple rejects alpha on App Store icon uploads.
   magick "$tight" \
     -resize "${inner}x${inner}" \
     -background none -gravity center -extent "${size}x${size}" \
@@ -26,5 +41,6 @@ gen_ios() {
     -strip \
     "$out_root/DefaultIcon-ios.png"
 
+  log_ok "DefaultIcon.png (1024×1024, ${padding}% padding, alpha preserved)"
   log_ok "DefaultIcon-ios.png (1024×1024, ${padding}% padding, alpha flattened over $bg)"
 }

package/skills/ti-branding/scripts/lib/gen-marketplace.sh

@@ -1,28 +1,43 @@
 #!/usr/bin/env bash
 # gen-marketplace.sh — store-submission artwork.
 #
-#   iTunesConnect.png:     1024×1024, no alpha (App Store)
-#   MarketplaceArtwork.png: 512×512, no alpha (Google Play)
+#   iTunesConnect.png      1024×1024 (App Store)
+#   MarketplaceArtwork.png 512×512   (Google Play)
 #
-# Uses the same --ios-padding as the iOS master (default 8%). Store assets are
-# scrutinized at large sizes and need visual breathing room — no safe-zone to
-# comply with, but aesthetically they should match the DefaultIcon-ios look.
+# Alpha handling depends on whether --bg-color was EXPLICITLY provided
+# (tracked via the 5th argument, `flatten`):
+#   - flatten=0 (no --bg-color) → alpha preserved, matches `ti create` default
+#   - flatten=1 (--bg-color X)  → alpha flattened on bg-color. Prevents the
+#                                  dark-mode-muddy-icon issue on Play Store
+#                                  and macOS App Store when the master has
+#                                  significant transparent areas.
+#
+# Uses the same --ios-padding as the iOS master (default 8%) so the three
+# square icons share the same visual weight.
 
 gen_marketplace() {
   local tight="$1"
   local bg="$2"
   local padding="$3"      # ios-padding percent per side
   local out_root="$4"
+  local flatten="${5:-0}" # 1 when --bg-color was explicitly provided
 
   mkdir -p "$out_root"
 
+  local flatten_args=()
+  local alpha_label="alpha"
+  if [[ "$flatten" == "1" ]]; then
+    flatten_args=(-background "$bg" -alpha remove -alpha off)
+    alpha_label="flat on $bg"
+  fi
+
   # App Store (1024²)
   local size_ios=1024
   local inner_ios=$(( size_ios * (100 - 2 * padding) / 100 ))
   magick "$tight" \
     -resize "${inner_ios}x${inner_ios}" \
     -background none -gravity center -extent "${size_ios}x${size_ios}" \
-    -background "$bg" -alpha remove -alpha off \
+    "${flatten_args[@]}" \
     -strip \
     "$out_root/iTunesConnect.png"
 
@@ -32,9 +47,9 @@ gen_marketplace() {
   magick "$tight" \
     -resize "${inner_play}x${inner_play}" \
     -background none -gravity center -extent "${size_play}x${size_play}" \
-    -background "$bg" -alpha remove -alpha off \
+    "${flatten_args[@]}" \
     -strip \
     "$out_root/MarketplaceArtwork.png"
 
-  log_ok "Marketplace artwork: iTunesConnect.png (1024², ${padding}% padding), MarketplaceArtwork.png (512², ${padding}% padding)"
+  log_ok "Marketplace artwork: iTunesConnect.png (1024², ${padding}% padding, ${alpha_label}), MarketplaceArtwork.png (512², ${padding}% padding, ${alpha_label})"
 }

package/skills/ti-branding/scripts/lib/gen-notification.sh

@@ -4,11 +4,21 @@
 # all non-transparent pixels become white and color information is discarded.
 #
 # Sizes per Android spec: mdpi=24px, hdpi=36, xhdpi=48, xxhdpi=72, xxxhdpi=96.
+#
+# Notification icons are NOT masked by the launcher, so they render as drawn.
+# We trim any transparent padding baked into the master first, then scale the
+# logo to fill the canvas edge-to-edge on its longer axis (with a 1px
+# anti-aliasing margin per side). This matches what first-party Android apps
+# ship (Gmail, Slack, Chrome) — the logo reaches the edge instead of sitting
+# in a visibly padded box in the status bar.
+#
+# Material's 22dp-inside-24dp "live area" is a conservative guideline; in
+# practice notification icons benefit from going closer to the edge because
+# the status bar is already tiny.
 
 gen_notification() {
   local master="$1"
-  local padding="$2"
-  local res_root="$3"
+  local res_root="$2"
 
   local densities=(mdpi hdpi xhdpi xxhdpi xxxhdpi)
   local sizes=(24 36 48 72 96)
@@ -16,13 +26,15 @@ gen_notification() {
   for i in "${!densities[@]}"; do
     local d="${densities[$i]}"
     local size="${sizes[$i]}"
-    # Notification icons get pretty heavily masked in the status bar, so use
-    # slightly tighter padding than the full safe-zone.
-    local inner=$(( size * (100 - 2 * padding) / 100 ))
+    # Edge-to-edge with a 1px anti-aliasing margin per side.
+    local inner=$(( size - 2 ))
+    (( inner < 1 )) && inner=1
     local dir="$res_root/drawable-$d"
     mkdir -p "$dir"
 
+    # Trim baked-in transparent padding from the master, then scale to inner.
     magick "$master" \
+      -trim +repage \
       -resize "${inner}x${inner}" \
       -channel RGB -fill white -colorize 100 +channel \
       -background none -gravity center -extent "${size}x${size}" \
@@ -30,5 +42,5 @@ gen_notification() {
       "$dir/ic_stat_notify.png"
   done
 
-  log_ok "Notification icons (white+alpha) × 5 densities"
+  log_ok "Notification icons (white+alpha, edge-to-edge) × 5 densities"
 }

package/skills/ti-branding/scripts/ti-branding

@@ -34,15 +34,21 @@ source "$LIB_DIR/gen-splash-icon.sh"
 # -----------------------------------------------------------------------------
 
 MASTER=""
+MONOCHROME_MASTER=""
 BG_COLOR="#FFFFFF"
-PADDING=22
+BG_COLOR_EXPLICIT=0
+PADDING=20
 IOS_PADDING=8
 WITH_NOTIFICATION=0
 WITH_SPLASH_ICON=0
 CLEANUP_LEGACY=0
 AGGRESSIVE=0
 OUTPUT=""
+OUTPUT_EXPLICIT=0
 DRY_RUN=0
+IN_PLACE=0
+IS_IN_PLACE=0
+NOTES=0
 PROJECT_ROOT="$(pwd)"
 
 # -----------------------------------------------------------------------------
@@ -82,8 +88,9 @@ ARGUMENTS:
 OPTIONS:
   --bg-color <hex>         Background color for adaptive layer + iOS alpha flatten.
                            Default: #FFFFFF
-  --padding <pct>          Android safe-zone padding per side (0–40). Default: 22
-                           (Android official minimum is 19.44%.)
+  --padding <pct>          Android safe-zone padding per side (0–40). Default: 20
+                           (Material spec floor is 19.44%; default 20 gives a
+                           tiny buffer while keeping the logo visibly prominent.)
   --ios-padding <pct>      iOS/marketplace aesthetic padding per side (0–40).
                            Default: 8. iOS icons have no launcher mask — this
                            is purely breathing room around the logo.
@@ -96,6 +103,17 @@ OPTIONS:
                            (<1% global market in 2026). Off by default.
   --output <dir>           Staging directory. Default: <project>/.ti-branding
   --project <dir>          Project root (default: current working directory).
+  --in-place               Skip the staging directory — write files directly into
+                           the project root. OVERWRITES existing icons. --output
+                           takes precedence when both are passed.
+  --monochrome-master <p>  Optional dedicated silhouette master for
+                           ic_launcher_monochrome.png + ic_stat_notify.png.
+                           Use when the colored logo has multi-color detail
+                           that would collapse into a featureless blob when
+                           naively whitened. Falls back to main master if omitted.
+  --notes                  Print full tiapp.xml snippets + padding tuning guide
+                           after the run. Default is a compact summary — use this
+                           when you need the config snippets to paste into tiapp.xml.
   --dry-run                Print what would be generated without writing files.
   -h, --help               Show this help.
 
@@ -113,15 +131,18 @@ EOF
 while [[ $# -gt 0 ]]; do
   case "$1" in
     -h|--help) usage; exit 0 ;;
-    --bg-color) BG_COLOR="$2"; shift 2 ;;
+    --bg-color) BG_COLOR="$2"; BG_COLOR_EXPLICIT=1; shift 2 ;;
     --padding) PADDING="$2"; shift 2 ;;
     --ios-padding) IOS_PADDING="$2"; shift 2 ;;
     --with-notification) WITH_NOTIFICATION=1; shift ;;
     --with-splash-icon) WITH_SPLASH_ICON=1; shift ;;
     --cleanup-legacy) CLEANUP_LEGACY=1; shift ;;
     --aggressive) AGGRESSIVE=1; shift ;;
-    --output) OUTPUT="$2"; shift 2 ;;
+    --output) OUTPUT="$2"; OUTPUT_EXPLICIT=1; shift 2 ;;
     --project) PROJECT_ROOT="$2"; shift 2 ;;
+    --in-place) IN_PLACE=1; shift ;;
+    --monochrome-master) MONOCHROME_MASTER="$2"; shift 2 ;;
+    --notes) NOTES=1; shift ;;
     --dry-run) DRY_RUN=1; shift ;;
     --) shift; break ;;
     -*) log_err "Unknown option: $1"; usage >&2; exit 2 ;;
@@ -172,6 +193,14 @@ if [[ ! "$BG_COLOR" =~ ^#[0-9A-Fa-f]{6}$ ]]; then
   exit 2
 fi
 
+# Resolve staging dir:
+#   explicit --output wins over --in-place (avoids ambiguity)
+#   --in-place (no --output) → write directly into the project root
+#   neither → default to .ti-branding/ inside the project
+if [[ $IN_PLACE -eq 1 && $OUTPUT_EXPLICIT -eq 0 ]]; then
+  OUTPUT="$PROJECT_ROOT"
+  IS_IN_PLACE=1
+fi
 OUTPUT="${OUTPUT:-$PROJECT_ROOT/.ti-branding}"
 
 # -----------------------------------------------------------------------------
@@ -191,11 +220,16 @@ if [[ -n "$MASTER" ]]; then
   log_info "Master:       $MASTER"
   log_info "Background:   $BG_COLOR"
   log_info "Padding:      Android ${PADDING}% / iOS ${IOS_PADDING}% per side"
-  log_info "Staging:      $OUTPUT"
+  if [[ $IS_IN_PLACE -eq 1 ]]; then
+    log_info "Writing IN PLACE to: $PROJECT_ROOT"
+  else
+    log_info "Staging:      $OUTPUT"
+  fi
 fi
 [[ $WITH_NOTIFICATION -eq 1 ]] && log_info "Extras:       + notification icons"
 [[ $WITH_SPLASH_ICON -eq 1 ]] && log_info "Extras:       + Android 12+ splash icon"
 [[ $CLEANUP_LEGACY -eq 1 ]] && log_info "Cleanup:      --cleanup-legacy$([[ $AGGRESSIVE -eq 1 ]] && echo " --aggressive")"
+[[ $IS_IN_PLACE -eq 1 && $DRY_RUN -eq 0 ]] && log_warn "⚠  --in-place mode: files in your project will be OVERWRITTEN. Commit first if you want a rollback."
 [[ $DRY_RUN -eq 1 ]] && log_warn "DRY RUN — no files will be written"
 
 # -----------------------------------------------------------------------------
@@ -227,13 +261,27 @@ log_step "3/6 Preparing masters (square for iOS, tight for Android)"
 PREPARED_BASE="$OUTPUT/_master"
 MASTER_SQUARE="${PREPARED_BASE}_square.png"
 MASTER_TIGHT="${PREPARED_BASE}_tight.png"
+MONO_TIGHT=""
 if [[ $DRY_RUN -eq 0 ]]; then
   mkdir -p "$OUTPUT"
   prepare_master "$MASTER" "$PREPARED_BASE"
   log_ok "Square master: $MASTER_SQUARE"
   log_ok "Tight master:  $MASTER_TIGHT"
+
+  # Optional: prepare a dedicated monochrome master if provided.
+  if [[ -n "$MONOCHROME_MASTER" ]]; then
+    if [[ ! -f "$MONOCHROME_MASTER" ]]; then
+      log_err "Monochrome master not found: $MONOCHROME_MASTER"
+      exit 2
+    fi
+    local_mono_base="$OUTPUT/_master_mono"
+    prepare_master "$MONOCHROME_MASTER" "$local_mono_base"
+    MONO_TIGHT="${local_mono_base}_tight.png"
+    log_ok "Monochrome master (for ic_launcher_monochrome + ic_stat_notify): $MONO_TIGHT"
+  fi
 else
   log_info "[dry-run] would prepare: $MASTER_SQUARE + $MASTER_TIGHT"
+  [[ -n "$MONOCHROME_MASTER" ]] && log_info "[dry-run] would prepare monochrome master from: $MONOCHROME_MASTER"
 fi
 
 # Resolve target paths based on project layout
@@ -247,14 +295,14 @@ ROOT_STAGING="$OUTPUT"
 log_step "4/6 Generating iOS master + marketplace artwork (square)"
 if [[ $DRY_RUN -eq 0 ]]; then
   gen_ios "$MASTER_TIGHT" "$BG_COLOR" "$IOS_PADDING" "$ROOT_STAGING"
-  gen_marketplace "$MASTER_TIGHT" "$BG_COLOR" "$IOS_PADDING" "$ROOT_STAGING"
+  gen_marketplace "$MASTER_TIGHT" "$BG_COLOR" "$IOS_PADDING" "$ROOT_STAGING" "$BG_COLOR_EXPLICIT"
 else
-  log_info "[dry-run] would emit DefaultIcon-ios.png, iTunesConnect.png, MarketplaceArtwork.png"
+  log_info "[dry-run] would emit DefaultIcon.png, DefaultIcon-ios.png, iTunesConnect.png, MarketplaceArtwork.png"
 fi
 
 log_step "5/6 Generating Android adaptive + legacy launcher icons (tight)"
 if [[ $DRY_RUN -eq 0 ]]; then
-  gen_android_adaptive "$MASTER_TIGHT" "$BG_COLOR" "$PADDING" "$ANDROID_RES"
+  gen_android_adaptive "$MASTER_TIGHT" "$BG_COLOR" "$PADDING" "$ANDROID_RES" "$MONO_TIGHT"
   gen_android_legacy "$MASTER_TIGHT" "$BG_COLOR" "$PADDING" "$ANDROID_RES"
   cp "$ASSETS_DIR/ic_launcher.xml" "$ANDROID_RES/mipmap-anydpi-v26/ic_launcher.xml"
   log_ok "Adaptive icon XML bind: $ANDROID_RES/mipmap-anydpi-v26/ic_launcher.xml"
@@ -265,7 +313,8 @@ fi
 if [[ $WITH_NOTIFICATION -eq 1 || $WITH_SPLASH_ICON -eq 1 ]]; then
   log_step "6/6 Generating optional extras"
   if [[ $WITH_NOTIFICATION -eq 1 && $DRY_RUN -eq 0 ]]; then
-    gen_notification "$MASTER_TIGHT" "$PADDING" "$ANDROID_RES"
+    # Use monochrome master if provided, else fall back to main (whitened by the generator).
+    gen_notification "${MONO_TIGHT:-$MASTER_TIGHT}" "$ANDROID_RES"
   elif [[ $WITH_NOTIFICATION -eq 1 ]]; then
     log_info "[dry-run] would emit ic_stat_notify.png × 5 densities"
   fi
@@ -285,11 +334,62 @@ fi
 
 log_step "Done"
 if [[ $DRY_RUN -eq 0 ]]; then
-  log_ok "All assets staged at: $OUTPUT"
+  # In --in-place mode, intermediate master files (_master_square.png /
+  # _master_tight.png) land directly in the project root alongside the real
+  # branded assets. Clean them up so the user is only left with the 4 icons.
+  if [[ $IS_IN_PLACE -eq 1 ]]; then
+    rm -f "$OUTPUT/_master_square.png" "$OUTPUT/_master_tight.png"
+    log_ok "All assets written IN PLACE at: $PROJECT_ROOT"
+  else
+    log_ok "All assets staged at: $OUTPUT"
+  fi
 
   # ---------------------------------------------------------------------------
-  # Post-generation notes (aclaraciones) — help the user understand what was
-  # made, how to adjust, and what tiapp.xml glue is still needed.
+  # Post-generation output — compact summary by default, full notes with --notes.
+  # ---------------------------------------------------------------------------
+
+  if [[ $NOTES -eq 0 ]]; then
+    # Compact summary — only config/destination + 3-line next steps + hint.
+    echo
+    echo "${C_BOLD}Summary${C_RESET}"
+    echo "  Background:   ${BG_COLOR}   Padding: Android ${PADDING}% / iOS ${IOS_PADDING}%"
+    if [[ $IS_IN_PLACE -eq 1 ]]; then
+      echo "  Written in place to: $PROJECT_ROOT"
+    else
+      echo "  Staged at:    $OUTPUT"
+    fi
+    echo
+    echo "${C_BOLD}Next steps${C_RESET}"
+    if [[ $IS_IN_PLACE -eq 1 ]]; then
+      echo "  • Preview the new icons in ${C_YELLOW}Preview.app${C_RESET}."
+      echo "  • If something looks wrong: ${C_DIM}git checkout -- .${C_RESET}"
+      echo "  • Rebuild: ${C_DIM}ti clean && ti build -p android -T emulator${C_RESET}"
+    else
+      case "$PROJECT_TYPE" in
+        alloy)
+          echo "  • Preview in ${C_YELLOW}Preview.app${C_RESET}, then copy to project:"
+          echo "      ${C_DIM}cp $OUTPUT/{DefaultIcon,DefaultIcon-ios,iTunesConnect,MarketplaceArtwork}.png $PROJECT_ROOT/${C_RESET}"
+          echo "      ${C_DIM}cp -R $OUTPUT/app/platform/android/res/. $PROJECT_ROOT/app/platform/android/res/${C_RESET}"
+          ;;
+        classic)
+          echo "  • Preview in ${C_YELLOW}Preview.app${C_RESET}, then copy to project:"
+          echo "      ${C_DIM}cp $OUTPUT/{DefaultIcon,DefaultIcon-ios,iTunesConnect,MarketplaceArtwork}.png $PROJECT_ROOT/${C_RESET}"
+          echo "      ${C_DIM}cp -R $OUTPUT/platform/android/res/. $PROJECT_ROOT/platform/android/res/${C_RESET}"
+          ;;
+        *)
+          echo "  • Review ${C_YELLOW}$OUTPUT/${C_RESET} and copy files to their final paths manually."
+          ;;
+      esac
+      echo "  • Cleanup staging: ${C_DIM}rm -rf $OUTPUT${C_RESET}"
+    fi
+    echo
+    log_info "Pass ${C_BOLD}--notes${C_RESET} to print tiapp.xml snippets + padding tuning guide."
+    echo
+    exit 0
+  fi
+
+  # ---------------------------------------------------------------------------
+  # Full notes (with --notes) — tiapp.xml snippets, padding tuning, etc.
   # ---------------------------------------------------------------------------
 
   echo
@@ -438,24 +538,31 @@ EOF
   echo
   echo "${C_BOLD}Next steps${C_RESET}"
   echo
-  echo "  1. Preview in ${C_YELLOW}Preview.app${C_RESET} (never use ${C_DIM}open${C_RESET} without -a — triggers heavy editors)"
+  if [[ $IS_IN_PLACE -eq 1 ]]; then
+    echo "  1. Preview the new icons in ${C_YELLOW}Preview.app${C_RESET} — the files in your project"
+    echo "     were overwritten directly (no staging directory was used)."
+    echo "  2. If something looks wrong, restore from git:  ${C_DIM}git checkout -- .${C_RESET}"
+    echo "  3. Rebuild:           ${C_DIM}ti clean && ti build -p android -T emulator${C_RESET}"
+  else
+    echo "  1. Preview in ${C_YELLOW}Preview.app${C_RESET} (never use ${C_DIM}open${C_RESET} without -a — triggers heavy editors)"
   case "$PROJECT_TYPE" in
     alloy)
       echo "  2. If good, copy to project:"
-      echo "       cp $OUTPUT/DefaultIcon-ios.png $OUTPUT/iTunesConnect.png $OUTPUT/MarketplaceArtwork.png $PROJECT_ROOT/"
+      echo "       cp $OUTPUT/DefaultIcon.png $OUTPUT/DefaultIcon-ios.png $OUTPUT/iTunesConnect.png $OUTPUT/MarketplaceArtwork.png $PROJECT_ROOT/"
       echo "       cp -R $OUTPUT/app/platform/android/res/. $PROJECT_ROOT/app/platform/android/res/"
       ;;
     classic)
       echo "  2. If good, copy to project:"
-      echo "       cp $OUTPUT/DefaultIcon-ios.png $OUTPUT/iTunesConnect.png $OUTPUT/MarketplaceArtwork.png $PROJECT_ROOT/"
+      echo "       cp $OUTPUT/DefaultIcon.png $OUTPUT/DefaultIcon-ios.png $OUTPUT/iTunesConnect.png $OUTPUT/MarketplaceArtwork.png $PROJECT_ROOT/"
       echo "       cp -R $OUTPUT/platform/android/res/. $PROJECT_ROOT/platform/android/res/"
       ;;
     *)
       echo "  2. Review staging dir and copy files to their final paths manually."
       ;;
   esac
-  echo "  3. Cleanup staging:   rm -rf $OUTPUT"
-  echo "  4. Rebuild:           ti clean && ti build -p android -T emulator"
+    echo "  3. Cleanup staging:   rm -rf $OUTPUT"
+    echo "  4. Rebuild:           ${C_DIM}ti clean && ti build -p android -T emulator${C_RESET}"
+  fi
   echo
 else
   log_info "Dry-run complete. Re-run without --dry-run to write files."