@maccesar/titools 2.10.0 → 3.1.0

package/AGENTS-VERCEL-RESEARCH.md

@@ -49,21 +49,32 @@ The index maps skills to their reference docs:
 ```
 
 How the assistant should use it:
-- Need Backbone.Models patterns? Read `~/.agents/skills/alloy-guides/references/MODELS.md`
-- Need the PurgeTSS grid system? Read `~/.agents/skills/purgetss/references/grid-layout.md`
 - Need ListView performance tips? Read `~/.agents/skills/ti-ui/references/listviews-and-performance.md`
+- Need the PurgeTSS grid system? Read `~/.agents/skills/purgetss/references/grid-layout.md`
+- Need controller cleanup patterns? Read `~/.agents/skills/ti-expert/references/controller-patterns.md`
+- Need Backbone.Models patterns (with `tidev/skills` installed)? Read `~/.agents/skills/alloy-guides/references/MODELS.md`
 
 ### Skill 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, animations, grid layouts          |
-| **ti-expert**    | Architecture + implementation | Starting point for most Alloy tasks           |
-| **ti-guides**    | SDK fundamentals              | Hyperloop, distribution, tiapp.xml, CLI       |
-| **ti-howtos**    | Native feature integration    | Location, push, media, platform-specific APIs |
-| **ti-ui**        | UI/UX patterns                | Layouts, ListViews, gestures, platform UI     |
+TiTools ships 3 opinionated skills:
+
+| Skill         | Purpose                       | Best for                                      |
+| ------------- | ----------------------------- | --------------------------------------------- |
+| **ti-expert** | Architecture + implementation | Starting point for most Alloy tasks           |
+| **purgetss**  | Utility-first styling         | UI styling, animations, grid layouts          |
+| **ti-ui**     | UI/UX patterns                | Layouts, ListViews, gestures, platform UI     |
+
+The doc-based reference skills live in [`tidev/skills`](https://github.com/tidev/skills) (community-maintained):
+
+| Skill            | Purpose                       | Best for                                       |
+| ---------------- | ----------------------------- | ---------------------------------------------- |
+| **ti-api**       | Complete API reference        | Properties, methods, events, constants         |
+| **ti-guides**    | SDK fundamentals              | Hyperloop, distribution, tiapp.xml, CLI        |
+| **ti-howtos**    | Native feature integration    | Location, push, media, platform-specific APIs  |
+| **alloy-guides** | Alloy MVC reference           | Models, views, controllers, widgets            |
+| **alloy-howtos** | Alloy CLI and debugging       | Project setup, CLI commands, errors            |
+
+Install both for the full coverage matrix originally shipped by TiTools v2.x.
 
 ### For complex workflows
 
@@ -73,7 +84,7 @@ The **ti-pro** agent (installed in `~/.claude/agents/`) handles:
 - Cross-referencing framework patterns
 - Platform-specific differences
 
-It preloads all 7 titanium-* skills for broader coverage.
+It preloads the 3 TiTools skills and recommends consulting `tidev/skills` when the question touches API surface, native-feature how-tos, MVC reference, or SDK fundamentals.
 
 ## How to use
 

package/README.md

@@ -8,12 +8,14 @@
 
 </div>
 
-TiTools is a Titanium SDK toolkit for AI coding assistants. It provides 8 skills, a research agent, and 100+ reference files for Titanium SDK, Alloy MVC, and PurgeTSS.
+TiTools is a Titanium SDK toolkit for AI coding assistants. It ships 3 opinionated skills (`ti-expert`, `purgetss`, `ti-ui`), a research agent, and reference files covering Titanium architecture, PurgeTSS styling, and UI/UX patterns.
 
 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.
 
+> **v3.0.0 — doc-based skills moved to `tidev/skills`.** Five documentation-only skills (`ti-api`, `ti-guides`, `ti-howtos`, `alloy-guides`, `alloy-howtos`) are now maintained in the official [`tidev/skills`](https://github.com/tidev/skills) repository alongside the rest of the TiDev community tooling. TiTools now focuses on the three opinionated skills above. See [Doc-based skills moved to tidev/skills](#doc-based-skills-moved-to-tidevskills) below for upgrade notes.
+
 Vercel's AGENTS.md evaluation reports a 100% pass rate for the knowledge index approach, compared to 53-79% using skills alone.
 
 ---
@@ -38,7 +40,7 @@ The fastest way to get started with Claude Code. One command to add the marketpl
 ```
 
 What you get:
