@appeeky/spec 0.0.0-stage → 0.1.0

package/dist/visibility.js

@@ -0,0 +1,239 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import YAML from "yaml";
+import { SPEC_DIR } from "./files.js";
+import { indexedLocales } from "./storefronts.js";
+import { normalize } from "./text.js";
+import { rankAppIds } from "./verify.js";
+/**
+ * AI visibility in the repo: whether ChatGPT, Claude, Gemini and Perplexity name
+ * the app when people ask for an app like it, who they name instead, and which
+ * pages they cite. The intents and prompts live in appeeky.spec.yaml; Appeeky AI
+ * Visibility asks the assistants on a schedule, and `visibility pull` writes what
+ * they answered to appeeky/visibility/<country>.yaml.
+ */
+export const MODELS = ["chatgpt", "claude", "gemini", "perplexity"];
+export const visibilityDir = (root) => join(root, SPEC_DIR, "visibility");
+export const visibilityChangesFile = (root) => join(visibilityDir(root), "changes.md");
+/** Which app and storefronts to watch. */
+export function visibilityTarget(project) {
+    const cfg = project.spec.aiVisibility;
+    const ids = rankAppIds(project);
+    const store = cfg?.store ?? (ids["app-store"] ? "app-store" : ids["google-play"] ? "google-play" : undefined);
+    if (!store || !ids[store])
+        return null;
+    const countries = cfg?.countries ?? [Object.keys(project.spec.targets)[0] ?? "us"];
+    return { store, appId: ids[store], countries };
+}
+/** ISO 639-1 language for a storefront's prompts, from the listing locale it indexes first. */
+export function languageFor(project, country) {
+    return (indexedLocales(project, country)[0] ?? project.spec.app.primaryLocale).slice(0, 2).toLowerCase();
+}
+const path = (appId, rest = "") => `/ai-visibility/${encodeURIComponent(appId)}${rest}`;
+export async function remoteIntents(api, appId, country) {
+    const rows = await api.get(path(appId, "/intents"), { country });
+    return (rows ?? []).filter((r) => r.status !== "archived");
+}
+export async function remotePrompts(api, appId, country, intentId) {
+    const detail = await api.get(path(appId, `/intents/${encodeURIComponent(intentId)}`), { country });
+    return (detail?.prompts ?? []).filter((p) => p.status !== "archived");
+}
+const pct = (n) => (n === null || n === undefined ? undefined : Math.round(n));
+export async function fetchVisibility(api, target, country, now = new Date()) {
+    const opp = await api.get(path(target.appId, "/opportunities"), { country, days: "30" });
+    const fixes = await api.get(path(target.appId, "/fixes"), { country }).catch(() => null);
+    const labels = new Map((opp?.intents ?? []).map((i) => [i.intentId, i.label]));
+    return {
+        pulledAt: now.toISOString().slice(0, 10),
+        country,
+        store: target.store,
+        appId: target.appId,
+        summary: opp?.summary ?? { winning: 0, weak: 0, missing: 0, noData: 0 },
+        intents: (opp?.intents ?? []).map((i) => {
+            const byModel = Object.fromEntries(Object.entries(i.byModel).map(([m, s]) => [m, pct(s?.visibilityPct)]));
+            return strip({
+                label: i.label,
+                status: i.status,
+                you: pct(i.ownerVisibilityPct),
+                byModel: Object.keys(byModel).length ? byModel : undefined,
+                namedInstead: i.winners.length ? i.winners.slice(0, 5).map((w) => `${w.name} (${Math.round(w.sharePct)}%)`) : undefined,
+            });
+        }),
+        sources: (opp?.sources.sources ?? []).slice(0, 15).map((s) => strip({ domain: s.domain, count: s.count, yours: s.citesOwner ? true : undefined, url: s.url })),
+        fixes: (fixes?.fixes ?? [])
+            .filter((f) => f.status === "open")
+            .map((f) => strip({ intent: labels.get(f.intentId) ?? f.intentId, title: f.title, why: f.rationale, page: f.targetUrl ?? undefined })),
+    };
+}
+const strip = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined));
+export const visibilityPath = (root, country) => join(visibilityDir(root), `${country}.yaml`);
+export async function readVisibility(root, country) {
+    const file = visibilityPath(root, country);
+    return existsSync(file) ? YAML.parse(await readFile(file, "utf8")) : null;
+}
+/** What moved since the last pull: an intent the assistants started or stopped naming the app for. */
+export function visibilityChanges(prev, next) {
+    const out = [];
+    const before = new Map(prev.intents.map((i) => [normalize(i.label), i]));
+    const rank = { missing: 0, weak: 1, winning: 2, no_data: -1 };
+    for (const i of next.intents) {
+        const was = before.get(normalize(i.label));
+        if (!was || was.status === "no_data" || i.status === "no_data" || was.status === i.status)
+            continue;
+        const verb = rank[i.status] > rank[was.status] ? "up" : "down";
+        out.push(`"${i.label}": ${was.status} → ${i.status} (${was.you ?? 0}% → ${i.you ?? 0}%), ${verb}`);
+    }
+    const cited = (f) => f.sources.some((s) => s.yours);
+    if (!cited(prev) && cited(next))
+        out.push("the assistants now cite your own site");
+    if (cited(prev) && !cited(next))
+        out.push("the assistants stopped citing your own site");
+    return out;
+}
+async function recordChanges(root, date, country, changes) {
+    if (changes.length === 0)
+        return;
+    const file = visibilityChangesFile(root);
+    const old = existsSync(file) ? await readFile(file, "utf8") : "# AI visibility changes\n\nWritten by `visibility pull`: intents the assistants started or stopped naming the app for.\n";
+    const [head, ...rest] = old.split(/\n(?=- )/);
+    const lines = changes.map((c) => `- ${date} · ${country.toUpperCase()} · ${c}`);
+    await writeFile(file, [head.trimEnd(), "", ...lines, ...rest.map((r) => r.trimEnd())].join("\n") + "\n");
+}
+/** Pull every watched storefront and write its file. */
+export async function pullVisibility(api, project, countries, now = new Date()) {
+    const target = visibilityTarget(project);
+    if (!target)
+        throw new Error("Set stores.appStore.appId (numeric) or stores.googlePlay.packageName first.");
+    await mkdir(visibilityDir(project.root), { recursive: true });
+    const out = [];
+    for (const country of countries ?? target.countries) {
+        try {
+            const data = await fetchVisibility(api, target, country, now);
+            const file = visibilityPath(project.root, country);
+            const prev = await readVisibility(project.root, country);
+            const changes = prev ? visibilityChanges(prev, data) : [];
+            await recordChanges(project.root, data.pulledAt, country, changes);
+            await writeFile(file, YAML.stringify(data, { lineWidth: 0 }));
+            out.push({ country, file, data, changes });
+        }
+        catch (e) {
+            out.push({ country, changes: [], error: e.message });
+        }
+    }
+    return out;
+}
+// ── Intents as code ─────────────────────────────────────────────────────────
+/** The intents and prompts Appeeky tracks for a storefront, in the spec's shape. */
+export async function readRemoteIntents(api, appId, country) {
+    const out = [];
+    for (const i of await remoteIntents(api, appId, country)) {
+        const prompts = await remotePrompts(api, appId, country, i.intentId);
+        out.push(strip({ label: i.label, description: i.description ?? undefined, prompts: prompts.map((p) => p.text) }));
+    }
+    return out;
+}
+/** Ask Appeeky to write intents and prompts from the store listing (runs in the background). */
+export async function bootstrapIntents(api, appId, country, language) {
+    const r = await api.post(`${path(appId, "/bootstrap")}?country=${encodeURIComponent(country)}&language=${encodeURIComponent(language)}`, {});
+    return { queued: Boolean(r?.taskRunId), already: Boolean(r?.alreadyBootstrapped) };
+}
+const key = (s) => normalize(s).replace(/\s+/g, " ").trim();
+/** Compare the spec's intents for a storefront with what Appeeky tracks. */
+export async function planSync(api, appId, country, wanted) {
+    const remote = await remoteIntents(api, appId, country);
+    const byLabel = new Map(remote.map((r) => [key(r.label), r]));
+    const plan = { country, addIntents: [], addPrompts: [], extraIntents: [], extraPrompts: [] };
+    const seen = new Set();
+    for (const intent of wanted) {
+        const r = byLabel.get(key(intent.label));
+        if (!r) {
+            plan.addIntents.push(intent);
+            continue;
+        }
+        seen.add(r.intentId);
+        const prompts = await remotePrompts(api, appId, country, r.intentId);
+        const have = new Map(prompts.map((p) => [key(p.text), p]));
+        const want = new Set(intent.prompts.map(key));
+        for (const text of intent.prompts)
+            if (!have.has(key(text)))
+                plan.addPrompts.push({ intentId: r.intentId, label: intent.label, text });
+        for (const p of prompts)
+            if (!want.has(key(p.text)))
+                plan.extraPrompts.push({ promptId: p.promptId, label: intent.label, text: p.text });
+    }
+    for (const r of remote)
+        if (!seen.has(r.intentId))
+            plan.extraIntents.push({ intentId: r.intentId, label: r.label });
+    return plan;
+}
+/** Apply a plan: add what the spec has; archive what it does not only when `prune` is set. */
+export async function applySync(api, appId, plan, language, prune) {
+    const q = `?country=${encodeURIComponent(plan.country)}&language=${encodeURIComponent(language)}`;
+    let intents = 0;
+    let prompts = 0;
+    let archived = 0;
+    for (const intent of plan.addIntents) {
+        const created = await api.post(`${path(appId, "/intents")}${q}`, { label: intent.label, description: intent.description ?? null });
+        intents++;
+        for (const text of intent.prompts) {
+            await api.post(`${path(appId, `/intents/${encodeURIComponent(created.id)}/prompts`)}${q}`, { text });
+            prompts++;
+        }
+    }
+    for (const p of plan.addPrompts) {
+        await api.post(`${path(appId, `/intents/${encodeURIComponent(p.intentId)}/prompts`)}${q}`, { text: p.text });
+        prompts++;
+    }
+    if (prune) {
+        for (const p of plan.extraPrompts) {
+            await api.request("DELETE", path(appId, `/prompts/${encodeURIComponent(p.promptId)}`));
+            archived++;
+        }
+        for (const i of plan.extraIntents) {
+            await api.request("DELETE", `${path(appId, `/intents/${encodeURIComponent(i.intentId)}`)}`);
+            archived++;
+        }
+    }
+    return { intents, prompts, archived };
+}
+/** Ask the assistants now instead of waiting for the schedule. Charged in AI Visibility credits. */
+export async function scanVisibility(api, appId, country) {
+    return api.post(`${path(appId, "/scan")}?country=${encodeURIComponent(country)}`, {});
+}
+// ── Measuring ───────────────────────────────────────────────────────────────
+/**
+ * `ai_visibility` around a push: the share of prompts whose answer names the
+ * app, averaged over the scanned days in the window and the assistants (0–1).
+ * Reads Appeeky's daily series once per assistant per run.
+ */
+export function visibilityMetricSource(api, project) {
+    const target = visibilityTarget(project);
+    if (!target)
+        return null;
+    const country = target.countries[0];
+    let series;
+    return {
+        label: "Appeeky AI Visibility",
+        async window(store, _appId, from, to) {
+            if (store !== target.store)
+                return null;
+            series ??= Promise.all(MODELS.map((model) => api.get(path(target.appId, "/trend"), { country, model, windowDays: "90" }).then((s) => s ?? []).catch(() => [])));
+            const byDay = new Map();
+            for (const points of await series) {
+                for (const p of points) {
+                    if (p.date < from || p.date >= to)
+                        continue;
+                    byDay.set(p.date, [...(byDay.get(p.date) ?? []), p.visibilityPct]);
+                }
+            }
+            if (byDay.size === 0)
+                return null;
+            const daily = [...byDay.values()].map((xs) => xs.reduce((a, b) => a + b, 0) / xs.length);
+            const days = Math.max(1, Math.round((Date.parse(to) - Date.parse(from)) / 86_400_000));
+            const values = { ai_visibility: daily.reduce((a, b) => a + b, 0) / daily.length / 100 };
+            return { from, to, days, values };
+        },
+    };
+}
+//# sourceMappingURL=visibility.js.map

