storebound/skills/store-pitfalls/SKILL.md

---
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, duplicates from retries, re-runs and parallel runs, App Store search ranks that are only a trend, Play without a search API, Play's Create app form (no API, opener and submit share a name, Free is final), App Privacy purposes over-mapped (Play advertising is Third-Party Advertising only), an unknown console page (bounded wait and a debug dump), a signed-in console read as a sign-in page (Google account widget frames). Read it before any store task, and when a store command does something you did not expect.
---

# Store pitfalls

Each entry: **symptom** → cause → what to do → what guards it now. The full changelog of lessons with dates is
`docs/pitfalls.md` in the storebound repository. When you hit a new one, tell the owner and add it there (and here).

## 1. A product you just created is "not there"
- **Symptom:** `apple iap-review` uploads nothing for a product `apple iap` created a minute ago; a list looks short.
- **Cause:** App Store Connect's `/inAppPurchasesV2` list (and Play's product list) can lag for a short while after a
  create. A command that walks the list skips what is not in it yet.
- **Do:** wait a minute and re-run. Never assume a product was handled because the command finished.
- **Guard:** `apple iap-review` compares the config's products with the store's list, names the missing ones
  ("the store's list can lag a minute after creating; re-run") and exits 1. `apple iap` and `play products` read the
  list again after creating and warn about any new product that is not in it yet; their dry runs name products that
  are not on the store.

## 2. A dry run that only prints a count
- **Symptom:** `--dry` says "listing: 20 locales" or "3 change(s)", but not which fields would change to what.
- **Cause:** the command logged a summary instead of the plan.
- **Do:** never ask the owner to approve a count. Show the rows that change (item, action, old → new). If a command
  only prints a count, say so and show the owner the diff from `pull` / `--json` output instead.
- **Guard:** `cli/lib/dry.ts` `dryPlan(title, rows)` prints the standard plan table (`apple iap`, `apple iap-review`,
  `play products` use it); `tests/pitfalls.test.ts` scans `cli/**` for `--dry` branches that print nothing but a count.

## 3. "The app name you entered is already being used"
- **Symptom:** creating the App Store record or saving the name fails although you own no app with that name.
- **Cause:** App Store app names are unique per storefront, across all developers.
- **Do:** ask the owner for a variant (a short suffix such as "Example Notes: Lists") and set `apple.name` in the config;
  keep `app.name` for Play and the brand. Do not pick the suffix yourself.
- **Guard:** `apple.name` overrides the App Store name.

## 4. Keyword field "too long" at fewer than 100 characters
- **Symptom:** App Store Connect rejects keywords that look short enough, mostly in Turkish, German, CJK.
- **Cause:** the 100 limit counts UTF-8 bytes, not characters ("ş" is 2 bytes, a CJK character 3).
- **Do:** shorten by bytes; drop words, not commas.
- **Guard:** `storebound check` counts bytes for keywords.

## 5. Data safety says "email collected" for an app that never asks for one
- **Symptom:** the proposal marks email (or phone) as collected because the app has accounts.
- **Cause:** account features do not imply email collection (anonymous ids, Game Center, Play Games sign-in).
- **Do:** answer only what the code proves; ask the owner for the rest (rule 5).
- **Guard:** `storebound scan` marks email only with evidence (an email field, an email sign-up call) and otherwise
  says "ask owner".

## 6. Boxes or wrong glyphs in localized screenshots
- **Symptom:** Turkish, Polish or Vietnamese captions show fallback glyphs (ş, ğ, ł, ệ) while the English ones are fine.
- **Cause:** the font (or the Google Fonts subset that was downloaded) does not cover those characters, and the
  browser silently draws them with another font.
- **Do:** check every language's characters before rendering, pick a font that covers them or let the fallback fill in.
- **Guard:** `storebound shots fonts` / `shots check` check each language's characters against the fonts' glyphs.

## 7. Console automation stops at sign-in or loses the session
- **Symptom:** `console fill` waits on a sign-in page, cannot find fields, or is signed out on the next run.
- **Cause:** the App Store Connect sign-in runs inside an `idmsa.apple.com` iframe; "User Access" is a plain heading,
  not a labeled group; Chrome drops session cookies unless the last session is restored.
- **Do:** let the owner sign in in the opened window (never type credentials); re-run after the sign-in.
- **Guard:** the console session handles the iframe and the plain heading and starts Chrome with
  `--restore-last-session`; a partial miss fills every field found and leaves only the missing ones to the owner.