-- All 8 Titanium skills
+- All 3 TiTools skills (`ti-expert`, `purgetss`, `ti-ui`)
 - ti-pro research agent
 - Session hook that auto-detects Titanium projects (`tiapp.xml`, Alloy, PurgeTSS)
 - Slash commands: `/ti-check`, `/ti-new-screen`, `/ti-audit`
@@ -72,9 +74,9 @@ claude   # or gemini, or codex
 ```
 
 What gets installed:
-- All 8 titanium-related skills to `~/.agents/skills/`
+- The 3 TiTools skills to `~/.agents/skills/`
 - ti-pro agent for Claude Code
-- Platform symlinks (Claude Code, Gemini CLI, Codex CLI)
+- Platform symlinks for Claude Code and Gemini CLI (Codex CLI auto-discovers from `~/.agents/skills/` — no symlink needed)
 - Knowledge index in your project's `AGENTS.md`/`CLAUDE.md`/`GEMINI.md`
 - Claude Code SessionStart hook for auto-updates
 
@@ -99,13 +101,45 @@ Use **Option A** if you only use Claude Code. Use **Option B** if you use multip
 
 ---
 
+## Doc-based skills moved to tidev/skills
+
+Starting with **v3.0.0**, five documentation-only skills migrated to the official [`tidev/skills`](https://github.com/tidev/skills) repository:
+
+- `ti-api` — Complete Titanium API reference
+- `ti-guides` — SDK fundamentals (Hyperloop, distribution, tiapp.xml)
+- `ti-howtos` — Native feature integration (location, push, media, platform-specific APIs)
+- `alloy-guides` — Alloy MVC framework reference
+- `alloy-howtos` — Alloy CLI, configuration, debugging
+
+**Why the move?** These skills are pure documentation mirrors of official Titanium and Alloy docs, so they belong in the community-maintained TiDev repository alongside the SDK source itself. Hansemann ([@hansemannn](https://github.com/hansemannn)) — TiDev maintainer — accepted the first batch in [tidev/skills#1](https://github.com/tidev/skills/pull/1) and `ti-howtos` followed in [tidev/skills#2](https://github.com/tidev/skills/pull/2).
+
+**What stays in TiTools:** the three *opinionated* skills that reflect personal Titanium conventions and toolchain choices (PurgeTSS-first styling, specific architecture patterns).
+
+### Upgrading from v2.x
+
+If you have v2.x installed, the five migrated skills will be **auto-removed** the next time you run `titools update` (they're listed in `LEGACY_SKILLS`). To get them back, install from `tidev/skills` directly:
+
+```bash
+git clone https://github.com/tidev/skills.git ~/Developer/git-clones/tidev-skills
+# Then symlink the five skills into ~/.agents/skills/ or your AI assistant's skills dir
+ln -s ~/Developer/git-clones/tidev-skills/skills/ti-api        ~/.agents/skills/ti-api
+ln -s ~/Developer/git-clones/tidev-skills/skills/ti-guides     ~/.agents/skills/ti-guides
+ln -s ~/Developer/git-clones/tidev-skills/skills/ti-howtos     ~/.agents/skills/ti-howtos
+ln -s ~/Developer/git-clones/tidev-skills/skills/alloy-guides  ~/.agents/skills/alloy-guides
+ln -s ~/Developer/git-clones/tidev-skills/skills/alloy-howtos  ~/.agents/skills/alloy-howtos
+```
+
+Refer to the [`tidev/skills` README](https://github.com/tidev/skills#readme) for the canonical install instructions, which may evolve independently of TiTools.
+
+---
+
 ## 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/`  |
