@appeeky/spec 0.0.0-stage → 0.2.0

package/dist/visibility.d.ts

@@ -0,0 +1,152 @@
+import type { AppeekyApi } from "./appeeky-api.js";
+import type { MetricSource } from "./metrics.js";
+import type { Project, SpecFile, StoreId } from "./schema.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 declare const MODELS: readonly ["chatgpt", "claude", "gemini", "perplexity"];
+export type Model = (typeof MODELS)[number];
+export type AiIntent = NonNullable<SpecFile["aiVisibility"]>["intents"][string][number];
+export declare const visibilityDir: (root: string) => string;
+export declare const visibilityChangesFile: (root: string) => string;
+export interface VisibilityTarget {
+    store: StoreId;
+    /** The store id: numeric App Store id or Google Play package name. */
+    appId: string;
+    countries: string[];
+}
+/** Which app and storefronts to watch. */
+export declare function visibilityTarget(project: Project): VisibilityTarget | null;
+/** ISO 639-1 language for a storefront's prompts, from the listing locale it indexes first. */
+export declare function languageFor(project: Project, country: string): string;
+export interface RemoteIntentRow {
+    intentId: string;
+    label: string;
+    description: string | null;
+    status: "active" | "paused" | "archived";
+    visibilityPct: number;
+    promptsTotal: number;
+}
+export interface RemotePrompt {
+    promptId: string;
+    text: string;
+    status: "active" | "paused" | "archived";
+}
+interface Opportunity {
+    intentId: string;
+    label: string;
+    status: "missing" | "weak" | "winning" | "no_data";
+    ownerVisibilityPct: number | null;
+    byModel: Partial<Record<Model, {
+        visibilityPct: number;
+        positionAvg: number | null;
+        promptsTotal: number;
+        date: string;
+    }>>;
+    winners: Array<{
+        name: string;
+        sharePct: number;
+        models: Model[];
+    }>;
+}
+export declare function remoteIntents(api: AppeekyApi, appId: string, country: string): Promise<RemoteIntentRow[]>;
+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;
+    /** Intents by status: missing = no assistant names the app, weak = some do, rarely. */
+    summary: {
+        winning: number;
+        weak: number;
+        missing: number;
+        noData: number;
+    };
+    intents: Array<{
+        label: string;
+        status: Opportunity["status"];
+        /** Share of prompts whose answer names the app, averaged over the assistants (0–100). */
+        you?: number;
+        byModel?: Partial<Record<Model, number>>;
+        /** Who the assistants name instead. */
+        namedInstead?: string[];
+    }>;
+    /** Pages the assistants cite, most cited first. */
+    sources: Array<{
+        domain: string;
+        count: number;
+        yours?: true;
+        url: string;
+    }>;
+    /** What Appeeky suggests changing, still open. */
+    fixes: Array<{
+        intent: string;
+        title: string;
+        why: string;
+        page?: string;
+    }>;
+}
+export declare function fetchVisibility(api: AppeekyApi, target: VisibilityTarget, country: string, now?: Date): Promise<VisibilityFile>;
+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;
+    file?: string;
+    data?: VisibilityFile;
+    changes: string[];
+    error?: string;
+}>>;
+/** The intents and prompts Appeeky tracks for a storefront, in the spec's shape. */
+export declare function readRemoteIntents(api: AppeekyApi, appId: string, country: string): Promise<AiIntent[]>;
+/** Ask Appeeky to write intents and prompts from the store listing (runs in the background). */
+export declare function bootstrapIntents(api: AppeekyApi, appId: string, country: string, language: string): Promise<{
+    queued: boolean;
+    already: boolean;
+}>;
+export interface SyncPlan {
+    country: string;
+    addIntents: AiIntent[];
+    addPrompts: Array<{
+        intentId: string;
+        label: string;
+        text: string;
+    }>;
+    /** Tracked in Appeeky but not in the spec: archived only with --prune. */
+    extraIntents: Array<{
+        intentId: string;
+        label: string;
+    }>;
+    extraPrompts: Array<{
+        promptId: string;
+        label: string;
+        text: string;
+    }>;
+}
+/** Compare the spec's intents for a storefront with what Appeeky tracks. */
+export declare function planSync(api: AppeekyApi, appId: string, country: string, wanted: AiIntent[]): Promise<SyncPlan>;
+/** Apply a plan: add what the spec has; archive what it does not only when `prune` is set. */
+export declare function applySync(api: AppeekyApi, appId: string, plan: SyncPlan, language: string, prune: boolean): Promise<{
+    intents: number;
+    prompts: number;
+    archived: number;
+}>;
+/** Ask the assistants now instead of waiting for the schedule. Charged in AI Visibility credits. */
+export declare function scanVisibility(api: AppeekyApi, appId: string, country: string): Promise<unknown>;
+/**
+ * `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 declare function visibilityMetricSource(api: AppeekyApi, project: Project): MetricSource | null;
+export {};

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;
+}
+export 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,82 @@
 {
   "name": "@appeeky/spec",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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",
+  "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",
+    "agents",
+    ".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 && 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",
+    "vendor:ugc": "node scripts/vendor-ugc-core.mjs",
+    "vendor:visibility": "node scripts/vendor-visibility-core.mjs"
+  },
+  "dependencies": {
+    "commander": "^13.1.0",
+    "yaml": "^2.6.1",
+    "zod": "^3.24.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.3",
+    "esbuild": "^0.28.2",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.2"
+  }
+}

package/skills/appeeky-spec/SKILL.md

@@ -0,0 +1,142 @@
+---
+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 (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
+---
+
+# 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 (`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 |
+
+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`, `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.
+
+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: the co-founder review
+
+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. `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.
+
+`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:
+
+| 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 |
+
+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.
+- **`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.