## 8. `scan` misses Capacitor plugins in a monorepo
- **Symptom:** SDKs or privacy manifests of Capacitor plugins are not found.
- **Cause:** the plugins live in `apps/native/node_modules` (a workspace package), not in the root `node_modules`.
- **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. A second run (or a retry) creates a duplicate
- **Symptom:** two in-app purchases or subscription groups with the same name, a screenshot twice in a set, an
  offer code campaign or a custom product page twice, after a timeout, a crash, a re-run a minute later, or two runs
  at once.
- **Cause:** a POST create retried after a timeout or a 5xx may have been applied the first time; the store's lists lag
  right after a create, so a re-run does not see what the last run made; two writers race; a Play edit redone after
  a commit whose answer was lost.
- **Do:** just run the command again: every write command is an upsert and converges (`docs/idempotency.md`). Never
  retry a create by hand (`storebound api`) without a GET first. If a run says another storebound run holds the lock,
  wait for it; use `--force-unlock` only when that run is really gone. Never run two write commands for the same app
  in parallel.
- **Guard:** `cli/lib/upsert.ts` (findOrCreate: fresh re-check + journal `.storebound/created.json`; createOnce: 409
  = found, an unclear answer is looked up, never re-sent blindly), retries only for requests that are safe twice,
  Play edits deleted on every error and never redone after an unclear commit, screenshot / preview sets keep the
  matching prefix in order, `.storebound/locks/` per app and store. `tests/idempotency.test.ts`.

## 10. "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.

## 11. "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.

## 12. A new Play app: "Create app" is both the opener and the submit
- **Symptom:** an agent cannot create the Play app through the API, or clicks "Create app" without knowing whether it
  opens the form or submits it; or an app goes out as Free and the owner later wants it paid.
- **Cause:** the Play Developer API cannot create apps. Play Console's Home has a "Create app" button that opens the
  form, and the form's final button has the same words. Free cannot become Paid later on Google Play. The package
  name is not in this form: the first AAB upload sets it.
- **Do:** `storebound console fill play-app-record` (pick the account with `play.developerId` or
  `play.developerAccount`); tell the owner that Free is final; the owner ticks the declarations and presses Create
  app; then `storebound play upload --track internal` (or `flow run release`) sets the package name.
- **Guard:** `createAppAllowed` lets the opener through only on the app list, never inside a form or dialog (English
  and Turkish); agreement checkboxes are never ticked; Free or paid is outlined as an owner check.

## 13. App Privacy purposes over-mapped
- **Symptom:** App Privacy says Developer's Advertising or Marketing for Device ID, Coarse Location, Product Interaction
  or Performance Data, although the app only shows an ad SDK's ads.
- **Cause:** a Play purpose was turned into two Apple purposes ("advertising" -> Third-Party Advertising AND
  Developer's Advertising or Marketing). Apple's definitions (developer.apple.com/app-store/app-privacy-details/):
  third-party ads are Third-Party Advertising; Developer's Advertising is first-party ads or marketing to your users.
- **Do:** one Apple purpose per Play purpose; put the owner's real answers in `appPrivacy.types` (Apple type ids,
  purposes, linked, tracking) and let `storebound check` compare them with Info.plist and PrivacyInfo.xcprivacy.
- **Guard:** `applePurpose` (cli/lib/declarations.ts), `appPrivacy.types` validation and `appPrivacyMismatches`
  (cli/lib/app-privacy.ts), `tests/app-privacy.test.ts`.

## 14. An unknown console page: bounded wait and a debug dump
- **Symptom:** `console fill` clicked Next (or opened the form) and then nothing happened in the log for a long time.
- **Cause:** the console showed a page storebound does not recognise (a changed layout, a new question): no field it
  can fill and no button it may click.
- **Do:** read the warning: it names the page ("the page after "Next""), its buttons, and where the debug dump is.
  Do that part by hand (the manual steps follow), or stop. To report it, re-run with `--debug-dump` and attach the
  folder `.storebound/console-debug/<form>-<time>/` after the owner looked at `screen.jpg` (the screenshot shows what
  the window showed). `page.json` / `page.html` hold labels and structure only: no values, cookies or tokens; emails,
  phone numbers and the account area are replaced.
- **Guard:** the watchdog in `fillSession` (`--step-timeout`, default 30 s; a heartbeat line a minute; 20 min without
  progress ends the run with exit 1), `cli/console/debug.ts`, `tests/console-flow.test.ts` (unknown-page fixture and a
  scan for waits without a deadline).

## 15. App Privacy data types not found in the real dialog
- **Symptom:** after Get Started and Next, `console fill apple-app-privacy` finds no data type checkbox.
- **Cause:** the real "Data Collection" dialog names each checkbox by its label run together with its help text
  ("NameIncluding first or last name"), and some labels differ from Apple's help page ("Purchases", "Other Data").