package/package.json

@@ -1,6 +1,78 @@
 {
   "name": "@appeeky/spec",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Your app's store listing as a spec: lint it, check keyword coverage, diff it against the live store and push it to App Store Connect and Google Play.",
+  "license": "FSL-1.1-MIT",
+  "type": "module",
+  "bin": {
+    "appeeky-spec": "dist/bin.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./dist/core.d.ts",
+      "import": "./dist/core.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "skills",
+    ".github/assets/cover.gif",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/appeeky/appeeky-spec.git"
+  },
+  "homepage": "https://spec.appeeky.com",
+  "bugs": {
+    "url": "https://github.com/appeeky/appeeky-spec/issues"
+  },
+  "keywords": [
+    "aso",
+    "app-store-optimization",
+    "app-store",
+    "app-store-connect",
+    "google-play",
+    "metadata",
+    "keywords",
+    "spec",
+    "cli",
+    "appeeky"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build",
+    "pack:check": "npm run build && npm pack --dry-run",
+    "release:dry": "node scripts/release.mjs --dry-run"
+  },
+  "dependencies": {
+    "commander": "^13.1.0",
+    "yaml": "^2.6.1",
+    "zod": "^3.24.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.3",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.2"
+  }
+}

package/skills/appeeky-spec/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: appeeky-spec
+description: Improve and ship an app's App Store / Google Play listing with Appeeky Spec (appeeky.spec.yaml + appeeky/store). Use when asked to do ASO on a repo, change an app's name, subtitle, keywords, promotional text or descriptions, check keyword coverage, set up listing-as-code or its GitHub Action, handle App Store screenshots, or push listing changes to App Store Connect or Google Play, or run the weekly growth routine. To choose target keywords see appeeky-spec-targets; for a new language or country see appeeky-spec-localize; to judge past releases see appeeky-spec-review; for AI assistants and the category chart see appeeky-spec-visibility; for screenshots, UGC, ads, pricing, attribution and data see appeeky-spec-experiments.
+metadata:
+  version: 1.3.0
+---
+
+# Appeeky Spec
+
+The app's store listings live in files, and every push is recorded and measured.
+
+| Path | What it holds |
+| --- | --- |
+| `appeeky.spec.yaml` | app, stores, `targets` (searches the app should be found for, per storefront), optional `storefronts` and `personas` |
+| `appeeky/store/app-store/<locale>.yaml` | name, subtitle, keywords, promotionalText, description, whatsNew, supportUrl, marketingUrl |
+| `appeeky/store/google-play/<language>.yaml` | title, shortDescription, fullDescription, video (Play codes like `tr-TR`) |
+| `appeeky/releases/<id>.yaml` | every push: before/after values, note, rank baseline, day-7/14 checks |
+| `appeeky/experiments/<id>.yaml` | screenshot, UGC, ads and pricing experiments |
+| `appeeky/loops.md` | generated by `status`, `verify`, `push` and `experiment`: every change being measured, its metric, next check and result so far |
+| `appeeky/playbook.md` | what worked and what did not for this app |
+| `appeeky/reviews/` | customer reviews per month (JSONL), `summary.md`, and `replies/` drafted for review |
+| `appeeky/competitors/<name>.yaml` | each competitor's listing, best ranks, ranks on your targets, recent low ratings |
+| `appeeky/visibility/<country>.yaml` | whether ChatGPT, Claude, Gemini and Perplexity name the app per intent, who they name instead, the pages they cite, suggested fixes; `changes.md` beside it |
+| `appeeky/category.csv` | rank in the category chart (top 100), one row a day |
+| `.appeeky/data/*.csv` (or `appeeky/data/`) | analytics, Search Ads, RevenueCat, Meta and TikTok per day; `README.md` says what each file holds |
+
+Run commands as `npx @appeeky/spec <command> --json` (or `appeeky-spec` when installed). Add `-C <dir>` when the spec is not in the current folder.
+
+## No spec yet
+
+In a terminal the user runs, `init` with no options is a guided setup. It finds the app, pulls both stores, suggests targets, offers the workflows and the skills, and shows the first coverage. As an agent, use the flags instead:
+
+1. Find the App Store app id and Google Play package name (Xcode project, `app.json`, `build.gradle`), or ask.
+2. Store access: `appstore` / `gps` CLIs with the user's keys (local), or `APPEEKY_API_KEY` with a store connected in Appeeky (hosted). Do not ask for or handle key files yourself.
+   - Local App Store: `appstore accounts add`, or `ASC_KEY_ID`, `ASC_ISSUER_ID`, `ASC_PRIVATE_KEY`.
+   - Local Google Play: `gps accounts add`, or `GPS_CREDENTIALS`.
+   - `--via auto` (default) uses a local CLI when installed, hosted when `APPEEKY_API_KEY` is set. `APPEEKY_API_KEY` also adds keyword popularity and ideas.
+3. `init --name "<App>" --app-store <id> --google-play <package> --pull`, then fill `targets` (see appeeky-spec-targets).
+4. `doctor --json` lists everything still missing (store access, targets, the key, attribution, workflows, skills, `.gitignore`), each with its fix. Exit code 1 means something must be fixed.
+
+### Automation
+
+`init --ci` (also on an existing spec) writes three GitHub workflows:
+
+| Workflow | When | What |
+| --- | --- | --- |
+| `listing-check.yml` | every pull request | comments what the listing changes do (`report`), fails on check errors |
+| `listing-push.yml` | merge to main touching `appeeky/store/**` or the spec | `push --yes`, then commits the release file |
+| `listing-daily.yml` | daily 06:00 UTC | `category pull`, `visibility pull`, `verify --playbook`, `reviews pull`, `competitors pull`, then commits |
+
+The merge is the approval gate: nothing reaches the store unless a person merged it. The workflows need `APPEEKY_API_KEY` (or store keys) as repository secrets.
+
+Without GitHub Actions the same commands run anywhere:
+
+- **Other CI** (GitLab, Bitbucket, CircleCI): the same three triggers and commands.
+- **cron or launchd** on the user's machine: `examples/weekly/` has a script.
+- **The user's own server** (or Railway, Fly, Render): `docker/docker-compose.yml` with a `.env` from `docker/.env.example`, then `docker compose up -d`. It runs the routines on a schedule and commits back. Its push routine only pushes listing changes that reached `main` after it started, so the merge stays the gate. Suggest `PUSH_DRY_RUN=1` for the first days.
+- **A scheduled agent:** it runs the daily commands and the weekly routine below.
+- **By hand:** `status` flags checks that are late.
+
+Without CI, a person runs `push`. Never take over that gate with `--yes`.
+
+## Workflow
+
+1. **Understand.** Run `status` (or read `appeeky/loops.md`; `status --json` lists the `free` stores): do not start a change on a store that already has a release being measured, or the two results mix. Read `appeeky/playbook.md` and recent releases (`log --json`). Do not repeat a change that already lost unless something changed. With `APPEEKY_API_KEY`, refresh and read what users and competitors say: `reviews pull` then `appeeky/reviews/summary.md`, `competitors pull` then `appeeky/competitors/`, `visibility pull` then `appeeky/visibility/`, and `data pull` for the numbers (`.appeeky/data/README.md`). `category pull` records today's category rank (the App Store needs no key). Words users use in reviews and searches competitors win are good candidates for targets.
+2. **Find gaps.** `coverage --json`, `suggest --json` and `check --json`. Missing or `partial` high-popularity targets are the opportunities. `crossLocalization` lists extra locales a storefront reads with spare keyword space. If listings are missing, run `pull` first.
+3. **Propose.** Edit the listing files. Keep every word that currently covers a target unless the user agrees to drop it. For each change say which targets it should gain and which it could lose. One clear hypothesis per release.
+4. **Verify.** `check --json` (no errors allowed) and `diff --json`. Changes marked `blocked` cannot go live yet; tell the user why (usually: the App Store needs a new version, `push --create-version <x.y.z>`).
+5. **Ship only with consent.** Pushing changes the live store; on Google Play it is public within minutes. Run `push --note "<hypothesis>"` only when the user asked; use `--yes` only when they said so explicitly. Commit the release file it writes.
+6. **Learn.** After day 7, `verify --playbook --json` (see appeeky-spec-review).
+
+Never run `pull` over uncommitted listing edits: it overwrites local files.
+
+### Weekly routine
+
+For a scheduled or "what should we do this week" run, propose exactly one listing change. Make it for a `free` store (`status --json`), never one with a release still being measured.
+
+1. Read the sources:
+   - `status`, `appeeky/loops.md`, `appeeky/playbook.md`
+   - `appeeky/competitors/changes.md`, `appeeky/reviews/summary.md`, `appeeky/visibility/changes.md`
+   - `.appeeky/data/README.md`
+2. Pick the change most likely to win:
+   - an uncovered target,
+   - words users write in reviews,
+   - a search a competitor just climbed,
+   - an intent the assistants answer with competitors.
+
+   Do not repeat a change the playbook says lost.
+3. Edit, then `check` and `diff`. Write the pull request: what changes, why (with the numbers), which metric should move and when it is checked.
+4. Do not `push`. A person merges; the push runs on merge.
+
+To run it every week without anyone starting it:
+
+| Where | How |
+| --- | --- |
+| GitHub Actions | `examples/weekly/appeeky-spec-weekly.yml` |
+| The user's machine | `examples/weekly/weekly.sh` with cron or launchd |
+| The user's own server | `WEEKLY_AT=0 7 * * 1` in the docker `.env`, with the `latest-agent` image |
+
+All of them copy `examples/weekly/propose.md` to `.github/appeeky-propose.md`.
+
+The agent needs one of two things:
+- **`CLAUDE_CODE_OAUTH_TOKEN`:** the user runs `claude setup-token` once on their computer. Runs then count against their Claude Pro or Max plan, with no API key.
+- **`ANTHROPIC_API_KEY`:** billed per use.
+
+Set it as a repository secret or in the `.env`. Never ask the user to paste a token into chat or commit it.
+
+### Before and after a change
+
+- `competitors discover --add <n>` finds apps like this one and adds them to `competitors:`.
+- `report --base main` prints the Markdown a pull request needs: listing changes, check results and coverage.
+- `log --markdown` summarizes past releases.
+
+## App Store rules
+
+- Name 30, subtitle 30, keyword field 100, promotional text 170 characters. Counted in characters, not bytes (a Cyrillic or CJK letter is one).
+- Name, subtitle and keyword field words are indexed once and combine into phrases across the three. Never repeat a word across them. Separate keywords with commas and no spaces; a field without commas is read as one phrase.
+- Weight: name > subtitle > keyword field. The description is not indexed for search.
+- Skip filler words ("app", "the", "and", "for"), the app's category name and plurals of words already present (English).
+- Only promotional text changes without a new version.
+- A storefront can index more than one listing locale (the US App Store also reads Spanish (Mexico)). Use the extra locale's keyword field for more keywords for that storefront; `coverage` counts it.
+- Do not use competitor brand names or trademarks.
+
+## Google Play rules
+
+- Title 30, short description 80, full description 4000 characters. All three are indexed; use the main keywords naturally in the full description, without stuffing.
+- No ranking or promotional words ("best", "#1", "top", "free", "sale"), emoji or all caps in the title.
+- Changes go live without an app update. A new language needs all three text fields.
+
+## Screenshots
+
+`screenshots pull` downloads the live App Store screenshots of every locale into `appeeky/screenshots/app-store/`. `screenshots check` (also part of `check`) flags wrong sizes and counts per display type. Screenshots are not indexed for search; they change conversion, so treat a new set as an experiment.
+
+## Other experiments
+
+Screenshots, UGC, ads, pricing, attribution, smart links and the app's numbers: see appeeky-spec-experiments.
+
+Docs: https://docs.appeeky.com/docs/spec
+
+## AI visibility and category rank
+
+Whether ChatGPT, Claude, Gemini and Perplexity name the app (`aiVisibility:` in the spec, `visibility init|sync|pull`), and the daily category chart rank (`category pull`): see appeeky-spec-visibility. Never run `visibility sync --prune` or `visibility scan` unless the user asked.
+
+## Reviews
+
+`reviews list --rating 1-2 --unanswered --json` shows what needs an answer. Draft each reply with `reviews reply <id> --text "..."`: specific to what the user said, no promises the app does not keep, under 350 characters for Google Play. The drafts land in `appeeky/reviews/replies/`; open a pull request with them and send them with `reviews push` only after it is approved. Recurring complaints in reviews are listing input too: a feature people look for belongs in the description or the screenshots.

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

@@ -0,0 +1,83 @@
+---
+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 | `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.
+- `--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. 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.