@maccesar/titools 2.0.7 → 2.2.1

package/README.md

@@ -1,333 +1,224 @@
-# titools - Titanium CLI for AI Coding Assistants
+# TiTools - Titanium CLI for AI coding assistants
 
-A comprehensive CLI that transforms your coding assistant into a **Titanium SDK expert**. Install skills, agents, and documentation for Titanium SDK, Alloy MVC, and PurgeTSS development.
+<div align="center">
 
-## Compatible Platforms
+![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)
 
-| 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/`  |
+</div>
 
-All three platforms use the same **Agent Skills open standard**: a `SKILL.md` file with YAML frontmatter.
+A CLI that gives your AI coding assistant access to **Titanium SDK** knowledge. One command installs 7 specialized skills, a research agent, and 100+ reference files for Titanium SDK, Alloy MVC, and PurgeTSS.
 
----
+Without `titools`, assistants fall back on general training data, which is often outdated or off-target for Titanium. With `titools`, your assistant can reference Alloy architecture, memory cleanup patterns, PurgeTSS utility classes, and platform-specific APIs.
+
+Based on [Vercel’s research on AGENTS.md](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals), they found that the knowledge index approach achieved a 100% pass rate, compared to 53–79% using skills alone.
 
-## Quick Install
+---
 
-### NPM Package (Recommended)
+## Quick setup
 
 ```bash
+# 1) Install the CLI
 npm install -g @maccesar/titools
-```
-
-This installs the `titools` CLI command globally:
 
-```bash
-# Install skills and agents
+# 2) Install skills globally
 titools install
 
-# Add AGENTS.md/CLAUDE.md to your project
-titools agents
-
-# Update to the latest version
-titools update
-
-# Show version
-titools --version
-```
-
-**What it installs:**
-- ✅ All 7 titanium-* skills
-- ✅ ti-researcher agent
-- ✅ Automatic documentation generation
-
-**Why use NPM?**
-- ✅ Cross-platform support (macOS, Linux, Windows)
-- ✅ No sudo required
-- ✅ Easy version management
-- ✅ Simple updates with `titools update`
-
----
-
-## Usage
-
-### titools install
-
-Installs Titanium skills and agents globally:
-- ✅ All 7 titanium-* skills
-- ✅ ti-researcher agent
-- ✅ AGENTS-TEMPLATE.md (template for documentation generation)
+# 3) Go to your Titanium project
+cd /path/to/your/project
 
-### Verify Installation
+# 4) Sync the knowledge index into your project files
+titools sync
 
-**Check titools version:**
-```bash
-titools --version
-```
-
-**Check central location:**
-```bash
-ls ~/.agents/skills/
-# Should show: alloy-expert, purgetss, ti-ui, ti-howtos, ti-guides, alloy-guides, alloy-howtos
-```
-
-**Claude Code (skills):**
-```bash
-ls -la ~/.claude/skills/
-# Should show symlinks pointing to ~/.agents/skills/
-```
+# 5) Start your AI coding assistant
+claude   # or gemini, or codex
 
-**Claude Code (agents):**
-```bash
-ls -la ~/.claude/agents/
-# Should show: ti-researcher.md
+# 6) Ask away!
+# "My ListView with 500 items scrolls like garbage on Android. How do I fix it?"
+# "How should I structure a new app with login, signup, and a dashboard?"
 ```
 
-**Gemini CLI:**
-```bash
-gemini skills list
-```
+What gets installed:
+- All 7 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`
 
-**Codex CLI:**
-```bash
-# Type /skills in Codex or use $ to mention a skill
-```
+Why NPM?
+- Cross-platform (macOS, Linux, Windows)
+- No sudo required
+- Simple updates with `titools update`
 
 ---
 
-## AGENTS.md: Boost AI Performance to 100%
-
-### ⚠️ Claude Code Users: Use CLAUDE.md
+## Compatible platforms
 
