@maccesar/titools 4.20.0 → 4.21.0

package/README.md

@@ -6,7 +6,7 @@
 
 </div>
 
-TiTools is a Titanium SDK toolkit for AI coding assistants. It ships 10 skills — 5 specialist skills (`ti-expert`, `purgetss`, `ti-ui`, `ti-game`, `ti-synthengine`) plus 5 documentation-mirror skills (`ti-api`, `ti-guides`, `ti-howtos`, `alloy-guides`, `alloy-howtos`) — a research agent, and reference files covering Titanium architecture, API reference, native how-tos, Alloy MVC, PurgeTSS styling and resource automation, UI/UX patterns, 2D games, and native sound synthesis.
+TiTools is a Titanium SDK toolkit for AI coding assistants. It ships 11 skills — 6 specialist skills (`ti-reuse-first`, `ti-expert`, `purgetss`, `ti-ui`, `ti-game`, `ti-synthengine`) plus 5 documentation-mirror skills (`ti-api`, `ti-guides`, `ti-howtos`, `alloy-guides`, `alloy-howtos`) — a research agent, and reference files covering reuse and simplification, Titanium architecture, API reference, native how-tos, Alloy MVC, PurgeTSS styling and resource automation, UI/UX patterns, 2D games, and native sound synthesis.
 
 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.
 
@@ -36,7 +36,7 @@ The fastest way to get started with Claude Code. One command to add the marketpl
 ```
 
 What you get:
-- All 10 TiTools skills (`ti-expert`, `purgetss`, `ti-ui`, `ti-game`, `ti-synthengine`, `ti-api`, `ti-guides`, `ti-howtos`, `alloy-guides`, `alloy-howtos`)
+- All 11 TiTools skills (`ti-reuse-first`, `ti-expert`, `purgetss`, `ti-ui`, `ti-game`, `ti-synthengine`, `ti-api`, `ti-guides`, `ti-howtos`, `alloy-guides`, `alloy-howtos`)
 - ti-pro research agent
 - Session hook that auto-detects Titanium projects (`tiapp.xml`, Alloy, PurgeTSS, `ti.game`, `ti.synthengine`)
 - Slash commands: `/ti-check`, `/ti-new-screen`, `/ti-audit`
@@ -174,6 +174,7 @@ The knowledge index is based on the latest Titanium SDK documentation. If your p
 
 | Skill        | Purpose                             | Best For                                |
 | ------------ | ----------------------------------- | --------------------------------------- |
+| ti-reuse-first | Reuse before writing new code     | Whether it should exist and what already does it; duplication sweeps |
 | ti-expert    | Architecture and implementation     | Starting point for most tasks           |
 | purgetss     | Alloy styling + asset automation    | Utility classes; Alloy/Classic branding, images, colors, fonts and modules |
 | ti-ui        | UI/UX patterns                      | Complex layouts, ListViews, platform UI |
@@ -186,7 +187,8 @@ The knowledge index is based on the latest Titanium SDK documentation. If your p
 | alloy-howtos | Alloy CLI, configuration, debugging | alloy.jmk, config.json, custom XML tags |
 
 Notes:
-- The first five (`ti-expert`, `purgetss`, `ti-ui`, `ti-game`, `ti-synthengine`) are specialist workflow skills reflecting TiTools' Titanium conventions and native-module contracts.
+- The first six (`ti-reuse-first`, `ti-expert`, `purgetss`, `ti-ui`, `ti-game`, `ti-synthengine`) are specialist workflow skills reflecting TiTools' Titanium conventions and native-module contracts.
+- `ti-reuse-first` runs before the others. It asks whether a thing needs to exist and what already does it — a search order that stops at the first rung that holds — and sweeps an existing `app/` for near-identical controllers, single-listener events, wrappers around one call, and layout recomputed in JavaScript. It is deliberately two-sided: it says when adding a module or a Widget is the right answer, so the bias does not simply invert.
 - `ti-game` documents the `ti.game` native module (2D sprite engine on OpenGL ES 2.0, Android and iOS). Its API reference was verified against the module source and tracks upstream `main` (the module ships features ahead of its manifest version); it applies to Alloy and Classic projects alike and does not depend on PurgeTSS.
 - `ti-synthengine` translates aesthetic sound requests into strict, production-ready JavaScript for the cross-platform `ti.synthengine` 1.0.0 module. Seven references preserve the official documentation and an eighth adds curated retro, xylophone, memory-pad, polyphony and timer-ownership recipes; the API contract was cross-checked against both native implementations.
 - The latter five are documentation-mirror skills sourced from the official Titanium SDK docs (`tidev/titanium-docs`) and audited against them via the internal `titools-skill-auditor`.
@@ -249,7 +251,7 @@ TiTools provides slash commands for common tasks. Both channels ship them: the p
 These commands automatically invoke the relevant skills:
 - `/ti-check` reads `tiapp.xml`, validates declared native modules, and reports project health
 - `/ti-new-screen` uses `ti-expert` + `purgetss` to create properly structured files
-- `/ti-audit` routes all 10 skills: core Titanium checks always, Alloy/PurgeTSS checks when detected, integration how-tos when used, and `ti-game` / `ti-synthengine` checks when those modules are declared
+- `/ti-audit` routes all 11 skills: the reuse sweep first, core Titanium checks always, Alloy/PurgeTSS checks when detected, integration how-tos when used, and `ti-game` / `ti-synthengine` checks when those modules are declared
 
 ---
 
@@ -289,6 +291,7 @@ All skills include automatic project detection to ensure compatibility:
 | Skill     | What It Detects       | How It Works                                                  |
 | --------- | --------------------- | ------------------------------------------------------------- |
 | purgetss  | PurgeTSS mode and project type | Checks PurgeTSS markers, then separates Alloy utilities from Classic standalone commands |
+| ti-reuse-first | Existing app structure | Searches `app/lib/`, `app/controllers/`, `app/widgets/`, `purgetss/config.cjs` before proposing anything new |
 | ti-expert | Alloy vs Classic      | Checks for `app/` (Alloy) vs `Resources/` (Classic) structure |
 | ti-ui     | Titanium projects     | Checks for `tiapp.xml` (both Alloy and Classic)               |
 | ti-game   | ti.game module        | Checks for `<module>ti.game</module>` in `tiapp.xml` or `require('ti.game')` |
@@ -301,16 +304,17 @@ Why this matters:
 
 ### Skill hierarchy
 
-`ti-expert` is the architectural starting point and coordinates with the rest of the bundled catalog:
+`ti-reuse-first` runs first — it decides whether there is anything to build — and `ti-expert` is the architectural starting point for what survives that question. Together they coordinate the rest of the bundled catalog:
 
 | Scope | Skills |
 | --- | --- |
+| Whether to build it at all | `ti-reuse-first`, first |
 | Architecture and UI | `ti-expert`, `ti-ui`, `purgetss` when configured |
 | Native modules | `ti-game`, `ti-synthengine` when declared |
 | Exact SDK/API guidance | `ti-api`, `ti-guides`, `ti-howtos` |
 | Alloy MVC and tooling | `alloy-guides`, `alloy-howtos` for Alloy projects |
 
-All ten ship with TiTools; no second skill package is required.
+All eleven ship with TiTools; no second skill package is required.
 
 ---
 
@@ -804,6 +808,7 @@ This pattern is documented across four bundled TiTools skills: `ti-ui`, `ti-expe
 
 | Skill     | SKILL.md                      | References                                            |
 | --------- | ----------------------------- | ----------------------------------------------------- |
+| ti-reuse-first | Reuse Before You Write   | 5 files (the ladder, Alloy reuse, indirection, PurgeTSS reuse, diagnostics) |
 | ti-expert | Architecture + Implementation | 26 files (patterns, feedback surfaces, file type association, sharing, testing, security, etc.) |
 | purgetss  | Setup + Critical Rules        | 34 files (Classic compatibility, grid, animations, icons, class-index, SVG pipeline, etc.) |
 | ti-ui     | UI Rules + Platform Diffs     | 14 files (layouts, lists, gestures, etc.)             |

package/agents/ti-pro.md

@@ -2,6 +2,7 @@
 name: ti-pro
 description: Titanium SDK and Alloy research specialist. Loads the complete TiTools skill catalog and uses the relevant scopes together for research-style questions. Use for codebase analysis, architecture reviews, Titanium SDK implementation research, cross-feature questions, native game or sound modules, and platform-specific differences. Returns concrete findings with file and line references.
 skills:
+  - ti-reuse-first
   - ti-expert
   - purgetss
   - ti-ui
