@appeeky/spec 0.0.0-stage → 0.2.0

package/skills/appeeky-spec-experiments/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: appeeky-spec-experiments
+description: Run and measure growth experiments outside the store listing in an Appeeky Spec repo, such as screenshots, UGC and creator videos, ads and pricing, with install attribution, smart links and the app's numbers. Use when asked to test screenshots, a TikTok or creator campaign, an ad creative or a price, to set up attribution, to see where installs and revenue come from, or to pull analytics, ads and RevenueCat data for analysis.
+metadata:
+  version: 1.0.0
+---
+
+# Experiments, attribution and data with Appeeky Spec
+
+A listing push is already an experiment: `verify` measures it. Everything else you try to grow the app, like a new screenshot set, a creator video, an ad or a price, is tracked the same way in `appeeky/experiments/<id>.yaml`. Each one has one hypothesis, one metric, a baseline, a date to check and a result.
+
+Run commands as `npx @appeeky/spec <command> --json`.
+
+## 1. Know what can be measured
+
+`experiment add --metric` takes one metric. Prefer one the spec can measure on its own. It then takes the baseline from the last days and `verify` closes the experiment when it is due:
+
+| Needs | Metrics |
+| --- | --- |
+| `APPEEKY_API_KEY` with the store connected in Appeeky | `conversion`, `page_views`, `downloads`, `proceeds`, `trials` |
+| RevenueCat connected in Appeeky (app-scoped project) | `revenue`, `rc_trials`, `trial_conversion` |
+| Apple Search Ads connected in Appeeky, or `search-ads pull` | `ad_installs`, `cpa` |
+| Meta / TikTok campaigns under `ads:` | `meta_spend`, `meta_installs`, `meta_cpi`, `tiktok_spend`, `tiktok_conversions`, `tiktok_cpa` |
+| `attribution:` in the spec | `organic_installs`, `organic_revenue`, `organic_paid`, and with `--link`: `link_clicks`, `link_installs`, `link_revenue` |
+| reviews pulled | `rating`, `low_ratings` |
+| AI Visibility / `category pull` | `ai_visibility`, `category_rank` (see appeeky-spec-visibility) |
+
+Without any of these, the user gives the value at the end (`experiment close --value`). Say so up front.
+
+## 2. Attribution: where installs come from
+
+With Appeeky Analytics in the app, the spec knows each install's source: organic store search, an Apple Search Ads keyword, a smart link, the Google Play referrer. It also knows what that install paid. Set it up once:
+
+- `attribution init` uses Appeeky's hosted service (`APPEEKY_API_KEY`). `attribution init --self <url>` uses the user's own server on Cloudflare (`ATTRIBUTION_TOKEN`).
+- It writes `attribution:` to the spec and prints the SDK key and the RevenueCat webhook. Adding the SDK to the app and the webhook to RevenueCat is a code and settings change: propose it, do not do it silently.
+- An app on both stores has one id per store under `attribution.app`.
+
+Then listing releases are judged on organic installs and revenue first, not only ranks.
+
+## 3. Start an experiment
+
+```bash
+npx @appeeky/spec experiment add --type ugc --persona new-parents \
+  --hypothesis "A 'my baby slept in 5 minutes' hook gets more installs per view than the product demo" \
+  --metric link_installs --days 14 --link tiktok
+```
+
+- `--type`: `screenshots`, `ugc`, `ads`, `pricing`, `other`.
+- `--persona`: an id from `personas` in the spec. Write the hypothesis for that person.
+- `--link [channel]` creates a smart link for the experiment (needs `attribution:`), so its installs and revenue are counted exactly. Channels: `tiktok`, `instagram`, `creator`, `tiktok_ads`, `meta_ads`, and others. Give each creator or ad its own experiment and link.
+  - **App Store caveat:** link installs can only be counted on Google Play. For an App Store-only app, measure `link_clicks`.
+- `--asset` records what ran: file paths, video links, ad ids.
+- `--baseline` and `--target` when the user knows them. Otherwise the baseline is measured.
+
+Rules:
+
+- One change per experiment. A new video with a new price measures neither.
+- Do not start a screenshot or pricing experiment on a store that has a listing release still being measured. Check `status` first; `free` stores are safe. Both would move conversion.
+- Screenshots are not indexed for search. They change conversion, so measure `conversion` (or `organic_installs` with attribution).
+
+## 4. Close it
+
+`verify` closes due experiments on measured metrics (`closedExperiments` in its JSON) and lists the ones that still need a value (`dueExperiments`). For those:
+
+```bash
+npx @appeeky/spec experiment close <id> --value 3.1 --note "Hook B: 3.1 installs per 1k views vs 1.8" --playbook
+```
+
+`--playbook` adds the result to `appeeky/playbook.md`. A lost experiment is a result too: write it so it is not tried again.
+
+## 5. Ads
+
+- `ads --json` gives spend, installs and cost per install for the last `--days` (default 30). It covers Apple Search Ads and the Meta and TikTok campaigns listed under `ads:` in the spec.
+- With the user's own Search Ads key, `search-ads pull` writes `appeeky/search-ads/`: `daily.csv`, `keywords.csv`, `search-terms.csv` and `summary.md`. The key is saved on the App Store Connect CLI account (`appstore accounts search-ads <account> --client-id … --team-id … --key-id … --private-key-path …`, the account in `stores.appStore.account`), or set as `ASA_*` env in CI. It reads only the campaigns for the App Store app (`stores.appStore.searchAds` sets the org and the campaigns). The summary lists search terms that installed and are not targets yet: propose them as targets, since ranking for them organically is free. `ads` and `verify` then read Search Ads from these files, without Appeeky.
+- `--save` keeps a copy in `appeeky/ads/<date>.yaml`.
+- Campaigns are listed by id. Ask the user which campaigns promote this app; never guess from names.
+
+## 6. Social posts and UGC videos
+
+With accounts and creator personas set up in Appeeky (`APPEEKY_API_KEY`):
+
+- `social pull` writes the connected accounts, recent posts and how each did to `appeeky/social/` (read `summary.md`). `ugc pull` writes the personas (`ready` when they can make clips) and their clips to `appeeky/ugc/`.
+- To post: write `appeeky/social/drafts/<date>-<slug>.yaml` (`accounts`, `text`, `when`, `media`, `why`) and run `social check`. To make a video: write `appeeky/ugc/briefs/<date>-<slug>.yaml` (`persona`, `script`, `scene`, `caption`, `durationSec`, `aspectRatio`, `why`) and run `ugc generate --dry-run` for its cost.
+- Open a pull request. `social push` and `ugc generate` run after the merge (the push workflow does it). Never run them, or `ugc generate --yes`, unless the user asked: posts are public and clips use media credits.
+- Give each post or video its own smart link (`experiment add --link <channel>`) so `experiment close` can say what it brought.
+
+## 7. Data for analysis
+
+`data pull --json` writes CSV files the agent can read: store analytics, traffic sources, sales, Apple Search Ads, RevenueCat, Meta and TikTok per day. It also writes attribution by source, keyword and smart link. `--days` defaults to 90, and `README.md` in the folder says what each file holds.
+
+- They are private business numbers. They go to `.appeeky/data/` (gitignored) unless the spec says `data: { commit: true }`. Never move them into the repo or paste them into a public pull request without asking.
+- Pulling again merges by date, so files grow; there is no need to delete them first.
+- Use them to find the next experiment: a country with many page views and low conversion, a channel with rising cost per install, a keyword that brings installs that never pay.

