@aicopycoders/exodus 2026.9.1100-beta.2 → 2026.9.1400-beta.0

package/assets/skills/find-competitors/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: find-competitors
+description: Find the competitors that are actually strong (scaling and working) in any niche, on Meta first and Amazon second, and turn them into a ranked competitor sheet and a watch list. Use it whenever someone asks "who are the real competitors", "who's scaling in this niche", "find brands that are working", "is anyone doing cortisol / sleep / X at scale", "check these brands", "who else sells to these people", "build me a watch list", "who should we spy on", or hands over a list of brands with notes and wants it verified and extended. Three entry points: BRIEF (cold start, no list), HEAD LIST (the user arrives with brands grouped by mechanism and a read on each), and GRID CELL (an existing segment grid with empty cells that need a competitor column). Carries the tool quirks (Atria, Meta Ad Library via Apify, Amazon) and two scripts so nobody rediscovers them. It ends at the ranked sheet and the watch list; ripping ads is the swipe process and patterns and gaps are their own skills.
+---
+
+# Find competitors
+
+A competitor is worth following when they are scaling and working, not when they are in the same category. The test is measurable and the search is by mechanism. Everything else here exists to make the first hour not depend on knowing the tools.
+
+Think mode until the plan-back. The sweep and the signal check are build bursts: say the plan and the cost back in two lines, get the go, run them comprehensively, write files as they land, report spend. Then back to a short list he can cut. Read the `thinking-vs-build` skill if installed.
+
+## What "strong" means
+
+Six signals, each cheap to check. The first five come from Atria's brand feed and the script computes them; the sixth comes from Amazon.
+
+| Signal | What it proves | Strong when |
+|---|---|---|
+| Active ads now | Breadth of spend | 50+ |
+| Longest-running active ad, days | A proven angle | 90+ |
+| New ads in the last 30 days | Momentum | 10+ |
+| Creative reuse (re-launched ads) | Winners they trust | 5+ in the top-impression sample |
+| Offer aggression | A funnel that converts cold | 3+ ads with intro-offer words; persona pages and quiz funnels count double |
+| Amazon review count and velocity | Demand off-platform | Top ten in two or more searches, or 1,000+ reviews and growing |
+
+**Follow** at three or more strong. **Watch** at two. **Skip** at one or none. Spend estimates from Atria or Motion are a tiebreak only; they are rough. Adjust the thresholds to the category (a niche with three advertisers is not a niche with three hundred), and say so on the sheet.
+
+One qualifier that is not a number: are they selling a mechanism (a UMP) or a category? Mechanism brands are the ones worth following. Group the sheet by UMP.
+
+## The doors, ranked by yield
+
+1. **The user's head list**, with their read on each brand. Highest signal, fastest. Keep their notes verbatim as the brief.
+2. **Keyword lanes on the Meta Ad Library**, 25 to 40 queries from the grid in `references/query-grid.md`, aggregated by advertiser. Run through Apify with `scripts/adlib_sweep.py`.
+3. **Amazon category and ingredient shortlists.** Brand names fall out of the top tens; review volume is a signal on its own.
+4. **Neighbours of a known strong brand.** Same Atria lane, named in comments and Reddit threads, the domains behind advertorial pages, the brands that share a spokesperson type.
+5. **Motion and Foreplay library pages** for the lanes, when the user has access.
+6. **A shadow Instagram account** saturated in the market and scanned for outliers. Slowest, best for zeitgeist. The Scout library in Exodus (`exodus-hooks`) already holds this when the brand is set up there.
+
+## Entry point 1: BRIEF (cold start)
+
+The strategist has a product and knows nothing about the market.
+
+1. **Load and say back.** Product, outcome sold today, star ingredient, the segment grid if one exists, focus order if agreed. One paragraph.
+2. **Build the query grid.** Outcome × mechanism × ingredient words, 25 to 40 lanes, written to a text file. Show the lanes as a list the user can cut before spending.
+3. **Plan-back.** "Sweep N lanes at 150 results each through Apify, about $X, then score the top 30 advertisers on Atria, a few minutes. Go?"
+4. **Sweep.** `adlib_sweep.py` writes one JSON per lane and `advertisers.md`, ranked by lanes hit and ads seen. Read the aggregate the way the reference describes (mechanism brands, single-angle brands, advertorial fronts, retailers).
+5. **Score.** `competitor_signals.py` on the top 30 advertisers, plus any brand the Amazon door added. Writes the sheet.
+6. **Fill the hand columns** for every FOLLOW: UMP, offer, persona pages, why it matters, what to steal. Two lines each, from the longest-running ads the script printed.
+7. **Hand back** the sheet in think-mode form: top ten as a list, verdicts, one line each. The user cuts. Then the watch list.
+
+Stop rule: 20 to 30 scored brands. More does not change the top ten.
+
+## Entry point 2: HEAD LIST (the user arrives with brands and a read)
+
+The list is grouped by UMP and each brand has a note ("spends 2M a month", "mostly gut, but they call out weed smokers", "not sure how well it performs").
+
+1. **Keep the notes verbatim** as the brief. They say what to look for, what to discount, and which segments to keep in mind.
+2. **Score every brand** with the script. No sweep needed yet.
+3. **Compare the numbers to the read.** Where the signals disagree with the note ("thought they hit cortisol harder" but the longest-running ads are gut), say so in one line per brand. That is the whole value of this pass.
+4. **Find the blind spots.** Two or three neighbours per UMP group: the same Atria lane, brands named in the comments under the listed brands' ads, the domains behind any advertorial page in the list. Score them.
+5. **Segments seen.** Any segment a listed brand calls out (a demographic, a state, an occasion) goes on the running segments-seen list for the `odf` skill.
+6. **Hand back:** the list confirmed and extended, ranked by UMP group, then straight into the rip. Do not rebuild what the user already knows.
+
+## Entry point 3: GRID CELL (an account going horizontal)
+
+A brand with winners wants new segments and needs to know who already sells to those people.
+
+1. **Take the grid** and the empty cells from the `odf` skill.
+2. **Search per cell, by the facet's self-ID words**, not the outcome word. "On HRT and still wake at 3am" finds different advertisers than "sleep supplement". Two to four lanes per cell.
+3. **Score** whoever appears in two or more of a cell's lanes.
+4. **Write a competitor column** onto the gap ranking: who is in the cell, how strong, on which UMP, and whether the cell is empty because nobody has found it or because someone tried and left (an inactive brand with a long past run is a warning).
+5. **Hand back** to the gaps ranking. This entry does not produce a general sheet.
+
+## The tools and their quirks
+
+Carry these into every run. They were learned the hard way. Both tools are the member's own paid accounts: get the keys from Atria and Apify, add them to `.env` by hand (`keys pull` leaves lines it does not own alone), and expect the scripts to stop with a clear message when a key is missing.
+
+**Atria** (`https://api.tryatria.com/open/v1`, header `X-API-Key`, key in `.env` as `ATRIA_API_KEY`).
+- Brand search: `/brand-library/search?keyword=` (the parameter is `keyword`, not `q`). Do not take the first result blindly; match the name or report the candidates.
+- Brand ads: `/brand-library/{id}/ads?status=active&page_size=50&order=` with `order` in `most_impressions`, `newest`, `oldest`, `most_active`, `best_match`. Fields include `days_running`, `start_date` (ISO with offset), `creative_duplicates`, `impression_rank`, `impression_trend`, `media_format`, `video_duration`, `link_url`.
+- `/ad-library/search` ignores every filter and returns the same feed. Never use it for discovery.
+- Single ad: `/ad-library/{mID}` gives body, title, link, video URLs on the Atria CDN, days running. The public ad page hides the transcript behind login, so ripping needs local transcription.
+- Rate limit: about ten quick calls returns 429. Pause 20 seconds. The script does this.
+- DCO ads store their videos under `cards`, not `videos`.
+
+**Meta Ad Library via Apify** (`apify~facebook-ads-scraper`, run-sync-get-dataset-items, token in `.env` as `APIFY_API_TOKEN`).
+- Keyword URL: `search_type=keyword_unordered&active_status=active&country=US&q=<phrase>`. Exact phrase in body: `search_type=keyword_exact_phrase`.
+- Page URL: `search_type=page&view_all_page_id=<id>` sorted by total impressions is the watch-list link shape.
+- Fields: `pageName`, `pageId`, `startDate`, `isActive`, `collationCount`, `snapshot.body`, `snapshot.title`, `snapshot.linkUrl`, `snapshot.videos[]`. Aggregate by `pageName`; the domain in `linkUrl` is the real brand behind advertorial pages.
+- Bills per result. 30 lanes at 150 is a few dollars. Plan-back first.
+
+**Amazon.** Search in the in-app browser, two result pages per query, pull ASIN, title, rating, review count, price, sponsored flag with a page script. Free and fast. Rank by relevance × review count. See the reference for the door.
+
+**Transcripts** for the rip that follows: ElevenLabs Scribe (`cloud_storage_url` = the video URL) or local whisper-cpp. Standardise on one per project so bank rows are comparable.
+
+## Scripts
+
+Run from the workspace root so `.env` is found. Write outputs into the brand's `inputs/research-raw/competitors/` folder.
+
+```
+python3 .claude/skills/find-competitors/scripts/adlib_sweep.py --keywords lanes.txt --outdir <brand>/inputs/research-raw/competitors/adlib --limit 150
+python3 .claude/skills/find-competitors/scripts/competitor_signals.py --file <brand>/inputs/research-raw/competitors/adlib/advertisers.txt --out <brand>/inputs/research-raw/competitors/competitor-sheet.md --json signals.json
+```
+
+`competitor_signals.py --names "Brand A" "Brand B"` scores a head list directly. Edit `STRONG` at the top of the script to change the thresholds for a category. Both scripts print progress per lane or brand so a cut connection loses only what was in flight.
+
+## The sheet
+
+```
+# <Brand> — Competitor sheet (v<n>, <date>)
+Thresholds used: <…>. Verdict: FOLLOW 3+ · WATCH 2 · SKIP 0–1.
+
+## By UMP
+### <UMP, e.g. cortisol>
+| Brand | Verdict | Active | Longest (d) | Launches 30d | Reuse | Offer | Amazon reviews | Offer & funnel | Why it matters | What to steal |
+
+### <UMP 2>
+…
+
+## Segments seen
+<a> · <b> · <c>
+
+## Watch list (FOLLOW rows)
+| Brand | Ad Library page link | Atria id | Domain |
+
+## Tool feedback from this run
+- …
+```
+
+The sheet lives in the folder. The FOLLOW rows become the watch list: an Ad Library page link per brand (the shape above) saved as a links file the rip can consume, and the brands added to Atria's followed list by hand in the app. When the brand is set up in Exodus, the Scout feed covers the Instagram side.
+
+## Hand-offs
+
+- **Rip:** the FOLLOW rows and their longest-running ads go to the swipe process (transcript, headline, body, rank, on-screen text) and into the ad bank next to the brand's own ads.
+- **Patterns:** what the FOLLOW set has in common is the `patterns-and-gaps` skill's job.
+- **Gaps:** the empty cells and the competitor column go to `patterns-and-gaps` and the `odf` grid.
+- **Positioning:** the `positioning-spiral` calls this at its research station.
+
+## Worked example (fictional)
+
+Evenkeel Reset Gummies, an evening saffron and magnesium gummy. Entry point BRIEF. Query grid of 28 lanes (see the reference). Sweep returned 214 advertisers; 31 appeared in three or more lanes. Signal check on those 31 plus four brands from the Amazon top tens. Result: nine FOLLOW, eight WATCH, the rest SKIP. The nine grouped into three UMPs: cortisol (four brands, all symptom-stacking in the hook, one at 289 days on a doctor-skit), perimenopause (three, all persona-page funnels), and sleep-onset (two, both melatonin-adjacent, both fatiguing). What it changed upstream: nobody strong owns "stay asleep" as a UMP; the cortisol brands own belly and face, not the night. That is a lane, and it went back to the positioning spiral as the mechanism station's next question.
+
+## What this skill is not
+
+It does not rip ads, find the patterns across them, or rank the gaps. It does not decide the mechanism. It finds who is strong, proves it with numbers, and puts them where the rest of the process can reach them.
+
+## Standards
+
+Before producing anything, read `STANDARDS.md` at the workspace root (and the section for this output type). Grade the draft against it before showing it; rewrite failures first. When the user reacts with a judgment, a banking phrase, or the same note twice, hand the reaction to `remember-that`. At the end of the session, `handoff` scrapes the chat and proposes entries.

