@maccesar/titools 2.2.4 → 2.2.8

package/README.md

@@ -8,11 +8,11 @@
 
 </div>
 
-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.
+TiTools is a CLI that installs Titanium SDK skills and a knowledge index for AI coding assistants. One command installs 7 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.
+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.
 
-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.
+Vercel's AGENTS.md evaluation reports a 100% pass rate for the knowledge index approach, compared to 53-79% using skills alone.
 
 ---
 
@@ -36,7 +36,7 @@ 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 like garbage on Android. How do I fix it?"
+# "My ListView with 500 items scrolls poorly on Android. How do I fix it?"
 ```
 
 What gets installed:
@@ -125,15 +125,15 @@ 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 & 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 |
+| 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-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. `ti-expert` and `purgetss` are opinionated and reflect personal coding conventions (biased toward PurgeTSS).
 
@@ -206,9 +206,9 @@ All skills include automatic project detection to ensure compatibility:
 | 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)                 |
+| 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
@@ -620,8 +620,8 @@ Behavior depends on where you run it:
 
 What it does:
 1. Checks GitHub for the latest CLI version
-2. If a newer version exists → prompts you to update the CLI first with `npm update -g @maccesar/titools`
-3. If CLI is current → syncs skills and agents from the installed package (no download needed)
+2. If a newer version exists, it prompts you to update the CLI first with `npm update -g @maccesar/titools`
+3. If the CLI is current, it syncs skills and agents from the installed package (no download needed)
 4. Updates platform symlinks only for platforms that already have them
 5. Cleans up legacy artifacts (`alloy-expert` skill, `ti-researcher` agent)
 6. Auto-syncs knowledge index files if they exist in the current project
@@ -691,13 +691,13 @@ Codex CLI:
 
 | Skill        | SKILL.md                      | References                                            |
 | ------------ | ----------------------------- | ----------------------------------------------------- |
-| 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.)                |
+| purgetss     | Setup + Critical Rules        | 21 files (grid, animations, icons, class-index, 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.)             |
 
 ---
 

package/lib/commands/update.js

@@ -167,7 +167,7 @@ export async function updateCommand(options) {
     // Install skills
     spinner.start('Syncing skills...');
     const skillsResult = await installSkills(repoDir, baseDir);
-    spinner.succeed(`Skills: ${formatList(skillsResult.installed)}`);
+    spinner.succeed(`${skillsResult.installed.length} skills updated`);
 
     // Install agents (only if Claude Code has symlinks)
     const claudePlatform = platformsWithSymlinks.find((p) => p.name === 'claude');
@@ -175,7 +175,7 @@ export async function updateCommand(options) {
       spinner.start('Syncing agents...');
       const agentsResult = await installAgents(repoDir, baseDir);
       if (agentsResult.installed.length > 0) {
-        spinner.succeed(`Agents: ${formatList(agentsResult.installed)}`);
+        spinner.succeed('Platform agents updated');
       } else {
         spinner.info('No agents to sync');
       }
@@ -183,21 +183,13 @@ export async function updateCommand(options) {
 
     cleanupLegacyArtifacts(baseDir);
 
-    // Update symlinks only for platforms that already had them
+    // Update symlinks silently for platforms that already had them
     for (const platform of platformsWithSymlinks) {
-      spinner.start(`Updating ${platform.displayName} symlinks...`);
-      const symlinkResult = await createSkillSymlinks(
+      await createSkillSymlinks(
         platform.skillsDir,
         SKILLS,
         baseDir
       );
-      if (symlinkResult.linked.length === SKILLS.length) {
-        spinner.succeed(`${platform.displayName} linked`);
-      } else {
-        spinner.warn(
-          `${platform.displayName}: ${symlinkResult.linked.length}/${SKILLS.length} linked`
-        );
-      }
     }
 
     // Summary

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maccesar/titools",
-  "version": "2.2.4",
+  "version": "2.2.8",
   "description": "Titanium SDK skills and agents for AI coding assistants (Claude Code, Gemini CLI, Codex CLI)",
   "main": "lib/index.js",
   "type": "module",

package/skills/alloy-guides/SKILL.md

@@ -5,11 +5,11 @@ argument-hint: "[concept]"
 allowed-tools: Read, Grep, Glob, Edit, Write, Bash(node *)
 ---
 
-# Alloy MVC Framework Guide
+# Alloy MVC framework guide
 
-Complete reference for building Titanium mobile applications with the Alloy MVC framework and Backbone.js.
+Reference for building Titanium mobile applications with the Alloy MVC framework and Backbone.js.
 
-## Project Detection
+## Project detection
 
 :::info AUTO-DETECTS ALLOY PROJECTS
 This skill automatically detects Alloy projects when invoked and provides framework-specific guidance.
@@ -26,7 +26,7 @@ This skill automatically detects Alloy projects when invoked and provides framew
 - **Not detected** → Indicates this skill is for Alloy projects only, does not suggest Alloy-specific features
 :::
 
-## Quick Reference
+## Quick reference
 
 | Topic                                            | Reference File                                                          |
 | ------------------------------------------------ | ----------------------------------------------------------------------- |
@@ -41,7 +41,7 @@ This skill automatically detects Alloy projects when invoked and provides framew
 | CLI commands, code generation                    | [CLI_TASKS.md](references/CLI_TASKS.md)                                 |
 | PurgeTSS integration (optional addon)            | [PURGETSS.md](references/PURGETSS.md)                                   |
 
-## Project Structure
+## Project structure
 
 Standard Alloy project structure:
 
@@ -64,7 +64,7 @@ app/
 └── widgets/              # Widget components
 ```
 