-**Claude Code specifically looks for `CLAUDE.md`** (not `AGENTS.md`).
+| 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/`  |
 
-The `titools agents` command detects if you use Claude Code and creates `CLAUDE.md` automatically:
-
-```bash
-cd /path/to/your/titanium/project
-titools agents
-
-# The command will ask:
-# Which AI assistant are you using?
-#   1) Claude Code (creates CLAUDE.md)
-#   2) Gemini CLI (creates GEMINI.md)
-#   3) Cursor/Copilot (creates AGENTS.md)
-```
-
-The content is identical - only the filename differs per AI assistant.
+All three platforms use the Agent Skills open standard: a `SKILL.md` file with YAML frontmatter.
 
 ---
 
-### How AGENTS.md/CLAUDE.md Works
-
-| Approach         | Pass Rate |
-| ---------------- | --------- |
-| No documentation | 53%       |
-| Skills only      | 53-79%    |
-| **AGENTS.md**    | **100%**  |
+## Knowledge index
 
-**Why it works:**
-- **No decision point** - Information is always present, no need to invoke skills
-- **Consistent availability** - Available in every turn, not async-loaded
-- **No ordering issues** - No "read docs first vs explore project first" dilemma
+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 instead of relying on general training data.
 
-### How to Install AGENTS.md
+### Why it works
 
-After installing titools, add AGENTS.md to your Titanium project:
+| Approach         | Reported Pass Rate |
+| ---------------- | ------------------ |
+| No documentation | 53%                |
+| Skills only      | 53-79%             |
+| Knowledge index  | 100%               |
 
-```bash
-cd /path/to/your/titanium/project
-
-# If using NPM installation:
-titools agents
-```
+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"
 
-The `titools agents` command will:
-1. Verify this is a Titanium project (checks for `tiapp.xml`)
-2. Detect your Titanium SDK version
-3. Create `AGENTS.md`/`CLAUDE.md`/`GEMINI.md` with a compressed 8KB documentation index
-4. Intelligently merge if file already exists (removes old block, adds new one)
+For details, see `AGENTS-VERCEL-RESEARCH.md`.
 
-**Priority Logic:** If multiple AI files exist (CLAUDE.md, GEMINI.md, AGENTS.md), the command updates all of them automatically:
-- CLAUDE.md has highest priority (Claude Code users)
-- GEMINI.md has medium priority (Gemini CLI users)
-- AGENTS.md has lowest priority (Cursor/Copilot users)
+### What gets generated
 
-### What AGENTS.md Contains
+The `titools sync` command generates a block like this inside your project files:
 
 ```
 [Titanium SDK Docs Index]|root: ~/.agents/skills