package/assets/skills/find-competitors/references/query-grid.md

@@ -0,0 +1,78 @@
+# The query grid
+
+Competitors are found by mechanism, not by category. "Stress relief supplement" is the worst query in any grid because it returns the category's grey middle. The grid crosses three word lists, and the strong brands show up in several cells at once.
+
+## Build the three lists
+
+Take them from the segment grid if one exists (the `odf` skill), otherwise from the brief and ten minutes with the reviews.
+
+1. **Outcome words**, in the market's own language, one per sub-outcome that matters. Not the label ("sleep"), the phrase a buyer types ("wake up at 3am", "can't stay asleep", "puffy face", "rage at my kids").
+2. **Mechanism words**, the beliefs the market already holds about the cause: cortisol, hormones, gut, nervous system, inflammation, blood sugar, estrogen, testosterone, thyroid. These are Belief facets, and they are also the UMPs competitors sell.
+3. **Ingredient words**, the star and its likely partners, plus the two or three ingredients the category's big brands lead with.
+
+## Cross them
+
+Not every combination. Use these shapes:
+
+- outcome alone (the plain phrase): `wake up at 3am`
+- mechanism + outcome: `cortisol belly`, `cortisol 3am`
+- mechanism + product word: `cortisol supplement`, `cortisol gummies`
+- ingredient alone: `saffron supplement`, `magnesium glycinate sleep`
+- ingredient + outcome: `ashwagandha sleep`
+- the demographic word when it is a market on its own: `perimenopause supplement`, `menopause belly`
+
+Aim for 25 to 40 lanes. Fewer than 20 misses brands; more than 50 returns the same advertisers again.
+
+## Worked grid (fictional evening gummy: saffron, magnesium glycinate, rhodiola)
+
+```
+# outcome phrases
+wake up at 3am
+can't stay asleep
+racing mind at night
+puffy face morning
+rage at my kids
+stress eating at night
+no energy after 40
+# mechanism + outcome
+cortisol belly
+cortisol 3am
+cortisol face
+high cortisol symptoms
+hormone balance sleep
+nervous system regulation
+# mechanism + product
+cortisol supplement
+cortisol gummies
+cortisol reset
+# ingredients
+saffron supplement
+saffron mood
+magnesium glycinate sleep
+rhodiola energy
+ashwagandha sleep
+ashwagandha cortisol
+l-theanine
+# demographic markets
+perimenopause supplement
+menopause belly
+menopause mood swings
+sleep supplement women over 40
+```
+
+## Reading the aggregate
+
+`adlib_sweep.py` writes `advertisers.md` ranked by how many lanes each advertiser appeared in. Read it like this:
+
+- **Many lanes, many ads:** a mechanism brand. Score it first.
+- **One lane, many ads:** a single-angle brand or a lane that is really a different market (a menopause brand in the "menopause belly" lane). Score it if the lane is in your focus order.
+- **Many lanes, few ads:** an affiliate or advertorial page pushing several products. Check the link domains column; the domains are the real brands.
+- **Pages with community-style names** ("The Blood Sugar Journal", "Cholesterol Relief Community") are advertorial fronts. Follow the domain, not the page.
+
+Drop retailers, marketplaces, and apps unless the brief says otherwise.
+
+## The Amazon door
+
+Amazon is a demand signal off Meta and a source of brand names the ad sweeps miss. For each outcome and ingredient word, search Amazon, take two result pages, and pull ASIN, title, rating, review count, price, and the sponsored flag with a page script in the in-app browser. Dedupe sponsored against organic. Rank by relevance times review count. Brand names in the top ten of two or more searches go into the signal check. Review count and velocity become the sixth column on the sheet.
+
+Apify has Amazon search-result actors if the browser route is slow, but they bill per result and the browser route was free and fast for 12 categories.