package/skills/appeeky-spec-localize/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: appeeky-spec-localize
+description: Add or improve a store listing for a new language or country in an Appeeky Spec repo (appeeky.spec.yaml + appeeky/store). Use when asked to localize App Store or Google Play metadata, launch in a new country, add a locale, translate keywords, or use spare keyword space in secondary locales such as Spanish (Mexico) for the US.
+metadata:
+  version: 1.0.0
+---
+
+# Localize a listing with Appeeky Spec
+
+Localizing is keyword research per market, not translation. People in each country search with their own words, and a literal translation of an English keyword is often a term nobody types.
+
+Run commands as `npx @appeeky/spec <command> --json`.
+
+## 1. Pick the storefront and the locale
+
+- Storefronts are countries (`us`, `de`, `tr`). Listing locales are languages (`en-US`, `de-DE`, `tr`). One storefront can read several locales.
+- Run `coverage --json`: `crossLocalization` shows extra locales a storefront already reads and how many keyword characters they leave unused. Filling those is the cheapest win (for the US App Store: the `es-MX` keyword field).
+- For a new market, ask the user which countries matter (downloads, revenue, plans) before writing many locales.
+
+## 2. Targets first
+
+Add the market's targets to `appeeky.spec.yaml` before writing copy:
+
+```yaml
+targets:
+  de: [einschlafgeräusche, weißes rauschen, regengeräusche]
+```
+
+Find the terms locally: what competitors in that country use in their titles and subtitles, store search suggestions, and keyword popularity from the Appeeky MCP server or `suggest --country <cc> --json` when `APPEEKY_API_KEY` is set. Mark terms you are unsure about and ask a native speaker when one is available.
+
+## 3. Write the listing file
+
+Create `appeeky/store/app-store/<locale>.yaml` or `appeeky/store/google-play/<language>.yaml` (Google Play uses codes like `de-DE`, `tr-TR`).
+
+- Only the fields you write are managed. Start with name, subtitle and keywords (App Store) or title and short description (Google Play); leave descriptions out until they are written properly.
+- Keep the brand in the name the same in every locale.
+- App Store keyword field: 100 characters, commas without spaces, no words already in the name or subtitle, no plurals of present words. Characters, not bytes.
+- Google Play: a new language needs title, short description and full description together.
+- For a secondary locale used only for another storefront's keywords (es-MX for the US), fill the keyword field with that storefront's target words that the primary locale does not cover. Name and subtitle should still read correctly in the locale's language.
+
+## 4. Check and ship
+
+1. `check --json` (no errors) and `coverage --country <cc> --json`: the new targets should be covered or partial.
+2. `diff --json`: a new locale shows as `newLocale`. On the App Store a new locale needs a version in Prepare for Submission.
+3. Push only when the user asks, with a note naming the market and the hypothesis: `push --note "Launch de-DE: einschlafgeräusche, weißes rauschen"`.
+
+## Mistakes to avoid
+
+- Machine-translating the English keyword field.
+- Copying the English subtitle into every locale.
+- Adding ten locales at once with no targets: nothing can be measured.
+- Using another app's brand name as a keyword.

