@maccesar/titools 5.2.0 → 5.2.1

package/CONTRIBUTING.md

@@ -0,0 +1,69 @@
+# Contributing to TiTools
+
+TiTools distributes thirteen Titanium SDK skills, a research agent and slash
+commands through an npm CLI and a Claude Code marketplace plugin. Product
+content lives in `skills/`, `agents/` and `commands/`; CLI source lives in
+`bin/` and `lib/`. Both channels use this source tree.
+
+## Development
+
+Use Node.js 18 or newer. Install dependencies with `npm ci`.
+
+Run the tests that cover a change first:
+
+```sh
+node --test test/manifest.test.js
+npm run lint
+```
+
+Tests use Node's built-in runner. Asset-helper checks additionally require the
+Python dependencies in `skills/ti-game-assets/scripts/requirements.txt`.
+Scripts under `scripts/` maintain reference navigation, fences and snapshots;
+they are repository tooling and are not installed as CLI commands.
+
+## Skill and command changes
+
+- A skill's directory and frontmatter `name` must match, using kebab-case.
+- Descriptions explain when to load the skill, stay within 1,024 characters and
+  begin with "Use when". Skill names have a 64-character limit.
+- Register new public skills in `lib/config.js`, the `ti-pro` agent and the
+  `ti-audit` applicability list. Update the README and add at least two requests
+  to [the public examples](docs/examples.md).
+- Keep entry points concise and put detail in linked references. Preserve
+  operational prerequisites, defaults, platform differences and cleanup.
+- Verify factual guidance against official documentation and implementation;
+  identify source revisions and distinguish source/host checks from device
+  acceptance. Preserve declared source-mirror transformations and raw assets.
+- Slash commands belong under `commands/`, where both channels can serve them.
+- CLI modules use ESM imports with explicit `.js` extensions. Use asynchronous
+  child processes inside spinners so the UI remains responsive.
+
+## Public repository boundaries
+
+Commit product source, public guides, tests, reusable maintenance scripts and
+GitHub/marketplace configuration. Keep personal scratch notes, assistant/editor
+workspace files, session state and unpublished audit conversations local.
+
+The ignored `.agents/`, `.claude/`, `docs/project/` and root assistant instruction
+files are private workspace material. `.claude-plugin/` and `.github/workflows/`
+are public product infrastructure. A leading dot does not make a tracked path
+private. The npm `files` allowlist is intentionally narrower than the repository.
+
+The supported installation methods are npm and the Claude Code marketplace,
+as described in the README. The obsolete standalone shell installer is retired.
+
+## Release checklist
+
+The `.github/workflows/publish.yml` workflow publishes with npm trusted
+publishing (OIDC). Do not publish manually from a maintainer machine.
+
+1. Run `npm test` and the required lint checks for a release.
+2. Add the release entry to `CHANGELOG.md`.
+3. Bump `package.json`, its lockfile and `.claude-plugin/plugin.json` together.
+4. Commit the release and tag that commit `vX.Y.Z`.
+5. Push `main` and the version tag. The tag triggers `publish.yml`.
+6. Verify the workflow and the npm registry version; a tag alone does not prove publication.
+7. Verify the plugin manifest on the default branch, which is also used by marketplace updates.
+
+Do not include private workspace files merely to obtain a clean working tree.
+Review the staged paths and actual npm payload before publishing.

package/README.md

@@ -12,7 +12,7 @@ The reference files are maintained against official documentation whenever an of
 
 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.
 
-Vercel's AGENTS.md evaluation reports a 100% pass rate for the knowledge index approach, compared to 53-79% using skills alone.
+The optional knowledge index helps assistants discover the installed reference documents. See [skills and the knowledge index](docs/knowledge-index.md).
 
 ---
 
@@ -115,20 +115,12 @@ All three platforms use the Agent Skills open standard: a `SKILL.md` file with Y
 
 The knowledge index is a compressed documentation map that gets injected into your project's instruction files. It tells the AI where Titanium reference docs are, so it can pull accurate information from the installed references instead of relying on general training data.
 
-### Why it works
+### Reference discovery
 
-| Approach         | Reported Pass Rate |
-| ---------------- | ------------------ |
-| No documentation | 53%                |
-| Skills only      | 53-79%             |
-| Knowledge index  | 100%               |
-
-Per Vercel's evaluation:
-- No decision point: information is present without needing to invoke skills
-- Consistent availability: available in every turn, not async-loaded
-- No ordering issues: avoids "read docs first vs explore project first"
-
-For details, see `AGENTS-VERCEL-RESEARCH.md`.
+Skills provide task-specific workflows; the knowledge index makes their reference
+locations discoverable from your project's instruction files. Load the relevant
+references before relying on an API, platform requirement or module contract.
+See [how the index works](docs/knowledge-index.md).
 
 ### What gets generated
 
@@ -178,9 +170,9 @@ The knowledge index is based on the latest Titanium SDK documentation. If your p
 | ti-expert    | Architecture and implementation     | Starting point for most tasks           |
 | purgetss     | Alloy styling + asset automation    | Utility classes; Alloy/Classic branding, images, colors, fonts and modules |
 | ti-ui        | UI/UX patterns                      | Complex layouts, ListViews, platform UI |