package/assets/skills/find-competitors/scripts/adlib_sweep.py

@@ -0,0 +1,100 @@
+#!/usr/bin/env python3
+"""
+adlib_sweep.py — sweep the Meta Ad Library by keyword lanes via Apify and aggregate advertisers.
+
+Usage:
+  python3 adlib_sweep.py --keywords lanes.txt --outdir adlib --limit 150 --country US        # prints the plan, spends nothing
+  python3 adlib_sweep.py --keywords lanes.txt --outdir adlib --limit 150 --country US --yes  # runs the sweep
+  python3 adlib_sweep.py --keywords lanes.txt --outdir adlib --aggregate-only
+
+lanes.txt: one query per line (the outcome × mechanism × ingredient grid, see references/query-grid.md).
+
+Needs APIFY_API_TOKEN in .env. Cost: the apify~facebook-ads-scraper actor bills per result; 30 lanes × 150
+results is a few dollars. Without --yes the script prints the plan and stops; say it back, get a go, rerun with --yes.
+
+Output:
+  <outdir>/<lane>.json          raw ads per lane
+  <outdir>/advertisers.md       advertisers ranked by how many lanes they appear in and ad count,
+                                with the lanes each one showed up in. This is the candidate list.
+"""
+import argparse, json, os, sys, urllib.parse, glob, collections
+from concurrent.futures import ThreadPoolExecutor
+
+try:
+    import requests
+    from dotenv import load_dotenv
+except ImportError:
+    sys.exit("pip3 install requests python-dotenv")
+
+here = os.path.abspath(os.getcwd())
+for _ in range(7):
+    env = os.path.join(here, ".env")
+    if os.path.exists(env): load_dotenv(env); break
+    here = os.path.dirname(here)
+
+
+def run(kw, outdir, limit, country, tok):
+    u = ("https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=" + country +
+         "&q=" + urllib.parse.quote(kw) + "&search_type=keyword_unordered&media_type=all")
+    path = os.path.join(outdir, kw.replace(" ", "_").replace("/", "-") + ".json")
+    try:
+        r = requests.post(f"https://api.apify.com/v2/acts/apify~facebook-ads-scraper/run-sync-get-dataset-items?token={tok}&timeout=600",
+                          json={"startUrls": [{"url": u}], "resultsLimit": limit}, timeout=(30, 660))
+        d = r.json() if r.status_code == 200 else []
+        if not isinstance(d, list): d = []
+        json.dump(d, open(path, "w"))
+        print(f"{kw:<40} {r.status_code} {len(d)} ads", flush=True)
+    except Exception as e:
+        print(kw, "ERR", e, flush=True)
+
+
+def aggregate(outdir):
+    by_page = collections.defaultdict(lambda: dict(lanes=set(), ads=0, page_id=None, longest_active=0, links=set()))
+    for f in glob.glob(os.path.join(outdir, "*.json")):
+        lane = os.path.basename(f)[:-5].replace("_", " ")
+        try: ads = json.load(open(f))
+        except Exception: continue
+        if not isinstance(ads, list): continue
+        for a in ads:
+            p = a.get("pageName") or (a.get("snapshot") or {}).get("pageName")
+            if not p: continue
+            e = by_page[p]; e["lanes"].add(lane); e["ads"] += 1; e["page_id"] = e["page_id"] or a.get("pageId")
+            lu = (a.get("snapshot") or {}).get("linkUrl")
+            if lu: e["links"].add(urllib.parse.urlparse(lu).netloc)
+    rows = sorted(by_page.items(), key=lambda kv: (-len(kv[1]["lanes"]), -kv[1]["ads"]))
+    with open(os.path.join(outdir, "advertisers.md"), "w") as f:
+        f.write("# Advertisers found across lanes\n\nRanked by number of lanes, then ads seen. Feed the top rows to competitor_signals.py.\n\n")
+        f.write("| Advertiser | Lanes | Ads seen | Domains | Lanes hit | Ad Library page |\n|---|---|---|---|---|---|\n")
+        for p, e in rows:
+            link = f"https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=ALL&view_all_page_id={e['page_id']}&search_type=page&sort_data[mode]=total_impressions&sort_data[direction]=desc" if e["page_id"] else ""
+            f.write(f"| {p} | {len(e['lanes'])} | {e['ads']} | {', '.join(sorted(e['links']))[:80]} | {', '.join(sorted(e['lanes']))[:120]} | {link} |\n")
+    with open(os.path.join(outdir, "advertisers.txt"), "w") as f:
+        for p, e in rows: f.write(p + "\n")
+    print("wrote", os.path.join(outdir, "advertisers.md"), f"({len(rows)} advertisers)")
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--keywords", required=True)
+    ap.add_argument("--outdir", default="adlib")
+    ap.add_argument("--limit", type=int, default=150)
+    ap.add_argument("--country", default="US")
+    ap.add_argument("--workers", type=int, default=5)
+    ap.add_argument("--aggregate-only", action="store_true")
+    ap.add_argument("--yes", action="store_true", help="actually run the paid sweep")
+    a = ap.parse_args()
+    os.makedirs(a.outdir, exist_ok=True)
+    if not a.aggregate_only:
+        tok = os.environ.get("APIFY_API_TOKEN") or sys.exit("APIFY_API_TOKEN not found in .env or environment")
+        lanes = [l.strip() for l in open(a.keywords) if l.strip() and not l.startswith("#")]
+        if not a.yes:
+            print(f"Plan: {len(lanes)} lanes x up to {a.limit} results = up to {len(lanes) * a.limit} billed results on apify~facebook-ads-scraper (country {a.country}).")
+            print(f"Outputs land in {a.outdir}/. Nothing was run. Say the plan back, get a go, then rerun with --yes.")
+            sys.exit(2)
+        with ThreadPoolExecutor(a.workers) as ex:
+            list(ex.map(lambda k: run(k, a.outdir, a.limit, a.country, tok), lanes))
+    aggregate(a.outdir)
+
+
+if __name__ == "__main__":
+    main()

