@appeeky/spec 0.1.0 → 0.2.0

package/dist/visibility-local.js

@@ -0,0 +1,246 @@
+import { existsSync } from "node:fs";
+import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import YAML from "yaml";
+import { indexedLocales, playLanguageFor } from "./storefronts.js";
+import { languageFor, readVisibility, recordChanges, visibilityChanges, visibilityDir, visibilityPath, visibilityTarget } from "./visibility.js";
+export const VISIBILITY_CORE_FILE = "./visibility-core.js";
+export async function loadVisibilityCore(load = (s) => import(s)) {
+    try {
+        return (await load(VISIBILITY_CORE_FILE));
+    }
+    catch {
+        throw new Error("This build of @appeeky/spec has no AI visibility pipeline (dist/visibility-core.js). Update it: npm install -g @appeeky/spec@latest");
+    }
+}
+export const KEY_NAMES = "OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY or PERPLEXITY_API_KEY";
+/** The listing the storefront shows, as context for intents and prompts. */
+export function appContext(project, country) {
+    const as = project.listings["app-store"][indexedLocales(project, country)[0] ?? ""];
+    const playLang = playLanguageFor(project, country);
+    const gp = playLang ? project.listings["google-play"][playLang] : undefined;
+    return {
+        title: as?.name ?? gp?.title ?? project.spec.app.name,
+        subtitle: as?.subtitle ?? gp?.shortDescription,
+        description: as?.description ?? gp?.fullDescription,
+        keywords: project.spec.targets[country] ?? [],
+        competitors: project.spec.competitors.map((c) => c.name).filter((n) => Boolean(n)),
+        country,
+        language: languageFor(project, country),
+    };
+}
+/** Every name the assistants may use for the app. */
+export function ownerNames(project) {
+    const names = new Set([project.spec.app.name, ...(project.spec.aiVisibility?.aliases ?? [])]);
+    for (const l of Object.values(project.listings["app-store"]))
+        if (l.name)
+            names.add(l.name);
+    for (const l of Object.values(project.listings["google-play"]))
+        if (l.title)
+            names.add(l.title);
+    return [...names];
+}
+/** The app's own domains: its website and the listing's marketing and support URLs. */
+export function ownDomains(project) {
+    const urls = [project.spec.web?.url, ...Object.values(project.listings["app-store"]).flatMap((l) => [l.marketingUrl, l.supportUrl])];
+    const out = new Set();
+    for (const u of urls) {
+        if (!u)
+            continue;
+        try {
+            const host = new URL(u).hostname.replace(/^www\./, "");
+            if (!/(^|\.)(apple\.com|google\.com|notion\.site|github\.io)$/.test(host))
+                out.add(host);
+        }
+        catch {
+            // not a URL
+        }
+    }
+    return [...out];
+}
+export function planLocalScan(core, project, country, env) {
+    const intents = project.spec.aiVisibility?.intents[country] ?? [];
+    const models = core.availableModels(env, project.spec.aiVisibility?.models);
+    const prompts = intents.reduce((n, i) => n + i.prompts.length, 0);
+    return { country, intents, prompts, models, helper: core.helperFor(env), quoteUsd: core.quoteScan(prompts, models, env) };
+}
+async function pool(items, size, run) {
+    let next = 0;
+    await Promise.all(Array.from({ length: Math.min(size, items.length) }, async () => {
+        while (next < items.length)
+            await run(items[next++]);
+    }));
+}
+export const historyFile = (root) => join(visibilityDir(root), "history.csv");
+export const answersFile = (root, country) => join(visibilityDir(root), "answers", `${country}.jsonl`);
+const HISTORY_HEADER = "date,country,intent,model,visibility_pct,position,prompts\n";
+const csv = (v) => (v === null || v === undefined ? "" : /[",\n]/.test(String(v)) ? `"${String(v).replace(/"/g, '""')}"` : String(v));
+/** Ask every assistant every prompt for one storefront, then write the snapshot, the answers and a history row per intent and assistant. */
+export async function scanLocal(core, project, plan, env, options = {}) {
+    const { country } = plan;
+    if (!plan.helper)
+        throw new Error(`Set ${KEY_NAMES} to scan with your own keys.`);
+    if (plan.models.length === 0)
+        throw new Error(`None of the assistants in aiVisibility.models has a key. Set ${KEY_NAMES}.`);
+    const target = visibilityTarget(project);
+    const now = options.now ?? new Date();
+    const owner = ownerNames(project);
+    const ctx = appContext(project, country);
+    const jobs = plan.intents.flatMap((i) => i.prompts.map((prompt) => plan.models.map((model) => ({ intent: i.label, prompt, model })))).flat();
+    const scored = [];
+    const raw = [];
+    const failed = [];
+    let cost = 0;
+    let done = 0;
+    await pool(jobs, options.concurrency ?? 4, async (job) => {
+        const answer = await core.ask(job.model, core.keyFor(job.model, env), { prompt: job.prompt, country, language: ctx.language }, options.fetcher);
+        cost += answer.costUsd;
+        let mentions = [];
+        let status = answer.status;
+        if (answer.status === "ok") {
+            try {
+                const x = await core.extract(plan.helper, { answer: answer.text, prompt: job.prompt, owner: owner[0], competitors: ctx.competitors ?? [], citations: answer.citations }, options.fetcher);
+                cost += x.costUsd;
+                mentions = x.mentions;
+                if (x.refusal)
+                    status = "refusal";
+            }
+            catch (e) {
+                status = "error";
+                answer.error = `extracting the apps: ${e.message}`;
+            }
+        }
+        if (status === "error")
+            failed.push({ model: job.model, error: answer.error ?? "no answer" });
+        const row = { ...job, status, mentions, citations: answer.citations };
+        scored.push(row);
+        raw.push({ ...row, text: answer.text, ...(answer.error ? { error: answer.error } : {}) });
+        done++;
+        if (done % 10 === 0 || done === jobs.length)
+            options.log?.(`${done}/${jobs.length} answers`);
+    });
+    const labels = plan.intents.map((i) => i.label);
+    const scores = core.score(scored, labels, owner);
+    const sources = core.citedDomains(scored, ownDomains(project));
+    const summary = { winning: 0, weak: 0, missing: 0, noData: 0 };
+    for (const s of scores) {
+        if (s.status === "no_data")
+            summary.noData++;
+        else
+            summary[s.status]++;
+    }
+    const order = { missing: 0, weak: 1, winning: 2, no_data: 3 };
+    const date = now.toISOString().slice(0, 10);
+    const data = {
+        pulledAt: date,
+        source: "local",
+        country,
+        store: target?.store ?? "app-store",
+        appId: target?.appId ?? project.spec.app.name,
+        summary,
+        intents: [...scores]
+            .sort((a, b) => order[a.status] - order[b.status] || (a.you ?? 0) - (b.you ?? 0))
+            .map((s) => {
+            const byModel = Object.fromEntries(Object.entries(s.byModel).map(([m, v]) => [m, Math.round(v.pct)]));
+            return {
+                label: s.label,
+                status: s.status,
+                ...(s.you !== undefined ? { you: Math.round(s.you) } : {}),
+                ...(Object.keys(byModel).length ? { byModel } : {}),
+                ...(s.namedInstead.length ? { namedInstead: s.namedInstead.map((w) => `${w.name} (${Math.round(w.pct)}%)`) } : {}),
+            };
+        }),
+        sources: sources.slice(0, 15).map((s) => ({ domain: s.domain, count: s.count, ...(s.yours ? { yours: true } : {}), url: s.url })),
+        fixes: [],
+    };
+    await mkdir(join(visibilityDir(project.root), "answers"), { recursive: true });
+    const file = visibilityPath(project.root, country);
+    const prev = await readVisibility(project.root, country);
+    const changes = prev ? visibilityChanges(prev, data) : [];
+    await recordChanges(project.root, date, country, changes);
+    await writeFile(file, YAML.stringify(data, { lineWidth: 0 }));
+    const byPrompt = (a) => `${a.intent}\u0000${a.prompt}\u0000${a.model}`;
+    raw.sort((a, b) => byPrompt(a).localeCompare(byPrompt(b)));
+    await writeFile(answersFile(project.root, country), raw.map((r) => JSON.stringify({ date, ...r })).join("\n") + "\n");
+    const hist = historyFile(project.root);
+    if (!existsSync(hist))
+        await writeFile(hist, HISTORY_HEADER);
+    const rows = scores.flatMap((s) => Object.entries(s.byModel).map(([m, v]) => [date, country, s.label, m, v.pct, v.position, v.prompts].map(csv).join(",")));
+    if (rows.length)
+        await appendFile(hist, rows.join("\n") + "\n");
+    return { country, file, data, changes, costUsd: Math.round(cost * 100) / 100, answered: scored.filter((a) => a.status !== "error").length, failed };
+}
+/** Days since the last local scan of a storefront, from history.csv; null when it never ran. */
+export async function daysSinceLocalScan(root, country, now = new Date()) {
+    const rows = await readHistory(root);
+    const last = rows.filter((r) => r.country === country).map((r) => r.date).sort().at(-1);
+    return last ? Math.floor((now.getTime() - Date.parse(last)) / 86_400_000) : null;
+}
+function splitCsv(line) {
+    const out = [];
+    let cur = "";
+    let quoted = false;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (quoted) {
+            if (ch === '"' && line[i + 1] === '"') {
+                cur += '"';
+                i++;
+            }
+            else if (ch === '"')
+                quoted = false;
+            else
+                cur += ch;
+        }
+        else if (ch === '"')
+            quoted = true;
+        else if (ch === ",") {
+            out.push(cur);
+            cur = "";
+        }
+        else
+            cur += ch;
+    }
+    out.push(cur);
+    return out;
+}
+async function readHistory(root) {
+    const file = historyFile(root);
+    if (!existsSync(file))
+        return [];
+    return (await readFile(file, "utf8"))
+        .split("\n")
+        .slice(1)
+        .filter(Boolean)
+        .map((l) => {
+        const [date, country, intent, model, pct] = splitCsv(l);
+        return { date: date, country: country, intent: intent, model: model, pct: Number(pct) };
+    });
+}
+/** `ai_visibility` from the local scans in the repo: the share of answers that name the app, averaged per scan day (0–1). */
+export function localVisibilityMetricSource(project) {
+    const target = visibilityTarget(project);
+    if (!target || !existsSync(historyFile(project.root)))
+        return null;
+    const country = target.countries[0];
+    let history;
+    return {
+        label: "AI visibility scans in the repo",
+        async window(store, _appId, from, to) {
+            if (store !== target.store)
+                return null;
+            history ??= readHistory(project.root);
+            const byDay = new Map();
+            for (const r of await history)
+                if (r.country === country && r.date >= from && r.date < to && Number.isFinite(r.pct))
+                    byDay.set(r.date, [...(byDay.get(r.date) ?? []), r.pct]);
+            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-local.js.map

package/dist/visibility.d.ts

@@ -57,6 +57,8 @@ export declare function remoteIntents(api: AppeekyApi, appId: string, country: s
 export declare function remotePrompts(api: AppeekyApi, appId: string, country: string, intentId: string): Promise<RemotePrompt[]>;
 export interface VisibilityFile {
     pulledAt: string;
+    /** Where the answers came from: Appeeky AI Visibility, or `visibility scan --local` on your own keys. */
+    source?: "appeeky" | "local";
     country: string;
     store: StoreId;
     appId: string;
@@ -96,6 +98,7 @@ export declare const visibilityPath: (root: string, country: string) => string;
 export declare function readVisibility(root: string, country: string): Promise<VisibilityFile | null>;
 /** What moved since the last pull: an intent the assistants started or stopped naming the app for. */
 export declare function visibilityChanges(prev: VisibilityFile, next: VisibilityFile): string[];
+export declare function recordChanges(root: string, date: string, country: string, changes: string[]): Promise<void>;
 /** Pull every watched storefront and write its file. */
 export declare function pullVisibility(api: AppeekyApi, project: Project, countries?: string[], now?: Date): Promise<Array<{
     country: string;

package/dist/visibility.js

@@ -91,7 +91,7 @@ export function visibilityChanges(prev, next) {
         out.push("the assistants stopped citing your own site");
     return out;
 }
-async function recordChanges(root, date, country, changes) {
+export async function recordChanges(root, date, country, changes) {
     if (changes.length === 0)
         return;
     const file = visibilityChangesFile(root);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appeeky/spec",
-  "version": "0.1.0",
+  "version": "0.2.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",
@@ -24,6 +24,7 @@
     "dist",
     "!dist/**/*.map",
     "skills",
+    "agents",
     ".github/assets/cover.gif",
     "LICENSE",
     "README.md"
@@ -56,14 +57,16 @@
     "node": ">=20"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "tsc -p tsconfig.build.json && node -e \"for (const f of ['ugc-core.js','visibility-core.js']) require('fs').copyFileSync('vendor/'+f,'dist/'+f)\"",
     "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"
+    "release:dry": "node scripts/release.mjs --dry-run",
+    "vendor:ugc": "node scripts/vendor-ugc-core.mjs",
+    "vendor:visibility": "node scripts/vendor-visibility-core.mjs"
   },
   "dependencies": {
     "commander": "^13.1.0",
@@ -72,6 +75,7 @@
   },
   "devDependencies": {
     "@types/node": "^22.15.3",
+    "esbuild": "^0.28.2",
     "typescript": "^5.8.3",
     "vitest": "^3.1.2"
   }

package/skills/appeeky-spec/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+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 (the co-founder review with the specialist subagents). 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
 ---
@@ -20,7 +20,8 @@ The app's store listings live in files, and every push is recorded and measured.
 | `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/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 (`history.csv` and `answers/` with `--local` scans) |
+| `appeeky/seo/` | Google Search Console for the app's website: `daily.csv`, `queries.csv`, `pages.csv`, `summary.md` (`seo pull`) |
 | `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 |
 
@@ -46,7 +47,7 @@ In a terminal the user runs, `init` with no options is a guided setup. It finds
 | --- | --- | --- |
 | `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 |
+| `listing-daily.yml` | daily 06:00 UTC | `category pull`, `visibility pull`, `verify --playbook`, `reviews pull`, `competitors pull`, `social pull`, `ugc pull`; `seo pull` with `GSC_CREDENTIALS` and `visibility scan --local` every `VISIBILITY_EVERY` days; 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.
 
@@ -71,23 +72,18 @@ Without CI, a person runs `push`. Never take over that gate with `--yes`.
 
 Never run `pull` over uncommitted listing edits: it overwrites local files.
 
-### Weekly routine
+### Weekly routine: the co-founder review
 
-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.
+For a scheduled or "what should we do this week" run, follow the co-founder review: `agents/cofounder.md` in this package, installed as the `/appeeky-cofounder` command by `agents install`.
 
-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.
+1. `status --json`: only the `free` stores may change. Read `appeeky/loops.md`, `appeeky/playbook.md` and the latest brief in `appeeky/briefs/`.
+2. Start the specialist subagents in parallel: `appeeky-aso`, `appeeky-reviews`, `appeeky-ads`, `appeeky-releases`, `appeeky-ugc`, `appeeky-social`. They only read, and each returns findings and up to two candidate changes. Without subagents, do their checklists yourself.
+3. Pick exactly one change for a free store, the one with the strongest evidence. Never repeat a change the playbook says lost.
+4. Edit, then `check` and `diff`.
+5. Write the brief to `appeeky/briefs/<date>.md`: where things stand, what each specialist found, the change (or why none), what is for a person (replies, ads, product requests, the next UGC experiment, posts to publish), and what was not picked.
+6. Write `.appeeky/proposal.md` for the pull request. Do not `push`. A person merges; the push runs on merge.
 
-   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.
+`npx @appeeky/spec agents install` writes the specialists and the command into `.claude/` (`--for opencode` or `all` for `.opencode/`). Commit them so scheduled runs have them too.
 
 To run it every week without anyone starting it:
 
@@ -97,7 +93,7 @@ To run it every week without anyone starting it:
 | 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`.
+Each uses `.github/appeeky-propose.md` when it exists, otherwise the installed `.claude/commands/appeeky-cofounder.md`. The pull request carries the brief, and the listing change when there is one.
 
 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.

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

@@ -19,7 +19,7 @@ Run commands as `npx @appeeky/spec <command> --json`.
 | --- | --- |
 | `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` |
+| 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` |
@@ -71,10 +71,20 @@ npx @appeeky/spec experiment close <id> --value 3.1 --note "Hook B: 3.1 installs
 ## 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. Data for analysis
+## 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.
 

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

@@ -1,13 +1,13 @@
 ---
 name: appeeky-spec-visibility
-description: Get an app named when people ask ChatGPT, Claude, Gemini or Perplexity for an app like it, 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, or how the app ranks in its category.
+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
 
-Two ways people find an app outside a keyword search: they ask an AI assistant, or they browse the category chart. The spec records both and `verify` measures them around every push.
+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`.
 
@@ -19,13 +19,18 @@ Run commands as `npx @appeeky/spec <command> --json`.
 - 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.
 
-Needs `APPEEKY_API_KEY` on a plan with AI Visibility.
+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.
+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. 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.
+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:
 
@@ -62,7 +67,29 @@ Never write fake reviews, posts or comments, and never make claims the app does
 
 ### Measure it
 
-`verify` reads Appeeky's daily series as `ai_visibility`, the 0–1 share of answers that name the app. 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` asks the assistants now. It uses AI Visibility credits: run it only when the user asks.
+`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