-| ti-game      | 2D games with the `ti.game` module  | Sprites, physics, tile layers, wall jumps, pathfinding, text/performance HUDs, particles, camera |
+| ti-game      | 2D games with the `ti.game` module  | Sprites, physics, tile maps, HUDs, camera, focused keyboard/mouse/gamepad actions, Apple Metal/Catalyst |
 | ti-game-assets | Visual and sound assets | Image generation/editing, synthesis variants, stereo placement, alpha cleanup, manifests, parallax and complete exports |
-| ti-synthengine | Sound design with `ti.synthengine` | Tones, chords, retro/UI effects, alarms, sweeps, patterns, ADSR envelopes, resonant filters, FM, detune, binaural positioning, engine statistics, mixing and troubleshooting |
+| ti-synthengine | Sound design with `ti.synthengine` | Tones, chords, retro/UI effects, alarms, sweeps, patterns, ADSR envelopes, resonant filters, FM, detune, binaural positioning, held voices, native sequences, master effects, voice LFOs, engine statistics, mixing and troubleshooting |
 | ti-admob-unified | Advertising, privacy and mediation | Official `ti.admob.unified` guides, copy-ready library, banners/fullscreen, UMP/ATT and selected-provider configuration |
 | ti-api       | Complete Titanium API reference     | Looking up properties, methods, events  |
 | ti-guides    | SDK fundamentals                    | tiapp.xml, Hyperloop, distribution, JDK/Xcode compatibility, release notes |
@@ -191,8 +183,8 @@ The knowledge index is based on the latest Titanium SDK documentation. If your p
 Notes:
 - The first eight (`ti-reuse-first`, `ti-expert`, `purgetss`, `ti-ui`, `ti-game`, `ti-game-assets`, `ti-synthengine`, `ti-admob-unified`) are specialist workflow skills reflecting TiTools' Titanium conventions and native-module contracts.
 - `ti-reuse-first` runs before the others. It asks whether a thing needs to exist and what already does it — a search order that stops at the first rung that holds — and sweeps an existing `app/` for near-identical controllers, single-listener events, wrappers around one call, and layout recomputed in JavaScript. It is deliberately two-sided: it says when adding a module or a Widget is the right answer, so the bias does not simply invert.