-|alloy-expert/references:{alloy-structure.md,anti-patterns.md,...}
+|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,...}
 ...
 ```
 
-The index points to all reference documentation, so your AI assistant can quickly retrieve accurate information without relying on potentially outdated training data.
-
-### Version Notice
-
-AGENTS.md is based on the **latest Titanium SDK documentation**. If your project uses an older version, the command will detect and warn you about potential API differences.
-
----
-
-## How to Use AGENTS.md/CLAUDE.md
-
-Once installed, the AI assistant automatically reads the documentation index in every conversation. Just ask natural questions about Titanium development:
-
-### Example Prompts
-
-**General Architecture:**
-```
-"How should I structure a new Alloy app with authentication?"
-"What's the best pattern for navigation between screens?"
-```
-
-**PurgeTSS Styling:**
-```
-"Create a product card with PurgeTSS: image, title, price, and buy button"
-"How do I use the 12-column grid system in PurgeTSS?"
-"Why does my build fail with platform-specific properties?"
-```
-
-**UI Components:**
-```
-"Create a ListView with custom templates for performance"
-"Implement pull-to-refresh on a ScrollView"
-```
-
-**Native Features:**
-```
-"Implement push notifications for iOS and Android"
-"How do I handle GPS location in the background?"
-```
+File selection per assistant:
+- Claude Code -> `CLAUDE.md`
+- Gemini CLI -> `GEMINI.md`
+- Codex CLI / others -> `AGENTS.md`
 
-**Debugging:**
-```
-"Why is my ListView scrolling poorly?"
-"I'm getting 'Alloy is not defined' in my lib file. How do I fix it?"
-```
-
----
+### How skills and the knowledge index work together
 
-## How Skills Work with AGENTS.md
+The knowledge index provides always-available context (the documentation map). Skills provide specialized, on-demand expertise (the actual knowledge).
 
-**AGENTS.md** provides always-available context (the documentation index).
-**Skills** provide specialized, on-demand expertise.
+Together they work like this:
 
-Together they work seamlessly:
-
-| Your Question                   | AGENTS.md Provides              | Skills Activate               |
+| Your Question                   | Knowledge Index Provides        | Skills Activate               |
 | ------------------------------- | ------------------------------- | ----------------------------- |
-| "Create a login screen"         | Context about project structure | `alloy-expert`, `purgetss`    |
+| "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 don't need to explicitly invoke skills** - the AI detects when to use them based on your question.
+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
+## Skills overview
 
-| Skill            | Purpose                       | Best For                                |
-| ---------------- | ----------------------------- | --------------------------------------- |
-| **alloy-expert** | Architecture + Implementation | Starting point for most tasks           |
-| **purgetss**     | Utility-first styling         | UI styling and animations               |
-| **ti-ui**        | UI/UX patterns                | Complex layouts, ListViews, platform UI |
-| **ti-howtos**    | Native feature integration    | Location, Push, Media, Platform APIs    |
-| **ti-guides**    | SDK fundamentals              | Hyperloop, distribution, configuration  |
-| **alloy-guides** | Alloy MVC reference           | Models, Views, Controllers, Widgets     |
-| **alloy-howtos** | Alloy CLI & debugging         | Project setup, CLI commands, errors     |
+| Skill        | Purpose                       | Best For                                |
+| ------------ | ----------------------------- | --------------------------------------- |
+| alloy-guides | Alloy MVC reference           | Models, Views, Controllers, Widgets     |
+| alloy-howtos | Alloy CLI & debugging         | Project setup, CLI commands, errors     |
+| purgetss     | Utility-first styling         | UI styling and animations               |
+| ti-expert    | Architecture + 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**. `alloy-expert` and `purgetss` are opinionated and reflect personal coding conventions (biased toward PurgeTSS).
+Note: `ti-guides`, `ti-howtos`, `ti-ui`, `alloy-guides`, and `alloy-howtos` are based on official Titanium SDK and Alloy documentation. `ti-expert` and `purgetss` are opinionated and reflect personal coding conventions (biased toward PurgeTSS).
 
 ---
 
-## Agents (Claude Code Only)
+## Agents (Claude Code only)
 
-In addition to skills, this repository includes **sub-agents** for Claude Code. Sub-agents run in isolated contexts and are ideal for research tasks that produce verbose output.
+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-researcher
+### ti-pro
 
-**Deep-dive research specialist that preloads all 7 titanium-\* skills.**
+Deep-dive research specialist that preloads all 7 titanium-related skills.
 
-| Aspect               | Details                                      |
-| -------------------- | -------------------------------------------- |
-| **Location**         | `~/.claude/agents/ti-researcher.md`          |
-| **Model**            | Sonnet (comprehensive analysis)              |
-| **Tools**            | Read-only (Read, Grep, Glob)                 |
-| **Preloaded Skills** | All 7 titanium-\* skills injected at startup |
+| Aspect           | Details                                           |
+| ---------------- | ------------------------------------------------- |
+| Location         | `~/.claude/agents/ti-pro.md`                      |
+| Model            | Sonnet (comprehensive analysis)                   |
+| Tools            | Read-only (Read, Grep, Glob)                      |
+| Preloaded Skills | All 7 titanium-related skills injected at startup |
 
-**When to use the agent vs skills:**
+When to use the agent vs skills:
 
-| Use Case                     | Use This                           | Why                                                  |
-| ---------------------------- | ---------------------------------- | ---------------------------------------------------- |
-| Quick inline reference       | `/alloy-expert`, `/purgetss`, etc. | Runs in main conversation, interactive               |
-| Analyzing an entire codebase | `ti-researcher` agent              | Isolates verbose output, cross-references all skills |
-| Multi-feature research       | `ti-researcher` agent              | Preloads all skills for comprehensive answers        |
-| Step-by-step implementation  | Skills directly                    | Task-oriented guidance                               |
-| Architecture review          | `ti-researcher` agent              | Read-only analysis across all documentation          |
+| 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:**
+Example prompts for the agent:
 
 ```
-"Use the ti-researcher agent to analyze this Alloy codebase's architecture"
-"Research how to implement location + push + background sync together in Titanium"
-"Compare ListView vs TableView for my use case with PurgeTSS styling"
-"Review this Titanium mobile app and identify anti-patterns"
+"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."
 ```
 
-> **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.
+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.
 
-**Key difference:**
-- **Skills** = Interactive help during development (inline, conversational)
-- **Agents** = Isolated research tasks (returns summary, keeps verbose output separate)
+Key difference:
+- Skills = interactive help during development (inline, conversational)
+- Agents = isolated research tasks (returns summary, keeps verbose output separate)
 
 ---
 
-## How Skills Work
+## How skills work
 
-Skills are **automatically activated** based on your questions. Just ask naturally:
+Skills are automatically activated based on your questions. Just ask naturally:
 
 ```