- **Do:** nothing by hand: storebound matches the label as a prefix. If the console changes again, the watchdog
  (pitfall 14) writes a debug dump: re-run with `--debug-dump` and attach it.
- **Guard:** `labelNames` and `TYPE_ALIASES` (`cli/lib/console-forms.ts`), `tests/console-flow.test.ts`.

## 16. "Still waiting for the sign-in" on a console that is signed in
- **Symptom:** `console fill` (often with the copied Chrome cookies) prints only "still waiting for the sign-in"
  while the window shows Play Console (the account chooser, the app list).
- **Cause:** Google pages embed `accounts.google.com` / `ogs.google.com` frames (the account widget, cookie rotation)
  while the owner is signed in; an older detector counted any frame on a sign-in host as a sign-in page.
- **Do:** read the line "sign-in detected because: <rule> at <url>" and the heartbeats (they name the page). A
  top-level `accounts.google.com` / `idmsa.apple.com` / App Store Connect `/login` URL right after the launch means the
  copied Chrome session did not carry over (expired or tied to that device): sign in once in the window, or run
  without `--use-chrome-session` (pitfall 18). Anything else: re-run with `--debug-dump` (up to 3 dumps of the sign-in wait) and attach the
  folder after the owner looked at `screen.jpg`.
- **Guard:** `signInReason` in `cli/console/fill.ts` (top-level URL, the main frame's password / email-entry form, a
  visible Apple sign-in frame; no other frame counts), the sign-in watchdog dump, `tests/console-fill.test.ts`.

## 17. App Privacy data types listed but never set up
- **Symptom:** after the data types were saved, `console fill apple-app-privacy` stops on the App Privacy page with
  every type showing "Set Up <type>" and nothing clicked.
- **Cause:** the real page shows "Set Up <type>" as plain text (a `<p>` in a div with a click handler: no button, no
  link) in a box after the Data Types heading, so role-based lookups miss it.
- **Do:** nothing by hand: storebound clicks each "Set Up <type>" by its exact text (only for types it answers, never
  the "?" help buttons or Publish) and fills that type's dialog step by step. A dialog step it does not know: it writes
  a debug dump, says `paused on "<type>"`, and goes on once the owner answered that step.
- **Guard:** `setUpAllowed` (`cli/lib/console-forms.ts`), `setUpClick` / `setUpType` (`cli/console/fill.ts`),
  `tests/console-flow.test.ts` with `tests/fixtures/console/apple-app-privacy-setup.html`.

## 18. Never copy Google session cookies: they are device-bound
- **Symptom:** `console fill play-app-record` with the owner's copied Chrome cookies reached the Play account chooser
  once (22:32); between runs Google showed `accounts.google.com/v3/signin/rejected`; from 23:12 the same copy landed on
  the account chooser.
- **Cause:** Google binds its session cookies to the device. Chrome's Device Bound Session Credentials keep a key in
  the TPM / Secure Enclave that cannot leave the machine; Google only renews the short-lived cookies for the browser
  that proves it holds that key (public on Windows from Chrome 146, rolling out on macOS from Chrome 147). Google also
  signs out sessions whose cookies look stolen ("logged out of their account for that session and any related
  suspicious sessions on that device", then an extra verification). Copied cookies in a second Chrome look exactly
  like cookie theft: the copy is refused, and the owner's REAL Chrome session can be signed out or the account asked
  to verify again.
- **Do:** never copy Google cookies. The default is storebound's own profile (`~/.storebound/console-profile/<store>`):
  the owner signs in there once, by hand; it is kept. `--use-chrome-session google` exists only as an explicit owner
  opt-in that prints the warning; an agent never adds it. Apple publishes no such binding, but `--use-chrome-session
  apple` is opt-in too. If Google says "Couldn't sign you in" in storebound's window, storebound prints "Google refused
  sign-in in this window (/signin/rejected)": try again, or sign in at accounts.google.com first in that window.
- **Guard:** `browserPlan` / `openConsoleBrowser` in `cli/console/session.ts` (no copy without the flag, the copy keeps
  only the form's own provider), Chrome started by storebound without `--enable-automation` and with
  `navigator.webdriver` false, `googleRejected`; `tests/console-session.test.ts`.
- **Sources:** https://blog.google/security/protecting-cookies-with-device-bound-session-credentials/ ,
  https://developer.chrome.com/docs/web-platform/device-bound-session-credentials ,
  https://knowledge.workspace.google.com/admin/security/investigate-and-take-action-on-suspicious-session-cookies

## 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).