@maccesar/titools 5.1.1 → 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

@@ -6,13 +6,13 @@
 
 </div>
 
-TiTools is a Titanium SDK toolkit for AI coding assistants. It ships 11 skills — 6 specialist skills (`ti-reuse-first`, `ti-expert`, `purgetss`, `ti-ui`, `ti-game`, `ti-synthengine`) plus 5 documentation-mirror skills (`ti-api`, `ti-guides`, `ti-howtos`, `alloy-guides`, `alloy-howtos`) — a research agent, and reference files covering reuse and simplification, Titanium architecture, API reference, native how-tos, Alloy MVC, PurgeTSS styling and resource automation, UI/UX patterns, 2D games, and native sound synthesis.
+TiTools is a Titanium SDK toolkit for AI coding assistants. It ships 13 skills — 8 specialist skills (`ti-reuse-first`, `ti-expert`, `purgetss`, `ti-ui`, `ti-game`, `ti-game-assets`, `ti-synthengine`, `ti-admob-unified`) plus 5 documentation-mirror skills (`ti-api`, `ti-guides`, `ti-howtos`, `alloy-guides`, `alloy-howtos`) — a research agent, and reference files covering reuse and simplification, Titanium architecture, API reference, native how-tos, Alloy MVC, PurgeTSS styling and resource automation, UI/UX patterns, 2D games, and native sound synthesis.
 
 The reference files are maintained against official documentation whenever an official source exists, so the assistant can retrieve current framework behavior instead of guessing from generic training data. As of v5.0.0 those sources are the Titanium SDK's own API definitions and the rewritten guides at [titaniumsdk.com](https://titaniumsdk.com). [Where the references come from](#where-the-references-come-from) has the detail.
 
 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).
 
 ---
 
@@ -36,7 +36,7 @@ The fastest way to get started with Claude Code. One command to add the marketpl
 ```
 
 What you get:
-- All 11 TiTools skills (`ti-reuse-first`, `ti-expert`, `purgetss`, `ti-ui`, `ti-game`, `ti-synthengine`, `ti-api`, `ti-guides`, `ti-howtos`, `alloy-guides`, `alloy-howtos`)
+- All 13 TiTools skills (`ti-reuse-first`, `ti-expert`, `purgetss`, `ti-ui`, `ti-game`, `ti-game-assets`, `ti-synthengine`, `ti-admob-unified`, `ti-api`, `ti-guides`, `ti-howtos`, `alloy-guides`, `alloy-howtos`)
 - ti-pro research agent
 - Session hook that auto-detects Titanium projects (`tiapp.xml`, Alloy, PurgeTSS, `ti.game`, `ti.synthengine`)
 - Slash commands: `/ti-check`, `/ti-new-screen`, `/ti-audit`
@@ -70,7 +70,7 @@ claude   # or gemini, or codex
 ```
 
 What gets installed:
-- The 10 TiTools skills to `~/.agents/skills/`
+- The 13 TiTools skills to `~/.agents/skills/`
 - ti-pro agent for Claude Code
 - Platform symlinks for Claude Code (Gemini CLI and Codex CLI auto-discover from `~/.agents/skills/` — no symlinks needed)
 - Knowledge index in your project's `AGENTS.md`/`CLAUDE.md`/`GEMINI.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,8 +170,10 @@ 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-synthengine | Sound design with `ti.synthengine` | Tones, chords, retro/UI effects, alarms, sweeps, patterns, mixing and troubleshooting |
+| 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, 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 |
 | ti-howtos    | Native feature integration          | Location, push, media, platform APIs    |
@@ -187,10 +181,11 @@ The knowledge index is based on the latest Titanium SDK documentation. If your p
 | alloy-howtos | Alloy CLI, configuration, debugging | alloy.jmk, config.json, custom XML tags |
 
 Notes:
