@maccesar/titools 2.2.10 → 2.2.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maccesar/titools",
-  "version": "2.2.10",
+  "version": "2.2.12",
   "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/SKILL.md

@@ -31,78 +31,46 @@ Behavior:
 
 ## Workflow
 
-1. Architecture: define structure (`lib/api`, `lib/services`, `lib/helpers`)
+1. Architecture: define structure by technical type with flat folders (`lib/api`, `lib/services`, `lib/actions`, `lib/repositories`, `lib/helpers`)
 2. Data strategy: choose Models (SQLite) or Collections (API)
 3. Contracts: define I/O specs between layers
 4. Implementation: write XML views and ES6+ controllers
 5. Quality: testing, error handling, logging, performance
 6. Cleanup: implement a `cleanup()` pattern for memory management
 
-## Quick start example
-
-Minimal example that matches the conventions:
-
-View (`views/user/card.xml`)
-```xml
-<Alloy>
-  <View id="cardContainer">
-    <View id="headerRow">
-      <ImageView id="userIcon" image="/images/user.png" />
-      <Label id="name" />
-    </View>
-    <Button id="viewProfileBtn"
-      title="L('view_profile')"
-      onClick="onViewProfile"
-    />
-  </View>
-</Alloy>
-```
+## Architectural Maturity Tiers
 
-Styles (`styles/user/card.tss`)
-```tss
-"#cardContainer": { left: 8, right: 8, top: 8, height: Ti.UI.SIZE, borderRadius: 12, backgroundColor: '#fff' }
-"#headerRow": { layout: 'horizontal', left: 12, right: 12, top: 12, height: Ti.UI.SIZE, width: Ti.UI.FILL }
-"#userIcon": { width: 32, height: 32 }
-"#name": { left: 12, font: { fontSize: 18, fontWeight: 'bold' } }
-"#viewProfileBtn": { left: 12, right: 12, bottom: 12, height: 40, width: Ti.UI.FILL, borderRadius: 6, backgroundColor: '#2563eb', color: '#fff' }
-```
+Choose the appropriate tier based on project complexity:
 
-Controller (`controllers/user/card.js`)
-```javascript
-const { Navigation } = require('services/navigation')
-
-function init() {
-  const user = $.args.user
-  $.name.text = user.name
-}
+### Tier 1: Basic (Rapid Prototyping)
+- **Best for**: Simple utility apps or developers transitioning from Classic.
+- **Structure**: Logic resides directly within `index.js`.
+- **UI Access**: Direct usage of the `$` object throughout the file.
+- **Pros**: Zero boilerplate, extremely fast start.
+- **Cons**: Unmaintainable beyond 500 lines of code.
 
-function onViewProfile() {
-  Navigation.open('user/profile', { userId: $.args.user.id })
-}
+### Tier 2: Intermediate (Modular Alloy)
+- **Best for**: Standard commercial applications.
+- **Structure**: Business logic extracted to `app/lib/` using a flat technical-type organization.
+- **Pattern**: Slim Controllers that `require()` services.
+- **Memory**: Mandatory implementation of `$.cleanup = cleanup`.
 
-function cleanup() {
-  $.destroy()
-}
+### Tier 3: Advanced / Enterprise (Service-Oriented)
+- **Best for**: High-complexity apps (IDEs like TiDesigner, multi-state platforms).
+- **Architecture**: Dependency Injection via a `ServiceRegistry`.
+- **ID Scoping**: Services do not receive the entire `$` object. They receive a "Scoped UI" object containing only relevant IDs.
+- **Cognitive Load**: "Black Box" logic—encapsulated units that reduce mental fatigue.
+- **Observability**: Structured logging with a mandatory `service` context.
 
-$.cleanup = cleanup
-```
+Detailed examples and full implementation samples are available in: [Architectural Tiers Detail](references/architecture-tiers.md)
 
