@maccesar/titools 2.5.0 → 2.6.0

package/README.md

@@ -1,293 +1,791 @@
-<p align="center">
-  <img src="https://codigomovil.mx/images/logotipo-purgetss-gris.svg" height="230" width="230" alt="PurgeCSS logo"/>
-</p>
+# TiTools - Titanium CLI for AI coding assistants
 
 <div align="center">
 
-![npm](https://img.shields.io/npm/dm/purgetss)
-![npm](https://img.shields.io/npm/v/purgetss)
-![NPM](https://img.shields.io/npm/l/purgetss)
+![npm](https://img.shields.io/npm/dm/@maccesar%2Ftitools)
+![npm](https://img.shields.io/npm/v/@maccesar%2Ftitools)
+![NPM](https://img.shields.io/npm/l/@maccesar%2Ftitools)
 
 </div>
 
-**PurgeTSS** is a toolkit for building mobile apps with the [Titanium framework](https://titaniumsdk.com). It provides utility classes, icon font support, an Animation module, a grid system, and the `shades` command for generating custom colors.
+TiTools is a Titanium SDK toolkit for AI coding assistants. It provides 9 skills, a research agent, and 100+ reference files for Titanium SDK, Alloy MVC, and PurgeTSS.
+
+The reference files are maintained against official documentation whenever an official source exists, so the assistant can retrieve current framework behavior instead of guessing from generic training data.
+
+Without TiTools, assistants rely on general training data. That data can be outdated or too generic for Titanium work. With TiTools, the assistant can look up Alloy architecture, memory cleanup patterns, PurgeTSS utility classes, and platform-specific APIs.
+
+Vercel's AGENTS.md evaluation reports a 100% pass rate for the knowledge index approach, compared to 53-79% using skills alone.
 
 ---
 
-- 23,300+ utility classes for styling Titanium views
-- Parses XML files to generate a clean `app.tss` with only the classes your project uses
-- Customizable defaults via `config.cjs`, with JIT classes for arbitrary values
-- Icon font support: Font Awesome, Material Icons, Material Symbols, Framework7-Icons
-- `build-fonts` command generates `fonts.tss` with class definitions and fontFamily selectors
-- `shades` command generates color shades from any hex color
-- Animation module for 2D matrix animations on views or arrays of views
-- Grid system for aligning and distributing elements within views
+## Safety and disclaimer
+
+TiTools modifies files in your Titanium project. In particular, the `ti-branding` skill can write branding assets into `app/platform/android/res/` and, when invoked with the `--cleanup-legacy` flag, **delete** obsolete branding artifacts (iOS launch images, Android legacy splash, density fossil folders, etc.).
+
+Recommendations before running destructive operations:
+
+- **Commit your project with git** so you can `git restore` if anything looks wrong.
+- **Always run with `--dry-run` first** when using `--cleanup-legacy` or replacing icons. The skill prints every target and its safety reasoning before touching anything.
+- **Review the staging directory** (`.ti-branding/`) before copying generated assets into your project.
+
+The maintainers of TiTools accept no responsibility for data loss, build breakage, or any other damage caused by the use of the CLI, skills, or generated scripts. The tool is provided AS IS under the MIT License — see [`LICENSE`](./LICENSE) for the full terms. Use at your own risk.
 
 ---
 
-## Animation Module (`purgetss.ui.js`)
+## Installation
 
-Install with `purgetss module` (or `purgetss m`). This places `purgetss.ui.js` in your project's `lib` folder.
+### Option A: Plugin Marketplace (Claude Code only)
 
-### Declaring an Animation object
+The fastest way to get started with Claude Code. One command to add the marketplace, one to install:
 
-```xml
-<Animation id="myAnimation" module="purgetss.ui" class="opacity-0 duration-300 ease-in" />
+```bash
+/plugin marketplace add macCesar/titools
+/plugin install titools@maccesar-titools
 ```
 
-You can use any position, size, color, opacity, or transformation class from `utilities.tss`.
+What you get:
+- All 9 Titanium skills
+- ti-pro research agent
+- Session hook that auto-detects Titanium projects (`tiapp.xml`, Alloy, PurgeTSS)
+- Slash commands: `/ti-check`, `/ti-new-screen`, `/ti-audit`
+- Auto-updates via marketplace
 
-### Available methods
+### Option B: CLI (Claude Code, Gemini CLI, Codex CLI)
 
-| Method                                    | Description                                                                                                                                                                                                                                     |
-| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `play(views, cb)` / `toggle(views, cb)`   | Animate views from current state to the animation state. Toggles `open`/`close` on each call.                                                                                                                                                   |
-| `open(views, cb)`                         | Explicitly run the `open` state animation.                                                                                                                                                                                                      |
-| `close(views, cb)`                        | Explicitly run the `close` state animation.                                                                                                                                                                                                     |
-| `apply(views, cb)`                        | Apply properties instantly without animation.                                                                                                                                                                                                   |
-| `draggable(views)`                        | Make a view or array of views draggable inside their parent.                                                                                                                                                                                    |
-| `undraggable(views)`                      | Remove draggable behavior and clean up all listeners.                                                                                                                                                                                           |
-| `detectCollisions(views, dragCB, dropCB)` | Enable collision detection on draggable views with hover and drop callbacks.                                                                                                                                                                    |
-| `swap(view1, view2)`                      | Animate two views exchanging positions. Auto-normalizes position from margins/right/center via `view.rect`. Inherits `duration`, `delay`, `curve`; fallback: 200ms.                                                                             |
-| `sequence(views, cb)`                     | Animate views one after another. Callback fires after the last view.                                                                                                                                                                            |
-| `shake(view, intensity)`                  | Bidirectional shake animation for error feedback. Inherits `duration`, `delay`; fallback: 400ms. Default intensity: 10px.                                                                                                                       |
-| `pulse(view, count)`                      | Scale-up-and-back pulse animation. Scale from Animation object (default 1.2x). Count: number of pulses (default 1).                                                                                                                             |
-| `snapTo(view, targets)`                   | Snap a view to the nearest target by center distance. Auto-normalizes target position. Inherits `duration`, `delay`, `curve`; fallback: 200ms.                                                                                                  |
-| `reorder(views, newOrder)`                | Animate views to new positions based on index mapping. Auto-normalizes positions. Inherits `duration`, `delay`, `curve`; fallback: 200ms.                                                                                                       |
-| `transition(views, layouts)`              | Multi-view layout transitions using `Matrix2D.translate().rotate().scale()`. Layout properties: `translation`, `rotate`, `scale`, `zIndex`. Compatible with TiDesigner presets. Views without a layout entry fade out; returning views fade in. |
+Cross-platform installation via npm. Works with all three AI coding assistants:
 
-### Callback event object
+```bash
+# 1) Install the CLI
+npm install -g @maccesar/titools
 
-All callbacks (`play`, `open`, `close`, `apply`) receive an enriched event object:
+# 2) Install skills globally
+titools install
 
-```js
-{
-  type: String,         // event type ('complete' or 'applied')
-  bubbles: Boolean,
-  cancelBubble: Boolean,
-  action: String,       // 'play' or 'apply'
-  state: String,        // 'open' or 'close'
-  id: String,           // Animation object ID
-  targetId: String,     // ID of the animated view
-  index: Number,        // position in array (0-based)
-  total: Number,        // total views in array
-  getTarget: Function   // returns the animated view object
-}
-```
-
-When animating an **array of views**, the callback is called once per view with the corresponding `index` and `total` values.
+# 3) Go to your Titanium project
+cd /path/to/your/project
 
-```js
-$.myAnimation.play([$.card1, $.card2, $.card3], (e) => {
-  console.log(`Animated ${e.index + 1} of ${e.total}`) // "Animated 1 of 3", etc.
-  if (e.index === e.total - 1) {
-    console.log('All done!')
-  }
-})
+# 4) Sync the knowledge index into your project files
+titools sync
+
+# 5) Start your AI coding assistant
+claude   # or gemini, or codex
+
+# 6) Ask away!
+# "How should I structure a new app with login, signup, and a dashboard?"
+# "My ListView with 500 items scrolls poorly on Android. How do I fix it?"
 ```
 
-### Multi-state animations
+What gets installed:
+- All 9 titanium-related skills to `~/.agents/skills/`
+- ti-pro agent for Claude Code
+- Platform symlinks (Claude Code, Gemini CLI, Codex CLI)
+- Knowledge index in your project's `AGENTS.md`/`CLAUDE.md`/`GEMINI.md`
+- Claude Code SessionStart hook for auto-updates
 
-Use `open`, `close`, and `complete` modifiers inside `animationProperties` to define different states:
+Why NPM?
+- Cross-platform (macOS, Linux, Windows)
+- No sudo required
+- Auto-updates via Claude Code hook (checks once per day)
 
-```xml
-<Animation id="fadeToggle" module="purgetss.ui" class="duration-300"
-  animationProperties="{
-    open: { opacity: 1 },
-    close: { opacity: 0 }
-  }"
-/>
+### Which option should I use?
+
+| | Plugin (Option A) | CLI (Option B) |
+|---|---|---|
+| **Claude Code** | Recommended | Supported |
+| **Gemini CLI** | Not available | Supported |
+| **Codex CLI** | Not available | Supported |
+| **Knowledge Index** | Not included | Included (`titools sync`) |
+| **Auto-updates** | Via marketplace | Via SessionStart hook |
+| **Slash commands** | `/ti-check`, `/ti-new-screen`, `/ti-audit` | Not available |
+| **Session hook** | Auto-detects Titanium projects | Auto-update only |
+
+Use **Option A** if you only use Claude Code. Use **Option B** if you use multiple AI assistants or want the Knowledge Index feature.
+
+---
+
+## Compatible platforms
+
+| Platform                                                  | Status           | Installation Path   |
+| --------------------------------------------------------- | ---------------- | ------------------- |
+| [Claude Code](https://claude.ai/claude-code)              | Fully Compatible | `~/.claude/skills/` |
+| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | Fully Compatible | `~/.gemini/skills/` |
+| [Codex CLI](https://developers.openai.com/codex/cli/)     | Fully Compatible | `~/.codex/skills/`  |
+
+All three platforms use the Agent Skills open standard: a `SKILL.md` file with YAML frontmatter.
+
+---
+
+## Knowledge index
+
+The knowledge index is a compressed documentation map that gets injected into your project's instruction files. It tells the AI where Titanium reference docs are, so it can pull accurate information from the installed references instead of relying on general training data.
+
+### Why it works
+
+| Approach         | Reported Pass Rate |
+| ---------------- | ------------------ |
+| No documentation | 53%                |
+| Skills only      | 53-79%             |
+| Knowledge index  | 100%               |
+
+Per Vercel's evaluation:
+- No decision point: information is present without needing to invoke skills
+- Consistent availability: available in every turn, not async-loaded
+- No ordering issues: avoids "read docs first vs explore project first"
+
+For details, see `AGENTS-VERCEL-RESEARCH.md`.
+
+### What gets generated
+
+The `titools sync` command generates a block like this inside your project files:
+
+```
+[Titanium SDK Docs Index]|root: ~/.agents/skills
+|MANDATORY: Your training data for Titanium SDK, Alloy, and PurgeTSS is OUTDATED and INCOMPLETE. These reference files are the SINGLE SOURCE OF TRUTH. Prefer retrieval-led reasoning over pre-training-led reasoning. ALWAYS read the relevant files below BEFORE writing any code.
+|ti-expert/references:{alloy-structure.md,anti-patterns.md,...}
+|purgetss/references:{animation-system.md,class-index.md,...}
+|ti-ui/references:{layouts-and-positioning.md,listviews-and-performance.md,...}
+...
 ```
 
-### Draggable views
+Note: The index is injected as direct content (no code blocks) so the model treats it as an active instruction, not illustrative text.
 
-```js
-$.myAnimation.draggable($.myView)
-// or with constraints:
-$.myAnimation.draggable([$.card1, $.card2])
+File selection per assistant:
+- Claude Code -> `CLAUDE.md`
+- Gemini CLI -> `GEMINI.md`
+- Codex CLI / others -> `AGENTS.md`
+
+### How skills and the knowledge index work together
+
+The knowledge index provides always-available context (the documentation map). Skills provide specialized, on-demand expertise (the actual knowledge).
+
+Together they work like this:
+
+| Your Question                   | Knowledge Index Provides        | Skills Activate               |
+| ------------------------------- | ------------------------------- | ----------------------------- |
+| "Create a login screen"         | Context about project structure | `ti-expert`, `ti-ui`          |
+| "Optimize ListView performance" | Points to docs location         | `ti-ui` reads specific files  |
+| "Implement push notifications"  | API reference paths             | `ti-howtos` provides workflow |
+
+You do not need to explicitly invoke skills. The AI detects when to use them based on your question.
+
+### Version notice
+
+The knowledge index is based on the latest Titanium SDK documentation. If your project uses an older version, the command will warn you about potential API differences.
+
+---
+
+## 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  |
+| 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 |
+
+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).
+
+---
+
+## Agents (Claude Code only)
+
+In addition to skills, this repository includes sub-agents for Claude Code. Sub-agents run in isolated contexts and are useful for research tasks that produce verbose output.
+
+### ti-pro
+
+Deep-dive research specialist that preloads all 8 titanium-related documentation skills.
+
+| Aspect           | Details                                           |
+| ---------------- | ------------------------------------------------- |
+| Location         | `~/.claude/agents/ti-pro.md`                      |
+| Model            | Sonnet (comprehensive analysis)                   |
+| Tools            | Read-only (Read, Grep, Glob)                      |
+| Preloaded Skills | All 8 Titanium documentation skills injected at startup |
+
+When to use the agent vs skills:
+
+| Use Case                     | Use This                        | Why                                                  |
+| ---------------------------- | ------------------------------- | ---------------------------------------------------- |
+| Quick inline reference       | `/ti-expert`, `/purgetss`, etc. | Runs in main conversation, interactive               |
+| Analyzing an entire codebase | `ti-pro` agent                  | Isolates verbose output, cross-references all skills |
+| Multi-feature research       | `ti-pro` agent                  | Preloads all skills for comprehensive answers        |
+| Step-by-step implementation  | Skills directly                 | Task-oriented guidance                               |
+| Architecture review          | `ti-pro` agent                  | Read-only analysis across all documentation          |
+
+Example prompts for the agent:
+
+```
+"Can you use the ti-pro agent to analyze this Alloy codebase's architecture?"
+"Can you research how to combine location, push, and background sync in Titanium?"
+"Can you compare ListView vs TableView performance for my use case?"
+"Review this Titanium mobile app and identify anti-patterns."
 ```
 
-Use `bounds` to restrict movement, and `drag`/`drop` modifiers for drag-state animations. Use `vertical-constraint` or `horizontal-constraint` classes to limit the drag axis.
+Tip: For automatic activation, include words like "Titanium", "Alloy", or "mobile app" in your prompt to ensure the specialized agent is used instead of generic code analysis.
 
-### Collision detection
+Key difference:
+- Skills = interactive help during development (inline, conversational)
+- Agents = isolated research tasks (returns summary, keeps verbose output separate)
 
-After calling `draggable()`, you can enable collision detection to know when a dragged view overlaps another:
+---
+
+## Slash Commands (Plugin only)
+
+When installed as a plugin, TiTools provides slash commands for common tasks:
+
+| Command | Description |
+|---|---|
+| `/ti-check` | Verify project setup: SDK version, Alloy structure, PurgeTSS config, common issues |
+| `/ti-new-screen <name>` | Create a new Alloy screen (controller + view + style) following project conventions |
+| `/ti-audit` | Audit project for anti-patterns, memory leaks, and best practice violations |
+
+These commands automatically invoke the relevant skills:
+- `/ti-check` reads `tiapp.xml` and reports project health
+- `/ti-new-screen` uses `alloy-guides` + `purgetss` to create properly structured files
+- `/ti-audit` uses `ti-expert` + `ti-ui` + `purgetss` + `alloy-guides` for comprehensive review
+
+---
+
+## Session Hook (Plugin only)
+
+The plugin includes a session start hook that auto-detects Titanium projects. When you open Claude Code in a directory with `tiapp.xml`, it automatically reports:
 
-```js
-$.myAnimation.draggable(views)
-$.myAnimation.detectCollisions(views, onHover, onDrop)
+```
+Titanium Alloy + PurgeTSS project detected. TiTools skills are available and MUST be used...
 ```
 
-**`dragCB(source, target)`** is called during drag:
-- `target` is the view under the drag center, or `null` when leaving all targets
-- Use this to show visual feedback (highlights, borders, scaling)
+This ensures Claude knows it's a Titanium project from the first prompt, preventing it from writing generic code.
 
-**`dropCB(source, target)`** is called on drop:
-- `target` is the view where the source was released
-- If no target is found, the source automatically snaps back to its original position with a 200ms animation
+---
 
-### Swap animation
+## How skills work
 
-Animate two views exchanging positions:
+Skills are automatically activated based on your questions. Just ask naturally:
 
-```js
-$.myAnimation.swap(view1, view2)
+```
+"Can you create a login screen with email validation and animations?"
 ```
 
-- Inherits `duration`, `delay`, and `curve` from the Animation object's classes
-- Falls back to 200ms duration, 0ms delay, and ease-in-out curve if not set
-- Handles iOS transform reset automatically
-- Temporarily raises z-index so views animate above siblings
-- Updates internal `_originLeft`/`_originTop` for subsequent drag operations
+The AI will automatically use:
+- `ti-expert` -> Architecture and controller structure
+- `purgetss` -> Styling classes and animations (if PurgeTSS detected)
+- `ti-howtos` -> Secure token storage
 
-### Sequence animation
+You do not need to call skills explicitly. The AI reads skill descriptions and loads the appropriate knowledge when needed.
 
-Animate views one after another (unlike `play(array)` which runs them in parallel):
+### Project detection
 
-```js
-$.fadeIn.sequence([$.title, $.subtitle, $.button], () => {
-  console.log('All views animated')
-})
+All skills include automatic project detection to ensure compatibility:
+
+| Skill        | What It Detects       | How It Works                                                  |
+| ------------ | --------------------- | ------------------------------------------------------------- |
+| purgetss     | PurgeTSS installation | Checks for `purgetss/` folder, `config.cjs`, `utilities.tss`  |
+| ti-expert    | Alloy vs Classic      | Checks for `app/` (Alloy) vs `Resources/` (Classic) structure |
+| alloy-guides | Alloy projects        | Checks for `app/views/`, `app/controllers/`                   |
+| alloy-howtos | Alloy projects        | Checks for `alloy.jmk`, `config.json`                         |
+| ti-ui        | Titanium projects     | Checks for `tiapp.xml` (both Alloy and Classic)               |
+| ti-guides    | Titanium projects     | Checks for `tiapp.xml` (both Alloy and Classic)               |
+| ti-howtos    | Titanium projects     | Checks for `tiapp.xml` (both Alloy and Classic)               |
+
+Why this matters:
+- PurgeTSS suggestions are only provided if PurgeTSS is installed
+- Alloy-specific patterns are only suggested for Alloy projects
+- Classic Titanium projects will not receive inappropriate Alloy advice
+
+### Skill hierarchy
+
+`ti-expert` acts as the orchestrator, delegating to specialized skills when needed:
+
+```
+                    ┌─────────────────┐
+                    │  ti-expert      │
+                    │  (Start Here)   │
+                    └────────┬────────┘
+                             │
+        ┌────────────────────┼────────────────────┐
+        │                    │                    │
+        ▼                    ▼                    ▼
+┌───────────────┐   ┌───────────────┐   ┌───────────────┐
+│   purgetss    │   │    ti-ui      │   │   ti-howtos   │
+│   (Styling)   │   │   (UI/UX)     │   │   (Native)    │
+└───────────────┘   └───────────────┘   └───────────────┘
+        │                    │                    │
+        └────────────────────┼────────────────────┘
+                             │
+        ┌────────────────────┼────────────────────┐
+        │                    │                    │
+        ▼                    ▼                    ▼
+┌───────────────┐   ┌───────────────┐   ┌───────────────┐
+│  ti-guides    │   │ alloy-guides  │   │ alloy-howtos  │
+│    (SDK)      │   │    (MVC)      │   │    (CLI)      │
+└───────────────┘   └───────────────┘   └───────────────┘
 ```
 
-- Each view fully completes before the next starts
-- Callback fires once after the last view
-- Respects `open`/`close` state (set once for the entire sequence)
+---
+
+## Skill details
 
-### Shake animation
+### ti-expert
 
-Quick horizontal shake for error feedback, using native `autoreverse` + `repeat` for smooth performance:
+The primary skill for Titanium Alloy development. Start here for most tasks.
 
-```js
-$.myAnimation.shake($.loginButton)        // default intensity: 10px
-$.myAnimation.shake($.input, 6)           // subtle: 6px
-$.myAnimation.shake($.errorLabel, 20)     // strong: 20px
+When it activates:
+- Designing project structure
+- Implementing controllers, views, services
+- Choosing data strategies (Models vs Collections)
+- Writing clean ES6+ code
+- Memory management and cleanup patterns
+- Performance optimization
+- Security patterns
+- Migrating legacy apps
+
+Example prompts:
+```
+"How should I structure a new Titanium Alloy app with authentication?"
+"Create a user service that fetches data from an API."
+"What's the best pattern for navigation between screens?"
+"Prevent memory leaks in my controllers."
+"Migrate classic Titanium code to modern Alloy patterns."
+"What's a clean way to organize services in an Alloy app?"
 ```
 
-### Snap to nearest target
+Key features:
+- Quick decision matrix for common questions
+- 18 reference guides for deep dives
+- Delegates to specialized skills when needed
 
-After dragging, snap a view to the closest target by center-to-center distance:
+---
 
-```js
-const matched = $.myAnimation.snapTo(draggedView, slotViews)
-if (matched) {
-  console.log('Snapped to:', matched.id)
-}
+### purgetss
+
+Utility-first styling toolkit for Titanium/Alloy.
+
+When it activates:
+- Setting up PurgeTSS in a project
+- Complex layouts (Grid system)
+- Declarative animations (`<Animation>` component)
+- Icon fonts (Font Awesome, Material Icons)
+- Custom color palettes
+- Platform-specific styling
+- config.cjs configuration
+
+Example prompts:
 ```
+"How do I set up PurgeTSS in my existing Alloy project?"
+"Create a responsive 12-column grid layout."
+"Add a fade-in animation when my view appears."
+"How do I configure custom colors in config.cjs?"
+"How do I use Font Awesome 7 icons?"
+"Style this button differently on iOS vs Android."
+```
+
+Rules:
+- Platform-specific properties require modifiers (e.g., `[platform=ios]`) to prevent cross-platform build failures
+- No flexbox (`flex-row`, `justify-between`) -> use `horizontal`/`vertical`
+- No `w-full` -> use `w-screen`
+- No `p-*` on Views -> use `m-*` on children
+- Arbitrary values use parentheses: `w-(100px)`, not `w-[100px]`
 
-### Reorder animation
+---
 
-Animate an array of views to new positions based on index mapping:
+### ti-ui
 
-```js
-// Reverse order: view[0] goes to position of view[2], view[2] to position of view[0]
-$.myAnimation.reorder(cardViews, [2, 1, 0])
+UI/UX expert for layouts and platform components.
+
+When it activates:
+- Layout systems (composite, vertical, horizontal)
+- ListView/TableView optimization
+- Event handling and bubbling
+- Animations and transforms
+- Gestures (swipe, pinch, longpress)
+- Orientation handling
+- App icons and splash screens
+- Android Action Bar / iOS Navigation patterns
+- Accessibility (VoiceOver, TalkBack)
+
+Example prompts:
+```
+"How do I create a high-performance ListView with custom templates?"
+"Handle swipe gestures on table rows."
+"Set up app icons for all iOS and Android densities."
+"Implement pull-to-refresh on a ScrollView."
+"How do I make my app accessible for VoiceOver users?"
+"How do I configure the Android Action Bar with custom menu items?"
 ```
 
-- All views animate simultaneously
-- Captures positions before animating to avoid conflicts
+Key rules:
+- No `Ti.UI.SIZE` in ListView items (causes jerky scrolling)
+- Prefer ListView over TableView for large datasets
+- Use `dp` units for cross-platform consistency
+- Remove global listeners on pause
 
-### Removing draggable behavior
+---
 
-Remove draggable behavior and clean up all event listeners:
+### ti-howtos
+
+Native feature integration expert.
+
+When it activates:
+- Location services and Maps
+- Push notifications (APNs/FCM)
+- Local notifications
+- Camera and Gallery
+- Audio/Video playback
+- File system operations
+- SQLite databases
+- HTTPClient networking
+- WebView integration
+- Android Intents and Services
+- iOS Background Services, iCloud, Keychain
+- Core Motion, WatchKit
+
+Example prompts:
+```
+"How do I implement battery-efficient GPS tracking?"
+"How do I set up push notifications for iOS and Android?"
+"How do I capture and resize photos from the camera?"
+"Download files with a progress indicator."
+"How should I store sensitive data in iOS Keychain?"
+"Create an Android background service."
+"Integrate with Apple Watch using WatchKit."
+"Handle background location updates on iOS."
+```
 
-```js
-$.myAnimation.undraggable(cardViews)
+Key rules:
+- Always handle both `onload` and `onerror` for HTTPClient
+- Always close database handles and result sets
+- Use `imageAsResized` to avoid memory exhaustion
+- Configure proper permissions in tiapp.xml
+
+---
+
+### ti-guides
+
+SDK fundamentals and advanced configuration.
+
+When it activates:
+- Hyperloop native access
+- Native module development
+- App distribution (Play Store, App Store)
+- tiapp.xml configuration
+- CLI commands and options
+- Memory and bridge optimization
+- CommonJS module patterns
+- Coding best practices
+
+Example prompts:
+```
+"How do I access native iOS APIs using Hyperloop?"
+"Configure tiapp.xml for a production build."
+"What do I need for Google Play submission?"
+"How do I create a native Android module?"
+"Optimize bridge crossings for better performance."
+"List reserved words I should avoid."
 ```
 
-### Property inheritance
+---
 
-The `swap`, `reorder`, `snapTo`, and `shake` methods inherit animation properties from the `<Animation>` object's classes. This means you can configure behavior declaratively in XML:
+### alloy-guides
 
-```xml
-<Animation id="myAnim" module="purgetss.ui" class="curve-animation-ease-out delay-100 duration-150" />
+Complete Alloy MVC framework reference.
+
+When it activates:
+- MVC architecture concepts
+- Backbone.js models and collections
+- Data binding patterns
+- XML markup elements
+- TSS styling syntax
+- Widget development
+- Sync adapters (sql, properties)
+- Migrations
+
+Example prompts:
+```
+"Explain how Alloy data binding works."
+"How do I create a model with the SQLite adapter?"
+"Bind a collection to a TableView."
+"How do I build a reusable widget?"
+"Show the TSS syntax for platform-specific styles."
+"How does the Alloy compilation process work?"
+```
+
+---
+
+### alloy-howtos
+
+Alloy CLI, configuration, and debugging.
+
+When it activates:
+- Alloy CLI commands (new, generate, compile)
+- Configuration files (alloy.jmk, config.json)
+- Debugging compilation errors
+- Conditional views
+- Custom XML tags
+- Best practices and naming conventions
+- Backbone.Events patterns
+
+Example prompts:
+```
+"How do I generate a new model with the CLI?"
+"Configure alloy.jmk build hooks."
+"How do I fix "No app.js found"?"
+"Create conditional views based on user state."
+"How do I build a custom XML tag without widgets?"
+"Set up Backbone.Events for global communication."
+```
+
+Key rules:
+- Use Backbone.Events instead of Ti.App.fireEvent
+- Never use double underscore prefixes (`__foo`)
+- Access config at runtime with `Alloy.CFG.yourKey`
+
+---
+
+## Usage examples and best practices
+
+### Example prompts
+
+Starting a new project:
+```
+"I'm starting a new Titanium Alloy app for a food delivery service.
+Can you help me set up the project structure?"
+```
+
+UI development:
+```
+"Can you create a product listing screen with:
+- Pull-to-refresh
+- Infinite scroll pagination
+- Image caching
+- Swipe-to-delete"
 ```
 
-| Property      | `play`/`toggle`/`open`/`close`/`sequence` | `swap`/`reorder`/`snapTo` |       `shake`       |
-| ------------- | :---------------------------------------: | :-----------------------: | :-----------------: |
-| `duration`    |                     ✅                     |             ✅             |       ✅ (÷6)        |
-| `delay`       |                     ✅                     |             ✅             |          ✅          |
-| `curve`       |                     ✅                     |             ✅             | fixed `EASE_IN_OUT` |
-| `autoreverse` |                     ✅                     |             —             |    fixed `true`     |
-| `repeat`      |                     ✅                     |             —             |      fixed `3`      |
+API integration:
+```
+"Can you build a complete authentication flow with:
+- Login/Register screens
+- JWT token management
+- Secure storage
+- Auto-refresh tokens"
+```
 
-Fallback defaults when not set: `swap`/`reorder`/`snapTo` → 200ms; `shake` → 400ms. All animation timing is controlled declaratively via the `<Animation>` object's classes.
+Performance optimization:
+```
+"My app is slow - the ListView scrolls poorly and memory usage is high. How do I optimize it?"
+```
 
-- Removes touch and orientation listeners
-- Removes views from collision detection registry
-- Cleans up internal tracking properties
+Migration:
+```
+"I have a legacy Titanium classic app from 2015. Can you help me migrate it to modern Alloy?"
+```
 
-### Utility classes for animations
+Platform-specific features:
+```
+"How do I implement Apple Sign-In for iOS and Google Sign-In for Android?"
+```
 
-| Class pattern                                       | Description                   |
-| --------------------------------------------------- | ----------------------------- |
-| `duration-{n}`                                      | Animation duration in ms      |
-| `delay-{n}`                                         | Delay before animation starts |
-| `rotate-{n}`                                        | 2D rotation in degrees        |
-| `scale-{n}`                                         | Scale factor                  |
-| `repeat-{n}`                                        | Number of repeats             |
-| `ease-in`, `ease-out`, `ease-linear`, `ease-in-out` | Timing curve                  |
-| `zoom-in-{n}`, `zoom-out-{n}`                       | Zoom animations               |
-| `drag-apply`, `drag-animate`                        | Drag interaction style        |
-| `vertical-constraint`, `horizontal-constraint`      | Constrain drag axis           |
+Debugging:
+```
+"How do I fix "Alloy is not defined" in my lib file?"
+```
 
-### Utility functions
+Codebase analysis (using agent):
+```
+"Use the ti-pro agent to analyze this project and:
+- review the overall architecture
+- identify memory leak patterns
+- check for common anti-patterns
+- suggest improvements"
+```
 
-| Function                               | Description                                                                                              |
-| -------------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| `deviceInfo()`                         | Logs detailed platform and display information to the console. Works in both Alloy and Classic projects. |
-| `saveComponent({ source, directory })` | Saves a view snapshot as PNG to the photo gallery.                                                       |
+### Tips for better results
 
-See the full documentation at [purgetss.com/docs/animation-module/introduction](https://purgetss.com/docs/animation-module/introduction).
+1. Be specific. Instead of "Make a list", try "Can you create a ListView with user avatars, names, and swipe actions?"
+2. Provide context. Instead of "How do I fix this error?", try "I'm getting this error when compiling: [error message]. Here's my code: [code]"
+3. Ask for architecture first. For complex features, start with "How should I architect a real-time chat feature?" then follow up with implementation details.
+4. Mention constraints. "Build a settings screen. Must work offline and sync when connected."
+5. Reference existing code. "Here's my current controller. How can I improve memory management?"
+
+More examples: See [Example Prompts](EXAMPLE-PROMPTS.md) for detailed prompts that test each skill's capabilities.
 
 ---
 
-## Customizing default components
+## CLI reference
 
-PurgeTSS sets defaults for three components out of the box:
+### titools install
 
-| Component   | Default                                 |
-| ----------- | --------------------------------------- |
-| `Window`    | `backgroundColor: '#FFFFFF'`            |
-| `View`      | `width: Ti.UI.SIZE, height: Ti.UI.SIZE` |
-| `ImageView` | `hires: true` (iOS only)                |
+Installs Titanium skills, agents, and platform symlinks.
 
-Override or extend them in `config.cjs` with `theme.extend`:
+```bash
+titools install [options]
+```
 
-```js
-module.exports = {
-  theme: {
-    extend: {
-      Window: {
-        apply: 'exit-on-close-false bg-surface'
-      }
-    }
-  }
-}
+Options:
+| Option          | Description                                                         |
+| --------------- | ------------------------------------------------------------------- |
+| `-l, --local`   | Install skills locally in the current project (`./.agents/skills/`) |
+| `-a, --all`     | Install to all detected platforms without prompting                 |
+| `--path <path>` | Install to a custom path (skips symlink setup)                      |
+
+Behavior depends on where you run it:
+
+| Context                    | Behavior                                                              |
+| -------------------------- | --------------------------------------------------------------------- |
+| Outside a Titanium project | Installs skills globally to `~/.agents/skills/`                       |
+| Inside a Titanium project  | Prompts you to choose: Global or Local installation                   |
+| With `--local` flag        | Installs skills locally to `./.agents/skills/` in the current project |
+
+What it does:
+- Installs all 7 titanium-related skills (global or local depending on context)
+- Installs ti-pro agent for Claude Code
+- Detects installed AI platforms and lets you choose which to link
+- Creates symlinks from platform directories to central skills
+- Cleans up legacy artifacts (`alloy-expert` skill, `ti-researcher` agent)
+- If run inside a Titanium project, prompts to run `titools sync` afterward
+- Warns Gemini users if local skills override existing global Gemini skills
+- Installs Claude Code SessionStart hook for auto-updates
+
+### titools auto-update
+
+Checks for updates and applies them silently. Designed to run from the Claude Code SessionStart hook, but can also be used manually.
+
+```bash
+titools auto-update            # Show progress
+titools auto-update --silent   # No output (for hooks)
 ```
 
-If an applied class sets a property that already exists in the defaults (e.g., `bg-surface` vs `backgroundColor: '#FFFFFF'`), the applied value wins. Array-type properties like `extendEdges` and `orientationModes` use bracket notation (`[ ]`) in the generated output.
+Options:
+| Option         | Description                        |
+| -------------- | ---------------------------------- |
+| `-s, --silent` | Suppress all output except errors |
 
-### Shorthand and explicit forms
+What it does:
+1. Checks a local cache (`~/.titools/last-check.json`) — if already checked today, exits immediately
+2. Queries npm for the latest version
+3. If a new version is available, runs `npm update -g @maccesar/titools`
+4. Syncs skills and refreshes platform symlinks
+5. If inside a Titanium project, updates existing Knowledge Index files
+6. Writes the cache so it won't check again for 24 hours
 
-Both are equivalent:
+The hook is installed automatically by `titools install` when Claude Code is selected. It runs `titools auto-update --silent` at the start of every Claude Code session.
 
-```js
-// Shorthand
-Window: { apply: 'exit-on-close-false' }
+### titools status
 
-// Explicit
-Window: { default: { apply: 'exit-on-close-false' } }
+Shows a quick overview of your installation.
+
+```bash
+titools status
 ```
 
-Use the explicit form when you need platform-specific variants:
+Displays: version, skills count, agent, hook status, last update check, platform symlinks, and project Knowledge Index status (if inside a Titanium project).
 
-```js
-Button: {
-  default: { apply: 'text-xl' },
-  ios: { apply: 'font-bold' },
-  android: { apply: 'text-2xl font-semibold', color: 'red' }
-}
+### titools doctor
+
+Diagnoses installation health.
+
+```bash
+titools doctor
+```
+
+Checks: skill directories exist, symlinks are valid (not broken), agent is installed, hook is configured, cache is readable, Knowledge Index version matches CLI version. Reports issues with fix suggestions.
+
+### titools sync
+
+Generates a compressed knowledge index inside your project's instruction files (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`).
+
+Important: This command only works inside a Titanium project (requires `tiapp.xml`). The knowledge index is project-specific. It detects your SDK version and points to the installed skill references.
+
+```bash
+titools sync [path] [options]
+```
+
+Arguments:
+| Argument | Description                                  |
+| -------- | -------------------------------------------- |
+| `[path]` | Project path (defaults to current directory) |
+
+Options:
+| Option          | Description                                |
+| --------------- | ------------------------------------------ |
+| `-f, --force`   | Overwrite existing files without prompting |
+| `-v, --verbose` | Show detailed diagnostics                  |
+
+What it does:
+- Verifies you're inside a Titanium project (`tiapp.xml`)
+- Detects Titanium SDK version from `tiapp.xml`
+- Prompts you to select which files to sync: `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`
+- Inserts or updates a compressed knowledge index block in selected files
+- Removes knowledge blocks from unselected files
+- Creates files if they don't exist
+
+### titools update
+
+Checks whether a newer `titools` CLI version is available on npm, then syncs installed skills and agents from the currently installed package.
+
+```bash
+titools update [options]
+```
+
+Options:
+| Option        | Description                                |
+| ------------- | ------------------------------------------ |
+| `-l, --local` | Update local skills in the current project |
+
+Behavior depends on where you run it:
+
+| Context                                                         | Behavior                                                    |
+| --------------------------------------------------------------- | ----------------------------------------------------------- |
+| Outside a Titanium project                                      | Updates global skills in `~/.agents/skills/` (if installed) |
+| Inside a Titanium project (local skills only)                   | Updates local skills automatically                          |
+| Inside a Titanium project (both local and global)               | Prompts you to choose: Global or Local                      |
+| Inside a Titanium project (with existing knowledge index files) | Also refreshes `AGENTS.md`/`CLAUDE.md`/`GEMINI.md`          |
+
+What it does:
+1. Checks npm for the latest CLI version
+2. If a newer version exists, it shows the update command `npm update -g @maccesar/titools`
+3. It exits without changing skills, agents, or knowledge files until the CLI is updated
+4. If the CLI is current, it syncs skills and agents from the installed package (no download needed)
+5. Updates platform symlinks only for platforms that already have them
+6. Cleans up legacy artifacts (`alloy-expert` skill, `ti-researcher` agent)
+7. Auto-syncs knowledge index files if they exist in the current project
+
+Note: This command syncs knowledge packages and agents from your installed CLI. To get new features, first update the CLI with `npm update -g @maccesar/titools`, then run `titools update` again.
+
+### titools remove
+
+Removes skills, agents, symlinks, and knowledge index blocks.
+
+```bash
+titools remove [options]
+```
+
+Options:
+| Option        | Description                                  |
+| ------------- | -------------------------------------------- |
+| `-l, --local` | Remove local skills from the current project |
+
+What it does:
+- Detects all installed components (skills, agents, symlinks, knowledge blocks)
+- Prompts you to select what to remove:
+  - ti-pro agent for Claude Code
+  - Knowledge index blocks from instruction files (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`)
+  - Skills from global (`~/.agents/skills/`) or project directory
+  - Platform symlinks from global or project directory
+- Removes both current and legacy artifacts
+- Removes Claude Code auto-update hook
+- Cleans up cache directory (`~/.titools/`)
+
+### Verify installation
+
+```bash
+titools status    # Quick overview of everything
+titools doctor    # Diagnose any issues
+titools --version # CLI version only
 ```
 
 ---
@@ -334,34 +832,140 @@ This pattern is documented across four skills: `ti-ui`, `ti-expert`, `ti-api`, a
 
 ---
 
-### Visit the official documentation site at [purgetss.com](https://purgetss.com) to learn more.
-
-## Requirements
-
-- **Titanium SDK** (Compatible with all versions; 13.1.1.GA recommended for full property support)
-- **Alloy Framework** (for most commands)
-- **Node.js 20+** (required for the CLI tool)
-
-## Table of Content
-
-- [Installation](https://purgetss.com/docs/installation)
-- [Commands](https://purgetss.com/docs/commands)
-- Customization
-  - [The Config File](https://purgetss.com/docs/customization/the-config-file)
-  - [Custom Rules](https://purgetss.com/docs/customization/custom-rules)
-  - [The `apply` Directive](https://purgetss.com/docs/customization/the-apply-directive)
-  - [The `opacity` Modifier](https://purgetss.com/docs/customization/the-opacity-modifier)
-  - [Arbitrary Values](https://purgetss.com/docs/customization/arbitrary-values)
-  - [Platform and Device Modifiers](https://purgetss.com/docs/customization/platform-and-device-modifiers)
-  - [Icon Fonts Libraries](https://purgetss.com/docs/customization/icon-fonts-libraries)
-- Animation Module
-  - [Introduction](https://purgetss.com/docs/animation-module/introduction)
-  - [The `play` Method](https://purgetss.com/docs/animation-module/the-play-method)
-  - [The `apply` Method](https://purgetss.com/docs/animation-module/the-apply-method)
-  - [The `open` and `close` Methods](https://purgetss.com/docs/animation-module/the-open-and-close-methods)
-  - [The `draggable` Method](https://purgetss.com/docs/animation-module/the-draggable-method)
-  - [Complex UI Elements](https://purgetss.com/docs/animation-module/complex-ui-elements)
-  - [Additional Methods](https://purgetss.com/docs/animation-module/additional-methods)
-  - [Available Utilities](https://purgetss.com/docs/animation-module/available-utilities)
-  - [Implementation Rules](https://purgetss.com/docs/animation-module/implementation-rules)
-- [Grid System](https://purgetss.com/docs/grid-system)
+## Skill contents summary
+
+| Skill        | SKILL.md                      | References                                            |
+| ------------ | ----------------------------- | ----------------------------------------------------- |
+| alloy-guides | MVC Quick Start               | 10 files (models, views, widgets, etc.)               |
+| alloy-howtos | Best Practices                | 6 files (CLI, config, debugging, etc.)                |
+| purgetss     | Setup + Critical Rules        | 21 files (grid, animations, icons, class-index, etc.) |
+| ti-api       | API Quick Reference           | 14 files (windows, views, lists, media, etc.)         |
+| ti-expert    | Architecture + Implementation | 19 refs + 1 asset (patterns, testing, security, etc.) |
+| ti-guides    | Core Workflow                 | 14 files (hyperloop, distribution, etc.)              |
+| ti-howtos    | Integration Workflow          | 18 files (location, media, maps, automation, etc.)    |
+| ti-ui        | UI Rules + Platform Diffs     | 14 files (layouts, lists, gestures, etc.)             |
+
+---
+
+## Troubleshooting
+
+### Skill not activating?
+
+If the AI doesn't seem to use Titanium knowledge:
+1. Mention "Titanium" or "Alloy" explicitly in your prompt
+2. Be more specific about what you're building
+3. Reference the technology stack
+4. Try explicit invocation: "Use the purgetss skill for styling questions"
+
+### Getting wrong suggestions?
+
+If the AI suggests patterns you don't use (for example, PurgeTSS when you're not using it):
+1. The skill may not have detected your project type correctly
+2. Explicitly mention your stack: "I'm using Classic Titanium, not Alloy"
+3. Be more specific about what you're building
+
+### PurgeTSS not detected?
+
+If the purgetss skill doesn't activate for your PurgeTSS project:
+1. Verify `purgetss/` folder exists in project root
+2. Check that `purgetss/config.cjs` exists
+3. Mention "PurgeTSS" explicitly in your prompt
+
+### Wrong advice?
+
+If the AI suggests incorrect patterns (like flexbox):
+1. Remind it you're using PurgeTSS
+2. Reference the correct pattern from memory
+3. Ask to check the PurgeTSS rules
+
+### Need more detail?
+
+Ask the AI to:
+```
+"Show me the reference documentation for ListView performance"
+"What does the ti-expert skill say about memory cleanup?"
+```
+
+### titools command not found?
+
+If the command is not found:
+```bash
+# Verify installation
+npm list -g @maccesar/titools
+
+# Re-install
+npm install -g @maccesar/titools
+```
+
+### Knowledge index not working?
+
+If your AI doesn't use the knowledge index information:
+1. Verify AGENTS.md/CLAUDE.md/GEMINI.md exists in your project root
+2. Check that your AI supports these files
+3. Try explicitly referencing: "Check the AGENTS.md documentation"
+
+### Version mismatch warning?
+
+The knowledge index is based on the latest documentation. Be cautious when using newer APIs in older projects.
+
+---
+
+## Uninstall
+
+```bash
+# Remove the CLI
+npm uninstall -g @maccesar/titools
+
+# Remove knowledge packages and agent
+titools remove
+```
+
+Note: `titools remove` can remove the knowledge index blocks from your project files, but it does not delete the files themselves.
+
+---
+
+## Contributing
+
+1. Fork the repository
+2. Improve SKILL.md or reference files
+3. Test with your preferred AI coding assistant
+4. Submit a pull request
+
+### Guidelines
+- Keep SKILL.md concise (<500 lines)
+- Use progressive disclosure (details in references)
+- Include concrete examples
+- Test with real sessions
+
+---
+
+## Legacy installation (not recommended)
+
+The bash installer is maintained for backward compatibility but NPM installation is recommended.
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/macCesar/titools/main/install.sh | bash
+```
+
+Use this only if you cannot use NPM for any reason.
+
+---
+
+## Credits
+
+Created by César Estrada ([@macCesar](https://github.com/macCesar)), creator of [PurgeTSS](https://github.com/macCesar/purgeTSS).
+
+## License
+
+MIT License - Free to use, modify, and distribute.
+
+---
+
+## Resources
+
+- [Titanium SDK](https://titaniumsdk.com/)
+- [PurgeTSS](https://purgetss.com/)
+- [TiDev Community](https://tidev.io/)
+- [Claude Code Skills](https://docs.anthropic.com/en/docs/claude-code)
+- [Gemini CLI Skills](https://geminicli.com/docs/cli/skills/)
+- [Codex CLI Skills](https://developers.openai.com/codex/skills/)