-- The first six (`ti-reuse-first`, `ti-expert`, `purgetss`, `ti-ui`, `ti-game`, `ti-synthengine`) are specialist workflow skills reflecting TiTools' Titanium conventions and native-module contracts.
+- 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 module. Seven references preserve the official documentation and an eighth adds curated retro, xylophone, memory-pad, polyphony and timer-ownership recipes; the API contract was cross-checked against both native implementations.
+- `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.
 
@@ -225,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:
 
@@ -274,7 +269,7 @@ TiTools provides slash commands for common tasks. Both channels ship them: the p
 These commands automatically invoke the relevant skills:
 - `/ti-check` reads `tiapp.xml`, validates declared native modules, and reports project health
 - `/ti-new-screen` uses `ti-expert` + `purgetss` to create properly structured files
-- `/ti-audit` routes all 11 skills: the reuse sweep first, core Titanium checks always, Alloy/PurgeTSS checks when detected, integration how-tos when used, and `ti-game` / `ti-synthengine` checks when those modules are declared
+- `/ti-audit` routes all 13 skills: the reuse sweep first, core Titanium checks always, Alloy/PurgeTSS checks when detected, integration how-tos when used, `ti-game-assets` checks for game asset workflows, and `ti-game` / `ti-synthengine` / `ti-admob-unified` checks when those modules are declared
 
 ---
 
@@ -318,6 +313,8 @@ All skills include automatic project detection to ensure compatibility:
 | ti-expert | Alloy vs Classic      | Checks for `app/` (Alloy) vs `Resources/` (Classic) structure |
 | ti-ui     | Titanium projects     | Checks for `tiapp.xml` (both Alloy and Classic)               |
 | ti-game   | ti.game module        | Checks for `<module>ti.game</module>` in `tiapp.xml` or `require('ti.game')` |
+| ti-game-assets | Game art/sound workflows | Reads asset inventories, generation/export workflows and requested visual or sound assets; no module install required for drawings |
+| ti-admob-unified | ti.admob.unified and mediation | Declared core/complement modules or requested ad/privacy/provider integration |
 | ti-synthengine | ti.synthengine module | Checks for `<module>ti.synthengine</module>` in `tiapp.xml` or `require('ti.synthengine')` |
 
 Why this matters:
@@ -333,11 +330,12 @@ Why this matters:
 | --- | --- |
 | Whether to build it at all | `ti-reuse-first`, first |
 | Architecture and UI | `ti-expert`, `ti-ui`, `purgetss` when configured |
-| Native modules | `ti-game`, `ti-synthengine` when declared |
+| Game assets | `ti-game-assets` for visual and sound creation, preparation and integration |
+| Native modules | `ti-game`, `ti-synthengine`, `ti-admob-unified` when declared or requested |
 | Exact SDK/API guidance | `ti-api`, `ti-guides`, `ti-howtos` |
 | Alloy MVC and tooling | `alloy-guides`, `alloy-howtos` for Alloy projects |
 
-All eleven ship with TiTools; no second skill package is required.
+All thirteen ship with TiTools; no second skill package is required.
 
 ---
 
@@ -454,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')`
@@ -472,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:
 ```
@@ -502,33 +501,87 @@ Key rules:
 
 ---
 
+### ti-game-assets
+
+Create game art and sound assets as a coherent set: transparent HD masters or strict logical-grid pixel art, animation states, three-layer parallax, synthesized effects/music/ambience, related sound variants and screen-position stereo. `ti-game` owns native game behavior and `ti-synthengine` owns the sound contract; the asset skill coordinates both.
+
+For the processing helpers and development tests, install Python dependencies in a virtual environment:
+
+```bash
+python3 -m venv /tmp/titools-assets-env
+/tmp/titools-assets-env/bin/pip install -r skills/ti-game-assets/scripts/requirements.txt
+TITOOLS_ASSETS_PYTHON=/tmp/titools-assets-env/bin/python npm test
+```
+
+Raster drawing generation/editing uses integrated `image_gen`. Authored SVG/procedural pipelines preserve editable sources and deterministically export PNG; offline synthesis can generate WAV. The bundled Python helpers validate alpha, SVG provenance, hashes and WAV headers/payloads. Cleaning writes new files and requires a reviewed protected region or an explicit defined-edge trial. Sound recipes remain source assets even without recorded audio files. Guides cover seamless texture/audio loops and responsible ad transitions through the separate `ti-admob-unified` skill. Technical checks, visual inspection and device listening are reported separately.
+
+### ti-admob-unified
+
+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 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
+- 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
-- 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.
 
 ---
 
@@ -597,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.
 
 ---
 
@@ -627,7 +680,7 @@ Behavior depends on where you run it:
 | With `--local` flag        | Installs skills locally to `./.agents/skills/` in the current project |
 
 What it does:
-- Installs the 10 TiTools skills (global or local depending on context)
+- Installs the 13 TiTools skills (global or local depending on context)
 - Installs ti-pro agent for Claude Code
 - Installs the `/ti-check`, `/ti-new-screen` and `/ti-audit` slash commands into `~/.claude/commands/`
 - Detects installed AI platforms and lets you choose which to link (only Claude Code needs platform symlinks; Gemini CLI and Codex CLI auto-discover from `~/.agents/skills/`)
@@ -832,11 +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-synthengine | Native Sound Synthesis   | 8 files (API, sound design, lifecycle, engine, official examples, curated recipes, recommendations, troubleshooting) |
+| 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 | 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 |
 
 ---
 
@@ -920,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

@@ -7,7 +7,9 @@ skills:
   - purgetss
   - ti-ui
   - ti-game
+  - ti-game-assets
   - ti-synthengine
+  - ti-admob-unified
   - ti-api
   - ti-guides
   - ti-howtos
@@ -29,8 +31,10 @@ When invoked, research complex topics by consulting the applicable skills from t
 - `ti-expert` - Architecture, patterns, conventions
 - `purgetss` - Utility-first styling classes (optional add-on; use when the project already has it or the user asks about it)
 - `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,7 +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 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/config.js

@@ -35,7 +35,9 @@ export const SKILLS = [
   'purgetss',
   'ti-ui',
   'ti-game',
+  'ti-game-assets',
   'ti-synthengine',
+  'ti-admob-unified',
   'ti-api',
   'ti-guides',
   'ti-howtos',

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>}