package/skills/appeeky-spec-review/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: appeeky-spec-review
+description: Review what past store listing changes did in an Appeeky Spec repo, decide whether to keep or revert them, update the playbook and plan the next change. Use when asked "did the last listing change work?", "should we revert?", for a weekly ASO review, to close experiments, or to summarize listing releases for a team update or PR.
+metadata:
+  version: 1.2.0
+---
+
+# Review listing releases with Appeeky Spec
+
+Each push in `appeeky/releases/` holds the before/after values, the hypothesis (`note`) and the search ranks from right before it. `verify` measures again on day 7 and day 14.
+
+Run commands as `npx @appeeky/spec <command> --json`.
+
+## 1. Measure
+
+```bash
+npx @appeeky/spec verify --playbook --json
+```
+
+This only measures releases that reached day 7 or day 14 and have not been measured for that day. Use `verify --now <release-id>` only when the user wants an early look, and say that early ranks are noisy. With `APPEEKY_API_KEY` set, each check also has `metrics`: conversion, downloads, revenue, trials and ads (Apple Search Ads, plus the Meta and TikTok campaigns under `ads:`) before and after the push, each marked `better`, `worse` or `flat`, and due experiments on those metrics are closed for you (`closedExperiments`). The JSON lists experiments that still need a value (`dueExperiments`).
+
+## 2. Read the verdict
+
+| Verdict | Meaning | Usual action |
+| --- | --- | --- |
+| `won` | More targets rose (3+ places) than fell | Keep. Note what worked in the playbook |
+| `lost` | One top-10 target, or two top-20 targets, fell out of the top 20 by 10+ places | Propose `revert` |
+| `mixed` | Some rose, as many or more fell | Look at which targets moved and their popularity before deciding |
+| `flat` | Nothing moved 3+ places | Wait for day 14; then treat as no effect |
+
+When the check has `control`, read `net`: the places the changed storefronts gained beyond the unchanged ones. A "won" with a small net was turned into "mixed" (see `note`): the whole store moved. A metric change marked flat with a `noise` larger than the change is within its normal week-to-week range; do not credit or blame the release for it.
+
+When no rank moved and the check has `decidedBy`, the verdict came from those outcome metrics, in this order:
+
+1. organic installs and revenue,
+2. else conversion,
+3. else downloads,
+4. else the category rank.
+
+Say so: "won on organic installs, ranks unchanged".
+
+A verdict decided by `category_rank` is the weakest kind. The chart moves with ads, featuring and season too, so say that and prefer waiting for day 14.
+
+Two more metrics can be in `metrics.changes` (see appeeky-spec-visibility):
+
+- `ai_visibility`: the share of AI assistant answers that name the app. Assistants update slowly, so read it on day 14.
+- `category_rank`: lower is better, so a negative change is good.
+
+Before recommending, check:
+
+- **Popularity.** One popular term lost can outweigh three tiny ones gained.
+- **Conversion and revenue.** When a check has `metrics` (or `conversion`), more ranks with lower conversion or revenue is not a win, and flat ranks with better conversion can be. Lead with the outcome the user cares about: revenue and trials before downloads, downloads before ranks.
+- **Other causes.** A new app version, a featuring, a competitor's change (`appeeky/competitors/changes.md`), an ad campaign starting (`ads --json`) or seasonality in the same window. Say when the result could be noise.
+- **Day 7 vs day 14.** App Store ranking changes settle over one to two weeks; prefer the day-14 check when it exists.
+
+## 3. Revert when it lost
+
+```bash
+npx @appeeky/spec revert <release-id>
+npx @appeeky/spec diff --json
+```
+
+`revert` only edits the files. Push only when the user agrees, with a note: `push --note "Revert <id>: lost '<keyword>' (<before> → <after>)"`. App Store fields other than promotional text need a new version.
+
+## 4. Close experiments
+
+`verify` closes due experiments on `conversion`, `downloads`, `revenue`, `trial_conversion`, `cpa`, `meta_cpi`, `tiktok_cpa` and the other measured metrics. With `attribution:` in the spec, checks also carry `organic_installs`, `organic_revenue` and `organic_paid`: whether more people found the app in search and paid. For UGC, creator or ad experiments, start them with `--link` so their installs are counted exactly. `appeeky-spec ads --json` shows spend and cost per install per paid channel; `--save` keeps a copy in `appeeky/ads/`. For the rest (installs per 1,000 views, tap-through rate), ask the user for the value or read it from the data they point to, then `experiment close <id> --value <n> --note "..." --playbook`. When starting one, prefer a measured metric: `experiment add --metric trial_conversion` takes its baseline from the last days.
+
+## 5. Update the playbook and plan
+
+`appeeky/playbook.md` gets one line per result from `--playbook`. Add a short "why" in your own words when the cause is clear (for example: "subtitle words beat keyword-field words for 'white noise'"). Then propose the next single change, with a hypothesis that does not repeat a losing one.
+
+## Summaries
+
+`log --markdown -n <count>` prints releases as Markdown tables with the note and the latest verdict, ready for a PR description or a team update.