-- `ti-game` documents the `ti.game` native module (2D sprite engine on OpenGL ES 2.0, Android and iOS). Its API reference was verified against the module source and tracks upstream `main` (the module ships features ahead of its manifest version); it applies to Alloy and Classic projects alike and does not depend on PurgeTSS.
-- `ti-synthengine` translates aesthetic sound requests into strict, production-ready JavaScript for the cross-platform `ti.synthengine` 1.0.0 beta module. Eight references preserve official documentation, accompanied by raw statistics benchmark trials; curated recipes add retro effects, xylophone interaction, memory pads, polyphony and timer ownership. The reviewed source includes eleven public methods with optional diagnostics; feature detection remains necessary for older beta binaries. Maintenance notes and a hash manifest distinguish the reviewed working tree from its base commit and published packages, track preserved navigation and state audit limits.
+- `ti-game` documents the `ti.game` native module (2D sprite engine using OpenGL ES 2.0 on Android and Metal on iPhone, iPad and Mac Catalyst). Its API reference was verified against the module source and records the reviewed upstream commit and fork documentation snapshot; it applies to Alloy and Classic projects alike and does not depend on PurgeTSS.
+- `ti-synthengine` translates sound requests into checked JavaScript for the public Android/iOS `ti.synthengine` 1.0.0 release. Its nineteen-method contract covers timed/held voices, identified native sequences, global tempo, selective categories/sends, master effects, live spatial/noise/filter controls and diagnostics. Two curated recipe guides cover retro cues and interactive instruments. Complete official-source mirrors, validation reports, bundled examples and raw evidence retain provenance; reversible errata correct source prose against native behavior. The clean reviewed commit, platform differences and scoped listening/performance acceptance are explicit in source notes.
 - `ti-game-assets` treats images and sounds as essential game assets. It coordinates integrated `image_gen` artwork with `ti-synthengine` sound design, variants and stereo placement, and ships Pillow helpers for conservative alpha cleanup and per-world visual/audio manifests.
 - The latter five are documentation-mirror skills, audited against official sources via the internal `titools-skill-auditor`. See [Where the references come from](#where-the-references-come-from).
 - `purgetss` reference files are audited against the official PurgeTSS documentation and against the package source (the CLI and the generated `utilities.tss`), but its workflow conventions are opinionated.
@@ -228,14 +220,14 @@ In addition to skills, this repository includes sub-agents for Claude Code. Sub-
 
 ### ti-pro
 
-Deep-dive research specialist that can combine the complete 10-skill TiTools catalog.
+Deep-dive research specialist that can combine the complete 13-skill TiTools catalog.
 
 | Aspect           | Details                                          |
 | ---------------- | ------------------------------------------------ |
 | Location         | `~/.claude/agents/ti-pro.md`                     |
 | Model            | Sonnet (comprehensive analysis)                  |
-| Tools            | Read-only (Read, Grep, Glob)                     |
-| Preloaded Skills | All 10 skills registered in `lib/config.js`      |
+| Tools            | Read, Grep, Glob, Bash                           |
+| Preloaded Skills | All 13 skills registered in `lib/config.js`      |
 
 When to use the agent vs skills:
 
@@ -460,7 +452,7 @@ Key rules:
 
 ### ti-game
 
-2D game development with the `ti.game` native module — a sprite engine rendered with OpenGL ES 2.0, same JS API on Android and iOS. Works in Alloy and Classic projects.
+2D game development with the `ti.game` native module — a sprite engine rendered with OpenGL ES 2.0 on Android and Metal on iPhone, iPad and Mac Catalyst, with a mostly shared JS API. Works in Alloy and Classic projects.
 
 When it activates:
 - `tiapp.xml` declares `ti.game`, or any file calls `require('ti.game')`
@@ -478,6 +470,7 @@ When it activates:
 - Native `TileLayer` maps with visible-cell rendering, Tiled GIDs, solid/one-way cells, live edits and A* integration
 - Collision-shape overlays plus the expandable performance HUD and opt-in `performance` telemetry event
 - Drag & drop, pinch, rotate, multitouch controls
+- Focused keyboard/mouse/gamepad actions, input contexts, canvas focus and native text-field ownership
 
 Example prompts:
 ```
@@ -524,41 +517,71 @@ Raster drawing generation/editing uses integrated `image_gen`. Authored SVG/proc
 
 ### ti-admob-unified
 
-Integrate César's `ti.admob.unified` module in Alloy or Classic using its official documentation for installation, API, UMP/ATT, privacy options, banner layout, fullscreen lifecycle and mediation. The skill includes the official copy-ready application library and guides for AppLovin, Meta, InMobi, Unity and Liftoff. The module's first public 1.0.0 release is under preparation at this snapshot.
-
-Source commit, per-file hashes and rebased links are recorded. Future updates use the maintainer auditor's source map and the read-only check `node scripts/verify-module-snapshot.mjs --source /path/to/ti.admob.unified`; new, changed or removed docs are reported before updating. Community guidance remains separate from official mirrors.
-
-Installing an adapter does not configure a publisher account or prove delivery. The skill distinguishes build/linking, Google test ads, each provider's test delivery and physical-device acceptance; it preserves the game's selected frequency policy instead of enabling every format.
+Integrate public **ti.admob.unified 1.0.0** in Alloy or Classic with its official
+[repository](https://github.com/macCesar/ti.admob.unified),
+[Android downloads](https://github.com/macCesar/ti.admob.unified/releases/tag/android-1.0.0)
+and [iOS downloads](https://github.com/macCesar/ti.admob.unified/releases/tag/ios-1.0.0).
+Install the core ZIP for each target and only the mediation complements you use.
+Requires Titanium SDK 13.4.1.GA, iOS 15+, Android API 24+ and compile SDK 36;
+this Apple module does not support Mac Catalyst.
+
+The skill covers consent-first UMP/ATT, synchronous tracking-status queries,
+standard/adaptive banners, interstitial, rewarded, rewarded interstitial and
+app-open ads. It includes the unchanged copy-ready integration library and
+AppLovin, Meta, InMobi, Unity and Liftoff setup/dependency/parity guides.
+Rewarded interstitial guidance includes an accurate reward introduction,
+visible Skip, SDK-reported rewards and cancellation tied to the presentation
+context. Loading an ad alone does not authorize showing it.
+
+The [skill entry point](skills/ti-admob-unified/SKILL.md) routes exact API,
+installation, lifecycle and [production guidance](skills/ti-admob-unified/references/production.md)
+for app IDs, units, app-ads.txt, privacy options and AdMob/store readiness.
+[Source notes](skills/ti-admob-unified/references/source-notes.md) record reviewed
+source `0348432`, platform ZIP hashes and native-backed corrections.
+
+A packaged adapter or Google test ad does not prove provider delivery or
+production eligibility. Keep configuration/linking, each selected provider's
+test delivery and physical-device visual/lifecycle acceptance separate. Game
+frequency and pause/audio/input ownership remain application policies.
 
 ### ti-synthengine
 
-Cross-platform sound design and synthesis with the native `ti.synthengine` 1.0.0 beta module for Android and iOS.
+Sound design and synthesis with the public native `ti.synthengine` 1.0.0 release for Android and iOS. Read the [skill entry point](skills/ti-synthengine/SKILL.md) for task routing, exact API references and current source provenance.
+
+Public repository: [macCesar/TiSynthEngine](https://github.com/macCesar/TiSynthEngine).
+Download [Android 1.0.0](https://github.com/macCesar/TiSynthEngine/releases/tag/android-1.0.0)
+and [iOS 1.0.0](https://github.com/macCesar/TiSynthEngine/releases/tag/ios-1.0.0),
+copy the ZIPs into the Titanium app root and follow the [installation guide](skills/ti-synthengine/references/guide.md).
+Requires Titanium SDK 13.2.0.GA+, Android compile API35+, and iOS 15+; the Apple package also supports Mac Catalyst.
 
 When it activates:
 - `tiapp.xml` declares `ti.synthengine`, or code calls `require('ti.synthengine')`
-- The app needs generated UI feedback, game cues, retro/chiptune effects, alarms, chords, pads, noise percussion, sweeps, panning, or vibrato
-- A synth call returns `false`, the first sound glitches, a pattern stops, a chord pumps, or output changes after a route switch
-- The app needs voice/queue/rejection counters, optional render-load/output meters, or help interpreting host benchmark evidence
+- Generated UI/game cues, instruments, alarms, chords, percussion, sweeps or binaural headphone placement
+- Sustained voices, simultaneous native sequences, shared tempo, selective effects/sends, priorities or live voice controls
+- Rejected calls, startup glitches, voice/queue diagnostics, render-load measurements or source/artifact compatibility questions
 
 Example prompts:
 ```
 "Create a short sci-fi laser that sweeps left to right with ti.synthengine."
-"Design a clean two-note success cue for a Titanium button."
-"Build a playable xylophone that can glide across bars without retriggering the same note on every touchmove."
-"Create a layered 12-voice chord and stop its repeating pulse cleanly when the window closes."
-"Why does playTone return false when the object looks valid?"
-"Start the engine safely after my Alloy window lays out and clean it up on close."
+"Build a playable xylophone without retriggering a bar on every touchmove."
+"Move a held spatial motor and change its noise clock and low-pass cutoff without restarting it."
+"Run music and a victory cue as independent native sequences, then cancel only the cue."
+"Apply reverb to music while keeping UI dry, and change the global tempo."
+"Explain what the Android Sim80 headphone result proves about performance."
 ```
 
 Key rules:
-- Option objects are closed contracts. Unsupported keys, invalid types, non-finite values, or broken envelopes reject the whole call
-- Read waveform constants from `synth.getDefaults().waveTypes`; never guess numeric values or option names
-- `playTone` accepts `note` or `frequency`, never both; `playChord` accepts `notes` or `frequencies`, never both
-- `duration` includes attack, the full-level middle, and release, so explicit envelope times must intersect correctly
-- Use `frequencyEnd` for sweeps, `panEnd` for stereo movement, and `lfoFreq`/`lfoDepth` for pitch vibrato
-- Binaural headphone positioning uses `spatialX`/`spatialY` from -1 to 1, without pan fields. Omit both to keep stereo; check installed coordinate limits because older 1.0.0 builds lack this beta addition
-- Curated recipes cover retro effects, playable xylophone gestures, four-pad memory cues, controlled waveform comparisons, layered chords and cancellable repetition
-- Start after the first layout settles, keep one lifecycle owner, check Boolean returns, and call `shutdown()` on cleanup
+- Read constants and exact ranges from the API; strict option dictionaries reject invalid fields or conflicting pitch sources
+- Timed tone/chord `duration` includes release. Native sequence intervals and note lengths are separate; held voices release through their IDs
+- Schedule successive sounds with `playSequence`, retain positive accepted IDs and cancel the owner's sequence. `stopAll()` is global panic
+- `setTempo` drives beat-based transport and synchronized modulation; millisecond sequences keep fixed timing
+- `bus`/`applyTo` select processed categories; explicit `effectSend` overrides that selection. One shared chain and final limiter remain global
+- Held spatial position, noise clock and one-pole cutoff support compatible 10 ms updates. A stereo voice cannot become spatial through an update
+- Omit both spatial coordinates for stereo; zero coordinates enable binaural center. Do not combine binaural coordinates with stereo pan fields
+- Start after layout, keep one lifecycle owner, handle Boolean acceptance and sequence IDs, release held notes on cancellation and shut down during teardown
+- Current platform metadata, zero-envelope and diagnostic differences are documented. Host checks and a short accepted listening scene do not establish complete physical maximum-load acceptance
+
+The [retro recipes](skills/ti-synthengine/references/recipes.md) and [interaction/instrument recipes](skills/ti-synthengine/references/recipes-interaction.md) preserve acoustic intent, overlap budgets and cleanup. [Source notes](skills/ti-synthengine/references/source-notes.md) identify the reviewed native commit and evidence limits.
 
 ---
 
@@ -627,7 +650,7 @@ Codebase analysis (using agent):
 4. Mention constraints. "Build a settings screen. Must work offline and sync when connected."
 5. Reference existing code. "Here's my current controller. How can I improve memory management?"
 
-More examples: See [Example Prompts](EXAMPLE-PROMPTS.md) for detailed prompts that test each skill's capabilities.
+See [example prompts](docs/examples.md) for requests covering every public skill.
 
 ---
 
@@ -862,13 +885,18 @@ This pattern is documented across four bundled TiTools skills: `ti-ui`, `ti-expe
 | Skill     | SKILL.md                      | References                                            |
 | --------- | ----------------------------- | ----------------------------------------------------- |
 | ti-reuse-first | Reuse Before You Write   | 5 files (the ladder, Alloy reuse, indirection, PurgeTSS reuse, diagnostics) |
-| ti-expert | Architecture + Implementation | 26 files (patterns, feedback surfaces, file type association, sharing, testing, security, etc.) |
-| purgetss  | Setup + Critical Rules        | 34 files (Classic compatibility, grid, animations, icons, class-index, SVG pipeline, etc.) |
+| ti-expert | Architecture + Implementation | 27 files (patterns, feedback surfaces, file type association, sharing, testing, security, etc.) |
+| purgetss  | Setup + Critical Rules        | 39 files (Classic compatibility, grid, animations, icons, class-index, SVG pipeline, etc.) |
 | ti-ui     | UI Rules + Platform Diffs     | 14 files (layouts, lists, gestures, etc.)             |
-| ti-game   | Native 2D Game Workflow       | 9 files (API, setup, patterns, recipes, tile maps, debugging, roadmap) |
+| ti-game   | Native 2D Game Workflow       | 12 files (API, input, source notes, setup, physics, patterns, recipes, tile maps, debugging, roadmap) |
 | ti-game-assets | Visual and Sound Assets | 10 guides and a manifest example; alpha and contract validation scripts |
-| ti-admob-unified | Unified Advertising | 11 official module guides, source/hash update checks, official example library and game integration guidance |
-| ti-synthengine | Native Sound Synthesis   | 10 Markdown references (8 official, curated recipes, maintenance notes), raw statistics trials and a source hash manifest |
+| ti-admob-unified | Unified Advertising | 20 Markdown references including production, rewarded interstitial, mediation parity, integration library guidance, provenance and game monetization; source/hash checks and official example assets |
+| ti-synthengine | Native Sound Synthesis   | 12 Markdown references (9 official parts, 2 curated recipe guides, maintenance notes), complete validation reports/evidence and a reversible source hash manifest |
+| ti-api | Titanium API | 20 references for core/platform APIs and native modules |
+| ti-guides | SDK Fundamentals | 16 references for setup, configuration, CLI and distribution |
+| ti-howtos | Native Integrations | 18 references for platform features and integration workflows |
+| alloy-guides | Alloy MVC | 11 references for controllers, views, models, styling and widgets |
+| alloy-howtos | Alloy CLI and Debugging | 6 references for commands, configuration and practical workflows |
 
 ---
 
@@ -952,28 +980,8 @@ Note: `titools remove` can remove the knowledge index blocks from your project f
 
 ## Contributing
 
-1. Fork the repository
-2. Improve SKILL.md or reference files
-3. Test with your preferred AI coding assistant
-4. Submit a pull request
-
-### Guidelines
-- Keep SKILL.md concise (<500 lines)
-- Use progressive disclosure (details in references)
-- Include concrete examples
-- Test with real sessions
-
----
-
-## Legacy installation (not recommended)
-
-The bash installer is maintained for backward compatibility but NPM installation is recommended.
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/macCesar/titools/main/install.sh | bash
-```
-
-Use this only if you cannot use NPM for any reason.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development, skill registration,
+public repository boundaries and the release workflow.
 
 ---
 

package/agents/ti-pro.md

@@ -33,7 +33,7 @@ When invoked, research complex topics by consulting the applicable skills from t
 - `ti-ui` - UI/UX patterns, layouts, gestures
 - `ti-game-assets` - Visual and sound asset contracts, raster generation, alpha/export validation, synthesis variants and stereo coordination when assets are involved
 - `ti-game` - Native `ti.game` architecture and API when the module is declared
-- `ti-synthengine` - Native sound synthesis and strict `ti.synthengine` contract when the module is declared
+- `ti-synthengine` - Native synthesis, held voices, identified sequences/tempo, selective processing, live controls and platform/evidence limits when the module is declared or requested
 - `ti-admob-unified` - Official unified advertising/privacy/mediation module contract and provider setup when declared or requested
 - `ti-api`, `ti-guides`, `ti-howtos` - Exact Titanium APIs, SDK fundamentals and native integrations
 - `alloy-guides`, `alloy-howtos` - Alloy MVC, CLI, configuration and compiler workflows when the project is Alloy

package/commands/ti-audit.md

@@ -23,11 +23,11 @@ Project-type audit:
 Native-module audit:
 
 10. If the project declares `ti.game`, invoke `ti-game` — check for sprites moved from timers instead of native properties, levels sized from `Ti.Platform.displayCaps` instead of the `resize` event, sprites added one by one instead of in one array, and timers or sounds left running when the window closes.
-11. If the project declares `ti.synthengine`, invoke `ti-synthengine` — check strict option names and types, mutually exclusive pitch fields, valid envelope intersections, checked Boolean results, one clear lifecycle owner, delayed startup after layout, app-owned timer cancellation, and `shutdown()` cleanup.
+11. If the project declares `ti.synthengine`, invoke `ti-synthengine` — check exact option/pitch/envelope contracts, Boolean acceptance and positive sequence IDs, native successive-note scheduling, per-owner sequence cancellation, held-note release/cancellation and compatible live updates. Check shared tempo versus millisecond timing, category/send selection, overlap/priority budgets, one lifecycle owner, delayed startup and teardown. Consult current source notes before assuming platform metadata/envelopes or rejection diagnostics match; separate host/load reports from scoped physical listening acceptance.
 
 12. If the project has game art/sound inventories or asset-generation/export workflows, invoke `ti-game-assets` — check contracts per set, master provenance/transparency, protected alpha cleanup, frame/pivot alignment, complete derived exports, parallax layers, sound variants and semantic event bindings. Consult `ti-game` and `ti-synthengine` equally in their applicable domains; do not require module installation or new sounds for an image-only task.
 
-13. If the project declares `ti.admob.unified`/mediation complements or implements an ad flow through this module, invoke `ti-admob-unified` — verify official module APIs, consent/request eligibility/initialization, test IDs, banner layout and refresh ownership, deliberate fullscreen presentation, callback cleanup and selected-provider mappings. Separate linking, Google test ads, provider delivery and physical acceptance. In games preserve native pause/audio/input ownership and the existing frequency policy.
+13. If the project declares `ti.admob.unified`/mediation complements or uses this module, invoke `ti-admob-unified` — verify public release/platform requirements, consent/request eligibility/initialization, ATT status versus permission, test IDs, independent banner lifecycle and deliberate fullscreen ownership. Check rewarded interstitial's reward introduction, visible Skip, reward-event credit and pending-context cancellation. Use the production guide for app IDs, app-ads.txt, privacy entry points and account readiness. Separate linking, Google test ads, selected-provider delivery and physical acceptance; preserve game frequency and pause/audio/input policy.
 
 If a conditional skill does not apply, record it as `not applicable` with the detected reason instead of inventing findings from it.
 

package/docs/examples.md

@@ -0,0 +1,91 @@
+# Example prompts
+
+Use these requests as starting points with an assistant that has TiTools installed.
+Mention the framework, module and platform involved. Conditional skills apply
+when the project uses that technology; an image request does not require adding
+an audio or advertising module.
+
+## Reuse and simplification — ti-reuse-first
+
+- "Find whether this Alloy project already has a suitable confirmation panel before adding another one."
+- "Review these repeated controller wrappers and explain which can be simplified without changing behavior."
+
+## Architecture — ti-expert
+
+- "Organize this Alloy screen so navigation, data access and view state have clear owners."
+- "Review this controller for timer, listener and window lifecycle leaks."
+
+## PurgeTSS — purgetss
+
+- "Style this Alloy layout with the PurgeTSS classes supported by the installed version."
+- "Prepare responsive images for this Classic Titanium project using the supported PurgeTSS asset workflow."
+
+## Native UI — ti-ui
+
+- "Build a ListView with reusable templates and predictable row heights."
+- "Check this window's safe-area, orientation and gesture handling on Android and iOS."
+
+## Native games — ti-game
+
+- "Build a platformer using native velocity, gravity and collision events instead of a JavaScript frame loop."
+- "Map keyboard and gamepad input to named actions while keeping native text-field focus usable."
+
+## Visual and sound assets — ti-game-assets
+
+- "Prepare a consistent sprite sheet, animation frames and three-layer parallax set for this game."
+- "Create three related pickup sound variants and an asset manifest with export and listening checks."
+
+## Native synthesis — ti-synthengine
+
+- "Install the public TiSynthEngine 1.0.0 Android/iOS packages and start audio after the window layout settles."
+- "Move a held spatial motor, process only music with reverb, and stop one native sequence without cancelling unrelated sounds."
+
+Use the [synthesis skill](../skills/ti-synthengine/SKILL.md) for exact options,
+public downloads and scoped performance evidence. Native sequence scheduling,
+held-voice ownership and historical/private artifacts have distinct contracts.
+
+## Advertising — ti-admob-unified
+
+- "Install public ti.admob.unified 1.0.0 on Android/iOS and configure consent-first startup with the official integration library."
+- "Offer a rewarded interstitial at a natural transition with a clear reward, a visible Skip option and cancellation when the screen changes."
+- "Check selected mediation providers and production readiness, including app IDs, app-ads.txt and privacy options, without treating Google test ads as provider acceptance."
+
+Use the [public Android](https://github.com/macCesar/ti.admob.unified/releases/tag/android-1.0.0)
+and [iOS](https://github.com/macCesar/ti.admob.unified/releases/tag/ios-1.0.0)
+packages and the [module skill](../skills/ti-admob-unified/SKILL.md). A synchronous
+ATT query is separate from UMP eligibility; Android's ATT convention is not
+permission for general tracking. Real account/provider delivery needs its own
+validation beyond the module's publication.
+
+## Exact Titanium APIs — ti-api
+
+- "Verify the supported properties and event payloads for this Titanium ListView implementation."
+- "Check this platform-specific API call against the SDK version used by the project."
+
+## SDK fundamentals — ti-guides
+
+- "Check this tiapp.xml and explain the relevant build and platform requirements."
+- "Set up the CommonJS modules and assets for a maintainable Classic Titanium project."
+
+## Native integrations — ti-howtos
+
+- "Implement location permissions and lifecycle handling for this Android/iOS app."
+- "Review this camera and file-sharing flow, including its required platform configuration."
+
+## Alloy MVC — alloy-guides
+
+- "Separate the controller, XML view and TSS responsibilities on this Alloy screen."
+- "Explain how this model collection, binding and cleanup should work."
+
+## Alloy tools — alloy-howtos
+
+- "Generate an Alloy controller and place its files according to the documented project structure."
+- "Diagnose this Alloy compilation error and check the relevant CLI and configuration options."
+
+## Combining skills
+
+"Review an Alloy game that uses PurgeTSS, ti.game and ti.synthengine. Start with
+existing components, then check scene input, native audio ownership and cleanup
+using the appropriate references."
+
+See [how the knowledge index works](knowledge-index.md) for reference discovery.

package/docs/knowledge-index.md

@@ -0,0 +1,57 @@
+# Skills and the knowledge index
+
+TiTools provides task-oriented skills and reference documents for Titanium SDK,
+Alloy and related native modules. A skill describes when its workflow applies;
+its references supply the details needed for that task.
+
+The optional knowledge index helps an assistant find the available references
+from the consuming project's instruction files. It is navigation, not a copy
+of every reference and not a promise about an assistant's answer accuracy.
+
+## Generate an index
+
+From a Titanium project containing `tiapp.xml`, run:
+
+```sh
+titools sync
+```
+
+Select the applicable instruction files, such as `AGENTS.md`, `CLAUDE.md` or
+`GEMINI.md`. TiTools maintains a delimited index block rather than replacing the
+project's other instructions. Re-running sync updates that block.
+
+Do not run project sync from the TiTools source repository. Installing skills
+and generating an index in a consuming app are separate operations.
+
+## Choose the relevant skills
+
+The catalog contains thirteen public skills:
+
+| Task | Skill |
+| --- | --- |
+| Reuse and simplification | `ti-reuse-first` |
+| Architecture and implementation | `ti-expert` |
+| PurgeTSS styling and assets | `purgetss` |
+| Titanium UI | `ti-ui` |
+| Native game behavior | `ti-game` |
+| Visual and sound asset production | `ti-game-assets` |
+| Native synthesis | `ti-synthengine` |
+| Unified advertising | `ti-admob-unified` |
+| Exact Titanium APIs | `ti-api` |
+| SDK fundamentals | `ti-guides` |
+| Native integrations | `ti-howtos` |
+| Alloy MVC | `alloy-guides` |
+| Alloy CLI and debugging | `alloy-howtos` |
+
+Conditional scopes depend on the app. A Titanium project does not automatically
+need PurgeTSS, games, synthesis or advertising. The `ti-pro` research agent can
+combine the relevant references for questions that cross those boundaries.
+
+## Keep references current
+
+Update the installed TiTools package and use `titools update` to refresh installed
+content. Use `titools status` and `titools doctor` to inspect installation health.
+An index cannot establish which native module binary is installed: check that
+module's release and artifact contract separately.
+
+See [example prompts](examples.md) and the [CLI documentation](../README.md).

package/lib/downloader.js

@@ -99,7 +99,7 @@ export async function downloadRepoArchive(destDir, ref = 'main') {
 
 /**
  * Download a single file from GitHub raw content
- * @param {string} filePath - Path in repository (e.g., 'AGENTS-VERCEL-RESEARCH.md')
+ * @param {string} filePath - Path in repository (e.g., 'docs/knowledge-index.md')
  * @param {string} destPath - Local destination path
  * @param {string} ref - Git ref (branch, tag, commit)
  * @returns {Promise<void>}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maccesar/titools",
-  "version": "5.2.0",
+  "version": "5.2.1",
   "description": "Titanium SDK skills and agents for AI coding assistants, including native game and sound synthesis modules",
   "main": "lib/index.js",
   "type": "module",
@@ -63,7 +63,9 @@
     "skills/",
     "agents/",
     "commands/",
-    "AGENTS-VERCEL-RESEARCH.md"
+    "CONTRIBUTING.md",
+    "docs/examples.md",
+    "docs/knowledge-index.md"
   ],
   "publishConfig": {
     "access": "public"

package/skills/purgetss/references/multi-density-images.md

@@ -360,7 +360,7 @@ If your source images live elsewhere (e.g. next to your design files in `docs/sc
 
 ```bash
 purgetss images ./docs/screenshots/home-hero.png
-purgetss images /Users/cesar/Design/banner.svg
+purgetss images /path/to/design/banner.svg
 ```
 
 When the source is outside `purgetss/images/`, subdirectory preservation uses the directory of the source file as the root instead. Processing that external source in Classic does not bootstrap unrelated PurgeTSS folders or config.

package/skills/ti-admob-unified/SKILL.md

@@ -1,11 +1,21 @@
 ---
 name: ti-admob-unified
-description: "Use when a Titanium app declares ti.admob.unified or its mediation complements, imports require('ti.admob.unified'), or asks to integrate/configure AdMob banners, interstitials, rewarded or app-open ads, UMP/ATT, privacy options, lifecycle, ad frequency or AppLovin, Meta, InMobi, Unity and Liftoff mediation with this module. Applies to Alloy and Classic on Android/iOS."
+description: "Use when a Titanium app declares ti.admob.unified or its mediation complements, imports require('ti.admob.unified'), or asks to integrate/configure AdMob banners, interstitials, rewarded, rewarded interstitial or app-open ads, UMP/ATT, privacy options, lifecycle, ad frequency or AppLovin, Meta, InMobi, Unity and Liftoff mediation with this module. Applies to Alloy and Classic on Android/iOS."
 ---
 
 # ti.admob.unified — ads, privacy and providers
 
-Integrate César's unified Titanium module using its official documentation and maintained application library. The local **1.0.0** contract is preparing for its first public release; do not claim a public release or usable production demand from these snapshots. Sources are pinned to **`5b4cbf9347a51c4f959dc262ac1500f82f28b4a0`**, copied 2026-10-11. See `references/source-snapshot.json` for paths/hashes and [references/source-notes.md](references/source-notes.md) for provenance and update checks. Check the installed build and current sources when behavior differs.
+Use the public **ti.admob.unified 1.0.0** module through its official
+[repository](https://github.com/macCesar/ti.admob.unified),
+[Android release](https://github.com/macCesar/ti.admob.unified/releases/tag/android-1.0.0)
+and [iOS release](https://github.com/macCesar/ti.admob.unified/releases/tag/ios-1.0.0).
+Reviewed released source: `034843299b2984253988e0ffccb9f6a1c91682c9` (2026-10-24).
+The core supports banners, interstitial, rewarded, rewarded interstitial and
+app-open formats; install only the mediation complements the app uses.
+Requires **Titanium 13.4.1.GA**, iOS 15+, Android API 24+ (compile SDK 36).
+Apple packages target iOS, not Mac Catalyst. See [source notes](references/source-notes.md)
+and the [snapshot](references/source-snapshot.json) for provenance and validation
+boundaries. Public module availability does not establish production ad eligibility.
 
 ## Required workflow
 
@@ -19,9 +29,12 @@ Read the relevant references before proposing calls or configuration. Do not inf
 | Consent-first startup, ATT, privacy options, request eligibility | [references/privacy.md](references/privacy.md) |
 | Fixed/adaptive banners, real reserved layout and pause/cleanup | [references/banners.md](references/banners.md) |
 | Interstitial/rewarded/app-open load/show, rewards and cleanup | [references/fullscreen.md](references/fullscreen.md) |
-| Select/install providers, publisher accounts, mappings, diagnostics | [references/mediation.md](references/mediation.md), [references/dependencies.md](references/dependencies.md) |
+| Rewarded interstitial introduction, visible Skip, rewards and cancellation | [references/rewarded-interstitial.md](references/rewarded-interstitial.md), [references/fullscreen.md](references/fullscreen.md) |
+| Production IDs, app-ads.txt, store/AdMob readiness and final-build checks | [references/production.md](references/production.md) |
+| Select/install providers, publisher accounts, mappings, diagnostics | [references/mediation.md](references/mediation.md), [references/dependencies.md](references/dependencies.md), [references/mediation-parity.md](references/mediation-parity.md) |
 | Replace legacy modules or internal builds | [references/migration.md](references/migration.md) |
 | Unsupported formats, extending providers, license/distribution | [references/roadmap.md](references/roadmap.md), [references/contributing.md](references/contributing.md), [references/third-party-notices.md](references/third-party-notices.md) |
+| Official docs index and release history | [references/index.md](references/index.md), [references/module-changelog.md](references/module-changelog.md) |
 | Game experience and frequency decisions | [references/game-monetization.md](references/game-monetization.md), plus fullscreen/privacy |
 
 Cite factual guidance with `[source: references/<file>.md]`. If the relevant source is unavailable, mark the claim `FROM_MEMORY (unverified):` and do not invent a method or provider setting.
@@ -30,12 +43,13 @@ Cite factual guidance with `[source: references/<file>.md]`. If the relevant sou
 
 - Inspect `tiapp.xml`, installed artifacts, project type and existing ad owner before adding another boundary. Use `ti-guides`/`ti-howtos`, Alloy or UI skills as applicable.
 - Prefer the official copy-ready `assets/example/lib/ads.js`: copy unchanged to Alloy `app/lib/ads.js` or Classic `Resources/lib/ads.js`. Its documentation imports `require('lib/ads')`; preserve its path and provenance. `assets/example/library-usage.js` and `assets/example/app.js` are official integration evidence, not navigation templates to paste wholesale.
-- Follow the documented UMP → request eligibility → initialization sequence. `canRequestAds()` is the gate, not ATT status or a guessed personalization flag. Resolve requested ATT separately; do not request it without an actual use case. Preserve privacy options and named-listener cleanup.
+- Follow UMP → optional foreground ATT → `canRequestAds()` → initialization/loading. A UMP error can retain prior eligibility; check the gate. `getTrackingAuthorizationStatus()` reads ATT without prompting or initializing. Android reports `applicable:false`; its `authorized:true` convention does not grant general tracking permission. The library defers ATT to `resumed` when needed. Preserve privacy options and named-listener cleanup.
 - Application IDs and ad-unit IDs are different. Use documented test IDs during development; do not switch to production IDs as an incidental fix.
-- Native activity/app lifecycle and SDK banner refresh belong to the module/Google. The app owns tab/window coverage and reserved layout. Do not add refresh timers or duplicate background handlers for banners.
-- Separate loading from deliberate fullscreen presentation. Do not show from a load callback. Coordinate game clock/audio/inputs and ad ownership; handle no-fill, failed presentation, actual close and destroyed screens without repeated ads or late navigation.
+- Preserve banners during Android's `_closeFromActivityForcedToDestroy` event; ordinary close still destroys the owner. Each banner manager has independent coverage/background state. Native activity/app lifecycle and SDK banner refresh belong to the module/Google. The app owns tab/window coverage and reserved layout. Do not add refresh timers or duplicate background handlers for banners.
+- Separate preloading from deliberate presentation. Loading alone never authorizes showing. An explicit pending Show intent must expire with its presentation context. Coordinate game clock/audio/inputs, no-fill, show failure, close and destroyed screens. Raw `load()`/`show()` are void; manager Boolean returns describe its attempt, not delivery. A stale-size rejection reloads but does not queue manager presentation. `autoReload` is a live close policy that loads another ad, never presents it.
+- Rewarded interstitial requires an accurate reward introduction and a visible Skip option. Present only while that introduction remains valid; credit only `rewarded`, not close/impression/click. Cancel pending introductions on background, lost eligibility, navigation or another fullscreen. Reward handling may need to survive screen changes for an already-presented ad.
 - Install only selected mediation complements on each target platform. All application calls use `ti.admob.unified`. Configure provider accounts and AdMob mappings; neither a packaged adapter nor `ready` diagnostics nor a Google test ad proves provider delivery. Do not invent placeholder keys, manual provider initializers or an `enableMediation` option.
-- Consult the roadmap before suggesting native ads, rewarded interstitial or a network outside the distributed set. Supporting several formats does not justify enabling all of them in a game.
+- Consult the roadmap before suggesting native ads, deferred ironSource or a network outside the distributed set. Supporting several formats does not justify enabling all of them in a game.
 
 ## Acceptance