-"Create a login screen with email validation and animations"
+"Can you create a login screen with email validation and animations?"
 ```
 
 The AI will automatically use:
-- `alloy-expert` → Architecture and controller structure
-- `purgetss` → Styling classes and animations (if PurgeTSS detected)
-- `ti-howtos` → Secure token storage
+- `ti-expert` -> Architecture and controller structure
+- `purgetss` -> Styling classes and animations (if PurgeTSS detected)
+- `ti-howtos` -> Secure token storage
 
-**You don't need to call skills explicitly** - the AI reads skill descriptions and loads the appropriate knowledge when needed.
+You do not need to call skills explicitly. The AI reads skill descriptions and loads the appropriate knowledge when needed.
 
-### Project Detection
+### Project detection
 
-All skills now include **automatic project detection** to ensure compatibility:
+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`  |
-| **alloy-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 & Classic)                 |
-| **ti-guides**    | Titanium projects     | Checks for `tiapp.xml` (both Alloy & Classic)                 |
-| **ti-howtos**    | Titanium projects     | Checks for `tiapp.xml` (both Alloy & Classic)                 |
+| 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 & Classic)                 |
+| ti-guides    | Titanium projects     | Checks for `tiapp.xml` (both Alloy & Classic)                 |
+| ti-howtos    | Titanium projects     | Checks for `tiapp.xml` (both Alloy & 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 won't receive inappropriate Alloy advice
+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
+### Skill hierarchy
 
-`alloy-expert` acts as the **orchestrator**, delegating to specialized skills when needed:
+`ti-expert` acts as the orchestrator, delegating to specialized skills when needed:
 
 ```
                     ┌─────────────────┐
-                    │  alloy-expert   │
+                    │  ti-expert      │
                     │  (Start Here)   │
                     └────────┬────────┘
                              │
@@ -352,13 +243,13 @@ All skills now include **automatic project detection** to ensure compatibility:
 
 ---
 
-## Skill Details
+## Skill details
 
-### alloy-expert
+### ti-expert
 
-**The primary skill for Titanium Alloy development.** Start here for most tasks.
+The primary skill for Titanium Alloy development. Start here for most tasks.
 
-**When it activates:**
+When it activates:
 - Designing project structure
 - Implementing controllers, views, services
 - Choosing data strategies (Models vs Collections)
@@ -368,28 +259,28 @@ All skills now include **automatic project detection** to ensure compatibility:
 - Security patterns
 - Migrating legacy apps
 
-**Example prompts:**
+Example prompts:
 ```
 "How should I structure a new Titanium Alloy app with authentication?"
-"Create a user service that fetches data from an API"
+"Create a user service that fetches data from an API."
 "What's the best pattern for navigation between screens?"
-"How do I prevent memory leaks in my controllers?"
-"Migrate this classic Titanium code to modern Alloy patterns"
+"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?"
 ```
 
-**Key features:**
-- PurgeTSS rules built-in (correct classes)
+Key features:
 - Quick decision matrix for common questions
-- 13 reference guides for deep dives
+- 18 reference guides for deep dives
 - Delegates to specialized skills when needed
 
 ---
 
 ### purgetss
 
-**Utility-first styling toolkit for Titanium/Alloy.**
+Utility-first styling toolkit for Titanium/Alloy.
 
-**When it activates:**
+When it activates:
 - Setting up PurgeTSS in a project
 - Complex layouts (Grid system)
 - Declarative animations (`<Animation>` component)
@@ -398,30 +289,30 @@ All skills now include **automatic project detection** to ensure compatibility:
 - Platform-specific styling
 - config.cjs configuration
 
-**Example prompts:**
+Example prompts:
 ```
-"Set up PurgeTSS in my existing Alloy project"
-"Create a responsive 12-column grid layout"
-"Add a fade-in animation when my view appears"
-"Configure custom colors in config.cjs"
+"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"
+"Style this button differently on iOS vs Android."
 ```
 
-**Critical 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]`
+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]`
 
 ---
 
 ### ti-ui
 
-**UI/UX expert for layouts and platform components.**
+UI/UX expert for layouts and platform components.
 
-**When it activates:**
+When it activates:
 - Layout systems (composite, vertical, horizontal)
 - ListView/TableView optimization
 - Event handling and bubbling
@@ -432,18 +323,18 @@ All skills now include **automatic project detection** to ensure compatibility:
 - Android Action Bar / iOS Navigation patterns
 - Accessibility (VoiceOver, TalkBack)
 
-**Example prompts:**
+Example prompts:
 ```
