aso: competitors, suggest and audit from official data; ASO card on the Growth tab

- aso competitors: top apps per keyword from the iTunes Search API (name, developer,
  rating count, release / update dates, localized genre), coverage gaps (words of 2+
  developers), new entrants vs the last snapshot (.storebound/aso/competitors/)
- aso suggest: candidates from own text, competitor names, localized category names and
  Apple Ads keyword suggestions (POST /v1/suggestions/keywords/query, relative 0-100
  popularity, only with credentials); 100-byte keyword field per locale as a diff,
  --write marks it a draft that check --aso and aso audit report
- aso audit: check --aso, free keyword room, rank trend arrows, gaps, Play short
  description / density, App Store conversion, PPO / Play experiment ideas, next 3 actions
- MCP: read-only aso_competitors, aso_suggest, aso_audit; desktop ASO card (visx rank chart)
- docs: README, aso-basics, store-pitfalls (Search API order, no Play search API), CHANGELOG;
  demo-app listing files; tests on recorded Search API and mocked Ads answers

skills/store-pitfalls/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: store-pitfalls
-description: Known pitfalls with App Store Connect, Google Play and storebound itself, learned from real releases, and what to do about each - store lists that lag right after a create, dry runs that print a count instead of a plan, App Store names taken on a storefront, keyword limits in bytes, Data safety answers without code evidence, missing font glyphs in screenshots, console sign-in and sessions, Capacitor monorepo plugins. Read it before any store task, and when a store command does something you did not expect.
+description: Known pitfalls with App Store Connect, Google Play and storebound itself, learned from real releases, and what to do about each - store lists that lag right after a create, dry runs that print a count instead of a plan, App Store names taken on a storefront, keyword limits in bytes, Data safety answers without code evidence, missing font glyphs in screenshots, console sign-in and sessions, Capacitor monorepo plugins, App Store search ranks that are only a trend, Play without a search API. Read it before any store task, and when a store command does something you did not expect.
 ---
 
 # Store pitfalls
@@ -67,6 +67,22 @@ Each entry: **symptom** → cause → what to do → what guards it now. The ful
 - **Do:** run `scan` from the project root; check that the stack line lists the plugins.
 - **Guard:** `storebound scan` and `privacy-manifest` resolve packages through workspace folders too.
 
+## 9. "We rank #4 for this keyword" (from the Search API)
+- **Symptom:** `aso rank` says #4, the owner's phone shows the app lower (or higher) in App Store search.
+- **Cause:** the iTunes Search API order is close to, not equal to, App Store search: no personalisation, no search
+  ads, no in-app event rows. It has no subtitle field either.
+- **Do:** read ranks as a trend over weeks (`aso audit` arrows), never as a promise; never claim a competitor's
+  subtitle (no public API has it); a popularity number exists only from Apple Ads, never estimate one.
+- **Guard:** `aso rank`, `aso competitors` and `aso audit` say it in their output; `aso suggest` shows popularity
+  "unknown" without Apple Ads credentials.
+
+## 10. "Check our Google Play keyword ranks"
+- **Symptom:** the owner asks for Play ranks or Play competitors per keyword.
+- **Cause:** Google Play has no public search API; reading Play search pages would be scraping.
+- **Do:** say so. Measure Play through the Play Console acquisition reports (search terms) and `analytics snapshot`
+  (store listing visitors, acquisitions); improve the listing text with `aso audit` (short description, density).
+- **Guard:** `aso` covers App Store search only; the aso-basics skill states the limit.
+
 ## Adding a lesson
 Every bug found in real use gets an entry in `docs/pitfalls.md` and here, and, where possible, a check or a test
 that fails without the fix (see CONTRIBUTING.md).