package/skills/appeeky-spec-targets/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: appeeky-spec-targets
+description: Choose and prioritize the searches an app should be found for (the `targets` in appeeky.spec.yaml), from personas, competitors and keyword popularity. Use when asked which keywords to target, to do keyword research, to fill or clean up targets, to define personas, or to react to a competitor changing its title or subtitle.
+metadata:
+  version: 1.0.0
+---
+
+# Choose targets with Appeeky Spec
+
+`targets` in `appeeky.spec.yaml` are the searches the app should be found for, per storefront. Coverage, suggestions, rank baselines and release verdicts are all measured against them, so wrong targets make every later step wrong. Pick them before editing any listing.
+
+Run commands as `npx @appeeky/spec <command> --json`.
+
+## 1. Start from people, not words
+
+Write down who the app is for as `personas`, with how each one searches:
+
+```yaml
+personas:
+  - id: new-parents
+    name: New parents
+    description: Need their baby to fall asleep, often at night with one hand free.
+    searches: [baby sleep sounds, white noise baby, lullaby]
+```
+
+Ask the user when you cannot tell from the repo, website or current listing. `searches` are seeds, not final targets. Experiments refer to personas by id.
+
+The same personas are the source of the AI visibility intents (`aiVisibility.intents`, see appeeky-spec-visibility). A persona's need ("fall asleep to rain sounds") is an intent. How they would ask an assistant is a prompt; it is longer and more conversational than a store search.
+
+## 2. Collect candidates
+
+From, in this order:
+
+1. The personas' `searches`.
+2. `suggest --json`: missing target words and Appeeky keyword ideas (with `APPEEKY_API_KEY`).
+3. Competitors: `competitors pull` writes the searches each competitor ranks best for to `appeeky/competitors/`, and what the top apps for the seed searches put in their titles and subtitles. With the Appeeky MCP server connected, use its keyword and competitor tools for popularity, difficulty, rankings and recent metadata changes.
+4. Store search suggestions in the storefront's language.
+
+Drop other apps' brand names and trademarks, generic one-word terms the category giants own ("music", "photo"), and searches the app does not actually serve.
+
+## 3. Prioritize
+
+For each candidate, look at popularity (how many search it), difficulty (how strong the apps ranking for it are) and relevance (would someone searching this install this app?).
+
+- Relevance first: an irrelevant search that ranks still does not convert.
+- Prefer specific phrases with decent popularity over head terms a small app cannot reach ("screenshot organizer" over "screenshot").
+- Keep about 5 to 15 targets per storefront. More cannot be covered by a 30 + 30 + 100 character listing and cannot be measured clearly.
+- Put the most important target first; it should go in the name or the title.
+
+## 4. Write them
+
+```yaml
+targets:
+  us: [screenshot organizer, screenshot search, screenshot manager]
+  de: [screenshots organisieren, bildschirmfotos suchen]
+```
+
+Then `coverage --json`: anything `missing` is the next listing change (see appeeky-spec). Each language market needs its own research, never translated targets (see appeeky-spec-localize).
+
+## Competitor moves
+
+When a competitor drops a word from its title or subtitle, the search can open up; when it adds one of your targets, expect pressure on that rank. Check whether the word is one of your targets and how your rank moves, and propose a listing change only for a target that matters. Desktop lists these under ASO → Competitor moves.
+
+## Changing targets later
+
+Targets are the yardstick of every release. Change them deliberately, say why in the commit, and do not swap targets in the same release as a listing change you want to measure.

