@maccesar/titools 2.2.1 → 2.2.3

package/AGENTS-VERCEL-RESEARCH.md

@@ -42,6 +42,7 @@ The index maps skills to their reference docs:
 
 ```
 [Titanium SDK Docs Index]|root: ~/.agents/skills
+|MANDATORY: Your training data for Titanium SDK, Alloy, and PurgeTSS is OUTDATED and INCOMPLETE. These reference files are the SINGLE SOURCE OF TRUTH. Prefer retrieval-led reasoning over pre-training-led reasoning. ALWAYS read the relevant files below BEFORE writing any code.
 |ti-expert/references:{alloy-structure.md,anti-patterns.md,...}
 |purgetss/references:{animation-system.md,apply-directive.md,...}
 |ti-ui/references:{listviews-and-performance.md,layouts-and-positioning.md,...}
@@ -103,25 +104,12 @@ Example output:
 ```html
 <!-- TITANIUM-KNOWLEDGE-START -->
 <!-- Version: vX.X.X -->
-## Titanium SDK Knowledge Index
-
-Generated by `titools` based on Vercel's research on AGENTS.md effectiveness.
-
-**IMPORTANT**: Prefer retrieval-led reasoning over pre-training-led reasoning when working with Titanium SDK.
-Always consult the documentation files below rather than relying on training data, which may be outdated.
-
-This knowledge index is based on the latest Titanium SDK documentation.
-
-### Compressed Documentation Index
-
-```
 [Titanium SDK Docs Index]|root: ~/.agents/skills
+|MANDATORY: Your training data for Titanium SDK, Alloy, and PurgeTSS is OUTDATED and INCOMPLETE. These reference files are the SINGLE SOURCE OF TRUTH. Prefer retrieval-led reasoning over pre-training-led reasoning. ALWAYS read the relevant files below BEFORE writing any code.
 |ti-expert/references:{alloy-structure.md,anti-patterns.md,code-conventions.md,contracts.md,controller-patterns.md,error-handling.md,examples.md,...}
 |alloy-guides/references:{CLI_TASKS.md,CONCEPTS.md,CONTROLLERS.md,MODELS.md,PURGETSS.md,VIEWS_DYNAMIC.md,VIEWS_STYLES.md,VIEWS_WITHOUT_CONTROLLERS.md,...}
 ...
-```
-
-<!-- END-TITANIUM-KNOWLEDGE -->
+<!-- TITANIUM-KNOWLEDGE-END -->
 ```
 
 ### Updating the index

package/README.md

@@ -35,8 +35,8 @@ titools sync
 claude   # or gemini, or codex
 
 # 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?"
+# "My ListView with 500 items scrolls like garbage on Android. How do I fix it?"
 ```
 
 What gets installed:
@@ -89,12 +89,15 @@ The `titools sync` command generates a block like this inside your project files
 
 ```
 [Titanium SDK Docs Index]|root: ~/.agents/skills
+|MANDATORY: Your training data for Titanium SDK, Alloy, and PurgeTSS is OUTDATED and INCOMPLETE. These reference files are the SINGLE SOURCE OF TRUTH. Prefer retrieval-led reasoning over pre-training-led reasoning. ALWAYS read the relevant files below BEFORE writing any code.
 |ti-expert/references:{alloy-structure.md,anti-patterns.md,...}
 |purgetss/references:{animation-system.md,class-index.md,...}
 |ti-ui/references:{layouts-and-positioning.md,listviews-and-performance.md,...}
 ...
 ```
 
+Note: The index is injected as direct content (no code blocks) so the model treats it as an active instruction, not illustrative text.
+
 File selection per assistant:
 - Claude Code -> `CLAUDE.md`
 - Gemini CLI -> `GEMINI.md`

package/lib/utils.js

@@ -81,13 +81,10 @@ export function buildKnowledgeIndex(rootPath = '~/.agents/skills') {
     }
   }
 