-## MVC Quick Start
+## MVC quick start
 
 **Controller** (`app/controllers/index.js`):
 ```javascript
@@ -89,7 +89,7 @@ $.index.open();
 "Label": { color: "#000" }
 ```
 
-## Key Concepts
+## Key concepts
 
 - **Models/Collections**: Backbone.js objects with sync adapters (sql, properties)
 - **Views**: XML markup with TSS styling
@@ -98,29 +98,29 @@ $.index.open();
 - **Widgets**: Reusable components with MVC structure
 - **Conventions**: File naming and placement drive code generation
 
-## Critical Rules
+## Critical rules
 
-### Platform-Specific Properties in TSS
+### Platform-specific properties in TSS
 
-:::danger CRITICAL: Platform-Specific Properties Require Modifiers
-Using `Ti.UI.iOS.*` or `Ti.UI.Android.*` properties in TSS WITHOUT platform modifiers causes cross-platform compilation failures.
+:::danger CRITICAL: Platform-specific properties require modifiers
+Using `Ti.UI.iOS.*` or `Ti.UI.Android.*` properties in TSS without platform modifiers causes cross-platform compilation failures.
 
-**Example of the damage:**
+Example of the failure:
 ```tss
-// ❌ WRONG - Adds Ti.UI.iOS to Android project
+// WRONG - Adds Ti.UI.iOS to Android project
 "#mainWindow": {
   statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT  // FAILS on Android!
 }
 ```
 
-**CORRECT approach - Use platform modifiers:**
+Correct approach - use platform modifiers:
 ```tss
-// ✅ CORRECT - Only adds to iOS
+// CORRECT - Only adds to iOS
 "#mainWindow[platform=ios]": {
   statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT
 }
 
-// ✅ CORRECT - Only adds to Android
+// CORRECT - Only adds to Android
 "#mainWindow[platform=android]": {
   actionBar: {
     displayHomeAsUp: true
@@ -128,23 +128,23 @@ Using `Ti.UI.iOS.*` or `Ti.UI.Android.*` properties in TSS WITHOUT platform modi
 }
 ```
 
-**Properties that ALWAYS require platform modifiers:**
+Properties that always require platform modifiers:
 - iOS: `statusBarStyle`, `modalStyle`, `modalTransitionStyle`, any `Ti.UI.iOS.*`
 - Android: `actionBar` config, any `Ti.UI.Android.*` constant
 
 **Available modifiers:** `[platform=ios]`, `[platform=android]`, `[formFactor=handheld]`, `[formFactor=tablet]`, `[if=Alloy.Globals.customVar]`
 