-"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"
-"Make my app accessible for VoiceOver users"
-"Configure the Android Action Bar with custom menu items"
+"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?"
 ```
 
-**Key rules:**
-- NO `Ti.UI.SIZE` in ListView items (causes jerky scrolling)
+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
@@ -452,9 +343,9 @@ All skills now include **automatic project detection** to ensure compatibility:
 
 ### ti-howtos
 
-**Native feature integration expert.**
+Native feature integration expert.
 
-**When it activates:**
+When it activates:
 - Location services and Maps
 - Push notifications (APNs/FCM)
 - Local notifications
@@ -468,18 +359,19 @@ All skills now include **automatic project detection** to ensure compatibility:
 - iOS Background Services, iCloud, Keychain
 - Core Motion, WatchKit
 
-**Example prompts:**
+Example prompts:
 ```
-"Implement battery-efficient GPS tracking"
-"Set up push notifications for iOS and Android"
-"Capture and resize photos from the camera"
-"Download files with progress indicator"
-"Store sensitive data in iOS Keychain"
-"Create an Android background service"
-"Integrate with Apple Watch using WatchKit"
+"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."
 ```
 
-**Key rules:**
+Key rules:
 - Always handle both `onload` and `onerror` for HTTPClient
 - Always close database handles and result sets
 - Use `imageAsResized` to avoid memory exhaustion
@@ -489,9 +381,9 @@ All skills now include **automatic project detection** to ensure compatibility:
 
 ### ti-guides
 
-**SDK fundamentals and advanced configuration.**
+SDK fundamentals and advanced configuration.
 
-**When it activates:**
+When it activates:
 - Hyperloop native access
 - Native module development
 - App distribution (Play Store, App Store)
@@ -501,23 +393,23 @@ All skills now include **automatic project detection** to ensure compatibility:
 - CommonJS module patterns
 - Coding best practices
 
-**Example prompts:**
+Example prompts:
 ```
-"Access native iOS APIs using Hyperloop"
-"Configure tiapp.xml for production build"
-"Prepare my app for Google Play submission"
-"Create a native Android module"
-"Optimize bridge crossings for better performance"
-"What are the reserved words I should avoid?"
+"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."
 ```
 
 ---
 
 ### alloy-guides
 
-**Complete Alloy MVC framework reference.**
+Complete Alloy MVC framework reference.
 
-**When it activates:**
+When it activates:
 - MVC architecture concepts
 - Backbone.js models and collections
 - Data binding patterns
@@ -527,13 +419,13 @@ All skills now include **automatic project detection** to ensure compatibility:
 - Sync adapters (sql, properties)
 - Migrations
 
-**Example prompts:**
+Example prompts:
 ```
-"Explain how Alloy data binding works"
-"Create a model with SQLite adapter"
-"Bind a collection to a TableView"
-"Build a reusable widget"
-"What's the TSS syntax for platform-specific styles?"
+"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?"
 ```
 
@@ -541,9 +433,9 @@ All skills now include **automatic project detection** to ensure compatibility:
 
 ### alloy-howtos
 
-**Alloy CLI, configuration, and debugging.**
+Alloy CLI, configuration, and debugging.
 
-**When it activates:**
+When it activates:
 - Alloy CLI commands (new, generate, compile)
 - Configuration files (alloy.jmk, config.json)
 - Debugging compilation errors
@@ -552,116 +444,254 @@ All skills now include **automatic project detection** to ensure compatibility:
 - Best practices and naming conventions
 - Backbone.Events patterns
 
-**Example prompts:**
+Example prompts:
 ```
-"Generate a new model with CLI"
-"Configure alloy.jmk build hooks"
-"Fix 'No app.js found' error"
-"Create conditional views based on user state"
-"Build a custom XML tag without widgets"
-"Set up Backbone.Events for global communication"
+"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:**
+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
+## Usage examples and best practices
 