package/skills/appeeky-spec-visibility/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: appeeky-spec-visibility
+description: Get an app named when people ask ChatGPT, Claude, Gemini or Perplexity for an app like it, get its website found in Google, and track its category chart rank, in an Appeeky Spec repo. Use when asked about AI visibility, AI search, LLM or GEO/AEO recommendations, "does ChatGPT recommend us", which questions to track, why a competitor is named instead, SEO for the app's website, Search Console, llms.txt, or how the app ranks in its category.
+metadata:
+  version: 1.0.0
+---
+
+# AI visibility and category rank with Appeeky Spec
+
+Three ways people find an app outside a store search: they ask an AI assistant, they search Google and land on the app's website, or they browse the category chart. The spec records all three and `verify` measures them around every push.
+
+Run commands as `npx @appeeky/spec <command> --json`.
+
+## AI visibility
+
+### The model
+
+- An **intent** is what someone wants: "fall asleep to rain sounds". Labels need 8+ characters.
+- A **prompt** is one way to ask for it: "what app plays rain sounds to help me sleep". Prompts need 15+ characters.
+- Both live in `appeeky.spec.yaml` under `aiVisibility.intents.<country>`. Appeeky AI Visibility asks each assistant every prompt on a schedule. It records whether the answer names the app, in what position, who else is named and which pages are cited.
+
+Two ways to ask the assistants, writing the same files:
+
+- **Appeeky AI Visibility** (`APPEEKY_API_KEY` on a plan with AI Visibility): Appeeky asks on a schedule; `visibility pull` writes the results.
+- **Your own keys** (`--local`): `visibility scan --local` asks from where Spec runs, with `OPENAI_API_KEY` (ChatGPT), `ANTHROPIC_API_KEY` (Claude), `GEMINI_API_KEY` (Gemini) and `PERPLEXITY_API_KEY` (Perplexity), any of them. Each key adds that assistant. The providers bill the user; no Appeeky account is needed. It also writes `history.csv` (one row per scan, intent and assistant) and `answers/<country>.jsonl` (every answer, for reading why an assistant named someone else).
+
+Use one of them per repo: both write `appeeky/visibility/<country>.yaml`.
+
+### Set up
+
+1. `visibility init`. If Appeeky already tracks intents, they are written into the spec. If not, Appeeky writes them from the store listing in the background; run `init` again a few minutes later. With your own keys, `visibility init --local` writes them from the listing right away, on the cheapest model of the key that is set (a fraction of a cent).
+2. Read the intents with the user. Keep the ones a real person of a persona would ask (see `personas` in the spec). Drop vague ones.
+3. With Appeeky: after the user approves the edits (in a pull request), run `visibility sync`. It only adds. It lists what exists only in Appeeky and archives it only with `--prune`, which you run only when the user asks.
+
+Good prompts:
+
+- Sound like a person typing: "best white noise app for a newborn", not "white noise app".
+- Never contain the app's own name (that measures nothing) or a competitor's name.
+- Each intent gets 2 to 4 prompts phrased differently: a question, a request for a list ("top 5…"), a comparison need ("an app like X but free" is fine without naming X).
+- Use the storefront's language. A `de` intent gets German prompts written for German speakers, not translations.
+
+### Read the results
+
+`visibility pull` writes `appeeky/visibility/<country>.yaml`:
+
+| Field | Meaning |
+| --- | --- |
+| `summary` | intents by status: `winning` (named in 25%+ of answers), `weak`, `missing`, `noData` (not scanned yet) |
+| `intents[].you` | share of answers that name the app, averaged over the assistants, 0–100 |
+| `intents[].byModel` | the same per assistant: one assistant can name you while another never does |
+| `intents[].namedInstead` | who the assistants name instead, with their share |
+| `sources` | pages the assistants cite (mostly Perplexity), most cited first; `yours: true` is the app's own site |
+| `fixes` | open suggestions from Appeeky for an intent |
+
+`appeeky/visibility/changes.md` keeps what moved between pulls: an intent that went from `missing` to `winning`, or the app's site starting to be cited.
+
+### Improve it
+
+Assistants repeat what the web says about an app. In order of what you can change:
+
+1. **The listing.** The first lines of the description and the subtitle should say what the app does in the intent's words ("rain sounds for sleep", not "an immersive audio experience"). This is a normal listing change: propose it in a pull request and measure it like any release (see appeeky-spec).
+2. **The app's own website.** A page per main use case, in plain words, with the app's name and store links. When `sources` shows the assistants cite pages like it from competitors, the same kind of page is the gap.
+3. **Cited third-party pages.** `sources` lists them: review sites, Reddit threads, "best apps for…" articles. Tell the user which ones name the competitors in `namedInstead` but not the app. Getting listed there is the user's outreach, not something to fake.
+4. **`fixes`.** Read each one. Propose the ones that are listing or website edits; summarize the rest for the user.
+
+Never write fake reviews, posts or comments, and never make claims the app does not live up to. Assistants also read those.
+
+### Measure it
+
+`verify` reads `ai_visibility`, the 0–1 share of answers that name the app, from Appeeky's daily series or from `appeeky/visibility/history.csv`. It compares the days before a push with the days after. Assistant answers change slowly and scans may be weekly, so a day-7 move is a hint and day 14 counts.
+
+`visibility scan` costs money: AI Visibility credits, or with `--local` the user's own provider accounts. Run it only when the user asks. `visibility scan --local --dry-run` shows the prompts, the assistants and the cost and asks nothing; that one is always fine. On a schedule, the daily routine runs `visibility scan --local --every <days>` when the user set `VISIBILITY_EVERY`.
+
+## The app's website: Google and AI assistants
+
+Set `web.url` in `appeeky.spec.yaml` (and `web.searchConsole` when the Search Console property is not the domain).
+
+- `seo check` reads the site the way a crawler does, with no key: title, description, canonical, sitemap and noindex for Google; store links, the Smart App Banner and app structured data for the app; and for AI assistants whether robots.txt lets their crawlers in (GPTBot, OAI-SearchBot, ClaudeBot, PerplexityBot, Google-Extended and others), whether there is an llms.txt, how much text is readable without JavaScript, and how many target keywords the page uses. Each finding has a fix.
+- `seo llms --out public/llms.txt` writes llms.txt from the listing. Propose it in the website's repo when the check says it is missing.
+- `seo pull` reads Google Search Console with the user's own service account (`GSC_CREDENTIALS`: the JSON key or its path; the service account's email must be a user of the property). It writes `appeeky/seo/daily.csv` (clicks and impressions per day, kept), `queries.csv` and `pages.csv` (last 28 days), and `summary.md`: the trend, top queries, queries close to the top (position 4–15) and queries with the store target keywords.
+
+`verify` reads `search_clicks` and `search_impressions` per day from `daily.csv`. Search Console lags two days.
+
+On the user's own DataForSEO account (`DATAFORSEO_LOGIN`, `DATAFORSEO_PASSWORD`), for `web.keywords.<country>` or the store targets:
+
+- `seo ranks` → `appeeky/seo/ranks.csv` and `ranks.md`: the site's Google position, where the app's store page ranks on Google, and whether the AI Overview shows and cites the site, per keyword. `changes.md` gets keywords entering or leaving the top 10. `verify` reads `web_rank` (lower is better) and `ai_overview_citations`.
+- `seo keywords` → `appeeky/seo/keywords.csv`: volume, difficulty, CPC, intent, plus related ideas (`tracked: no`). High-volume, low-difficulty ideas are candidates for `web.keywords` and, when people would search the store for them too, for store `targets`.
+- `seo domain` → `appeeky/seo/domain.md` and `ranked-keywords.csv`: what the site ranks for and which sites compete for the same searches.
+
+They cost money. Run them with `--dry-run` freely, and without it only when the user asks; the daily routine checks ranks on its own.
+
+Read them together: a query people search on Google is a phrase they may also ask an assistant, and a good intent or target. A page that ranks in Google is a page the assistants can cite. When `visibility` shows the assistants cite competitors' pages for an intent and `seo check` shows the site is thin or blocks AI crawlers, the website is the fix, and it is the user's website change, proposed as a list or in that repo, not a listing push.
+
+## Category rank
+
+`category pull` adds today's rank in the category chart (top 100) for each storefront to `appeeky/category.csv`.
+
+- **App Store:** reads Apple's chart, no key. The genre comes from the app, and a paid app is read from top-paid.
+- **Google Play:** needs `APPEEKY_API_KEY` and `category.googlePlay` in the spec (e.g. `HEALTH_AND_FITNESS`). Ask the user for the category if it is not set.
+- An empty rank means not in the top 100.
+
+The rank mostly follows downloads, so it moves with everything: listing changes, ads, featuring, seasonality. Read it as a sign, not a cause:
+
+- `verify` reads it as `category_rank`, where lower is better. When no target search moved and there is no analytics data, it decides the release (`decidedBy: ["category_rank"]`). Say so.
+- A jump on the day an ad campaign started is the ad, not the listing. Check `appeeky ads` and `loops.md` first.
+- It needs history: run it daily (the daily workflow does) so there are days before each push.