+| [Codex CLI](https://developers.openai.com/codex/cli/)     | Fully Compatible | `~/.agents/skills/` (auto-discovered) |
 
 All three platforms use the Agent Skills open standard: a `SKILL.md` file with YAML frontmatter.
 
@@ -160,7 +194,7 @@ Together they work like this:
 | ------------------------------- | ------------------------------- | ----------------------------- |
 | "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 |
+| "Implement push notifications"  | API reference paths             | `ti-howtos` (via tidev/skills) |
 
 You do not need to explicitly invoke skills. The AI detects when to use them based on your question.
 
@@ -172,18 +206,16 @@ The knowledge index is based on the latest Titanium SDK documentation. If your p
 
 ## Skills overview
 
-| Skill        | Purpose                         | Best For                                                                        |
-| ------------ | ------------------------------- | ------------------------------------------------------------------------------- |
-| alloy-guides | Alloy MVC reference             | Models, Views, Controllers, Widgets                                             |
-| alloy-howtos | Alloy CLI and debugging         | Project setup, CLI commands, errors                                             |
-| purgetss     | Utility-first styling           | UI styling and animations                                                       |
-| ti-api       | Complete API reference          | Properties, methods, events, constants                                          |
-| 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                                         |
+| Skill     | Purpose                         | Best For                                |
+| --------- | ------------------------------- | --------------------------------------- |
+| ti-expert | Architecture and implementation | Starting point for most tasks           |
+| purgetss  | Utility-first styling           | UI styling and animations               |
+| 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).
+Notes:
+- `purgetss` reference files are audited against the official PurgeTSS documentation, but the workflow conventions are opinionated.
+- `ti-expert` and `ti-ui` reflect personal Titanium conventions (biased toward PurgeTSS, Alloy-first).
+- For purely doc-based references (API surface, native-feature how-tos, Alloy MVC, SDK guides, Alloy CLI), install [`tidev/skills`](https://github.com/tidev/skills) — it pairs cleanly with TiTools.
 
 ---
 
@@ -193,14 +225,14 @@ In addition to skills, this repository includes sub-agents for Claude Code. Sub-
 
 ### ti-pro
 
-Deep-dive research specialist that preloads all 8 titanium-related documentation skills.
+Deep-dive research specialist that preloads the 3 TiTools 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 |
+| Aspect           | Details                                          |
+| ---------------- | ------------------------------------------------ |
+| Location         | `~/.claude/agents/ti-pro.md`                     |
+| Model            | Sonnet (comprehensive analysis)                  |
+| Tools            | Read-only (Read, Grep, Glob)                     |
+| Preloaded Skills | `ti-expert`, `purgetss`, `ti-ui`                 |
 
 When to use the agent vs skills:
 
@@ -241,8 +273,8 @@ When installed as a plugin, TiTools provides slash commands for common tasks:
 
 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
+- `/ti-new-screen` uses `ti-expert` + `purgetss` to create properly structured files
+- `/ti-audit` uses `ti-expert` + `ti-ui` + `purgetss` for comprehensive review
 
 ---
 
@@ -269,7 +301,7 @@ Skills are automatically activated based on your questions. Just ask naturally:
 The AI will automatically use:
 - `ti-expert` -> Architecture and controller structure
 - `purgetss` -> Styling classes and animations (if PurgeTSS detected)
-- `ti-howtos` -> Secure token storage
+- `ti-howtos` from [`tidev/skills`](https://github.com/tidev/skills) (if installed) -> Secure token storage
 
 You do not need to call skills explicitly. The AI reads skill descriptions and loads the appropriate knowledge when needed.
 
@@ -277,15 +309,11 @@ You do not need to call skills explicitly. The AI reads skill descriptions and l
 
 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)               |
+| 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 |
+| ti-ui     | Titanium projects     | Checks for `tiapp.xml` (both Alloy and Classic)               |
 
 Why this matters:
 - PurgeTSS suggestions are only provided if PurgeTSS is installed
@@ -302,25 +330,17 @@ Why this matters:
                     │  (Start Here)   │
                     └────────┬────────┘
                              │
-        ┌────────────────────┼────────────────────┐
-        │                    │                    │
-        ▼                    ▼                    ▼
-┌───────────────┐   ┌───────────────┐   ┌───────────────┐
-│   purgetss    │   │    ti-ui      │   │   ti-howtos   │
-│   (Styling)   │   │   (UI/UX)     │   │   (Native)    │
-└───────────────┘   └───────────────┘   └───────────────┘
-        │                    │                    │
-        └────────────────────┼────────────────────┘
-                             │
-        ┌────────────────────┼────────────────────┐
-        │                    │                    │
-        ▼                    ▼                    ▼
-┌───────────────┐   ┌───────────────┐   ┌───────────────┐
-│  ti-guides    │   │ alloy-guides  │   │ alloy-howtos  │
-│    (SDK)      │   │    (MVC)      │   │    (CLI)      │
-└───────────────┘   └───────────────┘   └───────────────┘
+                ┌────────────┴────────────┐
+                │                         │
+                ▼                         ▼
+        ┌───────────────┐         ┌───────────────┐
+        │   purgetss    │         │    ti-ui      │
+        │   (Styling)   │         │   (UI/UX)     │
+        └───────────────┘         └───────────────┘
 ```
 
+For pure API / native-feature how-to / MVC / SDK reference docs, install [`tidev/skills`](https://github.com/tidev/skills) alongside TiTools — its `ti-api`, `ti-guides`, `ti-howtos`, `alloy-guides`, and `alloy-howtos` skills layer below this hierarchy without conflict.
+
 ---
 
 ## Skill details
@@ -421,123 +441,7 @@ Key rules:
 
 ---
 
-### 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."
-```
-
-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."
-```
-
----
-
-### alloy-guides
-
-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`
+> **Looking for `ti-api`, `ti-guides`, `ti-howtos`, `alloy-guides`, or `alloy-howtos`?** Those five documentation-only skills now live in [`tidev/skills`](https://github.com/tidev/skills). See [Doc-based skills moved to tidev/skills](#doc-based-skills-moved-to-tidevskills) for install instructions.
 
 ---
 
@@ -636,7 +540,7 @@ Behavior depends on where you run it:
 | With `--local` flag        | Installs skills locally to `./.agents/skills/` in the current project |
 
 What it does:
-- Installs all 8 titanium-related skills (global or local depending on context)
+- Installs the 3 TiTools 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
@@ -823,22 +727,17 @@ Then only add `large-title-enabled` per-window as needed:
 </Window>
 ```
 
-This pattern is documented across four skills: `ti-ui`, `ti-expert`, `ti-api`, and `purgetss`.
+This pattern is documented across three TiTools skills: `ti-ui`, `ti-expert`, and `purgetss`. The `ti-api` skill in [`tidev/skills`](https://github.com/tidev/skills) also documents the underlying Window properties.
 
 ---
 
 ## 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.)             |
+| Skill     | SKILL.md                      | References                                            |
+| --------- | ----------------------------- | ----------------------------------------------------- |
+| ti-expert | Architecture + Implementation | 21 files (patterns, testing, security, etc.)          |
+| purgetss  | Setup + Critical Rules        | 29 files (grid, animations, icons, class-index, etc.) |
+| ti-ui     | UI Rules + Platform Diffs     | 14 files (layouts, lists, gestures, etc.)             |
 
 ---
 

package/agents/ti-pro.md

@@ -1,13 +1,9 @@
 ---
 name: ti-pro
-description: Titanium SDK and Alloy research specialist. Loads the 7 Titanium skills and uses them together to answer research-style questions. Use for codebase analysis, architecture reviews, Titanium SDK implementation research, cross-feature questions, and platform-specific differences. Returns concrete findings with file and line references.
+description: Titanium SDK and Alloy research specialist. Loads the 3 TiTools skills and uses them together to answer research-style questions. Use for codebase analysis, architecture reviews, Titanium SDK implementation research, cross-feature questions, and platform-specific differences. Returns concrete findings with file and line references.
 skills:
-  - alloy-guides
-  - alloy-howtos
-  - purgetss
   - ti-expert
-  - ti-guides
-  - ti-howtos
+  - purgetss
   - ti-ui
 tools: Read, Grep, Glob, Bash
 model: sonnet
@@ -19,16 +15,14 @@ You are a research specialist for Titanium SDK and Alloy mobile development. Wit
 
 ## What You Do
 
-When invoked, you research complex topics by consulting all 7 Titanium skills:
+When invoked, you research complex topics by consulting the 3 TiTools skills:
 
 - `ti-expert` - Architecture, patterns, conventions
-- `alloy-guides` - Alloy MVC complete reference
-- `alloy-howtos` - CLI, config, debugging
 - `purgetss` - Utility-first styling classes (optional add-on; use when the project already has it or the user asks about it)
-- `ti-guides` - SDK official guides, Hyperloop, distribution
-- `ti-howtos` - Native features, platform-specific APIs
 - `ti-ui` - UI/UX patterns, layouts, gestures
 
+If the user has [`tidev/skills`](https://github.com/tidev/skills) installed alongside TiTools, also consult its doc-based skills (`ti-api`, `ti-guides`, `ti-howtos`, `alloy-guides`, `alloy-howtos`) when API surface, native-feature how-tos, MVC reference, or SDK fundamentals are part of the question.
+
 ## Research Process
 
 1. **Understand the query** - Identify what needs research.
@@ -53,7 +47,7 @@ When invoked, you research complex topics by consulting all 7 Titanium skills:
 | -------------------------------------------- | -------------------------------------- |
 | `/ti-expert` for architecture guidance       | Inline consultation during development |
 | `/purgetss` to verify a class                | Quick inline reference                 |
-| `/ti-howtos` for step-by-step implementation | Task-oriented guidance                 |
+| `/ti-ui` for UI/UX patterns and layouts      | Task-oriented guidance                 |
 | Main conversation for iterative work         | Sub-agents run in isolation            |
 
 ## Response Format
@@ -73,10 +67,10 @@ Your app uses `Ti.App.fireEvent` which causes memory leaks.
 
 ## Key Points
 - **ti-expert/references/anti-patterns.md:45** - Ti.App.fireEvent leaks memory
-- **alloy-howtos/references/best_practices.md:23** - Use Backbone.Events instead
+- **ti-expert/references/controller-patterns.md:23** - Use Backbone.Events instead
 
 ## Solution
-[Code example from alloy-howtos]
+[Code example from ti-expert]
 ```
 
 ## Tool Usage

package/lib/cleanup.js

@@ -9,6 +9,7 @@ import {
   LEGACY_AGENTS,
   getAgentsSkillsDir,
   getClaudeAgentsDir,
+  getCodexSkillsDir,
 } from './config.js';
 import { detectPlatforms } from './platform.js';
 import { existsSync, lstatSync, rmSync } from 'fs';
@@ -53,6 +54,14 @@ export function removeLegacySkillSymlinks(platformSkillsDir) {
   return removeSkillSymlinks(platformSkillsDir, { legacyOnly: true });
 }
 
+// Codex reads skills from the canonical ~/.agents/skills/, so any TiTools-managed
+// symlinks at ~/.codex/skills/ from earlier versions are redundant and should be
+// cleaned up. Targets both active and legacy skill names.
+export function removeCodexRedundantSymlinks(baseDir) {
+  const codexSkillsDir = getCodexSkillsDir(baseDir);
+  return removeSkillSymlinks(codexSkillsDir);
+}
+
 export function removeSkills(baseDir, options = {}) {
   const skillsDir = getAgentsSkillsDir(baseDir);
   const skillList = getSkillList(options);
@@ -74,6 +83,8 @@ export function cleanupLegacyArtifacts(baseDir) {
     removeLegacySkillSymlinks(platform.skillsDir);
   }
 
+  removeCodexRedundantSymlinks(baseDir);
+
   if (baseDir) {
     removeSkills(undefined, { legacyOnly: true });
     removeAgents(undefined, { legacyOnly: true });
@@ -81,6 +92,7 @@ export function cleanupLegacyArtifacts(baseDir) {
     for (const platform of globalPlatforms) {
       removeLegacySkillSymlinks(platform.skillsDir);
     }
+    removeCodexRedundantSymlinks(undefined);
   }
 }
 
@@ -89,6 +101,7 @@ export default {
   getAgentList,
   removeSkillSymlinks,
   removeLegacySkillSymlinks,
+  removeCodexRedundantSymlinks,
   removeSkills,
   removeAgents,
   cleanupLegacyArtifacts,

package/lib/commands/skills.js

@@ -120,7 +120,8 @@ export async function skillsCommand(options) {
 
   if (detectedPlatforms.length === 0 && !options.path && !isLocal) {
     console.log(chalk.yellow('No AI coding assistants detected globally.'));
-    console.log('Install one of: Claude Code, Gemini CLI, or Codex CLI');
+    console.log('Install one of: Claude Code or Gemini CLI.');
+    console.log('(Codex CLI is supported via the canonical ~/.agents/skills/ — no platform-specific symlink needed.)');
     console.log('Or use: titools install --local');
     process.exit(1);
   }

package/lib/commands/update.js

@@ -30,6 +30,7 @@ import { formatList, isTitaniumProject } from '../utils.js';
 import { getAgentsSkillsDir } from '../config.js';
 import { existsSync } from 'fs';
 import { join, resolve } from 'path';
+import os from 'os';
 
 /**
  * Check if a platform has any skill symlinks installed
@@ -105,7 +106,9 @@ export async function updateCommand(options) {
   if (!options.local) {
     const projectDir = process.cwd();
     const isProject = isTitaniumProject(projectDir);
-    const hasLocalSkills = isProject && hasSkillsAt(projectDir);
+    // When cwd === home, "local" and "global" point to the same .agents/skills dir
+    const isHomeDir = projectDir === os.homedir();
+    const hasLocalSkills = !isHomeDir && isProject && hasSkillsAt(projectDir);
     const hasGlobalSkills = hasSkillsAt(undefined);
 
     // Only show prompt if BOTH local and global skills exist

package/lib/config.js

@@ -31,18 +31,19 @@ export const REPO_API_URL = 'https://api.github.com/repos/macCesar/titools';
 // Skills to install
 export const SKILLS = [
   'ti-expert',
-  'ti-api',
   'purgetss',
   'ti-ui',
-  'ti-howtos',
-  'ti-guides',
-  'alloy-guides',
-  'alloy-howtos',
 ];
 // Legacy skills to remove during updates/uninstall
+// ti-api, ti-guides, ti-howtos, alloy-guides, alloy-howtos moved to https://github.com/tidev/skills in v3.0.0
 export const LEGACY_SKILLS = [
   'alloy-expert',
   'ti-branding',
+  'ti-api',
+  'ti-guides',
+  'ti-howtos',
+  'alloy-guides',
+  'alloy-howtos',
 ];
 
 // Agents to install
@@ -77,12 +78,9 @@ export const getPlatforms = (baseDir = os.homedir()) => [
     skillsDir: getGeminiSkillsDir(baseDir),
     configDir: path.join(baseDir, '.gemini'),
   },
-  {
-    name: 'codex',
-    displayName: 'Codex CLI',
-    skillsDir: getCodexSkillsDir(baseDir),
-    configDir: path.join(baseDir, '.codex'),
-  },
+  // Codex CLI is intentionally omitted: it auto-discovers skills from the
+  // canonical ~/.agents/skills/ per the agentskills.io standard, so a
+  // platform-specific symlink at ~/.codex/skills/ would be redundant.
 ];
 
 // Files to install

package/lib/platform.js

@@ -26,7 +26,7 @@ export function detectPlatforms(baseDir) {
 
 /**
  * Get platform by name
- * @param {string} name - Platform name (claude, gemini, codex)
+ * @param {string} name - Platform name (claude, gemini)
  * @param {string} baseDir - Optional base directory
  * @returns {Object|null} Platform object or null
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maccesar/titools",
-  "version": "2.10.0",
+  "version": "3.1.0",
   "description": "Titanium SDK skills and agents for AI coding assistants (Claude Code, Gemini CLI, Codex CLI)",
   "main": "lib/index.js",
   "type": "module",
@@ -57,8 +57,7 @@
     "lib/",
     "skills/",
     "agents/",
-    "AGENTS-VERCEL-RESEARCH.md",
-    "scripts/titools-docs"
+    "AGENTS-VERCEL-RESEARCH.md"
   ],
   "publishConfig": {
     "access": "public"