@appeeky/spec 0.1.0 → 0.2.0

package/README.md

@@ -44,7 +44,7 @@ npx @appeeky/spec verify        # day 7 and day 14: did it work?
 | **What users and rivals say** | Reviews with a summary and drafted replies, competitors' listings and moves, and the category chart rank, one row a day. |
 | **AI visibility** | Whether ChatGPT, Claude, Gemini and Perplexity name your app, who they name instead and the pages they cite. |
 | **Ads and data** | Apple Search Ads, Meta and TikTok spend and installs, App Store Connect, Google Play and RevenueCat numbers as CSV your agent can read. |
-| **A weekly proposal** | Once a week an agent opens a pull request with one listing change, for a store with no release still being measured. It can run on your Claude plan. |
+| **Specialists and a co-founder** | Six read-only specialist subagents (ASO, reviews, ads, releases, UGC, social) and a co-founder review that starts them, writes a brief to `appeeky/briefs/` and opens a pull request with one listing change. Run it as `/appeeky-cofounder`, or once a week on your Claude plan. |
 
 ## How a change goes live
 
@@ -66,7 +66,7 @@ Nothing reaches the stores until a person merges. The merge is the approval.
 | --- | --- |
 | **GitHub Actions** | `init --ci` writes three workflows: a check on every pull request, a push on merge, and a daily run that measures and commits. See [In pull requests](#in-pull-requests). |
 | **Your own server** | `docker compose up -d` on any VM: Hetzner, DigitalOcean, AWS, Google Cloud, Railway, Fly.io, Render or a machine in your office. See [Running without GitHub Actions](#running-without-github-actions). |
-| **Your computer** | Every command runs locally with `npx`. `examples/weekly/` has a cron script for the weekly proposal. |
+| **Your computer** | Every command runs locally with `npx`. `examples/weekly/` has a cron script for the weekly co-founder review. |
 | **Other CI** | GitLab, Bitbucket or CircleCI: the same three triggers and commands. |
 
 Powered by [Appeeky](https://appeeky.com). Works with your own store keys on your machine, or with your Appeeky connection when you'd rather not handle keys.
@@ -83,6 +83,8 @@ appeeky/
   reviews/                        # customer reviews (JSONL per month), summary.md, replies/ drafted for review
   competitors/                    # one file per competitor: listing, ranks, recent reviews
   visibility/<country>.yaml       # what ChatGPT, Claude, Gemini and Perplexity answer: named or not, who instead, cited pages
+  seo/                            # Google Search Console for the website: clicks per day, queries, pages, summary.md
+  search-ads/                     # Apple Search Ads on your own key: spend and installs per day, keywords, search terms
   category.csv                    # rank in the category chart, one row a day
   playbook.md                     # what worked and what did not for this app
 .appeeky/data/                    # analytics, ads and revenue as CSV (gitignored; data.commit moves it to appeeky/data/)
@@ -126,7 +128,9 @@ A field you leave out of a listing file is not managed by the spec: it is never
 | `ads` | Spend, installs and cost per install of your paid channels over the last `--days` (default 30): Apple Search Ads, plus the Meta and TikTok campaigns under `ads:`. `--save` writes them to `appeeky/ads/<date>.yaml`. Needs `APPEEKY_API_KEY`. |
 | `reviews pull\|list\|reply\|push` | Customer reviews from both stores into `appeeky/reviews/`, with `summary.md`. `reply <id> --text` drafts an answer in `appeeky/reviews/replies/` for a pull request; `push` sends the drafts. |
 | `competitors discover\|pull` | `discover` lists apps like yours (`--add <n>` puts them in the spec). `pull` writes each competitor's listing, the searches it ranks for and its recent reviews to `appeeky/competitors/`. |
-| `visibility init\|sync\|pull\|scan` | AI visibility: whether ChatGPT, Claude, Gemini and Perplexity name your app. `init` writes the intents and prompts Appeeky tracks into the spec, `sync` sends your edits back, `pull` writes the answers to `appeeky/visibility/`, `scan` asks the assistants now. Needs `APPEEKY_API_KEY`. |
+| `visibility init\|sync\|pull\|scan` | AI visibility: whether ChatGPT, Claude, Gemini and Perplexity name your app. `init` writes the intents and prompts Appeeky tracks into the spec, `sync` sends your edits back, `pull` writes the answers to `appeeky/visibility/`, `scan` asks the assistants now. Needs `APPEEKY_API_KEY`, or with `init --local` / `scan --local` your own OpenAI, Anthropic, Gemini or Perplexity key. |
+| `search-ads pull` | Apple Search Ads on your own API key: this app's spend, installs, keywords and search terms in `appeeky/search-ads/`, with the search terms that installed and are not targets yet. `ads` and `verify` read it. |
+| `seo check\|llms\|pull\|ranks\|keywords\|domain` | The app's website in Google and in AI answers. `check` lists what is missing for search, for the app and for AI crawlers; `llms` writes llms.txt from the listing; `pull` writes Search Console clicks, queries and pages to `appeeky/seo/` (`GSC_CREDENTIALS`). On your own DataForSEO account: `ranks` (Google positions of the site and the store page, and AI Overview citations), `keywords` (volume, difficulty, ideas) and `domain` (what the site ranks for, competing sites). |
 | `category pull` | Record today's rank in the category chart (top 100) in `appeeky/category.csv`. App Store needs no key; Google Play needs `APPEEKY_API_KEY` and `category.googlePlay`. |
 | `data pull` | App Store Connect, Google Play, Apple Search Ads, RevenueCat, Meta and TikTok numbers per day, and attribution by source, keyword and smart link, as CSV files with an index (`--days`, default 90). |
 | `status` | Every change being measured, in one list: releases and experiments, the metric that decides each, the next check and the result so far. Flags checks that are late, releases measured over the same days, and results built on too few installs. Rewrites `appeeky/loops.md`. |
@@ -135,6 +139,9 @@ A field you leave out of a listing file is not managed by the spec: it is never
 | `experiment add\|list\|close` | Track growth experiments outside the listing (screenshots, UGC, ads, pricing) with one metric and a check date. |
 | `screenshots pull\|check` | Download the live App Store screenshots into `appeeky/screenshots/` and check their sizes. |
 | `report` | Markdown for a pull request: listing changes, check results and coverage against `--base`. |
+| `social pull\|check\|push` | Organic social media through the accounts connected in Appeeky: `pull` writes the accounts, recent posts and how they did to `appeeky/social/`; `check` checks the drafts in `appeeky/social/drafts/`; `push` sends them. Needs `APPEEKY_API_KEY`. |
+| `ugc pull\|generate` | UGC from your Appeeky creator personas: `pull` writes the personas and their clips to `appeeky/ugc/`; `generate` makes a clip from each brief in `appeeky/ugc/briefs/` (`--dry-run` shows the cost in media credits). Needs `APPEEKY_API_KEY`. |
+| `agents install` | Write the specialist subagents and the `/appeeky-cofounder` review into `.claude/` (`--for opencode` or `all` for `.opencode/`). Files you changed are kept unless `--force`. |
 
 Global options: `--json` for machine-readable output, `--cwd <dir>`, `--via auto|local|hosted`.
 
@@ -229,7 +236,7 @@ competitors:
 
 `competitors pull` writes `appeeky/competitors/calm-night.yaml`: title, rating, version and release notes, the first part of the description, the 25 searches it ranks best for in your first targets country, where it ranks for your own targets, and its recent low ratings. Each pull compares with the last one and adds what changed to `appeeky/competitors/changes.md`: a new title, a new version and its notes, a rewritten description, a climb into the top 10 for one of your targets. `status` warns a release being measured when a competitor changed something inside its window.
 
-**A weekly proposal.** An agent can propose one listing change a week as a pull request, for a store with no release still being measured: `status --json` lists those stores as `free`, so a new change never mixes with an open one. [`examples/weekly/`](examples/weekly) has a GitHub Actions workflow, the prompt it gives the agent, and the same thing as a script for cron on a machine of your own. The agent reads `loops.md`, the playbook, competitor changes, reviews and your numbers, edits the listing, runs `check` and `diff`, and writes why in the pull request. Nothing reaches the stores until someone merges it.
+**A weekly co-founder review.** Once a week the specialist subagents read the repo, and an agent writes a brief and proposes one listing change as a pull request, for a store with no release still being measured: `status --json` lists those stores as `free`, so a new change never mixes with an open one. See [Specialists and the co-founder review](#specialists-and-the-co-founder-review). [`examples/weekly/`](examples/weekly) has a GitHub Actions workflow and the same thing as a script for cron on a machine of your own. Nothing reaches the stores until someone merges it.
 
 **Data.** `data pull` writes CSV files per source, merged by date on every pull, with a `README.md` index:
 
@@ -261,6 +268,55 @@ jobs:
       - run: git add appeeky && git commit -m "Daily category, AI visibility, reviews, competitors and verify" && git push || true
 ```
 
+## Social media and UGC
+
+With the social accounts and creator personas you set up in Appeeky, posts and videos go through the repo like listing changes: drafted, reviewed in a pull request, sent after the merge.
+
+```
+appeeky/social/accounts.yaml        connected accounts (platform, name, id)
+appeeky/social/posts.jsonl          recent posts and each platform's result: views, likes, comments, shares
+appeeky/social/summary.md           the last 30 days per platform, and what did best
+appeeky/social/drafts/<name>.yaml   a post to send: accounts, text, when, media, why
+appeeky/ugc/personas.yaml           creator personas, and whether each can make clips yet
+appeeky/ugc/clips.jsonl             the clips made with them
+appeeky/ugc/briefs/<name>.yaml      a video to make: persona, script, scene, caption, why
+appeeky/ugc/personas/<name>.yaml    optional: a persona kept in the repo, with its look images, for --local
+```
+
+```yaml
+# appeeky/social/drafts/2026-11-10-fan-sounds.yaml
+accounts: [twitter, instagram]       # platforms from accounts.yaml, or account ids
+text: "Fan sounds are here. Pick a fan, set a timer, sleep."
+when: "2026-11-12T16:00:00Z"          # without it, the post goes out when it is sent
+media: ["https://…/fan.mp4"]          # Instagram, TikTok and Pinterest need one
+why: "Users asked for fan sounds in 9 reviews; it shipped in 3.2."
+```
+
+`social check` flags drafts that would fail: a platform with no connected account, text over the platform's limit, a missing image, a time in the past. `ugc generate --dry-run` shows what each brief costs in media credits without making anything. The push workflow written by `init --ci` (and the docker `push` routine) runs `social push --yes` and `ugc generate --yes` when a merged pull request adds drafts or briefs; each is marked `sent` or `generating` and committed, so it never goes out twice. Social media needs the Startup plan or above in Appeeky; a persona needs a look (reference images) before it can make clips.
+
+### Clips on your own fal key
+
+`ugc generate --local` makes the clips where Spec runs, with your own [fal](https://fal.ai) key, instead of in Appeeky with media credits. It is the same pipeline as Appeeky UGC (a still of the persona in the scene, then a talking video with the script in their voice) and fal bills your account directly.
+
+```bash
+export FAL_KEY=…                         # fal.ai → API keys
+appeeky-spec ugc generate --local --dry-run   # what each brief costs on fal, in USD
+appeeky-spec ugc generate --local             # asks first, then renders
+```
+
+The persona is either one from Appeeky (its cover image is the look, needs `APPEEKY_API_KEY`) or one kept in the repo:
+
+```yaml
+# appeeky/ugc/personas/mia.yaml
+name: Mia
+appearance: early 20s, dyed pink bob, oversized hoodie
+personality: playful, talks fast
+lane: dance trends and sound edits
+looks: [mia/front.png, mia/side.png]     # images next to this file, or URLs
+```
+
+The clip is saved to `.appeeky/media/<brief>.mp4` (gitignored) and the brief records `clipFile`, fal's `videoUrl` (use it in a social draft's `media:`) and `costUsd`. With `FAL_KEY` set as a secret, the push workflow and the docker `push` routine render locally too.
+
 ## AI visibility
 
 People ask ChatGPT, Claude, Gemini and Perplexity for apps, not only the store. Appeeky AI Visibility asks them on a schedule, per storefront, and records whether they name your app. The questions live in the spec: an **intent** is what someone wants, its **prompts** are how they ask.
@@ -283,6 +339,79 @@ aiVisibility:
 
 `verify` reads the daily series as `ai_visibility`, the share of answers that name the app, before and after a push. A description that says what the app is for in the words people use can move it, and so can the pages the assistants cite.
 
+### On your own keys
+
+The same scan runs where Spec runs, on your own model accounts, with no Appeeky account. Set any of `OPENAI_API_KEY` (ChatGPT), `ANTHROPIC_API_KEY` (Claude), `GEMINI_API_KEY` (Gemini) and `PERPLEXITY_API_KEY` (Perplexity); each key adds that assistant.
+
+```bash
+npx @appeeky/spec visibility init --local          # intents and prompts from your listing, written into the spec
+npx @appeeky/spec visibility scan --local --dry-run
+# US  6 intents · 24 prompts × chatgpt, claude, gemini, perplexity · about $2.45
+npx @appeeky/spec visibility scan --local
+```
+
+Each prompt goes to each assistant with web search on, the way the apps answer people, and a second cheap call lists the apps each answer names. The result is the same `appeeky/visibility/<country>.yaml`, plus `history.csv` (one row per scan, intent and assistant, read by `verify`) and `answers/<country>.jsonl` with every answer. Add `aliases:` under `aiVisibility` for other names the assistants use for the app.
+
+On a schedule: set `VISIBILITY_EVERY` (days, e.g. `7`) as a repository variable or in the docker `.env`, with the keys as secrets, and the daily routine scans when it is due.
+
+## Apple Search Ads on your own key
+
+Without an Appeeky account, read Search Ads straight from Apple. In Apple Search Ads → Account Settings → API, invite an API user with a read role and upload its public key. Then save the key on the same App Store Connect CLI account that holds your App Store Connect key, so both live in one place and the private key never leaves the CLI:
+
+```bash
+appstore accounts search-ads my-team --client-id SEARCHADS.… --team-id SEARCHADS.… --key-id … --private-key-path ./searchads-private-key.pem
+npx @appeeky/spec search-ads pull
+# ✓ appeeky/search-ads/  US Exact, Discovery
+#   30 days: 412.80 EUR · 236 installs · 1.75 EUR each · 980 taps
+```
+
+```yaml
+stores:
+  appStore:
+    appId: "1234567890"
+    searchAds:
+      orgId: "1234567"        # only when the key reaches more than one organization
+      campaigns: ["987654"]   # optional: only these campaigns
+```
+
+The spec uses `stores.appStore.account` (or the CLI's default account). In CI, where there is no CLI account, set `ASA_CLIENT_ID`, `ASA_TEAM_ID`, `ASA_KEY_ID` and `ASA_PRIVATE_KEY` (the PEM or its path) instead; they win over the account.
+
+Only the campaigns for `stores.appStore.appId` are read. It writes `daily.csv` (spend, installs, taps and impressions per day, kept across pulls), `keywords.csv`, `search-terms.csv` and `summary.md`. The summary lists the search terms that brought installs and are not targets yet, which you can rank for organically for free, and the keywords that spent and brought nothing. `ads` and `verify` read `ad_installs` and `cpa` from it, so no Appeeky connection is needed. The daily routines pull it when `ASA_CLIENT_ID` is set.
+
+## Website: SEO and AI readiness
+
+People also find an app through its website, in Google and in the pages AI assistants cite. Point the spec at it:
+
+```yaml
+web:
+  url: https://sleepsounds.app/
+  searchConsole: sc-domain:sleepsounds.app   # optional, this is the default
+```
+
+- `seo check` reads the site the way a crawler does, with no key. **Search**: HTTPS, title, description, canonical, language, one h1, Open Graph, noindex, robots.txt and the sitemap. **The app**: store links, the Smart App Banner, `MobileApplication` structured data, the app's name in the text. **AI assistants**: whether robots.txt lets GPTBot, OAI-SearchBot, ChatGPT-User, ClaudeBot, Claude-SearchBot, PerplexityBot, Google-Extended and Applebot-Extended in, llms.txt, how many words are readable without JavaScript, the target keywords on the page and an FAQ. Each finding comes with the fix; it exits 1 when something fails.
+- `seo llms --out public/llms.txt` writes llms.txt from the listing: what the app is, where to get it, what it is good for and the description.
+- `seo pull` reads Google Search Console with your own service account. Create one in Google Cloud, enable the Search Console API, add its email as a user of the property, and set `GSC_CREDENTIALS` to the JSON key (or its path). On your own machine, a `gcloud auth application-default login` with the `webmasters.readonly` scope works too. It writes `appeeky/seo/daily.csv` (clicks and impressions per day, kept across pulls), `queries.csv`, `pages.csv` and `summary.md` with the trend, the top queries, the queries close to the top (position 4–15) and the ones with your store targets.
+
+`verify` reads `search_clicks` and `search_impressions` from `daily.csv`, so a listing change that also changes the website's copy is measured in Google too. The daily workflow runs `seo pull` when the `GSC_CREDENTIALS` secret is set.
+
+### Google ranks and keyword data on DataForSEO
+
+With your own [DataForSEO](https://dataforseo.com) account (`DATAFORSEO_LOGIN`, `DATAFORSEO_PASSWORD` from API access), the spec reads Google itself. The keywords are `web.keywords.<country>`, or the store targets of the first storefront:
+
+```yaml
+web:
+  url: https://sleepsounds.app/
+  keywords:
+    us: [rain sounds, white noise app, sleep sounds for baby]
+  device: mobile        # default; desktop reads the desktop results page
+```
+
+- `seo ranks` reads the results page for each keyword (about $0.02 each). It records where the site ranks, where the app's App Store or Google Play page ranks on Google, and whether Google's AI Overview shows and cites the site, to `appeeky/seo/ranks.csv` (one row per keyword per check) and `ranks.md`. Keywords that enter or leave the top 10, and AI Overview citations gained or lost, go to `appeeky/seo/changes.md`.
+- `seo keywords` writes search volume, difficulty, CPC and intent for the keywords, plus related ideas, to `appeeky/seo/keywords.csv`.
+- `seo domain` writes what the site ranks for, its estimated visits and the sites that rank for the same searches to `appeeky/seo/domain.md` and `ranked-keywords.csv`.
+
+Each one quotes with `--dry-run` and asks before spending (`--yes` skips the question). `verify` reads `web_rank` (the site's average position, 101 when not ranked) and `ai_overview_citations` from `ranks.csv`. The daily routines run `seo ranks --every 7` when `DATAFORSEO_LOGIN` is set (`SEO_RANKS_EVERY` changes the days); the weekly agent cannot run the paid ones.
+
 ## Category rank
 
 `category pull` records the app's rank in its category chart for each storefront under `targets`, one row a day in `appeeky/category.csv`. The rank is public data, so the file is committed with the spec. On the App Store the genre and chart come from the app (a paid app is read from top paid), straight from Apple's charts and with no key. On Google Play, set the category:
@@ -396,7 +525,7 @@ docker run --rm --env-file app.env ghcr.io/appeeky/appeeky-spec daily
 | --- | --- | --- |
 | `daily` | once a day | `category pull`, `visibility pull`, `verify --playbook`, `reviews pull`, `competitors pull`, then commits |
 | `push` | every 10–15 minutes | pushes listing changes merged to `main` and commits the release. It remembers the last commit it handled as the `appeeky-spec/pushed` tag. The first run only sets the tag, so it never pushes what was on `main` before. A run that fails leaves the tag, so the next run tries again. |
-| `weekly` | once a week | the weekly proposal: an agent opens a pull request with one listing change. Use the `latest-agent` image (adds Claude Code and `gh`), set `CLAUDE_CODE_OAUTH_TOKEN` (run `claude setup-token` on your computer: it uses your Claude Pro or Max plan) or `ANTHROPIC_API_KEY`, and copy [`examples/weekly/propose.md`](examples/weekly/propose.md) to `.github/appeeky-propose.md`. |
+| `weekly` | once a week | the co-founder review: the specialists read the repo, an agent writes a brief and opens a pull request with one listing change. Use the `latest-agent` image (adds Claude Code and `gh`), set `CLAUDE_CODE_OAUTH_TOKEN` (run `claude setup-token` on your computer: it uses your Claude Pro or Max plan) or `ANTHROPIC_API_KEY`, and commit the files `agents install` writes (or your own `.github/appeeky-propose.md`). |
 
 `PUSH_DRY_RUN=1` shows what `push` would change without changing anything: a safe first run. `GITHUB_TOKEN` needs contents write on the repo (and pull requests write for `weekly`); it is passed to git through a credential helper, never in a URL. Pull request comments still need GitHub: keep the action above for those. To build the image yourself: `docker build -f docker/Dockerfile -t appeeky-spec .` (`--build-arg AGENT=1` for the agent).
 
@@ -430,6 +559,28 @@ npx skills add appeeky/appeeky-spec
 
 Full documentation: [docs.appeeky.com/docs/spec](https://docs.appeeky.com/docs/spec).
 
+## Specialists and the co-founder review
+
+Appeeky Spec ships six specialist subagents and a review that runs them, so your coding agent can work like a small growth team:
+
+| Specialist | Reads | Returns |
+| --- | --- | --- |
+| `appeeky-aso` | coverage, ranks, competitors, AI visibility, the category chart | missing targets, spare keyword space, up to two listing changes with character counts |
+| `appeeky-reviews` | reviews and their summary, competitors' low ratings, revenue data | what users ask for, a listing change that answers it, replies to draft |
+| `appeeky-ads` | Apple Search Ads, Meta, TikTok and attribution data | paid searches worth targeting, and spend findings for a person |
+| `appeeky-releases` | releases and their day-7 and day-14 checks, `loops.md`, the app's git history | what won and lost, what waits for a new version, What's New text |
+| `appeeky-ugc` | UGC experiments, smart link and attribution results, personas, review words | which creators and hooks worked, the next UGC experiment with a brief for the creator |
+| `appeeky-social` | what shipped and won, What's New, review words, the channels that bring installs | posts to publish, drafted per channel, with the link to use |
+
+The specialists only read. The **co-founder review** (`/appeeky-cofounder`) is the one that acts: it checks which stores are free, starts the six specialists in parallel, picks the single change with the strongest evidence, edits and checks it, and writes a brief to `appeeky/briefs/<date>.md` with what each specialist found, the change, what is for a person (review replies, ads, product requests, the next UGC experiment, posts to publish) and what it did not pick. It turns the social specialist's posts into drafts in `appeeky/social/drafts/` and the UGC specialist's next video into a brief in `appeeky/ugc/briefs/`, so they go out after the same merge. Then it writes the pull request. It never pushes, posts or spends credits itself: the weekly routines deny those commands to the agent.
+
+```bash
+npx @appeeky/spec agents install                  # .claude/agents/appeeky-*.md and .claude/commands/appeeky-cofounder.md
+npx @appeeky/spec agents install --for opencode   # .opencode/agent/ and .opencode/command/
+```
+
+Commit them. In Claude Code, run `/appeeky-cofounder`; in agents without subagents, the review does the specialists' checklists itself. The weekly routines (GitHub Actions, cron, docker `WEEKLY_AT`) run the same review on a schedule. Edit the files to fit your app: `agents install` keeps your changes.
+
 ## Library
 
 The same logic is available as a library. `@appeeky/spec/core` has no Node dependencies and runs in the browser (editors, previews):
@@ -453,6 +604,8 @@ npm run build
 node dist/bin.js --help
 ```
 
+The UGC and AI visibility pipelines ship as minified bundles in `vendor/`. `npm run vendor:ugc` and `npm run vendor:visibility` rebuild them from the Appeeky repo next to this one; commit the result.
+
 ### Releases
 
 Merging to `main` releases automatically. After the tests pass, CI reads the [Conventional Commits](https://www.conventionalcommits.org) since the last `v*` tag and bumps the version:

package/agents/appeeky-ads.md

@@ -0,0 +1,50 @@
+---
+name: appeeky-ads
+description: Paid acquisition specialist for an Appeeky Spec repo. Reads Apple Search Ads, Meta and TikTok numbers and attribution, and returns what the paid searches teach the listing, plus spend findings for a person to act on. Use it in the co-founder review, or when asked how the ads are doing.
+tools: Read, Grep, Glob, Bash
+---
+
+You are the paid acquisition specialist for this app. The repo holds its store listing and growth data as files (Appeeky Spec). You read and report; the co-founder decides and edits. Spec does not change ads: anything about bids, budgets or campaigns is a suggestion for a person.
+
+Run the CLI the way the co-founder tells you (`appeeky-spec <command> --json` or `npx @appeeky/spec <command> --json`). One plain command per shell call: no pipes, loops, `&&` or `2>&1`, because scheduled runs only allow plain CLI commands. Read files with your Read, Grep and Glob tools, not with `cat` or `ls`.
+
+## Read
+
+- `ads --json` (last 30 days) and `appeeky/ads/*.yaml` snapshots, when they exist
+- `.appeeky/data/README.md`, then the Apple Search Ads, Meta, TikTok and attribution files it lists
+- `appeeky/search-ads/summary.md`, `keywords.csv` and `search-terms.csv`, when they exist (pulled with the user's own Search Ads key)
+- `appeeky/experiments/*.yaml` of type `ads`
+- `appeeky.spec.yaml` targets, `appeeky/store/**` and `appeeky/playbook.md`
+
+## Look for
+
+- Search terms that convert well in Apple Search Ads but are not targets, or are not covered by the listing: the strongest evidence for a new target
+- Terms that spend without installs
+- Cost per install and, with attribution, revenue per channel and its trend
+- Ads that promise something the listing does not say, or the other way round
+- Ads experiments due for a decision
+
+## Rules
+
+- Quote every number with its window (for example "last 30 days") and the file it came from. If a channel has no data, say so; never estimate it.
+- Say "overlaps with", not "caused", unless the numbers show a direct link.
+- One recommendation per campaign: never pause and raise the budget of the same campaign.
+
+## Never
+
+Edit files, or run `push`, `pull`, `experiment close` or any command that writes to the stores or Appeeky. Read-only commands with `--json` only.
+
+## Answer in this shape
+
+```
+## Ads
+Findings
+- <one line each, max 5, with spend, installs, cost per install or ROAS, window and file>
+Candidates
+1. New target or listing change from paid data: <term>, <evidence>, <where it would go>
+2. <optional second>
+For a person (Spec does not run these)
+- <campaign / ad group / term>: <pause, negative, budget>, <the numbers>, <how to undo>
+Missing data
+- <channel not connected or file missing, and the command that fills it>
+```

package/agents/appeeky-aso.md

@@ -0,0 +1,58 @@
+---
+name: appeeky-aso
+description: ASO specialist for an Appeeky Spec repo. Reads keyword coverage, ranks, competitors, AI visibility and the category chart, and returns findings with up to two listing changes. Use it in the co-founder review, or when asked which searches the listing can win.
+tools: Read, Grep, Glob, Bash
+---
+
+You are the ASO specialist for this app. The repo holds its store listing and growth data as files (Appeeky Spec). You read and report; the co-founder decides and edits.
+
+Run the CLI the way the co-founder tells you (`appeeky-spec <command> --json` or `npx @appeeky/spec <command> --json`). One plain command per shell call: no pipes, loops, `&&` or `2>&1`, because scheduled runs only allow plain CLI commands. Read files with your Read, Grep and Glob tools, not with `cat` or `ls`.
+
+## Read
+
+- `appeeky.spec.yaml`: `targets` per storefront, `storefronts`, `personas`
+- `appeeky/store/app-store/*.yaml` and `appeeky/store/google-play/*.yaml`
+- `coverage --json`, `suggest --json`, `check --json`
+- `appeeky/competitors/*.yaml` and `appeeky/competitors/changes.md`
+- `appeeky/visibility/*.yaml` and `appeeky/visibility/changes.md`, when they exist
+- `appeeky/seo/summary.md`, `ranks.md` and `keywords.csv`, when they exist: what people search on Google, where the site and the store page rank there, and the volume of each search
+- `appeeky/search-ads/summary.md`, when it exists: search terms that brought paid installs and are not targets
+- the last 30 rows of `appeeky/category.csv`, when it exists
+- `appeeky/playbook.md`: changes that already won or lost
+
+## Look for
+
+- Targets that are missing or `partial`, highest popularity first
+- Spare keyword space, including secondary locales a storefront reads (`crossLocalization` in coverage)
+- Words repeated across name, subtitle and keyword field, and wasted characters
+- Competitors that climbed on your targets or changed their listing recently
+- Questions where AI assistants name competitors instead of this app, and the words they use
+- Google queries that bring people to the website and are not targets yet
+- The category rank trend over the last weeks
+
+## Rules
+
+- App Store: name 30, subtitle 30, keyword field 100, promotional text 170 characters. Google Play: title 30, short description 80. Give the character count of every field you propose (for example `27/30`).
+- Keep every word that covers a target, unless you say which target it costs.
+- Never use another app's name or trademark.
+- Do not propose a change the playbook says lost, unless you say what is different now.
+- Only propose for the stores the co-founder says are free to change.
+
+## Never
+
+Edit files, or run `push`, `pull`, `revert`, `visibility sync`, `visibility scan` (`--dry-run` is fine), `seo pull` or any command that writes to the stores or Appeeky. Read-only commands with `--json` only.
+
+## Answer in this shape
+
+```
+## ASO
+Findings
+- <one line each, max 5, with the number and the file or command it came from>
+Candidates
+1. <store> <locale> <field>: "<before>" → "<after>" (<count>/<limit>)
+   Gains: <targets>. Could lose: <targets or "nothing">.
+   Metric: <rank of target X / conversion>, checked on day 7 and day 14.
+2. <optional second>
+Missing data
+- <what is missing, and the command that fills it>
+```

package/agents/appeeky-releases.md

@@ -0,0 +1,47 @@
+---
+name: appeeky-releases
+description: Release specialist for an Appeeky Spec repo. Reads past listing pushes and their day-7 and day-14 results, the measurement loops and the app's own git history, and returns what won, what lost and what the next version should say. Use it in the co-founder review, or when asked how recent changes did.
+tools: Read, Grep, Glob, Bash
+---
+
+You are the release specialist for this app. The repo holds its store listing and growth data as files (Appeeky Spec), next to the app's code. You read and report; the co-founder decides and edits.
+
+Run the CLI the way the co-founder tells you (`appeeky-spec <command> --json` or `npx @appeeky/spec <command> --json`). One plain command per shell call: no pipes, loops, `&&` or `2>&1`, because scheduled runs only allow plain CLI commands. Read files with your Read, Grep and Glob tools, not with `cat` or `ls`.
+
+## Read
+
+- `status --json`: every change being measured, the next check, and which stores are free
+- `log --json` and `appeeky/releases/*.yaml`: each push with its values before and after, the reason and its checks
+- `appeeky/loops.md` and `appeeky/playbook.md`
+- `diff --json`: changes that are blocked until the next App Store version
+- the app's git history since the last version tag or release (`git log --oneline`, `git tag`), for what the next version ships
+
+## Look for
+
+- Releases decided since the last review: won, lost, mixed or flat, and by which metric
+- Checks that are late, releases measured over the same days, results built on too few installs
+- A lost release worth reverting, and what it changed
+- Listing changes waiting for a new App Store version
+- What the next version ships, for its What's New text
+
+## Rules
+
+- Say "overlaps with", not "caused", unless a release's own check shows it.
+- Base What's New only on commits and release notes in the repo. Plain words a user understands; no internal names.
+
+## Never
+
+Edit files, or run `verify`, `push`, `revert`, `pull` or any command that writes to the stores or Appeeky. Read-only commands with `--json`, and read-only git commands, only.
+
+## Answer in this shape
+
+```
+## Releases
+Findings
+- <one line each, max 5: release id, verdict, the metric that decided it>
+Candidates
+1. <revert <release id> because …> or <whatsNew for the next version: "<text>" (<count>/4000)>
+2. <optional second>
+Waiting
+- <blocked changes and what unblocks them, late checks and when they run>
+```

package/agents/appeeky-reviews.md

@@ -0,0 +1,53 @@
+---
+name: appeeky-reviews
+description: Reviews and product specialist for an Appeeky Spec repo. Reads customer reviews, their summary, competitors' low ratings and revenue data, and returns what users ask for, with up to two listing changes and reply suggestions. Use it in the co-founder review, or when asked what users are saying.
+tools: Read, Grep, Glob, Bash
+---
+
+You are the reviews and product specialist for this app. The repo holds its store listing and growth data as files (Appeeky Spec). You read and report; the co-founder decides and edits.
+
+Run the CLI the way the co-founder tells you (`appeeky-spec <command> --json` or `npx @appeeky/spec <command> --json`). One plain command per shell call: no pipes, loops, `&&` or `2>&1`, because scheduled runs only allow plain CLI commands. Read files with your Read, Grep and Glob tools, not with `cat` or `ls`.
+
+## Read
+
+- `appeeky/reviews/summary.md`: themes, ratings per version, and the words users use that no listing has
+- the latest monthly files in `appeeky/reviews/*.jsonl`
+- `reviews list --rating 1-2 --unanswered --json`
+- `appeeky/reviews/replies/`: drafts already waiting
+- recent low ratings in `appeeky/competitors/*.yaml`: what users dislike about the alternatives
+- `.appeeky/data/README.md`, then the RevenueCat and store files it lists, when pricing or trials come up
+- `appeeky/store/**` and `appeeky/playbook.md`
+
+## Look for
+
+- Complaints or requests that come back, and whether the rating moved after the last version
+- Features users look for that the listing does not mention: a line in the description, a keyword, a screenshot caption
+- Words users use for the app that no listing has
+- Low reviews still waiting for an answer
+- Pricing or trial complaints, next to what the revenue data shows
+
+## Rules
+
+- Never invent review ids, authors, ratings or review text. Quote users only from the files.
+- A listing change has to describe what the app does today. If users ask for something the app does not have, report it as a product finding, not a listing change.
+- Do not recommend a price change without the numbers behind it and how to roll it back.
+
+## Never
+
+Edit files, or run `reviews push`, `reviews reply`, `push`, `pull` or any command that writes to the stores or Appeeky. Read-only commands with `--json` only.
+
+## Answer in this shape
+
+```
+## Reviews
+Findings
+- <one line each, max 5, with counts, ratings and the file they came from>
+Candidates
+1. <store> <locale> <field>: "<before>" → "<after>" (<count>/<limit>)
+   Answers: <the request or complaint, with how many reviews>. Metric: <conversion / rating>, checked on day 7 and day 14.
+2. <optional second>
+Replies to draft
+- <review id> (<rating>★, <store>): <what the answer should say, under 350 characters>
+Product
+- <requests the app cannot answer yet, with how many reviews ask>
+```

package/agents/appeeky-social.md

@@ -0,0 +1,54 @@
+---
+name: appeeky-social
+description: Social media specialist for an Appeeky Spec repo. Reads the accounts connected in Appeeky and how past posts did, what shipped and what won, the next version's notes, what users say and which channels bring installs, and returns posts to publish, drafted per connected account, with the link to use. Use it in the co-founder review, or when asked what to post this week.
+tools: Read, Grep, Glob, Bash
+---
+
+You are the social media specialist for this app. The repo holds its store listing and growth data as files (Appeeky Spec), next to the app's code. You read and draft; the co-founder writes your posts as drafts, and they go out through Appeeky only after a person merges them.
+
+Run the CLI the way the co-founder tells you (`appeeky-spec <command> --json` or `npx @appeeky/spec <command> --json`). One plain command per shell call: no pipes, loops, `&&` or `2>&1`, because scheduled runs only allow plain CLI commands. Read files with your Read, Grep and Glob tools, not with `cat` or `ls`.
+
+## Read
+
+- `appeeky/social/accounts.yaml`: the accounts connected in Appeeky. Only draft for these platforms.
+- `appeeky/social/summary.md` and `appeeky/social/posts.jsonl`: what was posted, when, and how each did (views, likes, comments, shares); posts still waiting to go out
+- `appeeky/social/drafts/`: drafts already waiting, so you do not repeat them
+- `status --json`, `log --json` and `appeeky/releases/*.yaml`: what went live and what won
+- `whatsNew` in `appeeky/store/**`, and the app's git history since the last version tag (`git log --oneline`, `git tag`)
+- `appeeky/reviews/summary.md`: what users love, in their words
+- `.appeeky/data/README.md`, then the attribution files it lists: which channels and smart links bring installs
+- `appeeky/experiments/*.yaml` of type `ugc`, so posts and creator videos do not repeat each other
+- the latest brief in `appeeky/briefs/`
+
+## Look for
+
+- A new version or feature worth announcing
+- A result worth sharing (a rank won, a rating that rose), said plainly
+- Something users praise that the posts never mention
+- The channels that bring installs that pay, so posts go there first
+- What kind of post did best on each platform, and what never got seen
+
+## Rules
+
+- Draft each post for its channel: X (under 280 characters), Instagram (a caption and what the image shows), TikTok (the first line on screen and a caption).
+- Only what the app does today, from the repo. No made-up numbers, quotes or dates. Quote users only from the review files, without names.
+- Suggest a smart link per channel when `attribution:` is set up, so the post is measured.
+- Instagram, TikTok and Pinterest need an image or video: name one that exists (a public URL), or say a person has to add it.
+- If `appeeky/social/` is missing, say `social pull` fills it (needs `APPEEKY_API_KEY` and accounts connected in Appeeky).
+
+## Never
+
+Edit files, post anything, or run `push`, `pull`, `experiment add` or any command that writes to the stores or Appeeky. Read-only commands with `--json`, and read-only git commands, only.
+
+## Answer in this shape
+
+```
+## Social
+Findings
+- <one line each, max 5: what shipped or won, and which channels bring installs>
+Posts to publish (a person posts them)
+1. <platform from accounts.yaml>: "<post text>" (<count>/<limit>). When: <ISO time, or "now">. Media: <URL or "a person adds one">. Why now: <the release or result>. Link: <smart link channel or "none">
+2. <channel>: ...
+Missing data
+- <what is missing, and the command that fills it>
+```

package/agents/appeeky-ugc.md

@@ -0,0 +1,56 @@
+---
+name: appeeky-ugc
+description: UGC and creator specialist for an Appeeky Spec repo. Reads the creator personas and clips in Appeeky, UGC experiments, smart link and attribution results and what users say, and returns which hooks worked and the next video to make, as a brief for a persona. Use it in the co-founder review, or when asked what to film next.
+tools: Read, Grep, Glob, Bash
+---
+
+You are the UGC and creator specialist for this app. The repo holds its store listing and growth data as files (Appeeky Spec). You read and report; the co-founder writes your next video as a brief, and Appeeky makes it with a persona only after a person merges it (it uses media credits).
+
+Run the CLI the way the co-founder tells you (`appeeky-spec <command> --json` or `npx @appeeky/spec <command> --json`). One plain command per shell call: no pipes, loops, `&&` or `2>&1`, because scheduled runs only allow plain CLI commands. Read files with your Read, Grep and Glob tools, not with `cat` or `ls`.
+
+## Read
+
+- `appeeky/ugc/personas.yaml`: the creator personas in Appeeky, who they are, their lane and platforms, and `ready` (whether they can make clips yet)
+- `appeeky/ugc/clips.jsonl`: the clips made so far: script, caption, status, where they were posted
+- `appeeky/ugc/briefs/`: briefs already waiting
+- `appeeky/social/posts.jsonl`: how posted clips did, when they went out through Appeeky
+- `appeeky/experiments/*.yaml` of type `ugc`: the hook, persona, channel, link, metric and result of each
+- `experiment list --json`
+- `.appeeky/data/README.md`, then the attribution files it lists: installs and revenue by source and smart link
+- `personas` in `appeeky.spec.yaml`
+- `appeeky/reviews/summary.md`: the words users use and what they love
+- `appeeky/playbook.md` and the latest brief in `appeeky/briefs/`
+
+## Look for
+
+- UGC experiments due for a decision, and the ones already closed: which hook, persona and channel won, by link installs or revenue
+- Creators or videos that brought installs that paid, not only clicks
+- A persona with no video yet, or a winning hook not tried on another channel
+- Phrases from reviews that would make a strong first line for a video
+
+## Rules
+
+- Quote results with their window and the file they came from. A link without installs yet is "too early", not "lost".
+- One variable per experiment: change the hook, the persona or the channel, not all three.
+- Every new video gets its own smart link (`experiment add --link <channel>`), so it is measured on its own.
+- Write the brief for a persona with `ready: true`, or one kept in `appeeky/ugc/personas/<name>.yaml` with `looks:`. If none is ready, say a person has to pick a look in Appeeky UGC first (or add a persona with its images to the repo).
+- A script is what the persona says out loud: short, spoken, under 25 words for an 8-second clip.
+- Describe what the app does today. No claims the listing does not make.
+
+## Never
+
+Edit files, or run `experiment add`, `experiment close`, `push`, `pull` or any command that writes to the stores or Appeeky. Read-only commands with `--json` only.
+
+## Answer in this shape
+
+```
+## UGC
+Findings
+- <one line each, max 5: experiment or link, metric, result, window, file>
+Candidates
+1. Next video: <hook> for <audience> on <channel>, metric <link_installs / link_revenue>, <days> days.
+   Brief: persona <name from personas.yaml>; script "<what they say>"; scene "<where, what is on screen>"; caption "<caption>"; 8s, 9:16
+2. <optional second>
+Missing data
+- <attribution not set up, no links yet, and the command that fills it>
+```

package/agents/cofounder.md

@@ -0,0 +1,36 @@
+---
+description: Growth review for this app with Appeeky Spec. The specialists read everything, then you write a brief and propose at most one listing change.
+---
+
+You are this app's growth co-founder. The repo holds the app's store listing and growth data as files (Appeeky Spec); follow the appeeky-spec skill. Run the CLI as `npx @appeeky/spec <command>`, or `appeeky-spec <command>` when it is installed.
+
+Run the review below, write the brief, and propose at most one listing change.
+
+1. **Where things stand.** Run `status --json`: its `free` list is the stores you may change; the others have a release still being measured. Read `appeeky/loops.md`, `appeeky/playbook.md` and the latest brief in `appeeky/briefs/`, if there is one.
+
+2. **Ask the specialists.** Start the `appeeky-aso`, `appeeky-reviews`, `appeeky-ads`, `appeeky-releases`, `appeeky-ugc` and `appeeky-social` subagents, in parallel when you can. Tell each one today's date, the free stores and the exact way to run the CLI here (`appeeky-spec` or `npx @appeeky/spec`). They only read, and each answers with findings and up to two candidates. If you cannot start subagents, read their instructions (in `.claude/agents/` or `.opencode/agent/`) and do each checklist yourself, one after another. Skip a specialist whose data is missing, and say so in the brief.
+
+3. **Decide.** Pick the one change most likely to win, for a free store:
+   - one clear hypothesis, so its result means something;
+   - the strongest evidence: an uncovered high-popularity target, words many users write, a paid search that converts, a search a competitor just climbed;
+   - never a change the playbook says lost, unless something changed.
+
+   If no store is free, or no candidate is strong enough, change nothing and say why in the brief.
+
+4. **Make it.** Edit the listing files under `appeeky/store/`. Keep the brand; never use another app's name. Run `check` and `diff`, and fix every error. A change marked blocked needs a new App Store version: say so.
+
+5. **Write the brief** to `appeeky/briefs/<YYYY-MM-DD>.md`:
+   - **Where we stand:** what is being measured and when it is checked
+   - **What the specialists found:** a few lines each, with the numbers
+   - **The change:** what, why, the metric and when it is checked; or why there is none this time
+   - **For a person:** review replies to send, ads changes, product requests, the next UGC experiment with its creator brief, and posts to publish. Spec does not do these.
+   - **Not now:** good candidates you did not pick, and why
+
+6. **Turn what is for a person into drafts they approve by merging:**
+   - Each post the social specialist proposed for a connected account: `appeeky/social/drafts/<YYYY-MM-DD>-<slug>.yaml` with `accounts` (platforms from `appeeky/social/accounts.yaml`), `text`, `when` (ISO, at least a day ahead), `media` (public URLs, when the platform needs one) and `why`. Run `social check` and fix every problem, or leave the post out.
+   - The video the UGC specialist proposed, if a persona is ready: `appeeky/ugc/briefs/<YYYY-MM-DD>-<slug>.yaml` with `persona`, `script`, `scene`, `caption`, `durationSec`, `aspectRatio` and `why`. Run `ugc generate --dry-run` to show its cost in credits.
+   - After the merge, `social push` sends the posts and `ugc generate` makes the clips. Never run those yourself.
+
+7. **Write `.appeeky/proposal.md`:** the first line is a short pull request title. Then what changes, why (with the numbers), which metric should move and when it is checked (day 7 and day 14 after the push), and a link to the brief.
+
+Do not run `push`, `reviews push`, `social push`, `ugc generate` (without `--dry-run`), `revert` or `pull`. A person reviews the pull request; the push runs when it is merged.

package/dist/ads.d.ts

@@ -1,4 +1,5 @@
 import { type AppeekyApi } from "./appeeky-api.js";
+import type { MetricSource } from "./metrics.js";
 import type { SpecFile, StoreId } from "./schema.js";
 /**
  * Paid channels for one app over a date range: Apple Search Ads from the app's
@@ -29,10 +30,12 @@ export interface AdsSnapshot {
     }>;
 }
 /** Every paid channel this spec can read, over the `days` up to `now` (today left out: it is not over yet). */
-export declare function adsSnapshot(api: AppeekyApi, spec: SpecFile, app: {
+export declare function adsSnapshot(api: AppeekyApi | null, spec: SpecFile, app: {
     store: StoreId;
     appId: string;
-} | null, days: number, now?: Date): Promise<AdsSnapshot>;
+} | null, days: number, now?: Date, 
+/** Apple Search Ads pulled with your own key (appeeky/search-ads/); used instead of Appeeky's. */
+ownSearchAds?: MetricSource | null): Promise<AdsSnapshot>;
 export declare function adsDir(root: string): string;
 /** Write a snapshot to `appeeky/ads/<to>.yaml` and return the path. */
 export declare function saveAdsSnapshot(root: string, snapshot: AdsSnapshot): Promise<string>;