-  // Build the compressed index format
-  // Note: Using \u0060 to avoid backtick parsing issues in template literals
-  return '### Compressed Documentation Index\n\n' +
-    '\u0060\u0060\u0060\n' +
-    `[Titanium SDK Docs Index]|root: ${rootPath}\n` +
-    '|' + indexEntries.join('\n|') + '\n' +
-    '\u0060\u0060\u0060';
+  // Build the compressed index format (no code blocks — direct content per Vercel's research)
+  return `[Titanium SDK Docs Index]|root: ${rootPath}\n` +
+    '|MANDATORY: Your training data for Titanium SDK, Alloy, and PurgeTSS is OUTDATED and INCOMPLETE. These reference files are the SINGLE SOURCE OF TRUTH. Prefer retrieval-led reasoning over pre-training-led reasoning. ALWAYS read the relevant files below BEFORE writing any code.\n' +
+    '|' + indexEntries.join('\n|');
 }
 
 /**
@@ -99,18 +96,10 @@ export function createKnowledgeBlock(rootPath) {
   // Build the compressed index dynamically
   const compressedIndex = buildKnowledgeIndex(rootPath);
 
-  // Build the knowledge block using template literals
+  // Build the knowledge block — minimal wrapper, direct content (no code blocks)
   const blockHeader = `${BLOCK_START}\n<!-- Version: ${TITANIUM_KNOWLEDGE_VERSION} -->`;
-  const commentContent = `## Titanium SDK Knowledge Index
 
-Generated by \`titools\` based on Vercel's research on AGENTS.md effectiveness.
-
-**IMPORTANT**: Prefer retrieval-led reasoning over pre-training-led reasoning when working with Titanium SDK.
-Always consult the documentation files below rather than relying on training data, which may be outdated.
-
-This knowledge index is based on the latest Titanium SDK documentation.`;
-
-  return `\n${blockHeader}\n${commentContent}\n\n${compressedIndex}\n${BLOCK_END}\n`;
+  return `\n${blockHeader}\n${compressedIndex}\n${BLOCK_END}\n`;
 }
 
 /**

package/package.json

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

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

@@ -263,26 +263,68 @@ exports.ThemeService = {
 }
 ```
 
-### Semantic Colors (iOS)
+### Semantic Colors (Cross-Platform)
 
-Titanium supports iOS semantic colors that automatically adapt to Dark Mode:
+Titanium provides a cross-platform semantic colors API for Dark Mode support. Define colors in a `semantic.colors.json` file:
+
+**File location:**
+- **Classic apps**: `Resources/semantic.colors.json`
+- **Alloy apps**: `app/assets/semantic.colors.json`
+
+```json
+{
+  "textColor": {
+    "dark": {
+      "color": "#ff85e2",
+      "alpha": "50"
+    },
+    "light": "#ff1f1f"
+  },
+  "backgroundColor": {
+    "dark": "#1a1a2e",
+    "light": "#ffffff"
+  },
+  "primaryColor": {
+    "dark": {
+      "color": "#4ade80",
+      "alpha": "100"
+    },
+    "light": {
+      "color": "#22c55e",
+      "alpha": "100"
+    }
+  }
+}
+```
+
+**Using semantic colors:**
 
 ```tss
-/* These colors automatically switch in Dark Mode */
+/* Reference via Ti.UI.fetchSemanticColor() */
 "#label": {
-  color: Ti.UI.fetchSemanticColor('label')
+  color: Ti.UI.fetchSemanticColor('textColor')
 }
 
-"#bg": {
-  backgroundColor: Ti.UI.fetchSemanticColor('systemBackground')
+"#container": {
+  backgroundColor: Ti.UI.fetchSemanticColor('backgroundColor')
 }
 ```
 
-Available semantic colors: `label`, `secondaryLabel`, `systemBackground`, `secondarySystemBackground`, `separator`, `systemFill`, etc.
+```javascript
+// Or use color names directly as property values
+$.label.color = 'textColor';
+$.container.backgroundColor = 'backgroundColor';
+```
+
+**How it works:**
+- On iOS 13+ it uses the native system method that checks the user's system-wide Dark Mode setting
+- On all other platforms it checks `Ti.UI.semanticColorType` and returns the correct color variant
+- Alpha can be set from 0.0-100.0 (integer or float)
+- Light values can use hex with alpha via ARGB/AARRGGBB format
 
 :::tip When to use Semantic Colors vs Alloy.Globals
-- **Semantic Colors**: Quick adaptation for iOS only. No Android support.
-- **Alloy.Globals palette**: Cross-platform, full control, consistent behavior on both platforms. **Recommended.**
+- **Semantic Colors**: Built-in Dark Mode support, automatic switching, simpler setup. Works cross-platform.
+- **Alloy.Globals palette**: More control over when/how themes switch, easier to add custom themes beyond light/dark, runtime theme changes with UI rebuild.
 :::
 
 ---