-**For more platform-specific patterns, see** [Code Conventions (ti-expert)](skills/ti-expert/references/code-conventions.md#platform--device-modifiers) or [Platform UI guides (ti-ui)](skills/ti-ui/references/platform-ui-ios.md).
+For more platform-specific patterns, see [Code conventions (ti-expert)](skills/ti-expert/references/code-conventions.md#platform--device-modifiers) or [Platform UI guides (ti-ui)](skills/ti-ui/references/platform-ui-ios.md).
 :::
 
-## Common Patterns
+## Common patterns
 
-### Creating a Model
+### Creating a model
 ```bash
 alloy generate model book sql title:string author:string
 ```
 
-### Data Binding
+### Data binding
 ```xml
 <Collection src="book" />
 <TableView dataCollection="book">
@@ -152,7 +152,7 @@ alloy generate model book sql title:string author:string
 </TableView>
 ```
 
-### Platform-Specific Code
+### Platform-specific code
 ```javascript
 if (OS_IOS) {
     // iOS-only code
@@ -162,25 +162,25 @@ if (OS_ANDROID) {
 }
 ```
 
-### Widget Usage
+### Widget usage
 ```xml
 <Widget src="mywidget" id="foo" />
 ```
 
-## Compilation Process
+## Compilation process
 
-1. **Cleanup**: Resources folder cleaned
-2. **Build Config**: alloy.jmk loaded (pre:load task)
-3. **Framework Files**: Backbone.js, Underscore.js, sync adapters copied
-4. **MVC Generation**: Models, widgets, views, controllers compiled to JS
-5. **Main App**: app.js generated from template
-6. **Optimization**: UglifyJS optimization, platform-specific code removal
+1. Cleanup: Resources folder cleaned
+2. Build Config: alloy.jmk loaded (pre:load task)
+3. Framework Files: Backbone.js, Underscore.js, sync adapters copied
+4. MVC Generation: Models, widgets, views, controllers compiled to JS
+5. Main App: app.js generated from template
+6. Optimization: UglifyJS optimization, platform-specific code removal
 
 ## References
 
 Read detailed documentation from the reference files listed above based on your specific task.
 
-## Related Skills
+## Related skills
 
 For tasks beyond Alloy MVC basics, use these complementary skills:
 

package/skills/alloy-guides/references/CONCEPTS.md

@@ -6,7 +6,7 @@ This guide covers the important concepts related to the Alloy framework, includi
 
 ## Model-View-Controller
 
-Alloy utilizes the model-view-controller (MVC) pattern, which separates the application into three different components:
+Alloy uses the model-view-controller (MVC) pattern, which separates the application into three different components:
 
 * **Models** provide the business logic, containing the rules, data and state of the application
 
@@ -26,7 +26,7 @@ Alloy views are built from Titanium UI components. You define views using XML ma
 
 Alloy controllers generally have a one-to-one relationship with Alloy views. Controllers directly use the Titanium SDK API without an abstraction layer. The controller has access to all of the view components.
 
-Additionally, Alloy provides built-in support for Underscore.js, which provides a set of utility functions, such as array and iterative helpers.
+Also, Alloy provides built-in support for Underscore.js, which provides a set of utility functions, such as array and iterative helpers.
 
 ## Alloy and the Titanium SDK
 
@@ -103,7 +103,7 @@ app/
 
 Alternatively, you can use special conditional code and attributes inside the controllers, views and styles to apply platform-specific code and components.
 
-Additionally, the `assets` folder is laid out the same way as the `Resources` folder in a Titanium project for platform-specific files and density-specific images.
+Also, the `assets` folder is laid out the same way as the `Resources` folder in a Titanium project for platform-specific files and density-specific images.
 
 ## Widgets
 

package/skills/alloy-guides/references/CONTROLLERS.md

@@ -137,7 +137,7 @@ if (OS_IOS) {
 
 ### Passing Arguments
 
-When initializing an external controller, you can pass arguments to customize it, for instance, `const controller = Alloy.createController('controller', {args1: 'foo'})`. In the external controller, the special variable `$.args` is used to receive the arguments. Prior to Alloy 1.6, you needed to use `arguments[0]`. For example, suppose you want to add multiple TableViewRow objects to a TableView object.
+When initializing an external controller, you can pass arguments to customize it, for instance, `const controller = Alloy.createController('controller', {args1: 'foo'})`. In the external controller, the special variable `$.args` is used to receive the arguments. Before Alloy 1.6, you needed to use `arguments[0]`. For example, suppose you want to add multiple TableViewRow objects to a TableView object.
 
 For the TableViewRow object, called 'row', the view contains only the object, and the controller contains only a few lines of code to parse the arguments:
 

package/skills/alloy-guides/references/MODELS.md

@@ -11,7 +11,7 @@
 
 Alloy uses Backbone.js to provide support for its models and collections. Alloy also borrows the concepts of migrations and adapters from Rails for storage integration.
 
-For models, collections and sync adapters, these guides only provides information on how Alloy utilizes the Backbone.js functionality and some simple examples of using it.
+For models, collections and sync adapters, these guides only provides information on how Alloy uses the Backbone.js functionality and some simple examples of using it.
 
 ## Alloy Collection and Model Objects
 
@@ -214,7 +214,7 @@ exports.definition = {
 
 #### Underscore.js Functionality
 
-Additionally, the Backbone.Collection class inherits some functionality from [Underscore.js](https://underscorejs.org/), which can help simplify iterative functions. For example, to add the title of each book object in the library collection to a table, you could use the `map` function to set the table:
+Also, the Backbone.Collection class inherits some functionality from [Underscore.js](https://underscorejs.org/), which can help simplify iterative functions. For example, to add the title of each book object in the library collection to a table, you could use the `map` function to set the table:
 
 **Iterating over a collection with underscore**
 
@@ -281,7 +281,7 @@ You can bind both a collection of models or an individual model. To bind a model
 
 ### Global Singleton vs Local Instance
 
-In the above code snippet, the model and collection are global singletons under `Alloy.Models.currentCategory` and `Alloy.Collections.book`. You can also use local instances for the current controller by adding `instance="true"` as attribute. You also need to assign them an ID in order to reference them in the XML and controller.
+In the above code snippet, the model and collection are global singletons under `Alloy.Models.currentCategory` and `Alloy.Collections.book`. You can also use local instances for the current controller by adding `instance="true"` as attribute. You also need to assign them an ID to reference them in the XML and controller.
 
 ```xml
 <Alloy>
@@ -360,7 +360,7 @@ You can bind deep object properties:
 
 Before, you needed to use a transformer to create a reference like `authorName`.
 
-Prior to CLI 7.1.0, the only way to set object properties (e.g. `font.fontFamily` for a Label) was to use TSS. You can use dot notation in XML:
+Before CLI 7.1.0, the only way to set object properties (e.g. `font.fontFamily` for a Label) was to use TSS. You can use dot notation in XML:
 
 ```xml
 <Alloy>
@@ -760,7 +760,7 @@ The sync adapter exports three functions:
 
 ### Migrations
 
-A migration is a description of incremental changes to a database, which takes your database from version 1 to version X, with a migration file for each step in the evolution of your database schema. This is helpful to keep different versions of a database in sync. For example, when version 7 of your application is deployed, migrations are able to successfully update the database from versions 1 through 6. Currently, migrations are only used with the `sql` sync adapter.
+A migration is a description of incremental changes to a database, which takes your database from version 1 to version X, with a migration file for each step in the evolution of your database schema. This is helpful to keep different versions of a database in sync. For example, when version 7 of your application is deployed, migrations can successfully update the database from versions 1 through 6. Currently, migrations are only used with the `sql` sync adapter.
 
 The `migration.up` function upgrades the database from the previous version, while the `migration.down` function rolls back the changes to the previous version.
 
@@ -1014,7 +1014,7 @@ To use Backbone 1.1.2 to support Alloy Model and Collections objects, open the p
 
 #### Model APIs
 
-**Validation**: Model validation is now only enforced with the `save()` method. Previously, models were also validated with the `set()` method. To force validation when the `set()` method is called, pass `{validate: true}` to the method or extend the Model class. Additionally, validation now occurs even during 'silent' changes (passing `{silent: true}` to methods). Previously, it would not. Failed validations return the `invalid` event. Previously, a failed model validation would return the `error` event.
+**Validation**: Model validation is now only enforced with the `save()` method. Previously, models were also validated with the `set()` method. To force validation when the `set()` method is called, pass `{validate: true}` to the method or extend the Model class. Also, validation now occurs even during 'silent' changes (passing `{silent: true}` to methods). Previously, it would not. Failed validations return the `invalid` event. Previously, a failed model validation would return the `error` event.
 
 **Parse Method**: All `parse` methods now run after a `fetch`. You cannot change the `id` of a model during `parse`. The `parse` method receives `options` as a second parameter.
 

package/skills/alloy-guides/references/VIEWS_WITHOUT_CONTROLLERS.md

@@ -84,7 +84,7 @@ $.index.add(profile.getView());
 $.index.open();
 ```
 
-**Prior to Alloy 1.4.0**, to dynamically generate a view:
+**Before Alloy 1.4.0**, to dynamically generate a view:
 
 1. Create a new instance of the controller using `Alloy.createController()`.
 2. Modify the properties directly.

package/skills/alloy-guides/references/VIEWS_XML.md

@@ -354,7 +354,7 @@ For UI objects that belong to a specific platform, use the `platform` attribute:
 <SplitWindow platform="ios"/>
 ```
 
-Additionally, use the alias `Ti` for `Titanium` when specifying namespaces.
+Also, use the alias `Ti` for `Titanium` when specifying namespaces.
 
 Many of the Titanium view proxies not part of the `Titanium.UI` namespace do not require that the `ns` attribute be explicitly set. The following elements are implicitly mapped to a namespace:
 

package/skills/alloy-guides/references/WIDGETS.md

@@ -10,7 +10,7 @@ See [Importing Widgets](./VIEWS_XML.md#importing-widgets) for more information o
 
 ## Creating Widgets
 
-Widgets should be built in their own directory in the Alloy project's `app/widgets/` directory. Widgets have their own views, controllers, models, styles and assets and are laid out the same as the `app` directory in the Alloy project. Additionally, since widgets are self-contained, they should not reference any code or assets not within its path, except for internationalization and localization files, which are located in the `i18n` folder.
+Widgets should be built in their own directory in the Alloy project's `app/widgets/` directory. Widgets have their own views, controllers, models, styles and assets and are laid out the same as the `app` directory in the Alloy project. Also, since widgets are self-contained, they should not reference any code or assets not within its path, except for internationalization and localization files, which are located in the `i18n` folder.
 
 ## Assets and Libs
 

package/skills/alloy-howtos/SKILL.md

@@ -7,25 +7,25 @@ allowed-tools: Read, Grep, Glob, Edit, Write, Bash(alloy *), Bash(node *)
 
 # Titanium Alloy How-tos
 
-Comprehensive guide for the Alloy MVC Framework in Titanium SDK.
+Practical guide for Alloy MVC projects in the Titanium SDK.
 
-## Project Detection
+## Project detection
 
-:::info AUTO-DETECTS ALLOY PROJECTS
-This skill automatically detects Alloy projects when invoked and provides CLI and configuration guidance.
+:::info Auto-detects Alloy projects
+This skill checks for Alloy projects when invoked and provides CLI and configuration guidance.
 
-**Detection occurs automatically** - no manual command needed.
+Detection is automatic. No manual command is needed.
 
-**Alloy project indicators:**
+Alloy project indicators:
 - `app/` folder with Alloy structure
 - `alloy.jmk` or `config.json` files
 
-**Behavior based on detection:**
-- **Alloy detected** → Provides Alloy CLI command guidance, configuration file help, Alloy-specific troubleshooting
-- **Not detected** → Indicates this skill is for Alloy projects only, suggests Alloy guides if user wants to migrate
+Behavior based on detection:
+- Alloy detected -> Provide Alloy CLI command guidance, configuration file help, Alloy-specific troubleshooting
+- Not detected -> Explain this skill is for Alloy projects only and suggest Alloy guides if the user wants to migrate
 :::
 
-## Quick Reference
+## Quick reference
 
 | Topic                                        | Reference                                                               |
 | -------------------------------------------- | ----------------------------------------------------------------------- |
@@ -36,16 +36,16 @@ This skill automatically detects Alloy projects when invoked and provides CLI an
 | Debugging & Common Errors                    | [debugging_troubleshooting.md](references/debugging_troubleshooting.md) |
 | Code Samples & Conditionals                  | [samples.md](references/samples.md)                                     |
 
-## Critical Best Practices
+## Key practices
 
-### Naming Conventions
+### Naming conventions
 - **Never use double underscore prefixes** (`__foo`) - reserved for Alloy
 - **Never use JavaScript reserved words as IDs**
 
-### Global Events - Use Backbone.Events
-**AVOID** `Ti.App.fireEvent` / `Ti.App.addEventListener` - causes memory leaks and poor performance.
+### Global events - use Backbone.Events
+Avoid `Ti.App.fireEvent` / `Ti.App.addEventListener`. It can cause memory leaks and poor performance.
 
-**USE** Backbone.Events pattern:
+Use the Backbone.Events pattern:
 ```javascript
 // In alloy.js
 Alloy.Events = _.clone(Backbone.Events);
@@ -61,7 +61,7 @@ $.controller.addEventListener('close', () => {
 Alloy.Events.trigger('updateMainUI');
 ```
 
-### Global Variables in Non-Controller Files
+### Global variables in non-controller files
 Always require Alloy modules:
 ```javascript
 const Alloy = require('alloy');
@@ -69,9 +69,9 @@ const Backbone = require('alloy/backbone');
 const _ = require('alloy/underscore')._;
 ```
 
-## Conditional Views
+## Conditional views
 
-Use IF attributes in XML for conditional rendering (evaluated before render):
+Use `if` attributes in XML for conditional rendering (evaluated before render):
 
 ```xml
 <Alloy>
@@ -98,7 +98,7 @@ Data-binding conditionals:
 <TableViewRow if="$model.shouldShowCommentRow()">
 ```
 
-## Common Error Solutions
+## Common error solutions
 
 | Error                                   | Solution                                                |
 | --------------------------------------- | ------------------------------------------------------- |
@@ -107,7 +107,7 @@ Data-binding conditionals:
 | `Alloy is not defined` (non-controller) | Add `const Alloy = require('alloy');`                   |
 | iOS `invalid method passed to UIModule` | Creating Android-only object - use `platform` attribute |
 
-## CLI Quick Reference
+## CLI quick reference
 
 ```bash
 # New project
@@ -130,15 +130,15 @@ alloy move <old> <new>
 alloy remove <name>
 ```
 
-## Configuration Files Priority
+## Configuration files priority
 
 **config.json precedence:** `os:ios` > `env:production` > `global`
 
 Access at runtime: `Alloy.CFG.yourKey`
 
-## Custom XML Tags
+## Custom XML tags
 
-Create reusable components without widgets - just drop a file in `app/lib/`:
+Create reusable components without widgets. Drop a file in `app/lib/`:
 
 **app/lib/checkbox.js**
 ```javascript
@@ -155,7 +155,7 @@ exports.createCheckBox = args => {
 <CheckBox module="checkbox" id="terms" caption="I agree" onChange="onCheck" />
 ```
 
-Key: `module` attribute points to file in `app/lib/` (without `.js`), function must be `create<TagName>`.
+Key: the `module` attribute points to the file in `app/lib/` (without `.js`). The function must be `create<TagName>`.
 
 See [custom_tags.md](references/custom_tags.md) for complete examples.
 
@@ -163,7 +163,7 @@ See [custom_tags.md](references/custom_tags.md) for complete examples.
 
 ### references/
 
-Complete documentation for each topic area:
+Reference docs by topic:
 - **best_practices.md** - Coding standards, naming conventions, global events patterns
 - **cli_reference.md** - All CLI commands with options and model schema format
 - **config_files.md** - alloy.jmk tasks, config.json structure, widget.json format
@@ -171,9 +171,9 @@ Complete documentation for each topic area:
 - **debugging_troubleshooting.md** - Common errors with solutions
 - **samples.md** - Controller examples, conditional views, data-binding patterns
 
-## Related Skills
+## Related skills
 
-For tasks beyond Alloy CLI and configuration, use these complementary skills:
+For tasks beyond Alloy CLI and configuration, use these related skills:
 
 | Task                                     | Use This Skill |
 | ---------------------------------------- | -------------- |

package/skills/alloy-howtos/references/best_practices.md

@@ -1,12 +1,12 @@
-# Alloy Best Practices and Recommendations
+# Alloy best practices and recommendations
 
-This guide provides recommendations for writing Alloy applications. This guide supplements the existing Titanium SDK [Best Practices and Recommendations](https://titaniumsdk.com/guide/Titanium_SDK/Titanium_SDK_Guide/Best_Practices_and_Recommendations/) guide, specifically focusing on Coding Best Practices and Style and Conventions.
+Recommendations for writing Alloy apps. This supplements the Titanium SDK [Best Practices and Recommendations](https://titaniumsdk.com/guide/Titanium_SDK/Titanium_SDK_Guide/Best_Practices_and_Recommendations/) guide and focuses on coding style and conventions.
 
 ## Titanium-to-Alloy Guidance
 
 ### Loading Libraries in Alloy
 
-If you have pre-existing functionality to make available globally, you can require modules in all controllers or create a single global reference:
+If you need global functionality, require modules in all controllers or create a single global reference:
 
 **alloy.js**
 ```javascript
@@ -16,13 +16,13 @@ Alloy.Globals.refToYourModule = require('yourModule');
 
 ### Performance Best Practices
 
-The same best practices from traditional Titanium development apply to Alloy. Everything you can do in traditional Titanium development can be done in Alloy's controllers.
+The same best practices from traditional Titanium development apply to Alloy. Alloy controllers can do what classic controllers can.
 
-Use compiler directives to speed up runtime performance (see Conditional Code in Alloy Controllers).
+Use compiler directives to reduce runtime work (see Conditional Code in Alloy Controllers).
 
 ### Project Organization
 
-Determine if it makes sense to bend Alloy around your existing organization, or bend your existing organization around Alloy. Alloy was created to standardize Titanium coding methodologies, making projects cleaner and more maintainable.
+Decide whether to adapt Alloy to your existing structure, or to adopt Alloy's structure. Alloy standardizes common Titanium patterns and makes projects easier to maintain.
 
 ## Coding Style Best Practices
 
@@ -33,7 +33,7 @@ Determine if it makes sense to bend Alloy around your existing organization, or
 
 ### Global Variables
 
-Do not declare global variables in app.js and use them in other files. This is allowed but not recommended and will be deprecated.
+Avoid declaring globals in app.js and using them in other files. It still works, but it is not recommended and may be deprecated.
 
 Instead, declare these in your JS files:
 
@@ -61,7 +61,7 @@ const loading = Alloy.createWidget("com.titaniumsdk.loading");
 
 ### Global Events
 
-**Avoid `Ti.App.fireEvent` and `Ti.App.addEventListener`** - This crosses the bridge between native and JavaScript lands, which can cause memory leaks and slower processes.
+**Avoid `Ti.App.fireEvent` and `Ti.App.addEventListener`.** It crosses the native-JS bridge and can cause memory leaks and slower execution.
 
 #### Use Callbacks for Master-Child Communication
 
@@ -118,4 +118,4 @@ Alloy.Events.trigger('updateMainUI');
 ```javascript
 Alloy.createController('child').on('refresh', refreshData);
 ```
-This is a cleaner approach to cross-controller communication using Backbone's built-in event capabilities.
+This is a simpler way to do cross-controller communication with Backbone events.