-Service (`lib/services/navigation.js`)
-```javascript
-exports.Navigation = {
-  open(route, params = {}) {
-    const controller = Alloy.createController(route, params)
-    const view = controller.getView()
+## Organization policy (low freedom)
 
-    view.addEventListener('close', function() {
-      if (controller.cleanup) controller.cleanup()
-    })
+- Use technical-type organization in `lib` (for example: `api`, `services`, `actions`, `repositories`, `helpers`, `policies`, `providers`).
+- Keep `lib` flat and predictable: `lib/<type>/<file>.js` only.
+- Do not recommend deep nesting like `lib/services/auth/session/login.js`.
+- Keep UI layers aligned by screen (`controllers/`, `views/`, `styles/`) and avoid unnecessary depth.
 
-    view.open()
-    return controller
-  }
-}
-```
 
 ## Code standards (low freedom)
 
@@ -159,40 +127,47 @@ For the complete reference with examples, see [Alloy builtins and globals](refer
 
 | Question                           | Answer                                                         |
 | ---------------------------------- | -------------------------------------------------------------- |
-| How to create a new Alloy project? | `ti create -t app --alloy` (not `--classic` + `alloy new`)      |
+| How to create a new Alloy project? | `ti create -t app --alloy` (not `--classic` + `alloy new`)     |
 | Fastest way to build?              | `tn <recipe>` (using TiNy CLI wrapper)                         |
+| Controller > 100 lines?            | Extract to Tier 2 (Services)                                   |
+| More than 50 IDs in XML?           | Use Tier 3 (ID Scoping)                                        |
 | Where does API call go?            | `lib/api/`                                                     |
 | Where does business logic go?      | `lib/services/`                                                |
+| How deep should `lib` folders be?  | One level: `lib/<type>/<file>.js`                              |
 | Where do I store auth tokens?      | Keychain (iOS) / KeyStore (Android) via service                |
 | Models or Collections?             | Collections for API data, Models for SQLite persistence        |
 | Ti.App.fireEvent or EventBus?      | Always EventBus (Backbone.Events)                              |
 | Direct navigation or service?      | Always Navigation service (auto cleanup)                       |
-| Inline styles or TSS files?        | Always TSS files (per-controller + `app.tss` for global)        |
-| Controller 100+ lines?             | Extract logic to services                                      |
+| Inline styles or TSS files?        | Always TSS files (per-controller + `app.tss` for global)       |
 
 ## Reference guides (progressive disclosure)
 
-Architecture
-- [CLI expert and TiNy](references/cli-expert.md): advanced build workflows, LiveView, TiNy (`tn`) recipes
-- [Structure and organization](references/alloy-structure.md): models vs collections, folder maps, widget patterns, automatic cleanup
-- [Alloy builtins and globals](references/alloy-builtins.md): `OS_IOS`/`OS_ANDROID`, `Alloy.CFG`, `Alloy.Globals`, `$.args`, compiler directives
-- [ControllerAutoCleanup.js](assets/ControllerAutoCleanup.js): drop-in utility for automatic controller cleanup
-- [Architectural patterns](references/patterns.md): repository, service layer, event bus, factory, singleton
-- [Contracts and communication](references/contracts.md): layer interaction examples and JSDoc specs
-- [Anti-patterns](references/anti-patterns.md): fat controllers, memory leaks, inline styling, direct API calls
-
-Implementation
-- [Code conventions](references/code-conventions.md): ES6 features, TSS design system, accessibility
-- [Theming and dark mode](references/theming.md): theme system, Alloy.Globals palette, runtime switching, design tokens
-- [Controller patterns](references/controller-patterns.md): templates, animation, dynamic styling
-- [Examples](references/examples.md): API clients, SQL models, full screen examples
-
-Quality and reliability
-- [Unit and integration testing](references/testing-unit.md): unit testing, mocking patterns, controller testing, test helpers
-- [E2E testing and CI/CD](references/testing-e2e-ci.md): Appium, WebdriverIO, GitHub Actions, Fastlane
-- [Error handling and logging](references/error-handling.md): AppError classes, Logger service, validation
-
-Performance and security
-- [ListView and ScrollView performance](references/performance-listview.md): ListView templates, data binding, image caching, ScrollView optimization
-- [Performance optimization](references/performance-optimization.md): bridge crossings, memory management, animations, debounce/throttle, database
-- [Security fundamentals](references/security-fundamentals.md): token storage, certificate pinning, encryption, HTTPS, OWASP
+### Architecture & Patterns
+- [Architectural Tiers Detail](references/architecture-tiers.md)
+- [Architectural Patterns](references/patterns.md) (Factory, Singleton, Repository)
+- [Structure & Organization](references/alloy-structure.md)
+- [Contracts & Communication](references/contracts.md)
+- [State Management](references/state-management.md)
+- [Anti-patterns to Avoid](references/anti-patterns.md)
+
+### Implementation & API
+- [Alloy Builtins & Globals](references/alloy-builtins.md)
+- [Code Conventions](references/code-conventions.md)
+- [Controller Patterns](references/controller-patterns.md)
+- [Theming & Dark Mode](references/theming.md)
+- [Migration Patterns](references/migration-patterns.md)
+- [Examples Collection](references/examples.md)
+
+### Quality & Performance
+- [Performance Optimization](references/performance-optimization.md)
+- [ListView & ScrollView Performance](references/performance-listview.md)
+- [Error Handling & Logging](references/error-handling.md)
+- [Unit & Integration Testing](references/testing-unit.md)
+- [E2E Testing & CI/CD](references/testing-e2e-ci.md)
+
+### Security
+- [Security Fundamentals](references/security-fundamentals.md)
+- [Device Security](references/security-device.md)
+
+### Tools
+- [CLI Expert & TiNy](references/cli-expert.md)

package/skills/ti-expert/references/alloy-structure.md

@@ -4,52 +4,81 @@
 
 ```
 app/
-├── controllers/           # View orchestrators
+├── controllers/          # View orchestrators
 │   ├── index.js          # Bootstrap only (no business logic)
-│   └── feature/
-│       └── list.js       # Controller for list view
+│   ├── home.js
+│   └── userProfile.js
 ├── models/               # OPTIONAL: For persistence with migrations
 │   └── user.js           # Model definition (ONLY if using SQLite)
 ├── views/                # XML views
 │   ├── index.xml
-│   └── feature/
-│       └── list.xml      # View definition
+│   ├── home.xml
+│   └── userProfile.xml
 ├── styles/               # TSS styles (one per view + global)
 │   ├── app.tss           # Global application styles
 │   ├── index.tss         # Styles for index view
-│   └── feature/
-│       └── list.tss      # Styles for feature/list view
+│   ├── home.tss
+│   └── userProfile.tss
 ├── lib/                  # Reusable logic (no UI)
 │   ├── api/
-│   │   └── client.js     # API calls
+│   │   ├── authApi.js
+│   │   ├── userApi.js
+│   │   └── frameApi.js
 │   ├── services/
-│   │   ├── auth.js       # Business logic services
-│   │   ├── navigation.js # Navigation orchestration
-│   │   └── nativeService.js # Native module wrapper (e.g. Audio, FB, Maps)
-│   └── helpers/
-│       ├── utils.js      # Pure utility functions
-│       └── i18n.js       # Complex string transformations
+│   │   ├── authService.js
+│   │   ├── navigationService.js
+│   │   └── notificationService.js
+│   ├── actions/
+│   │   ├── syncUserAction.js
+│   │   └── refreshSessionAction.js
+│   ├── repositories/
+│   │   ├── userRepository.js
+│   │   └── settingsRepository.js
+│   ├── helpers/
+│   │   ├── validator.js
+│   │   ├── formatter.js
+│   │   └── dateHelper.js
+│   ├── policies/
+│   │   ├── permissionPolicy.js
+│   │   └── featurePolicy.js
+│   └── providers/
+│       ├── containerProvider.js
+│       └── loggerProvider.js
 ├── widgets/              # Truly reusable components (used in 3+ places)
 │   └── customButton/
 ├── config.json           # Alloy configuration
 └── alloy.js              # Collections & Global services
 ```
 
+## Organization strategy
+
+- `lib/` uses technical-type grouping (Laravel-style naming adapted to Titanium).
+- UI stays in Alloy MVC folders (`controllers`, `views`, `styles`).
+- This is a hybrid approach: technical grouping for reusable logic + screen-based organization for UI files.
+- Keep folder depth low to preserve discoverability.
+- Use clear composed names (`authService.js`, `userRepository.js`, `authApi.js`) and keep multiple files per folder as the normal case.
+
+### Folder depth policy (critical)
+
+- Allowed in `lib`: `lib/<type>/<file>.js`
+- Avoid in `lib`: `lib/<type>/<domain>/<subdomain>/<file>.js`
+- If a folder grows too much, split by new technical type, not deep tree nesting.
+
 ## lib/ folder and module require paths
 
 :::danger CRITICAL: lib/ Folder is FLATTENED During Build
 When Alloy compiles, the **entire `lib/` folder is flattened to the root of Resources**. This means:
-- `app/lib/services/picsum.js` → `Resources/iphone/services/picsum.js`
-- `app/lib/api/client.js` → `Resources/iphone/api/client.js`
+- `app/lib/services/authService.js` → `Resources/iphone/services/authService.js`
+- `app/lib/api/authApi.js` → `Resources/iphone/api/authApi.js`
 
 **Therefore, require statements should NOT include `lib/` prefix:**
 ```javascript
 // ❌ WRONG - Will fail at runtime
-const client = require('lib/api/client')
+const authApi = require('lib/api/authApi')
 
 // ✅ CORRECT - Path relative to flattened lib/
-const client = require('api/client')
-const picsum = require('services/picsum')
+const authApi = require('api/authApi')
+const authService = require('services/authService')
 ```
 
 **This applies to:**
@@ -62,13 +91,18 @@ const picsum = require('services/picsum')
 app/
 ├── lib/
 │   ├── services/
-│   │   ├── picsum.js     # require('services/logger')
-│   │   ├── navigation.js # require('services/logger')
-│   │   └── logger.js
-│   └── api/
-│       └── client.js     # require('services/logger')
+│   │   ├── authService.js       # require('services/navigationService')
+│   │   ├── navigationService.js # require('services/notificationService')
+│   │   └── notificationService.js
+│   ├── api/
+│   │   ├── authApi.js           # require('services/authService')
+│   │   ├── userApi.js
+│   │   └── frameApi.js
+│   └── repositories/
+│       ├── userRepository.js
+│       └── settingsRepository.js
 ├── controllers/
-│   └── index.js          # require('services/picsum')
+│   └── index.js                 # require('services/authService')
 ```
 :::
 
@@ -145,6 +179,7 @@ api.getFrames()
 - Handle UI events and delegate to services.
 - Format data for display (simple cases).
 - Manage view lifecycle (including cleanup).
+- Keep `lib` modules flat and easy to locate.
 
 **DON'T:**
 - Use inline style attributes in XML (define in TSS files).

package/skills/ti-expert/references/architecture-tiers.md

@@ -0,0 +1,248 @@
+# Titanium Architectural Maturity Tiers
+
+To ensure scalability and maintainability, Titanium projects should follow one of these three tiers based on their complexity.
+
+---
+
+# Tier 1 — Basic (Rapid Prototyping)
+
+**Best for:** Utilities, internal tools, proof of concept, learning Alloy.
+
+### Characteristics
+
+* Logic directly in `index.js`
+* Direct `$` access everywhere
+* No separation of concerns
+* No cleanup strategy
+
+### When to upgrade?
+
+* Controller > 100–150 lines
+* Logic duplicated in multiple controllers
+* UI starts feeling coupled
+
+---
+
+## Example (Tier 1)
+
+### Controller (`controllers/index.js`)
+
+```javascript
+function onButtonClick() {
+  $.label.text = "Clicked!"
+  Ti.API.info("Button was clicked")
+}
+
+$.index.open()
+```
+
+Simple. Fast. Dangerous beyond small apps.
+
+---
+
+# Tier 2 — Intermediate (Modular Alloy)
+
+**Best for:** Standard commercial applications.
+
+### Characteristics
+
+* Business logic extracted to `app/lib/`
+* Slim controllers
+* Flat organization (`lib/services`, `lib/api`)
+* Mandatory `cleanup`
+* Reusable UI components
+
+### Why this tier exists
+
+This tier separates UI from logic, but still allows services to reference global dependencies.
+
+It’s modular — but not yet decoupled.
+
+---
+
+## Example (Tier 2)
+
+### View (`views/userCard.xml`)
+
+```xml
+<Alloy>
+  <View id="cardContainer">
+    <View id="headerRow">
+      <ImageView id="userIcon" image="/images/user.png" />
+      <Label id="name" />
+    </View>
+
+    <Button id="viewProfileBtn"
+      title="View Profile"
+      onClick="onViewProfile" />
+  </View>
+</Alloy>
+```
+
+---
+
+### Controller (`controllers/userCard.js`)
+
+```javascript
+const { Navigation } = require('services/navigation')
+
+function init() {
+  const user = $.args.user
+  $.name.text = user.name
+}
+
+function onViewProfile() {
+  Navigation.open('userProfile', { userId: $.args.user.id })
+}
+
+function cleanup() {
+  $.destroy()
+}
+
+$.cleanup = cleanup
+```
+
+---
+
+### Service (`lib/services/navigation.js`)
+
+```javascript
+exports.Navigation = {
+  open(route, params = {}) {
+    const controller = Alloy.createController(route, params)
+    const view = controller.getView()
+
+    view.addEventListener('close', () => {
+      if (controller.cleanup) controller.cleanup()
+    })
+
+    view.open()
+    return controller
+  }
+}
+```
+
+---
+
+### What improves from Tier 1?
+
+* Controllers stay under control
+* Logic is reusable
+* Memory is explicitly cleaned
+* Code is easier to test
+
+But services can still depend directly on other services or globals.
+
+---
+
+# Tier 3 — Advanced / Enterprise (Service-Oriented)
+
+**Best for:** Complex applications (IDEs, platforms, multi-state apps).
+
+This is where architectural maturity changes fundamentally.
+
+---
+
+## Core Concepts
+
+### 1️⃣ Dependency Injection
+
+Services receive what they need — they don’t fetch it.
+
+### 2️⃣ Service Registry
+
+Centralized dependency wiring.
+
+### 3️⃣ ID Scoping
+
+Services receive only the UI elements they own.
+
+### 4️⃣ Encapsulation (Black Box Principle)
+
+Once a service method works, treat it as trusted.
+
+### 5️⃣ Observability
+
+All logs are structured and include service context.
+
+---
+
+## Example (Tier 3)
+
+---
+
+### Service (`lib/services/chatService.js`)
+
+```javascript
+/**
+ * @param {Object} deps
+ * @param {Object} deps.ui - Scoped UI elements
+ * @param {Object} deps.logger
+ * @param {Object} deps.designService
+ */
+module.exports = function createChatService(deps) {
+  const { ui, logger, designService } = deps
+
+  function sendMessage(text) {
+    if (!text) return
+
+    ui.sendBtn.enabled = false        // ID Scoping
+    designService.trackMessage(text)  // Inter-service communication
+
+    logger.event('message:sent', {
+      service: 'ChatService',
+      length: text.length
+    })
+  }
+
+  return {
+    sendMessage
+  }
+}
+```
+
+---
+
+### Registry (`lib/services/indexServiceRegistry.js`)
+
+```javascript
+const createChatService = require('services/chatService')
+const createDesignService = require('services/designService')
+
+module.exports = function createIndexServiceRegistry(deps) {
+  const { $, Ti, logger } = deps
+
+  // 1. Independent services
+  const designService = createDesignService({ Ti, logger })
+
+  // 2. Dependent services with scoped UI
+  const chatService = createChatService({
+    ui: {
+      sendBtn: $.sendBtn,
+      messageInput: $.messageInput
+    },
+    logger,
+    designService
+  })
+
+  return {
+    chatService,
+    designService
+  }
+}
+```
+
+---
+
+## Decision Matrix
+
+| Signal                              | Move To |
+| ----------------------------------- | ------- |
+| Controller > 100 lines              | Tier 2  |
+| Controller > 300 lines              | Tier 3  |
+| More than 50 IDs in XML             | Tier 3  |
+| Services need to talk to each other | Tier 3  |
+| Multiple application states         | Tier 3  |
+| Memory leaks appear                 | Tier 3  |
+
+---

package/skills/ti-guides/references/app-distribution.md

@@ -198,3 +198,176 @@ Installation method:
 2. Open Xcode, then Window, then Devices.
 3. Select the device, then Installed Apps, then +.
 4. Select the IPA file.
+
+---
+
+## Mac Catalyst distribution (Mac App Store)
+
+Mac Catalyst allows you to run your iPad app on macOS. Titanium SDK 13.1.1.GA and later supports building for Mac Catalyst.
+
+### 1. Enable Mac Catalyst for your App ID
+
+1. Go to [Apple Developer → Identifiers](https://developer.apple.com/account/resources/identifiers/list)
+2. Select your App ID or create a new one
+3. Enable **Mac Catalyst** capability
+4. Save the changes
+
+### 2. Create Mac App Store Distribution Certificate
+
+1. Go to [Apple Developer → Certificates](https://developer.apple.com/account/resources/certificates/list)
+2. Click **+** to create a new certificate
+3. Select **Mac App Store Distribution**
+4. Upload your CSR (Certificate Signing Request)
+5. Download and install the certificate
+
+### 3. Mac Catalyst build targets
+
+Titanium provides two targets for Mac Catalyst:
+
+| Target | Description | Configuration |
+|--------|-------------|---------------|
+| `macos` | Development builds for testing on Mac | Debug-maccatalyst |
+| `dist-macappstore` | Production builds for Mac App Store | Release-maccatalyst |
+
+### 4. Build for Mac Catalyst (Development)
+
+```bash
+ti build -p ios -T macos
+```
+
+The `.app` bundle will be created at:
+```
+build/iphone/build/Products/Debug-maccatalyst/AppName.app
+```
+
+For a production-ready build:
+```bash
+ti build -p ios -T macos --deploy-type production
+```
+
+The `.app` bundle will be at:
+```
+build/iphone/build/Products/Release-maccatalyst/AppName.app
+```
+
+### 5. Build for Mac App Store (Distribution)
+
+```bash
+ti build -p ios -T dist-macappstore [-R <CERTIFICATE_NAME>]
+```
+
+Example:
+```bash
+ti build -p ios -T dist-macappstore -R "Apple Distribution: Your Team Name (TEAM_ID)"
+```
+
+If you omit the `-R` flag, Titanium will prompt you to select a certificate.
+
+**What happens during the build:**
+- Uses `Release-maccatalyst` configuration
+- Sets code signing to Manual with identity `-`
+- Creates a `.xcarchive` for Mac App Store
+- Installs the archive in Xcode's Organizer
+- Destination: `generic/platform=macOS`
+
+### 6. Upload to Mac App Store Connect
+
+1. Open Xcode → Window → Organizer
+2. Select your Mac Catalyst archive
+3. Click **Validate App** to check for issues
+4. Click **Distribute App**
+5. Select **Mac App Store**
+6. Follow the prompts to upload
+
+### 7. Create app listing in App Store Connect
+
+1. Go to [App Store Connect](https://appstoreconnect.apple.com)
+2. **My Apps → + → New App**
+3. Select **Mac** as platform
+4. Enter app details:
+   - Name
+   - Primary Language
+   - Bundle ID (must match your App ID with Mac Catalyst enabled)
+   - SKU
+5. Complete required metadata:
+   - Description
+   - Keywords
+   - Screenshots (Mac-specific sizes)
+   - Category
+   - Age rating
+
+### 8. Mac Catalyst entitlements
+
+Add Mac-specific entitlements in `tiapp.xml`:
+
+```xml
+<ios>
+  <entitlements>
+    <dict>
+      <!-- File access for saving to Downloads -->
+      <key>com.apple.security.files.user-selected.read-write</key>
+      <true/>
+      <key>com.apple.security.files.downloads.read-write</key>
+      <true/>
+
+      <!-- App sandbox (required for Mac App Store) -->
+      <key>com.apple.security.app-sandbox</key>
+      <true/>
+
+      <!-- Network access -->
+      <key>com.apple.security.network.client</key>
+      <true/>
+
+      <!-- Additional entitlements as needed -->
+      <key>com.apple.security.print</key>
+      <true/>
+    </dict>
+  </entitlements>
+</ios>
+```
+
+### 9. Common issues
+
+**Issue**: "No suitable signing certificate found"
+- Ensure you have a **Mac App Store Distribution Certificate** (not iOS Distribution)
+- The certificate must be installed in your Keychain
+
+**Issue**: Build fails with code signing errors
+- Verify your App ID has Mac Catalyst enabled
+- Check that the certificate matches the App ID
+- Try cleaning the build: `ti clean -p ios`
+
+**Issue**: App crashes on launch
+- Verify entitlements are correctly configured
+- Check Console.app for crash logs
+- Ensure all required capabilities are enabled
+
+### 10. Versioning
+
+Update version numbers in `tiapp.xml`:
+
+```xml
+<ti:app xmlns:ti="http://ti.tidev.io">
+  <id>com.yourcompany.yourapp</id>
+  <name>Your App Name</name>
+  <version>1.0.0</version>
+  <publisher>Your Company</publisher>
+  ...
+</ti:app>
+```
+
+- `version`: Display version (e.g., "1.0.0")
+- For iOS, use `pv-version-code` in `<ios>` section for build number
+- For Mac, the build number can be set in Xcode or via `CFBundleVersion`
+
+### 11. Testing on Mac
+
+Before submitting to Mac App Store:
+
+1. Build with `macos` target for testing
+2. Run the app on different Mac architectures (Intel and Apple Silicon)
+3. Test all features that use file system, network, and other sandboxed resources
+4. Verify entitlements are working correctly
+5. Test on macOS versions you plan to support
+
+---

package/skills/ti-guides/references/cli-reference.md

@@ -258,7 +258,7 @@ Omit `-V` and `-P` to be prompted.
 | `-P, --pp-uuid <uuid>`           | Provisioning profile UUID (for device/dist targets).                                                   |
 | `-R, --distribution-name <name>` | iOS Distribution Certificate (for dist targets).                                                       |
 | `--sim-focus`                    | Focus the iOS Simulator after launching (default: true). Use --no-sim-focus to disable.                |
-| `-T, --target <value>`           | Target: simulator, device, dist-appstore, or dist-adhoc.                                               |
+| `-T, --target <value>`           | Target: simulator, device, dist-appstore, dist-adhoc, macos, or dist-macappstore.                            |
 | `-V, --developer-name <name>`    | iOS Developer Certificate (required for device target).                                                |
 | `-W, --watch-device-id <udid>`   | Watch simulator UDID (simulator only).                                                                 |
 | `--watch-app-name <name>`        | Name of the watch app to launch (simulator only).                                                      |
@@ -394,6 +394,48 @@ ti build -p ios -T dist-appstore -R "Pseudo, Inc." -P "AAAAAAAA-0000-9999-8888-7
 
 Installs the package to Xcode Organizer.
 
+### Mac Catalyst (macOS Development)
+
+```bash
+ti build -p ios -T macos
+```
+
+Builds a Mac Catalyst version of your iOS app for local testing. The resulting `.app` bundle is located at:
+```
+build/iphone/build/Products/Debug-maccatalyst/AppName.app
+```
+
+For a production build:
+```bash
+ti build -p ios -T macos --deploy-type production
+```
+
+The release `.app` bundle will be at:
+```
+build/iphone/build/Products/Release-maccatalyst/AppName.app
+```
+
+### Mac App Store (Mac Catalyst Distribution)
+
+```bash
+ti build -p ios -T dist-macappstore [-R <CERT_NAME>]
+```
+
+Example:
+```bash
+ti build -p ios -T dist-macappstore -R "Apple Distribution: Your Name (TEAM_ID)"
+```
+
+**Important Notes:**
+- Requires a Mac App Store Distribution Certificate (not iOS Distribution)
+- The build creates an archive for Mac App Store distribution
+- The `.xcarchive` is installed in Xcode's Organizer
+- Uses `Release-maccatalyst` configuration
+- Destination: `generic/platform=macOS`
+- Code signing is set to Manual with identity `-`
+
+The target `dist-macappstore` is available in Titanium SDK 13.1.1.GA and later.
+
 ---
 
 ## SDK management