package/assets/skills/find-competitors/scripts/competitor_signals.py

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+"""
+competitor_signals.py — score a list of brands on the six strength signals using the Atria API.
+
+Usage:
+  python3 competitor_signals.py --names "Brand A" "Brand B" --out sheet.md
+  python3 competitor_signals.py --file brands.txt --out sheet.md --json signals.json
+
+brands.txt: one brand name per line (blank lines and # comments ignored).
+
+Needs ATRIA_API_KEY in the workspace .env (or the environment). Rate limit is tight:
+~10 calls in quick succession returns 429, so the script pauses and retries.
+
+Signals per brand (all from Atria's brand feed, no spend estimates). Three feed orders are used:
+most_impressions (top ads, offer words, reuse), newest (launches in 30 days), oldest (longest-running).
+  active_total   active ads right now
+  longest_days   days_running of the longest active ad
+  launches_30d   active ads with start_date in the last 30 days
+  reuse          active ads Atria marks as creative duplicates (re-launched winners), in the top-impression sample
+  offer          intro-offer words seen in active ad bodies (%, off, free, trial, quiz)
+  verdict        FOLLOW (3+ strong) · WATCH (2) · SKIP (0–1)
+
+Thresholds (edit STRONG below to fit the category):
+  active_total >= 50 · longest_days >= 90 · launches_30d >= 10 · reuse >= 5 · offer >= 3
+Cost: about 6 to 8 Atria calls per brand. 30 brands is a few minutes with the rate-limit pauses.
+"""
+import argparse, json, os, re, sys, time, datetime as dt
+from collections import Counter
+
+try:
+    import requests
+except ImportError:
+    sys.exit("pip3 install requests python-dotenv  (use --break-system-packages on Homebrew python)")
+
+try:
+    from dotenv import load_dotenv
+    here = os.path.abspath(os.getcwd())
+    for _ in range(7):
+        env = os.path.join(here, ".env")
+        if os.path.exists(env):
+            load_dotenv(env); break
+        here = os.path.dirname(here)
+except ImportError:
+    pass
+
+KEY = os.environ.get("ATRIA_API_KEY")
+if not KEY:
+    sys.exit("ATRIA_API_KEY not found in .env or environment")
+H = {"X-API-Key": KEY}
+B = "https://api.tryatria.com/open/v1"
+STRONG = dict(active_total=50, longest_days=90, launches_30d=10, reuse=5, offer=3)
+OFFER_RX = re.compile(r"(\d{2}% ?off|% off|free (shipping|trial|gift)|buy \d get|bogo|quiz|first[- ]time|intro(ductory)? (offer|price)|money[- ]back|save \$?\d)", re.I)
+
+
+def get(path, params, tries=5):
+    for i in range(tries):
+        r = requests.get(B + path, headers=H, params=params, timeout=60)
+        if r.status_code == 429:
+            time.sleep(20); continue
+        r.raise_for_status()
+        return r.json().get("data") or {}
+    raise RuntimeError(f"429 persisted on {path}")
+
+
+def search_brand(name):
+    items = get("/brand-library/search", {"keyword": name, "page_size": 8}).get("items", [])
+    first = name.lower().split()[0]
+    exact = [i for i in items if i.get("name", "").lower() == name.lower()]
+    close = [i for i in items if first in i.get("name", "").lower()]
+    if exact or close:
+        return (exact or close)[:1]
+    # no name match: do not guess. Report what Atria returned so the user can pick.
+    return [dict(_candidates=[i.get("name") for i in items[:6]])]
+
+
+def brand_ads(bid, status="active", pages=2, order="most_impressions", stop=None):
+    out, cur, total = [], None, None
+    for _ in range(pages):
+        p = {"status": status, "page_size": 50, "order": order}
+        if cur: p["cursor"] = cur
+        d = get(f"/brand-library/{bid}/ads", p)
+        items = d.get("items", []); out += items; cur = d.get("cursor"); total = d.get("total", total)
+        time.sleep(0.8)
+        if not cur or len(items) < 50: break
+        if stop and items and stop(items[-1]): break
+    return out, total
+
+
+def parse_date(s):
+    if not s: return None
+    try: return dt.datetime.fromisoformat(str(s).replace("Z", "+00:00")).replace(tzinfo=None)
+    except Exception: pass
+    try: return dt.datetime.utcfromtimestamp(int(s))
+    except Exception: return None
+
+
+def age_days(a, now):
+    d = parse_date(a.get("start_date"))
+    return (now - d).days if d else 10**6
+
+
+def score(name):
+    hits = search_brand(name)
+    if not hits or "_candidates" in hits[0]:
+        cands = hits[0]["_candidates"] if hits else []
+        return dict(name=name, found=False, error=("no name match; Atria offered: " + ", ".join(cands)) if cands else "no results")
+    b = hits[0]; bid = b["id"]
+    now = dt.datetime.now(dt.timezone.utc).replace(tzinfo=None)
+    act, total = brand_ads(bid, "active", 1, "most_impressions")
+    newest, _ = brand_ads(bid, "active", 4, "newest", stop=lambda a: age_days(a, now) > 30)
+    oldest, _ = brand_ads(bid, "active", 1, "oldest")
+    longest = max([a.get("days_running") or 0 for a in (oldest[:5] + act)] or [0])
+    launches = sum(1 for a in newest if age_days(a, now) <= 30)
+    if len(newest) >= 200 and launches >= 200: launches = f"{launches}+"
+    reuse = sum(1 for a in act if (a.get("creative_duplicates") or 0) > 0)
+    offer = sum(1 for a in act if OFFER_RX.search((a.get("body") or "") + " " + (a.get("title") or "")))
+    fmts = Counter(a.get("media_format") for a in act)
+    top = sorted(oldest[:5] + act, key=lambda a: -(a.get("days_running") or 0))[:3]
+    sig = dict(active_total=total if total is not None else len(act), longest_days=longest,
+               launches_30d=launches, reuse=reuse, offer=offer)
+    def num(x):
+        try: return int(str(x).rstrip("+"))
+        except Exception: return 0
+    strong = [k for k, v in STRONG.items() if num(sig[k]) >= v]
+    verdict = "FOLLOW" if len(strong) >= 3 else "WATCH" if len(strong) == 2 else "SKIP"
+    return dict(name=b.get("name", name), atria_id=bid, found=True, lifetime_ads=b.get("ad_num"),
+                website=b.get("website"), industries=b.get("industries"), **sig,
+                strong=strong, verdict=verdict, formats=dict(fmts),
+                longest_ads=[dict(days=a.get("days_running"), title=(a.get("title") or "")[:90],
+                                  hook=(a.get("body") or "")[:160].replace("\n", " "), link=a.get("link_url")) for a in top])
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--names", nargs="*", default=[])
+    ap.add_argument("--file")
+    ap.add_argument("--out", default="competitor-sheet.md")
+    ap.add_argument("--json")
+    a = ap.parse_args()
+    names = list(a.names)
+    if a.file:
+        names += [l.strip() for l in open(a.file) if l.strip() and not l.startswith("#")]
+    if not names: sys.exit("no brand names given")
+    rows = []
+    for n in names:
+        try:
+            r = score(n); rows.append(r)
+            print(f"{r.get('name', n):<34} {r.get('verdict', 'NOT FOUND'):<9} active={r.get('active_total')} longest={r.get('longest_days')}d launches30={r.get('launches_30d')} reuse={r.get('reuse')} offer={r.get('offer')}", flush=True)
+        except Exception as e:
+            rows.append(dict(name=n, found=False, error=str(e))); print(n, "ERR", e, flush=True)
+        time.sleep(1.0)
+    order = {"FOLLOW": 0, "WATCH": 1, "SKIP": 2}
+    rows.sort(key=lambda r: (order.get(r.get("verdict"), 3), -(r.get("active_total") or 0)))
+    with open(a.out, "w") as f:
+        f.write(f"# Competitor sheet ({dt.date.today()})\n\nVerdict: FOLLOW = 3+ strong signals · WATCH = 2 · SKIP = 0–1. Thresholds: {STRONG}\n\n")
+        f.write("| Brand | Verdict | Active | Longest (d) | Launches 30d | Reuse | Offer | Strong on | Longest-running ad |\n|---|---|---|---|---|---|---|---|---|\n")
+        for r in rows:
+            if not r.get("found"):
+                f.write(f"| {r['name']} | NOT FOUND | | | | | | | {r.get('error', '')} |\n"); continue
+            la = r["longest_ads"][0] if r["longest_ads"] else {}
+            f.write(f"| {r['name']} | {r['verdict']} | {r['active_total']} | {r['longest_days']} | {r['launches_30d']} | {r['reuse']} | {r['offer']} | {', '.join(r['strong'])} | {la.get('days', '')}d: {la.get('hook', '')[:100]} |\n")
+        f.write("\n## Fill in by hand\n\nFor every FOLLOW: UMP (the mechanism they sell) · offer · persona pages · why it matters · what to steal · Amazon review count.\n")
+    if a.json: json.dump(rows, open(a.json, "w"), indent=1)
+    print("wrote", a.out)
+
+
+if __name__ == "__main__":
+    main()