@@ -24,6 +25,7 @@ You are a research specialist for Titanium SDK and Alloy mobile development. Wit
 
 When invoked, research complex topics by consulting the applicable skills from the complete TiTools catalog:
 
+- `ti-reuse-first` - Whether the thing should exist at all, and what already does it; duplication and dead-structure sweeps
 - `ti-expert` - Architecture, patterns, conventions
 - `purgetss` - Utility-first styling classes (optional add-on; use when the project already has it or the user asks about it)
 - `ti-ui` - UI/UX patterns, layouts, gestures
@@ -56,6 +58,7 @@ Do not force conditional skills onto an unrelated project. State which scopes we
 
 | Use Instead                                  | Reason                                 |
 | -------------------------------------------- | -------------------------------------- |
+| `/ti-reuse-first` before writing new code    | Inline reuse check during development  |
 | `/ti-expert` for architecture guidance       | Inline consultation during development |
 | `/purgetss` to verify a class                | Quick inline reference                 |
 | `/ti-ui` for UI/UX patterns and layouts      | Task-oriented guidance                 |

package/commands/ti-audit.md

@@ -7,22 +7,23 @@ Audit the current Titanium project by invoking every applicable TiTools skill. F
 
 Core Titanium audit:
 
-1. Invoke `ti-expert` — check architecture, navigation ownership, event/timer cleanup, memory leaks, bridge pressure, testing boundaries, adaptive layouts and code conventions.
-2. Invoke `ti-guides` — check `tiapp.xml`, CommonJS/Hyperloop usage, Titanium CLI/build assumptions, memory and bridge guidance, distribution settings, and toolchain compatibility.
-3. Invoke `ti-api` — verify every audited `Ti.*` API, event, property, constant and third-party module call against its exact signature. Do not report a suspected API defect from memory.
-4. Invoke `ti-ui` when the project creates Titanium UI — check layouts, list performance, event bubbling, gestures, animations, accessibility, orientation and platform-specific UI.
-5. Invoke `ti-howtos` when the project implements a native integration such as location, maps, push, camera, media, SQLite, HTTPClient, WebView, intents, Keychain/iCloud, Hyperloop or CI/CD — audit the complete integration and platform setup, not only the JavaScript call site.
+1. Invoke `ti-reuse-first` — before judging how anything is built, establish whether it should exist and what already does it: near-identical controllers, panels copied instead of parameterized, events with a single listener, wrappers around one call, repeated class strings, and layout recomputed in JavaScript that TSS resolves declaratively. Report each finding with the command that measured it, and with what consolidating it would cost as well as save — duplication kept on purpose is a valid answer.
+2. Invoke `ti-expert` — check architecture, navigation ownership, event/timer cleanup, memory leaks, bridge pressure, testing boundaries, adaptive layouts and code conventions.
+3. Invoke `ti-guides` — check `tiapp.xml`, CommonJS/Hyperloop usage, Titanium CLI/build assumptions, memory and bridge guidance, distribution settings, and toolchain compatibility.
+4. Invoke `ti-api` — verify every audited `Ti.*` API, event, property, constant and third-party module call against its exact signature. Do not report a suspected API defect from memory.
+5. Invoke `ti-ui` when the project creates Titanium UI — check layouts, list performance, event bubbling, gestures, animations, accessibility, orientation and platform-specific UI.
+6. Invoke `ti-howtos` when the project implements a native integration such as location, maps, push, camera, media, SQLite, HTTPClient, WebView, intents, Keychain/iCloud, Hyperloop or CI/CD — audit the complete integration and platform setup, not only the JavaScript call site.
 
 Project-type audit:
 
-6. If the project is Alloy (`app/views/`, `app/controllers/`, `app/styles/`), invoke `alloy-guides` — check controllers, XML/TSS, models, collections, widgets, sync adapters and cleanup patterns.
-7. If the Alloy project uses `alloy.jmk`, `config.json`, `widget.json`, conditional views, custom XML tags or Alloy CLI workflows, invoke `alloy-howtos` — check configuration precedence, build hooks, generated structures and compilation/debugging conventions.
-8. If the project uses PurgeTSS (`purgetss/`, `purgetss/config.cjs`, a PurgeTSS-generated `app.tss`, or `purgetss.{ui,colors,fonts}.js`), invoke `purgetss` and detect Alloy vs. Classic before applying findings. In Alloy, audit unsupported utility classes, padding on Views, unnecessary manual TSS, dynamic components, grids, icons and animations. In Classic, audit only the supported standalone asset/CommonJS commands and their `Resources/` outputs; do not require or recommend `alloy.jmk`, generated TSS, utility classes, or `$.UI.create()`.
+7. If the project is Alloy (`app/views/`, `app/controllers/`, `app/styles/`), invoke `alloy-guides` — check controllers, XML/TSS, models, collections, widgets, sync adapters and cleanup patterns.
+8. If the Alloy project uses `alloy.jmk`, `config.json`, `widget.json`, conditional views, custom XML tags or Alloy CLI workflows, invoke `alloy-howtos` — check configuration precedence, build hooks, generated structures and compilation/debugging conventions.
+9. If the project uses PurgeTSS (`purgetss/`, `purgetss/config.cjs`, a PurgeTSS-generated `app.tss`, or `purgetss.{ui,colors,fonts}.js`), invoke `purgetss` and detect Alloy vs. Classic before applying findings. In Alloy, audit unsupported utility classes, padding on Views, unnecessary manual TSS, dynamic components, grids, icons and animations. In Classic, audit only the supported standalone asset/CommonJS commands and their `Resources/` outputs; do not require or recommend `alloy.jmk`, generated TSS, utility classes, or `$.UI.create()`.
 
 Native-module audit:
 
-9. If the project declares `ti.game`, invoke `ti-game` — check for sprites moved from timers instead of native properties, levels sized from `Ti.Platform.displayCaps` instead of the `resize` event, sprites added one by one instead of in one array, and timers or sounds left running when the window closes.
-10. If the project declares `ti.synthengine`, invoke `ti-synthengine` — check strict option names and types, mutually exclusive pitch fields, valid envelope intersections, checked Boolean results, one clear lifecycle owner, delayed startup after layout, app-owned timer cancellation, and `shutdown()` cleanup.
+10. If the project declares `ti.game`, invoke `ti-game` — check for sprites moved from timers instead of native properties, levels sized from `Ti.Platform.displayCaps` instead of the `resize` event, sprites added one by one instead of in one array, and timers or sounds left running when the window closes.
+11. If the project declares `ti.synthengine`, invoke `ti-synthengine` — check strict option names and types, mutually exclusive pitch fields, valid envelope intersections, checked Boolean results, one clear lifecycle owner, delayed startup after layout, app-owned timer cancellation, and `shutdown()` cleanup.
 
 If a conditional skill does not apply, record it as `not applicable` with the detected reason instead of inventing findings from it.
 

package/commands/ti-new-screen.md

@@ -6,6 +6,7 @@ argument-hint: "<screenName>"
 
 Create a new Alloy screen with the given name. Before creating files:
 
+0. Invoke the `ti-reuse-first` skill and confirm the screen has to be new. Run rung 1 against this project: list `app/controllers/` and `app/widgets/` and check whether an existing screen covers the case with a parameter, or whether a `<Require>` into an existing window is enough. If the answer is that an existing screen should be parameterized instead, say so, name it, and **stop** — do not generate the trio. Only continue when a new screen is genuinely the answer.
 1. Invoke the `alloy-guides` skill to follow Alloy MVC patterns
 2. If PurgeTSS is detected (purgetss/ folder exists), invoke the `purgetss` skill — all styling MUST use utility classes in the XML, NOT custom TSS
 3. If PurgeTSS is detected, invoke the `ti-ui` skill for layout patterns

package/lib/config.js