-### Starting a New Project
+### Example prompts
+
+Starting a new project:
 ```
 "I'm starting a new Titanium Alloy app for a food delivery service.
-Help me set up the project structure."
+Can you help me set up the project structure?"
 ```
 
-### UI Development
+UI development:
 ```
-"Create a product listing screen with:
+"Can you create a product listing screen with:
 - Pull-to-refresh
 - Infinite scroll pagination
 - Image caching
 - Swipe-to-delete"
 ```
 
-### API Integration
+API integration:
 ```
-"Build a complete authentication flow:
+"Can you build a complete authentication flow with:
 - Login/Register screens
 - JWT token management
 - Secure storage
 - Auto-refresh tokens"
 ```
 
-### Performance Optimization
+Performance optimization:
 ```
-"My app is slow. The ListView scrolls poorly and
-the app uses too much memory. Help me optimize it."
+"My app is slow - the ListView scrolls poorly and memory usage is high. How do I optimize it?"
 ```
 
-### Migration
+Migration:
 ```
-"I have a legacy Titanium classic app from 2015.
-Help me migrate it to modern Alloy with PurgeTSS."
+"I have a legacy Titanium classic app from 2015. Can you help me migrate it to modern Alloy?"
 ```
 
-### Platform-Specific Features
+Platform-specific features:
 ```
-"Implement Apple Sign-In for iOS and Google Sign-In for Android"
+"How do I implement Apple Sign-In for iOS and Google Sign-In for Android?"
 ```
 
-### Debugging
+Debugging:
 ```
-"I'm getting 'Alloy is not defined' in my lib file. How do I fix it?"
+"How do I fix "Alloy is not defined" in my lib file?"
 ```
 
-### Codebase Analysis (Using Agent)
+Codebase analysis (using agent):
 ```
-"Use the ti-researcher agent to analyze this project:
-- Review the overall architecture
-- Identify memory leak patterns
-- Check for PurgeTSS anti-patterns
-- Suggest improvements"
+"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"
 ```
 
+### Tips for better results
+
+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.
+
 ---
 
-## Best Practices
+## CLI reference
+
+### titools install
+
+Installs Titanium skills, agents, and platform symlinks.
+
+```bash
+titools install [options]
+```
+
+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
+
+### titools sync
 
-### 1. Be Specific
-Instead of: "Make a list"
-Try: "Create a ListView with user avatars, names, and swipe actions"
+Generates a compressed knowledge index inside your project's instruction files (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`).
 
-### 2. Provide Context
-Instead of: "Fix the error"
-Try: "I'm getting this error when compiling: [error message]. Here's my code: [code]"
+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.
 
-### 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.
+```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
+
+Updates installed skills and agents to the latest version.
+
+```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:
+- Checks GitHub for the latest version
+- Downloads and installs updated skills and agents
+- Updates platform symlinks for all detected platforms
+- Cleans up legacy artifacts (`alloy-expert` skill, `ti-researcher` agent)
+- Auto-syncs knowledge index files if they exist in the current project
 
-### 4. Mention Constraints
-"Build a settings screen. Must work offline and sync when connected."
+Note: This updates knowledge packages and agents, not the CLI binary itself. To update the CLI, use `npm update -g @maccesar/titools`.
 
-### 5. Reference Existing Code
-"Here's my current controller. How can I improve memory management?"
+### titools remove
+
+Removes skills, agents, symlinks, and knowledge index blocks.
+
+```bash
+titools remove [options]
+```
 
-> **More examples:** See [Example Prompts](docs/EXAMPLE-PROMPTS.md) for detailed prompts that test each skill's capabilities.
+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
+
+### Verify installation
+
+Check titools version:
+```bash
+titools --version
+```
+
+Check central location (global install):
+```bash
+ls ~/.agents/skills/
+# Should show: ti-expert, purgetss, ti-ui, ti-howtos, ti-guides, alloy-guides, alloy-howtos
+```
+
+Claude Code (skills):
+```bash
+ls -la ~/.claude/skills/
+# Should show symlinks pointing to ~/.agents/skills/
+```
+
+Claude Code (agents):
+```bash
+ls -la ~/.claude/agents/
+# Should show: ti-pro.md
+```
+
+Gemini CLI:
+```bash
+gemini skills list
+```
+
+Codex CLI:
+```bash
+# Type /skills in Codex or use $ to mention a skill
+```
 
 ---
 