package/assets/skills/handoff/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: handoff
+description: End a working session properly, and periodically read the sessions back. Fires on "handoff", "wrap up", "scrape this chat", "save this session", "add this to my workflow", "note your place and close", "what did we do today", or at the natural end of a session. It (1) scrapes the chat into a dated session file with verbatim asks, outputs and where they live, corrections, and the steering behind each ask; (2) proposes STANDARDS.md entries from what it saw the user say, edit, and pick, and waits for a yes; (3) writes a resume prompt so the next session starts warm; (4) updates the one-page distilled workflow. In review mode ("handoff review", "read my last ten sessions", "how do I actually work") it reads the session files and standards and writes an end-to-end read of the user's workflow with patterns, disagreements between their own versions, and suggestions. The session files are the most valuable asset in the folder: the before-and-after record of how the user thinks. Never edit one after it is written.
+---
+
+# Handoff
+
+The chat is where feedback actually lives: what was said, what was edited, what was picked. Most of it evaporates when the window closes. This skill catches it, once, at the end.
+
+Read `STANDARDS.md` first ("How I give feedback" decides how much this skill proposes). Sessions live in `workflow/` at the workspace root: `workflow/sessions/` for the dated session files, `workflow/workflow.md` for the one-page distilled workflow, `workflow/reviews/` for review reads. Create the folder on first use.
+
+## Mode 1: session (default)
+
+Start with one question and nothing else: "Pull this session into your workflow?" No means write nothing. Yes means all four steps, then a short reply.
+
+### Step 1. Scrape the chat
+
+Write `workflow/sessions/YYYY-MM-DD_<brand>-<topic>.md` (date is the session start). Split the chat into phases by intent (setup, research, planning, build, review, meta). Per phase:
+
+1. **Ask (verbatim).** The user's exact words in a blockquote, typos included. Several quotes if the ask evolved. Never paraphrase here.
+2. **What happened.** Two to four sentences.
+3. **Outputs.** Paths, artifact links, Drive links, Exodus surfaces. Exact.
+4. **Steering.** Why they asked it, what it reveals about how they work, the rule or preference it implies. One paragraph.
+5. **Corrections.** Anything redirected, quoted verbatim, with the lesson.
+6. **Tool feedback.** Gaps hit in Exodus or any tool.
+
+At the end of the file: **Where everything lives** (a table), **Principles extracted** (numbered, from this session's quotes only), **What to make better next time** (concrete, from the corrections).
+
+Rules: quotes exact; include the meta-asks (honesty checks, "can you see the context"); include reversals; note when another person or session edited files; never save secrets (write "keys pasted in chat" and nothing else); if context was summarised, say so and mark unquotable phases "reconstructed". Once written, the file is read-only to the system.
+
+### Step 2. Propose standards
+
+Read the session back for three kinds of signal and turn each into a proposed entry in the shape STANDARDS.md uses (one dated line, the quote underneath, the section):
+
+- **Said.** Anything with always, never, from now on, I hate, I love, do it like this. Also any note given twice across this and earlier sessions (check the Log).
+- **Edited.** Any place the user changed a draft: what was there, what they made it, the principle in one line. These are before-and-after pairs; record them as pairs.
+- **Picked.** Any place the user chose from a set (three hooks out of twenty, one option of four): what they kept, what they rejected, the pattern in one line.
+
+Present them as a numbered list, at most ten, strongest first. The user answers by number. Write only the approved ones, exactly as `remember-that` would (section, log line, bank promote for approved winning lines, offer for anything that touches a workflow or primer). If "How I give feedback" says no proposals, skip this step and say so.
+
+### Step 3. Write the resume prompt
+
+Append to the session file a section **Resume** with: what is done, what is missing, what is next (in that order, the way "note your place" works), the files to read first, and one paragraph the user can paste into a new session to start warm. Say the paragraph back in the reply so it is one copy away.
+
+### Step 4. Update the distilled workflow
+
+Open `workflow/workflow.md` (create it if it does not exist). Add or adjust only what this session changed. Keep it one page. Do not rewrite it.
+
+### The reply
+
+Short: the session file path, the two or three strongest steering signals in one line each, the proposals awaiting a yes (or that they were written), the resume paragraph, and any change to `workflow.md`. No essay.
+
+## Mode 2: review
+
+Fires on "handoff review", "read my sessions", "how do I actually work", or when the session count since the last review passes the number in "How I give feedback" (default ten). Reads every session file, `workflow.md`, and `STANDARDS.md`, and writes `workflow/reviews/YYYY-MM-DD_review.md`:
+
+1. **The shape of it.** The user's workflow as a numbered sequence of stages, drawn from what they actually did across sessions, not what any skill says they should do.
+2. **The rules underneath it.** What drives the work: the modes they switch between, what they read raw before trusting, how they brief (by example, by list), the taxonomy they use, what they check every time.
+3. **Where their own versions disagree.** Places the sessions contradict each other or the standards, one line each, with the decision it implies.
+4. **Where it stands.** What is done, unfinished, blocked, and what has moved on disk since the last scrape.
+5. **Suggestions.** Three to five, each with the evidence rung it rests on (own sessions, standards, logic marked HYPOTHESIS). Things to make into rules, tools, or skills; things to retire; things the user keeps doing by hand that should be a bot (hand to `bot-builder`).
+6. **Standards proposals** from the review, same numbered shape as Mode 1, waiting for a yes.
+
+Then say the three biggest findings in the reply and stop. The user decides what to act on.
+
+## Mode 3: resume
+
+At the start of a session, check the newest file in `workflow/sessions/`. If it has a Resume section, offer it: "Last session ended at: <done / missing / next>. Continue from there?" Yes means read the files it names and pick up at "next". Do not re-derive what was already decided.
+
+## Rules
+
+- Session files are never edited after writing. A correction to a scrape is a new note in the next session.
+- Quotes are the asset. Steering is your read of them, labelled as such.
+- Plain language throughout. Collaborators will read these. No jargon that needs explaining. Do not call anyone a junior.
+- Keep the where-it-lives table current; the scrape is mechanical when the index was kept during the session.
+- Never propose the same standard twice. Check the Log.
+- The user is the only source of rules. Proposals wait.
+
+## Changelog
+
+- 2026-09-14 · v1. Absorbs the earlier workflow-scrape skill; adds proposals from said, edited, picked; adds review and resume modes.