@@ -30,6 +30,7 @@ export const REPO_API_URL = 'https://api.github.com/repos/macCesar/titools';
 
 // Skills to install
 export const SKILLS = [
+  'ti-reuse-first',
   'ti-expert',
   'purgetss',
   'ti-ui',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maccesar/titools",
-  "version": "4.20.0",
+  "version": "4.21.0",
   "description": "Titanium SDK skills and agents for AI coding assistants, including native game and sound synthesis modules",
   "main": "lib/index.js",
   "type": "module",

package/skills/ti-expert/SKILL.md

@@ -9,12 +9,15 @@ allowed-tools: Read, Grep, Glob, Edit, Write, Bash(git *), Bash(node *)
 
 Practical architecture and implementation guidance for Titanium SDK apps (Alloy and Classic). Focus on maintainability, clear boundaries, and low-friction testing.
 
+> **Before anything new exists, run the `ti-reuse-first` skill.** It answers *whether* a controller, view, Widget, `app/lib/` module, event or wrapper should exist at all and what already does it; this guide answers *how* to build whatever survives that question. Copying an existing controller as a template counts as creating something new.
+
 ## Required workflow
 
 This file is an index. Read the references that govern the task before making a recommendation or changing code.
 
 | Task | Required reading |
 | --- | --- |
+| Anything new — a controller/view/style trio, Widget, `app/lib/` module, event, wrapper, or a file copied as a template | Run the `ti-reuse-first` skill first, then the row below that matches what survives |
 | Architecture tier, folders, or boundaries | [Architecture tiers](references/architecture-tiers.md), [Alloy structure](references/alloy-structure.md) |
 | Feedback, alerts, choices, or app-owned versus system UI | [Feedback surfaces](references/feedback-surfaces.md) |
 | Reusable Snackbar, Dialog, Bottom Sheet, Widget, or `<Require>` | [Feedback Widget contracts](references/feedback-widget-contracts.md), [Alloy structure](references/alloy-structure.md) |
@@ -151,14 +154,14 @@ For the complete reference with examples, see [Alloy builtins and globals](refer
 | ---------------------------------- | -------------------------------------------------------------- |
 | How to create a new Alloy project? | `ti create -t app --alloy` (not `--classic` + `alloy new`)     |
 | Fastest way to build?              | `tn <recipe>` (using TiNy CLI wrapper)                         |
-| Controller > 100 lines?            | Extract to Tier 2 (Services)                                   |
+| Controller > 100 lines?            | A smell, not a threshold — see `ti-reuse-first`                |
 | More than 50 IDs in XML?           | Use Tier 3 (ID Scoping)                                        |
 | Where does API call go?            | `lib/api/`                                                     |
 | Where does business logic go?      | `lib/services/`                                                |
 | How deep should `lib` folders be?  | One level: `lib/<type>/<file>.js`                              |
 | Where do I store auth tokens?      | Keychain (iOS) / KeyStore (Android) via service                |
 | Models or Collections?             | Collections for API data, Models for SQLite persistence        |
-| Ti.App.fireEvent or EventBus?      | Always EventBus (Backbone.Events)                              |
+| Ti.App.fireEvent or EventBus?      | EventBus — once `ti-reuse-first` says it needs an event        |
 | Direct navigation or service?      | Always Navigation service (auto cleanup)                       |
 | Snackbar, Dialog, or Bottom Sheet? | Classify urgency, persistence, reversibility, and choice first |
 | Widget or `<Require>`?             | Widget for a self-contained API/lifecycle; `<Require>` for app composition |

package/skills/ti-expert/references/patterns.md

@@ -15,6 +15,8 @@
 
 <!-- TOC-END -->
 
+> **Before introducing any of these:** each pattern below adds a layer, and a layer only pays for itself where there is a boundary — a place the implementation could plausibly change, or where the two sides genuinely should not know each other. Around a single call site with one caller, the same pattern is a detour that costs on every read. The `ti-reuse-first` skill runs that check; use it first, and treat the patterns here as the answer to *how* once it has established *whether*.
+
 ## 1. Native module abstraction (Wrapper)
 
 **Use when:** Using native modules like Maps, Biometrics, or specialized Media players.

package/skills/ti-reuse-first/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: ti-reuse-first
+description: "Use before anything new exists in a Titanium or Alloy project — 'hazme un panel de avisos', 'necesito otra pantalla', 'hazlo igual que el de Index', 'voy a copiar paneles/derechos como base', '¿dónde pongo esta función?'. A search order stopping at the first rung that holds: must this exist, is it already in app/, does a Ti.* API, the platform, an installed module or a PurgeTSS class cover it, can it be one line, and only then the smallest thing that works — copied exactly, without guards nobody asked for. AUTO-DETECT: if tiapp.xml exists, invoke BEFORE creating any controller, view, Widget, app/lib/ module, event or wrapper, or copying a file as a template: it answers whether the thing should exist and what already does it; ti-expert answers how to build what survives. Also audits app/ for duplicated controllers, single-listener events, wrappers around one call, and layout JS that TSS resolves — 'esto ya lo tengo en otro lado', 'simplifícalo', DRY, KISS. Not a licence to skip a module five call sites need."
+allowed-tools: Read, Grep, Glob, Edit, Write, Bash(git *), Bash(node *)
+---
+
+# Reuse before you write
+
+## Overview
+
+Most of the avoidable damage in a mature Alloy app is not wrong code. It is code that should never have been written: the fourth panel that repeats the first three, the event with one listener, the wrapper around one call, the helper that restates a `Ti.*` API. It compiles, it passes review, and it is permanent.
+
+This skill supplies the missing question. Every other Titanium skill answers *how do I build this well*; this one asks *should this exist at all, and if so, does something already do it*. Run it first — its answer changes what the other skills are asked to build.
+
+The method is a search order with early exit: seven rungs, cheapest first, stop at the first one that holds. It is a search order, not a prohibition. Climbing all seven honestly and landing on "write the module" is a correct outcome — see [When adding structure is the right answer](references/the-ladder.md#when-adding-structure-is-the-right-answer). A bias against structure is the same failure as a bias toward it, pointed the other way.
+
+## When to use
+
+Use it before:
+
+- Creating any controller/view/style trio, Widget, or `app/lib/` module.
+- Copying an existing controller, view, or panel as a template.
+- Introducing an event, a wrapper, a service layer, a registry, or a factory.
+- Answering "where should this live" — the answer is often "nowhere new".
+- Reviewing a design that adds a layer, or a diff whose file count outgrew its intent.
+
+Use it in diagnostic mode when someone says a codebase feels repetitive, when a bug had to be fixed in four places, or when planning a refactor.
+
+Do not use it to choose between two designs that both already exist and both work — that is `ti-expert`'s decision matrix. Do not use it to argue against a module that several call sites genuinely need. And do not let it stall a one-line fix: rung 6 exists so trivial work stays trivial.
+
+## Required workflow
+
+This file is an index. Open the reference that governs the decision before recommending or writing anything.
+
+| Decision | Required reading |
+| --- | --- |
+| Anything new — first pass, always | [The ladder](references/the-ladder.md) |
+| A new panel, screen, dialog, or a controller/view/style trio; Widget vs `<Require>` vs a shared base | [Alloy reuse](references/alloy-reuse.md) |
+| An event, wrapper, service layer, registry, factory, or any new layer between two pieces of code | [Indirection](references/indirection.md) |
+| Repeating class strings in XML, or reaching for a new TSS block | [PurgeTSS reuse](references/purgetss-reuse.md) |
+| Auditing an existing `app/` for duplication and dead structure | [Diagnostics](references/diagnostics.md) |
+| Whether the thing you would build already exists as a Titanium API | Verify the exact signature with the `ti-api` skill — never from memory |
+
+Support each recommendation with `[source: references/<file>.md]`. If a claim cannot be verified from the loaded references or from the inspected project, prefix it with `FROM_MEMORY (unverified):` and do not present it as settled. This matters more here than in most skills: the whole method is *look before you build*, and a skill that answers from memory has already skipped its own first step.
+
+## The ladder
+
+Ask these in order and stop at the first rung that holds. Full detail, with the Titanium specifics for each, is in [The ladder](references/the-ladder.md).
+
+| # | Question | If it holds |
+| --- | --- | --- |
+| 0 | Does this need to exist? | Delete the requirement, not the code. State what you skipped and why. |
+| 1 | Is it already in this codebase? | Reuse or parameterize it. `grep` before you conclude it is not. |
+| 2 | Does a `Ti.*` API or Alloy builtin cover it? | Use it. Verify the signature with `ti-api`. |
+| 3 | Does the platform own this workflow? | Use the native surface. Trust, permission and payment flows stay native. |
+| 4 | Does a module already in `tiapp.xml` or `package.json` cover it? | Use it. New dependencies need an argument. |
+| 5 | Can it be one line at the call site? | Write the line. A direct reference beats a mechanism. |
+| 6 | None of the above. | Build the smallest thing that works, where the next person will look. |
+
+Two rules keep the ladder honest:
+
+**Rung 1 is a search, not a recollection.** "I do not think we have that" is not an answer to rung 1. Run the search — `grep`, `ls app/lib/`, `ls app/widgets/` — and report what you found. The command is cheap; the duplicate is permanent.
+
+**Classic projects climb the same ladder.** Only the paths change: `Resources/` instead of `app/`, CommonJS modules instead of `app/lib/`, and rungs 2 through 5 are identical because they are about Titanium and the platform, not about Alloy. Rung 1's Alloy-specific answers — `<Require>`, Widgets, `$.args` — have no Classic equivalent; there the reuse mechanism is a CommonJS module that returns a configured view. Detect which kind of project you are in before quoting a path.
+
+**Copy the file that solves your problem, not the one whose name sounds close.** A full-screen legal-text window and a three-line confirmation overlay share a folder and nothing else. Before adopting any file as a template, open it and check its *shape* matches: how much screen it takes, how it opens and closes, what it owns. See [the worked example](references/alloy-reuse.md#worked-example-1-the-wrong-template).
+
+## Diagnostic mode
+
+Run the ladder backwards over code that already exists. The sweep — greps for near-identical controllers, single-listener events, wrappers around one call, and JS that recomputes what TSS resolves — is in [Diagnostics](references/diagnostics.md).
+
+Report what you measure, with the command that measured it: *"14 of 18 panel controllers define their own `mostrarPanel`"* is a finding. *"There is a lot of duplication in the panels"* is an impression. The first one survives a disagreement; the second one starts an argument nobody can settle.
+
+Duplication is evidence, not a verdict. Three copies that are drifting apart on purpose — because they are genuinely three different things — are cheaper than one abstraction with three flags. Say what the consolidation would cost as well as what it would save, then let the human decide.
+
+## Reference guides
+
+- [The ladder](references/the-ladder.md) — the seven rungs, each translated into Titanium and Alloy decisions, plus when adding structure is the right answer.
+- [Alloy reuse](references/alloy-reuse.md) — Widget vs `<Require>` vs a shared base vs a new trio; creating a controller on demand instead of embedding one per window; the measured panel case.
+- [Indirection](references/indirection.md) — events vs direct calls, wrappers, service layers, and how to tell a boundary from a detour.
+- [PurgeTSS reuse](references/purgetss-reuse.md) — custom rules and `apply` in `config.cjs` instead of repeating class strings; what belongs in `_app.tss` and what never goes in `app.tss`.
+- [Diagnostics](references/diagnostics.md) — the sweep for duplication and dead structure in an existing `app/`, with the exact commands.
+
+## Related skills
+
+- `ti-expert` — architecture, tiers, and the patterns worth introducing *after* this skill has established that something must be built.
+- `purgetss` — the class contract itself; verify every utility class there.
+- `ti-api` — the exact signature of any `Ti.*` API this skill sends you to reuse.

package/skills/ti-reuse-first/references/alloy-reuse.md

@@ -0,0 +1,127 @@
+# Alloy reuse
+
+Alloy has real mechanisms for reusing XML and JS together — `<Require>` and Widgets — and `app/lib/` is not the only place shared code can live. This reference is about choosing between them, and about the decision that comes before all of them: whether the new screen needs to be a new file at all.
+
+## The four exits
+
+When something has to appear in more than one place, there are four ways out, and the reflex — copy the trio, or embed one instance everywhere — is usually the worst of them.
+
+| Exit | What it is | When it is right |
+| --- | --- | --- |
+| **Parameterize what exists** | Pass `$.args` to a controller that already does 90% of it | The differences are text, an icon, a callback, or a visible/hidden branch |
+| **`<Require>`** | Compose an app-local controller inside a view | Shares the host's lifecycle, styling and domain; no independent contract |
+| **Widget** | A packaged component with `widget.json`, its own styles and assets | Owns a public API, its own state and cleanup, and could move to another project |
+| **New trio** | A fresh controller/view/style | Genuinely a different screen, not a variation of one |
+
+`ti-expert`'s [alloy-structure.md § "When to use widget vs require"](../../ti-expert/references/alloy-structure.md) has the Widget-vs-`<Require>` table in full; read it rather than deciding from memory. What it does not cover, and what this reference adds, is the first row — parameterizing rather than adding anything — and the question of *where the instance lives*, below.
+
+Usage count alone does not decide. Three call sites for a thing with no state and no lifecycle may still be three lines of `$.args`; one call site for something with timers and cleanup may still deserve a Widget.
+
+## Where the instance lives: on demand, not one per window
+
+A component needed in four windows does not need four instances. The reflex — a `<Require>` in each window's XML, a listener in each controller, and a `destruir()` each one has to remember to call — pays the cost of four view hierarchies, four listener registrations, and four chances to forget the cleanup, in exchange for saving a `createController` call.
+
+The alternative is to build it when it is needed, on whatever window is visible, and destroy it on close:
+
+```js
+// In the controller that knows which window is on screen.
+Alloy.createController('paneles/avisoPush', opciones).mostrar()
+```
+
+```js
+// In the component: it attaches to the window it was handed, and cleans itself up.
+const ventana = $.args.ventana
+
+function mostrar() {
+  if (!ventana) { return false }
+  ventana.add($.getView())
+  $.getView().show()
+  $.animarVista.open($.getView())
+  return true
+}
+
+function cerrar(despues) {
+  $.animarVista.close($.getView(), () => {
+    $.getView().hide()
+    ventana.remove($.getView())
+    $.destroy()
+    if (typeof despues === 'function') { despues() }
+  })
+}
+```
+
+The trade is real and worth stating: creating on demand costs a controller construction at the moment of use, which is visible if the component appears many times per second. That is the case for a list row, and it is why `ListView` templates exist. It is not the case for an alert, a confirmation, or a notice that arrives occasionally — there, a resident instance is memory held for an event that mostly does not happen.
+
+The test: **how often does this appear, and does it need to survive being closed?** Rarely and no → create on demand. Constantly, or it holds state between appearances → resident.
+
+## When a family of screens has already formed
+
+The interesting case is not one duplicate. It is the fifteenth, when a house pattern has emerged without anyone deciding on it, and each new screen re-types it.
+
+Measure before proposing anything. In one shipping Alloy app, over the 18 modal panels in `app/controllers/paneles/` (excluding the shared header component):
+
+```bash
+# Denominator: panel controllers, excluding the shared component.
+PANELS=$(ls app/controllers/paneles/*.js | grep -v panelHeader)
+for p in "animarVista.open" "animarVista.close" "opacoClick" '$.getView().hide()' "mostrarPanel"; do
+  printf "%-22s %s/%s\n" "$p" "$(grep -lF "$p" $PANELS | wc -l | tr -d ' ')" "$(echo "$PANELS" | wc -l | tr -d ' ')"
+done
+```
+
+| Repeated in every panel | Count |
+| --- | --- |
+| `$.animarVista.open($.getView())` | 16 / 18 |
+| `$.animarVista.close($.getView(), …)` | 15 / 18 |
+| `opacoClick` — dismiss on background tap | 15 / 18 |
+| `$.getView().hide()` / `.show()` | 15 / 18 |
+| An exported `mostrarPanel` | 14 / 18 |
+
+And in the 18 corresponding views, counted as exact `class` attributes rather than substrings: 16 carry an identical `<Animation>` element, 14 an identical full-screen scrim, and 9 an identical zoom-in card.
+
+That is a house pattern with no home. Every new panel re-types show, close, dismiss-on-background and animation, and a change to any of them is a fifteen-file edit that will be applied to twelve.
+
+**What the numbers do not decide is the fix.** They establish the cost; the shape of the consolidation is a judgment call, and there are three defensible answers:
+
+- **A Widget** (`app/widgets/panelBase/`) exposing `open()`, `close()` and a content slot. Strongest boundary, real public API, portable to the next project. Costs the most to introduce and forces every panel through one contract — which is wrong if the panels are drifting apart deliberately.
+- **A shared behavior module** (`app/lib/panel.js`) that each controller hands `$` to, keeping the XML per-panel and lifting only the repeated JS. Smallest change, preserves per-panel layout freedom, does not unify the duplicated XML.
+- **Leave it, and only stop the bleeding** — a `config.cjs` custom rule for the two repeated class strings, so at least new panels stop re-typing the appearance. Correct when the panels are genuinely diverging and a shared base would become a flag farm.
+
+Present the measurement and the three options with what each costs. The choice of which is right depends on where the app is going, and that is the human's to make — a consolidation imposed on screens that were about to diverge is worse than the duplication it removed.
+
+## Worked example 1: the wrong template
+
+**The task**: show a three-line notice over whatever window is visible when a push notification arrives with the app open.
+
+**What happened**: `paneles/derechos` was copied as the template — a full-screen modal window built to scroll legal text. The result filled the screen for a three-line message.
+
+**What was already there**: `paneles/tombolaSalir` — a scrim with a centered card, two buttons, dismiss on background tap. The same shape as the task. It was one folder listing away.
+
+**The error was not in the code**; the copied file was perfectly good code. The error was choosing the template by proximity — same folder, similar name — instead of by shape. Both files are "panels"; only one of them is a small overlay.
+
+**The check that would have caught it**: before copying any file as a template, open it and answer three questions. *How much screen does it take? How does it open and close? What does it own?* If any answer differs from the task, keep looking — the right file is usually in the same folder.
+
+## Worked example 2: four instances of a thing that appears once
+
+**The task**: the same notice, reachable from four different windows.
+
+**What was built first**: a `<Require>` in each of the four window XMLs, an `Alloy.Events` listener in each of the four controllers, and a `destruir()` each window had to remember to call. Four copies of a view hierarchy, permanently resident, for a notice that arrives occasionally.
+
+**What replaced it**: one `Alloy.createController('paneles/avisoPush', opciones).mostrar()` in the controller that already tracks which window is visible, with the panel attaching itself to the window it is handed and calling `$.destroy()` on close. The four `<Require>` elements, the four listeners and the `destruir()` contract all went away.
+
+**The tell**: *am I creating N copies of something that is only ever used one at a time?* If the answer is yes, the instance should be created at the moment of use. The question to ask out loud is the one that unlocked this: **can this be loaded dynamically?**
+
+## Worked example 3: the right template, plus inventions
+
+**The task**: a panel inside the Tómbola window, behaving like the one already working in `index` — the same handling the Estilos and Ruleta panels use. The instruction named the reference implementation explicitly.
+
+**What was built**: the reference behavior, plus additions nobody asked for. Touch events were intercepted, `touchEnabled` was toggled on and off around the transition, and an `animating` flag was introduced that refused to close the panel until the open callback fired. None of the reference panels carry any of that.
+
+**What happened**: the flag deadlocked. When the open callback did not arrive, `animating` stayed `true` and the panel could no longer be closed. The user could not open and close it repeatedly, and could not keep drawing cards. Each attempt to fix the symptom added another guard on top of the first — a patch on a patch, all of it defending against a problem that had never been observed.
+
+**What replaced it**: the reference behavior, unedited. Animate, hide the whole container on close, leave the events connected. The `touchEnabled` toggling and the `animating` lock were deleted, not repaired.
+
+**The admission afterwards was the diagnosis**: *"intenté prevenir toques durante la animación sin evidencia de que hiciera falta"*. Three panels in the same app had run for months without that guard. The evidence that it was unnecessary was already in the codebase, in the very files that had been named as the model.
+
+**The rule**: when the instruction is *do it like the one that already works*, reuse means copying the behavior, not copying it and improving it. Additions to a reference implementation need the same argument any new code needs — a real, observed failure. An input you are guarding against because it *might* happen is rung 0 work: the requirement does not exist yet, so neither should the guard.
+
+**The tell**: *does the file I was told to copy do this?* If it does not, and no bug report says it should, do not add it. And if a symptom appears after an addition of yours, the first move is to remove the addition — not to guard it.

package/skills/ti-reuse-first/references/diagnostics.md

@@ -0,0 +1,137 @@
+# Diagnostics
+
+Running the ladder backwards over code that already exists. Each sweep below is a command, a reading, and — the part that matters — what would make the finding wrong.
+
+Two rules before starting:
+
+**Report the command with the number.** *"14 of 18 panel controllers define their own `mostrarPanel`"* is a finding someone can check and disagree with. *"There is a lot of duplication in the panels"* is an impression, and impressions produce arguments instead of decisions.
+
+**Duplication is evidence, not a verdict.** Three copies drifting apart on purpose are cheaper than one abstraction with three flags. Every finding here needs its second half: what the consolidation would cost, not only what it would save. Then the human decides — this sweep produces a report, not a refactor.
+
+## 1. Near-identical controllers
+
+Look for a house pattern that formed without anyone deciding on it: the same function names, the same open/close dance, the same event wiring, re-typed per screen.
+
+```bash
+# Which function names recur across a family of controllers?
+# find, not **/ — globstar is off in the bash 3.2 that ships with macOS,
+# where **/*.js silently collapses to */*.js and misses everything deeper.
+find app/controllers -name '*.js' -exec grep -ho "^function [a-zA-Z0-9_]*" {} + |
+  sort | uniq -c | sort -rn | head -20
+
+# How many files in a family share one construct? Exclude the shared pieces that
+# live in the same folder but are not members — they inflate the denominator.
+FAM=$(ls app/controllers/paneles/*.js | grep -v panelHeader)
+for p in "mostrarPanel" "opacoClick" "animarVista.open" '$.getView().hide()'; do
+  printf "%-22s %s/%s\n" "$p" "$(grep -lF "$p" $FAM | wc -l | tr -d ' ')" "$(echo "$FAM" | wc -l | tr -d ' ')"
+done
+
+# Rough size clustering — near-identical files tend to have near-identical line counts.
+wc -l app/controllers/paneles/*.js | sort -n
+```
+
+**Reading it:** a construct in most of a family is a house pattern with no home. Every new member re-types it, and a change to it is an N-file edit that will be applied to N-2.
+
+**What makes it wrong:** the family is not a family. Screens that share a folder are not necessarily variations of one thing, and a shared base imposed on genuinely different screens becomes a flag farm. Check that the members do the same *kind* of job before proposing to unify them.
+
+**Where to go:** [Alloy reuse § when a family of screens has already formed](alloy-reuse.md#when-a-family-of-screens-has-already-formed) — it lays out the three defensible fixes and what each costs.
+
+## 2. Events with a single listener
+
+```bash
+# Every event name that is fired, and every one that is listened for.
+grep -rhno "Alloy\.Events\.trigger(['\"][^'\"]*" app/ | sed "s/.*['\"]//" | sort | uniq -c | sort -rn
+grep -rhno "Alloy\.Events\.on(['\"][^'\"]*"      app/ | sed "s/.*['\"]//" | sort | uniq -c | sort -rn
+
+# Same, for the leakier cross-context bus.
+grep -rn "Ti\.App\.fireEvent\|Ti\.App\.addEventListener" app/
+```
+
+**Reading it:** an event with one trigger and one listener, where the two modules can see each other, is a function call with a name to keep in sync and a listener to clean up. Replace it with a direct call or a callback in `$.args`.
+
+An event fired but never listened for is dead. An event listened for but never fired is either dead or fired from native code — check before deleting.
+
+**What makes it wrong:** the listener set is genuinely open (a theme finishing its download, a session expiring), or the sender is a lower layer that must not know about the receiver. Both are correct uses; the count alone cannot tell them apart. Read the two modules before concluding.
+
+**Where to go:** [Indirection § events versus a direct call](indirection.md#events-versus-a-direct-call).
+
+## 3. Wrappers that wrap nothing
+
+```bash
+# One-line functions that forward their arguments unchanged.
+grep -rn -B1 -A3 "^function [a-zA-Z0-9_]*(" app/lib/*.js |
+  grep -A1 "^function" | grep -E "return (Ti|Modules|Alloy)\.[A-Za-z.]+\("
+
+# How many callers does each exported function actually have?
+grep -ho "^exports\.[a-zA-Z0-9_]*" app/lib/*.js | sed 's/exports\.//' | sort -u |
+  while read f; do printf "%-28s %s\n" "$f" "$(grep -rl "\.$f(" app/ | wc -l | tr -d ' ')"; done | sort -k2 -n
+```
+
+**Reading it:** a function that forwards one call unchanged, from one site, adding no normalization, no error handling and no default, is a longer name for the thing it calls.
+
+**What makes it wrong:** it is a vendor seam. A wrapper whose whole job is to be the one place that changes when the module does is doing that job even while it is trivial. Ask whether the module's API is spreading through controllers — if it is, the wrapper is earning its keep in advance.
+
+**Where to go:** [Indirection § wrappers](indirection.md#wrappers).
+
+## 4. Layout computed in JavaScript
+
+```bash
+# Measuring and repositioning after the draw.
+grep -rn "postlayout\|\.rect\b\|\.size\.width\|\.size\.height" app/controllers/ app/lib/
+
+# Positions and sizes assigned from JS rather than declared in TSS.
+grep -rn "applyProperties({[^}]*\(top\|left\|right\|bottom\|width\|height\):" app/controllers/
+```
+
+**Reading it:** a `postlayout` handler that measures a window and repositions its children runs after the first draw — the content visibly jumps — and re-runs on every layout pass. TSS conditionals (`[formFactor=tablet]`, `[platform=ios]`, `[if=…]`) resolve once, before anything is drawn.
+
+**What makes it wrong:** the handler reacts to a real orientation change, or the value genuinely is not knowable at build time. When a decision must be made before the first draw, `Ti.Platform.displayCaps` answers it without waiting for a layout pass.
+
+**Where to go:** [Indirection § layout logic in JavaScript](indirection.md#layout-logic-in-javascript).
+
+## 5. Repeated class strings in the views
+
+```bash
+# The most-repeated class attributes in the project.
+grep -rho 'class="[^"]*"' app/views/ | sort | uniq -c | sort -rn | head -20
+```
+
+**Reading it:** the same combination in several views, meant to stay identical, is a name waiting to be given — an `apply` rule in `purgetss/config.cjs`.
+
+**What makes it wrong:** the agreement is coincidental. Two screens with the same padding today for unrelated reasons will need different padding tomorrow, and a shared class couples things that were never related.
+
+**Where to go:** [PurgeTSS reuse § when a repeated string has earned a name](purgetss-reuse.md#when-a-repeated-string-has-earned-a-name).
+
+## 6. Structure nobody reaches
+
+```bash
+# Exported functions with no caller anywhere in app/.
+grep -ho "^exports\.[a-zA-Z0-9_]*" app/lib/*.js | sed 's/exports\.//' | sort -u |
+  while read f; do
+    [ "$(grep -rl "\.$f(" app/ | grep -v "app/lib" | wc -l | tr -d ' ')" = "0" ] && echo "no external caller: $f"
+  done
+
+# Config keys nobody reads, and modules declared but never required.
+grep -o '"[a-zA-Z0-9_]*":' app/config.json | tr -d '":' | sort -u |
+  while read k; do
+    [ "$(grep -rl "Alloy\.CFG\.$k" app/ | wc -l | tr -d ' ')" = "0" ] && echo "unread config key: $k"
+  done
+grep -o "<module[^>]*>[^<]*</module>" tiapp.xml | sed 's/.*>\(.*\)<.*/\1/' |
+  while read m; do
+    [ "$(grep -rl "require('$m')\|require(\"$m\")" app/ | wc -l | tr -d ' ')" = "0" ] && echo "module never required in JS: $m"
+  done
+```
+
+**Reading it:** each of these is rung 0 in hindsight — something built for a caller that never arrived.
+
+**What makes it wrong, and this one bites:** a `grep` for a caller finds only the callers spelled that way. A function reached through a dynamic name, from a Widget, from `alloy.js`, from a native module, or from a project file outside `app/` will look dead and will not be. Modules in particular are frequently declared for their build-time side effects and never `require`d in JS — reached instead from a `module=` attribute in a view, or simply linked into the build. That is normal, not dead. A module declared once per platform also shows up twice; pipe through `sort -u` before reading the list. **Never delete on the strength of this sweep alone.** Report the candidate, say how it was found, and let someone who knows the history confirm.
+
+## Reporting
+
+Group findings by what they cost, not by how many there are:
+
+1. **Costs a bug soon** — one behavior in N places that must agree and are already drifting. Cite the files and how they differ.
+2. **Costs on every read** — a detour that always resolves to one place; a wrapper around one call; an event with one listener.
+3. **Costs nothing yet** — a house pattern with no home, worth consolidating when the next member is added rather than today.
+
+For each, give the measurement, the command, the proposed change, **and what it would cost** — including the case for leaving it alone. Then stop. A sweep that ends in an unrequested refactor has answered a question nobody asked, and the diff will be judged against a request that does not exist.

package/skills/ti-reuse-first/references/indirection.md

@@ -0,0 +1,89 @@
+# Indirection
+
+Every layer between a caller and the work it wants done has to earn its place. This reference is about telling the ones that do from the ones that do not — and the distinction is not "how many layers" but whether each one is a **boundary** (a place where the two sides genuinely should not know each other, or where the implementation could plausibly change) or a **detour** (a hop that always resolves to the same destination).
+
+Both look identical in a diff. Only one of them pays for itself.
+
+## Events versus a direct call
+
+An event bus is the right tool when the sender must not know the receiver: several listeners, an unknown number of them, or a genuine layering boundary the sender should not reach across. When there is exactly one listener and the sender can already see it, an event is a function call with a name to keep in sync, a registration to perform, and a leak to clean up.
+
+```js
+// A lib that has no business knowing about windows announces an intention.
+// Somewhere else, exactly one controller is listening.
+Alloy.Events.trigger('abrirTienda')
+```
+
+```js
+// The controller that already owns abrirTienda() hands it over as a value.
+if (esTemaNuevo) {
+  opciones.alAceptar = abrirTienda
+}
+Alloy.createController('paneles/avisoPush', opciones).mostrar()
+```
+
+The second version deletes the event name, the listener, and the cleanup. It also fixes a layering problem the event was hiding: the module that handles push registration had to know that "open the store" was a thing that could happen. With a callback passed in, it does not — it takes a function and calls it, and the decision about what that function is stays in the controller that owns the navigation.
+
+**Decision table:**
+
+| Situation | Use |
+| --- | --- |
+| One known listener, caller can see it | Direct call or a callback in `$.args` |
+| Parent needs to hear from a child controller it created | The child's exported function, or a callback the parent passed down |
+| Several listeners, or the set is genuinely open | `Alloy.Events` (a `Backbone.Events` clone) |
+| Sender must not know the receiver exists — a real seam | `Alloy.Events` |
+| Cross-context, JS to native or between contexts | `Ti.App.fireEvent` — the last resort, and only then |
+
+`ti-expert`'s decision matrix answers "`Ti.App.fireEvent` or EventBus?" with "always EventBus", and that is correct as far as it goes — it is comparing two event mechanisms, and `Ti.App.fireEvent` is the leakier one. It is not an argument that the interaction needs an event at all. Ask this question first; ask `ti-expert`'s second.
+
+**The test:** *if I delete the event and call the function directly, what breaks?* If the answer is "nothing, but it feels less decoupled", the coupling was imaginary and the event was the cost of imagining it.
+
+## Wrappers
+
+A wrapper around a native module is a real pattern with a real purpose: it is the one place that changes when the vendor does, and it keeps the module's API from spreading through the app.
+
+It stops being that when it forwards one call, unchanged, from one call site.
+
+```js
+// A boundary: normalizes two platform APIs, owns the error contract, one place to change.
+function comprar(sku) { … }
+
+// A detour: this is Ti.Media.vibrate with a longer name.
+function vibrar(patron) {
+  Ti.Media.vibrate(patron)
+}
+```
+
+Signs a wrapper is a detour: it has one function; that function forwards its arguments unchanged; it has one call site; it adds no error handling, no normalization, and no default. Signs it is a boundary: it reconciles iOS and Android behavior; it owns retries, logging or error translation; it is called from several places; or it is the seam a test substitutes.
+
+The honest version of "we might swap this vendor later" is: write the wrapper when the swap becomes plausible, not when it becomes imaginable. The refactor from direct calls to a wrapper is mechanical and a `grep` finds every site; the cost of carrying an unnecessary layer is paid every time someone reads the code.
+
+## Service layers and registries
+
+`ti-expert` describes three architectural tiers and a set of patterns — Repository, Service layer, Factory, ServiceRegistry with dependency injection — and its matrix says a controller over 100 lines should be extracted to Tier 2. Those tiers are real and the guidance is sound *for apps that are at that tier*. The failure mode is applying a tier's machinery to an app that is not there yet, because the pattern is available rather than because the app needs it.
+
+The line-count rule is a smell detector, not a instruction. A 140-line controller that does one screen's work, reads top to bottom, and shares nothing with any other screen is fine. A 90-line controller that repeats what three other controllers do is already a problem. Split when there is a second consumer, a real seam, or something worth testing on its own — not when a number is exceeded.
+
+Before introducing a registry or dependency injection, answer: how many services are there, and how many of them have more than one implementation? Injection buys the ability to substitute. If nothing is ever substituted — not in tests, not per platform, not per environment — it has been bought and not used.
+
+## Layout logic in JavaScript
+
+This is the same failure in a different costume: JavaScript recomputing what the style system resolves declaratively.
+
+A `postlayout` handler that measures a window and repositions its children runs after the first draw, so the content visibly jumps; it re-runs on every layout pass; and each device rule it encodes is a hand-written `if` that will eventually miss a case. TSS conditionals — `[formFactor=tablet]`, `[formFactor=handheld]`, `[platform=ios]`, `[if=…]` — resolve once, before anything is drawn, and cost nothing at runtime.
+
+The same applies to positioning by arithmetic. Anchoring a button with `right: 178` works exactly once; a horizontal container with `height: Ti.UI.SIZE`, where `left` is the gap from the previous sibling, keeps working when the text, the width or the language changes.
+
+**The test:** *am I adding up widths in my head to pick a number?* If so, the layout system is being asked to accept a result it could have computed. Reserve `postlayout` for reacting to a real orientation change, and use `Ti.Platform.displayCaps` when a decision must be made before anything is drawn.
+
+## When indirection is the right call
+
+Do not read this reference as an argument for flat code. These layers are worth their cost, and refusing them is the same error inverted:
+
+- **A seam with two implementations today** — per-platform behavior, a test double, a mock server. Substitution that actually happens is what injection is for.
+- **A repeated integration.** Five controllers each with their own `HTTPClient`, timeout and error handling is one bug in five places. The module that unifies them is not indirection; it is the fix.
+- **An event with an open listener set.** A theme finishing its download, a session expiring — the publisher genuinely cannot know who cares, and the set grows. That is a bus, correctly used.
+- **A wrapper at a vendor boundary.** When the native module's API is spreading through controllers, one wrapper is cheaper than the eventual migration.
+- **Something with its own lifecycle** — state, timers, listeners, cleanup that belong together. One owner beats scattering them across the controllers that happen to use it.
+
+State which of these applies when you propose a layer. "It is a seam: iOS and Android disagree here, and the wrapper is where they are reconciled" is a case anyone can check. "For decoupling" is not.

package/skills/ti-reuse-first/references/purgetss-reuse.md

@@ -0,0 +1,84 @@
+# PurgeTSS reuse
+
+In a PurgeTSS project the duplication moves into the XML, where it is easy to miss because a repeated `class` string does not look like copied code. It is. The same five utilities typed into fifteen views is fifteen places to edit when the design changes, and the edit will land in twelve of them.
+
+This reference covers where a style belongs and when a repeated string has earned a name. For whether a given utility class exists at all, invoke the `purgetss` skill — its class contract resembles Tailwind's but is not identical, and a class that does not exist fails silently.
+
+## Where a style belongs
+
+| Situation | Where it goes |
+| --- | --- |
+| A composition of existing utilities used in several views | A named class in `purgetss/config.cjs` via `apply` |
+| A property PurgeTSS has no utility for | A rule in `purgetss/config.cjs`, or a hand-written block in `_app.tss` |
+| A one-off on a single element | The `class` attribute in that view, inline |
+| Anything at all | **Never `app/styles/app.tss`** |
+
+`app.tss` is generated. PurgeTSS overwrites it on every run — it copies `_app.tss` into it [source: purgetss installation-setup.md] — so edits made there are work that deletes itself, usually a build or two later, which is long enough for the cause to be forgotten.
+
+## Rung 1 for styles: search before you write a block
+
+Before hand-writing a TSS rule, check whether a utility already does it. The PurgeTSS class set is large, and reimplementing a utility as a manual block is the styling version of reimplementing a `Ti.*` API.
+
+```bash
+grep -n "className" app/styles/_app.tss purgetss/config.cjs   # is it already a project class?
+grep -rn "class=\"[^\"]*someUtility" app/views/                # how is this done elsewhere?
+```
+
+If the design already exists somewhere in `app/views/`, copy how it is expressed there rather than inventing a second way to say the same thing. Two spellings of one visual result is duplication that no `grep` for a class name will ever find.
+
+## When a repeated string has earned a name
+
+Extract with `apply` when the same combination appears in several views **and** they are meant to stay identical — a design decision, not a coincidence.
+
+```javascript
+// purgetss/config.cjs
+theme: {
+  '.fondo-panel': {
+    apply: 'fondo-opaco hidden opacity-0'
+  },
+  '.tarjeta-panel': {
+    apply: 'zoom-in-125 bg-panel close:duration-0 open:duration-100'
+  }
+}
+```
+
+```xml
+<!-- Before: fifteen views carrying the same two strings -->
+<View class="fondo-opaco hidden opacity-0">
+  <View class="zoom-in-125 bg-panel close:duration-0 open:duration-100">
+
+<!-- After: one place to change the house style -->
+<View class="fondo-panel">
+  <View class="tarjeta-panel">
+```
+
+A measured example, from the same app whose panels are counted in [Alloy reuse](alloy-reuse.md#when-a-family-of-screens-has-already-formed): of 18 panel views, 14 carry an identical scrim string and 9 an identical card string. Two `apply` rules replace 23 repetitions, and the next panel inherits the house style instead of re-typing it.
+
+Count exact attributes, not substrings. Grepping for `zoom-in-125` in those same views returns 15 files — but six of them spell the rest of the string differently, and a class extracted from a substring match would quietly change how those six look. The count that matters is of the whole attribute.
+
+Counting is one command:
+
+```bash
+# Exact class attributes, most repeated first.
+grep -rho 'class="[^"]*"' app/views/ | sort | uniq -c | sort -rn | head -20
+```
+
+**When not to extract:**
+
+- **One use.** A name for a single site is indirection with a stylesheet accent — now the reader has to look somewhere else to learn what one element looks like.
+- **Coincidental agreement.** Two screens that happen to use the same padding today, for unrelated reasons, will need different padding tomorrow. Extracting them couples two things that were never related, and the flag that eventually separates them costs more than the duplication did.
+- **Names that describe appearance rather than role.** `.tarjeta-panel` survives a redesign; `.caja-blanca-redondeada` becomes a lie the first time the card turns grey, and nobody renames it.
+
+The test: *if this changes, must every user of it change too?* Yes → one name. No → leave them apart.
+
+## Device and platform differences belong here, not in JavaScript
+
+PurgeTSS carries platform and device modifiers, and `config.cjs` rules take `ios`, `android`, `handheld` and `tablet` blocks [source: purgetss custom-rules.md]. A tablet layout expressed as `tablet:w-1/2` resolves at build time, once. The same result computed in a `postlayout` handler runs after the first draw, so the content visibly jumps, and re-runs on every layout pass.
+
+If a layout decision is being made with arithmetic in a controller, the question is which modifier expresses it. See [Indirection § layout logic in JavaScript](indirection.md#layout-logic-in-javascript).
+
+## Verify every class
+
+PurgeTSS looks like Tailwind and diverges from it in specific places, and Titanium has no equivalent of a browser's inspector to show a class doing nothing. A misremembered class name produces no error, no warning, and an element that quietly ignores it.
+
+Invoke the `purgetss` skill and confirm each class you write. Citing it costs one line; a class that silently does nothing costs a build, a device, and someone's afternoon.

package/skills/ti-reuse-first/references/the-ladder.md

@@ -0,0 +1,123 @@
+# The ladder
+
+Seven rungs, cheapest first. Ask them in order and stop at the first one that holds. The point of the order is that each rung costs less than the one below it — a `grep` costs seconds, a new `app/lib/` module costs every future reader — so the search should exhaust the cheap answers before it reaches for the expensive one.
+
+The ladder is a search order, not a prohibition. See [When adding structure is the right answer](#when-adding-structure-is-the-right-answer) at the bottom before using it to argue against building something.
+
+## Rung 0 — Does this need to exist?
+
+The only code with no maintenance cost is the code that was never written. Before anything else, ask what breaks if this does not exist.
+
+Things that usually fail rung 0 in a Titanium app:
+
+- A setting nobody will change. A constant is a setting with the configuration removed.
+- Error handling for a state that cannot occur. `if (!Alloy.Globals.ventanaActual)` earns its place because there genuinely is a moment with no visible window; a null check on `$.getView()` inside its own controller does not.
+- A "manager" holding one function. That is a function.
+- A parameter with one caller passing one value.
+- A cleanup path for an object the platform already destroys.
+
+If the answer is "nothing breaks", say so and stop. Then say it out loud in the response: *"I skipped the retry wrapper — the call has one caller and `ti-api` says the method throws synchronously."* Work you decided not to do is invisible unless you name it, and unnamed decisions get re-litigated next session.
+
+## Rung 1 — Is it already in this codebase?
+
+This rung fails most often not because the thing was absent but because nobody looked. **"I do not think we have that" is not an answer to rung 1.** Run the search and report what came back.
+
+Where to look, in a standard Alloy project. In a Classic project the same search runs over `Resources/`, and the reuse mechanism at the end of it is a CommonJS module returning a configured view rather than a Widget or `<Require>`:
+
+| Looking for | Search |
+| --- | --- |
+| A helper or service | `ls app/lib/` then `grep -rn "functionName" app/lib/` |
+| A screen, panel, or dialog | `ls app/controllers/` and any subfolders |
+| A reusable component with its own API | `ls app/widgets/` |
+| A style or class | `grep -n "className" app/styles/_app.tss purgetss/config.cjs` |
+| A constant, endpoint, or flag | `grep -rn "VALUE" app/config.json app/alloy.js app/lib/` |
+| An already-declared native module | `grep -n "<module" tiapp.xml` |
+
+Three failure modes live on this rung. The first two are opposites; the third arrives after the search has already succeeded.
+
+**Missing what is there.** A `grep` for the exact identifier finds nothing, so the conclusion is "we do not have it" — when the project spells it differently. Search for the *concept*: two or three plausible names, plus the domain noun. Looking for a debounce, also try `throttle`, `timer`, `delay`.
+
+**Copying the wrong thing.** This one is more expensive, because it produces working code that is wrong in shape. When a file *is* found, the temptation is to copy it as a template. Before doing that, open it and check that it solves the same problem — not that it lives in the same folder or has a similar name. A full-screen modal window for scrolling legal text and a three-line confirmation overlay are both "panels", and adopting the first as a template for the second produces an aviso that fills the screen. See [Alloy reuse § worked example 1](alloy-reuse.md#worked-example-1-the-wrong-template).
+
+The test: *does this file's shape match my problem — how much screen it takes, how it opens and closes, what it owns — or does it just share a folder with it?*
+
+**Copying the right thing and then improving it.** The template is found, it is the correct one, and the copy arrives with additions the original never had: a lock around the animation, a `touchEnabled` toggle, an interception "just in case". The reference implementation has been running without them; that is the evidence they are not needed. Reuse means copying the behavior, not copying it and defending it against a failure nobody has seen. See [Alloy reuse § worked example 3](alloy-reuse.md#worked-example-3-the-right-template-plus-inventions).
+
+## Rung 2 — Does a `Ti.*` API or Alloy builtin cover it?
+
+Titanium's namespace is broad, and reimplementing part of it is easy to do by accident because the reimplementation always looks reasonable in isolation.
+
+Reinventions worth checking for, each verified against the `ti-api` skill's references:
+
+| Hand-rolled | Already exists |
+| --- | --- |
+| A date formatter | `String.formatDate(date, format)` [source: ti-api api-xml-global.md] |
+| A key/value store over the filesystem | `Ti.App.Properties` [source: ti-api api-app-platform.md] |
+| Screen-size math from a window's `size` | `Ti.Platform.displayCaps` [source: ti-api api-app-platform.md] |
+| A lookup table of translated strings | `L(key, hint)` [source: ti-api api-xml-global.md] |
+| A language check helper | `Ti.Locale.currentLanguage` — a property, not a method [source: ti-api api-core.md] |
+| A custom event emitter | `Alloy.Events` (a `Backbone.Events` clone) [source: ti-expert migration-patterns.md] |
+| A globals bag for passing controller params | `$.args` |
+| A compile-time platform flag | `OS_IOS` / `OS_ANDROID` |
+| A config module | `Alloy.CFG`, from `app/config.json` |
+
+**Verify the exact signature before writing the call.** Whether something is a property or a method, and which namespace owns it, is exactly the class of detail that memory gets wrong — and a wrong `Ti.*` call does not fail at lint, it fails on the device in the user's hand. Invoke `ti-api` and cite it.
+
+## Rung 3 — Does the platform own this workflow?
+
+Some interactions belong to the operating system, and rebuilding them costs more than the code: an app-built version loses the platform's accessibility, localization, and — where trust is involved — its credibility.
+
+Keep native: permission prompts, authentication and biometrics, payment and in-app purchase, the share sheet and intent chooser, media pickers, and the system alert and option dialogs (`Ti.UI.createAlertDialog`, `Ti.UI.createOptionDialog` [source: ti-api api-core.md]).
+
+Build app-owned: feedback that belongs to the app's own surface — inline validation, snackbars, screen-level empty and error states, and modals whose content is the app's rather than the system's. `ti-expert`'s feedback-surfaces reference draws the line in detail; consult it rather than guessing.
+
+The trap is the middle: a confirmation dialog. If it is a plain "are you sure?", the system dialog is free and correct. If it carries the app's own branding, illustration, or a third option, it is app-owned — and then rung 1 applies, because the app almost certainly already has one.
+
+## Rung 4 — Does a module already in the project cover it?
+
+Check `tiapp.xml` `<modules>` and `package.json` before adding anything. Apps accumulate capable dependencies and then hand-roll what they already paid for.
+
+Frequent cases: an animation module already declared (`purgetss.ui`, `ti.animation`) while new code animates by hand with `setTimeout`; a networking or storage module present while a controller talks to `Ti.Network.HTTPClient` directly; an icon font already installed while a new screen ships a PNG.
+
+A genuinely new dependency needs an argument, not just a fit — its size, its platform coverage, who maintains it, and what happens at the next SDK bump. State that argument before proposing it.
+
+## Rung 5 — Can it be one line at the call site?
+
+This rung catches the most common over-engineering in Alloy code: replacing a reference with a mechanism.
+
+If module A needs module B to do something and A can see B, **call B**. An event is a mechanism for when the sender must not know the receiver — several unknown listeners, or a genuine layering boundary. With one known listener it is a function call with extra steps, plus a listener to register, a name to keep in sync, and a leak to clean up.
+
+```js
+// Mechanism: the sender announces, hoping someone is listening.
+Alloy.Events.trigger('abrirTienda')
+
+// Reference: the caller passes the function it already has in scope.
+opciones.alAceptar = abrirTienda
+```
+
+The same rung catches layout: a `postlayout` handler that measures a window and repositions children is JavaScript doing what a TSS conditional (`[formFactor=tablet]`, `[platform=ios]`) does declaratively, once, before anything is drawn. See [Indirection](indirection.md) for the full treatment.
+
+## Rung 6 — Build the smallest thing that works
+
+Reaching this rung honestly is a result, not a failure. Now build it — and only it.
+
+- One file, in the place the next person would look for it: `app/lib/<type>/<name>.js`, one level deep.
+- The narrowest API that serves today's callers. Parameters get added when a second caller needs them, not in anticipation.
+- No configuration until something needs configuring.
+- Named for what it does in this app's vocabulary, not for the pattern it implements. `PushManager` beats `NotificationServiceFactory`.
+
+Then check the diff against the request: every changed line should trace back to something that was asked for.
+
+## When adding structure is the right answer
+
+A skill that only ever says "do not build it" has replaced one bias with another, and the second one is harder to notice because it looks like discipline. These are the cases where climbing all seven rungs correctly lands on *build it*, and where hesitating is the error:
+
+- **The same logic exists at three or more call sites and they must stay in agreement.** Network calls repeated across five controllers, each with its own timeout and error handling, is not five small conveniences — it is five places to fix one bug, and four of them will be missed. That is a module in `app/lib/`, and rung 1 is what proves the case: the `grep` that finds five copies is the argument.
+- **A boundary the app genuinely has.** Persistence, networking, and native-module access are real seams. A wrapper there is not indirection; it is the place where the swap happens when the vendor changes.
+- **Something with its own lifecycle.** State, timers, listeners, and cleanup that belong together belong in one owner — a Widget or a service. Scattering them across the controllers that happen to use them is the expensive version.
+- **A contract several teams or projects depend on.** Portability is a reason, and `app/widgets/` is where it lives.
+- **Tests.** Extracting logic so it can be tested is a real reason to add a file, even when there is only one caller.
+
+The distinction that matters is between a **boundary** and a **detour**. A boundary is a place where the implementation could plausibly change, or where the two sides genuinely should not know each other. A detour is a hop that always resolves to the same destination. Both look like a layer in the diff; only one of them pays for itself.
+
+When the answer is "build it", say why in a sentence — which rung failed, and what the evidence was. *"Five call sites, measured; extracting to `lib/api/themes.js`"* is a decision anyone can check. *"For maintainability"* is not.

package/skills/ti-ui/SKILL.md

@@ -9,6 +9,8 @@ allowed-tools: Read, Grep, Glob, Edit, Write, Bash(node *)
 
 A practical guide to Titanium SDK UI. Covers layouts, event handling, animations, performance, and platform-specific components for iOS and Android.
 
+> **When "new UI" means new files, run the `ti-reuse-first` skill first.** A new window, panel or dialog is often an existing one that needs a parameter, and a layout computed in JavaScript is often a TSS condition. This guide covers how to build whatever survives that question.
+
 ## Project detection
 
 > **️ℹ️ auto-detects titanium projects**