-## Skill Contents Summary
+## Skill contents summary
 
 | Skill        | SKILL.md                      | References                                            |
 | ------------ | ----------------------------- | ----------------------------------------------------- |
-| alloy-expert | Architecture + Implementation | 14 files (patterns, testing, security, assets, etc.)  |
-| purgetss     | Setup + Critical Rules        | 17 files (grid, animations, icons, class-index, etc.) |
-| ti-ui        | UI Rules + Platform Diffs     | 13 files (layouts, lists, gestures, etc.)             |
-| ti-howtos    | Integration Workflow          | 12 files (location, media, maps, automation, etc.)    |
-| ti-guides    | Core Workflow                 | 10 files (hyperloop, distribution, etc.)              |
+| ti-expert    | Architecture + Implementation | 19 refs + 1 asset (patterns, testing, security, etc.) |
+| purgetss     | Setup + Critical Rules        | 21 files (grid, animations, icons, class-index, etc.) |
+| ti-ui        | UI Rules + Platform Diffs     | 14 files (layouts, lists, gestures, etc.)             |
+| ti-howtos    | Integration Workflow          | 18 files (location, media, maps, automation, etc.)    |
+| ti-guides    | Core Workflow                 | 14 files (hyperloop, distribution, etc.)              |
 | alloy-guides | MVC Quick Start               | 10 files (models, views, widgets, etc.)               |
 | alloy-howtos | Best Practices                | 6 files (CLI, config, debugging, etc.)                |
 
@@ -669,7 +699,7 @@ Then follow up with implementation details.
 
 ## Troubleshooting
 
-### Skill Not Activating?
+### Skill not activating?
 
 If the AI doesn't seem to use Titanium knowledge:
 1. Mention "Titanium" or "Alloy" explicitly in your prompt
@@ -677,39 +707,35 @@ If the AI doesn't seem to use Titanium knowledge:
 3. Reference the technology stack
 4. Try explicit invocation: "Use the purgetss skill for styling questions"
 
-### Getting Wrong Suggestions?
+### Getting wrong suggestions?
 
-If the AI suggests patterns you don't use (e.g., PurgeTSS when you're not using it):
+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?
+### 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?
+### 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?
+### Need more detail?
 
 Ask the AI to:
 ```
 "Show me the reference documentation for ListView performance"
-"What does the alloy-expert skill say about memory cleanup?"
+"What does the ti-expert skill say about memory cleanup?"
 ```
 
----
-
-## Troubleshooting
-
 ### titools command not found?
 
 If the command is not found:
@@ -721,16 +747,16 @@ npm list -g @maccesar/titools
 npm install -g @maccesar/titools
 ```
 
-### AGENTS.md not working?
+### Knowledge index not working?
 
-If your AI doesn't use the AGENTS.md information:
-1. Verify AGENTS.md/CLAUDE.md exists in your project root
-2. Check that your AI supports these files (Claude Code does)
+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?
 
-AGENTS.md is based on the latest documentation. Be cautious when using newer APIs in older projects.
+The knowledge index is based on the latest documentation. Be cautious when using newer APIs in older projects.
 
 ---
 
@@ -740,18 +766,11 @@ AGENTS.md is based on the latest documentation. Be cautious when using newer API
 # Remove the CLI
 npm uninstall -g @maccesar/titools
 
-# Remove skills and agents
-titools uninstall
-```
-
-**Note:** AGENTS.md/CLAUDE.md/GEMINI.md files in your projects are NOT removed. To remove them manually:
-
-```bash
-rm -f /path/to/your/project/AGENTS.md
-rm -f /path/to/your/project/CLAUDE.md
-rm -f /path/to/your/project/GEMINI.md
+# 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.
 
 ---
 
@@ -770,9 +789,9 @@ rm -f /path/to/your/project/GEMINI.md
 
 ---
 
-## Legacy Installation (Not Recommended)
+## Legacy installation (not recommended)
 
-The bash installer is maintained for backward compatibility but **NPM installation is strongly 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
@@ -784,7 +803,7 @@ 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).
+Created by César Estrada ([@macCesar](https://github.com/macCesar)), creator of [PurgeTSS](https://github.com/macCesar/purgeTSS).
 
 ## License