thoughtleaders-cli 0.6.55__tar.gz → 0.7.0__tar.gz

{thoughtleaders_cli-0.6.55 → thoughtleaders_cli-0.7.0}/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tl-cli",
-  "version": "0.6.55",
+  "version": "0.7.0",
   "description": "ThoughtLeaders CLI — query sponsorship deals, channels, brands, uploads, and intelligence from the terminal",
   "author": {
     "name": "ThoughtLeaders",

{thoughtleaders_cli-0.6.55 → thoughtleaders_cli-0.7.0}/AGENTS.md

@@ -1,6 +1,6 @@
 # Project Overview
 
-**tl-cli** is a Python CLI for querying ThoughtLeaders sponsorship data (sponsorships, channels, brands, uploads, snapshots, reports, recommender). Built with Typer + Rich + httpx. Designed as an "agent-first tool" — the CLI handles structured commands and output, while the user's AI agent (Claude) provides intelligence.
+**tl-cli** is a Python CLI for querying ThoughtLeaders sponsorship data (sponsorships, channels, brands, uploads, snapshots, reports, recommender). Built with Typer + Rich + httpx. Designed as an "AI agent-first tool" — the CLI handles data commands and output, while the user's AI agent (Claude) provides decision making.
 
 # Architecture
 
@@ -11,25 +11,16 @@
 ## Command Pattern (all data commands follow this)
 
 Every data command in `src/tl_cli/commands/` uses explicit Typer subcommands:
-- `list` — list/search with `key:value` filters as positional args
 - `show` — detail view by ID
 - `history` — historical data list
 - `create` / `add` — create new records (where applicable)
 
 When adding a new data command, follow this pattern. See `sponsorships.py` for the reference implementation.
 
-`deals`, `matches`, and `proposals` are shortcut commands that delegate to sponsorships' `do_list`/`do_show`/`do_create` with a pre-set status filter. They reject explicit `status:` filters — users should use `tl sponsorships list` for finer-grained status filtering.
-
-`recommender` (`commands/recommender.py`) wraps the recommender API at `/api/cli/v1/recommender/*` — `tags` (free), `top-channels` / `top-profiles` / `top-brands`, `inspect-channel`, `inspect-brand`, `similar-to-profile` (all 25 credits flat, Intelligence-gated). The three `top-*` URLs share one server resolver; `top-brands` dedupes the underlying profile rows by brand. Channel→channel and brand→brand similarity stay on `tl channels similar` / `tl brands similar`. When updating the SKILL or examples, prefer steering category/topic discovery (e.g. "Cooking channels") to `tl recommender top-channels "<tag>"` rather than `WHERE content_category = <code>` SQL — the recommender is ranked, not equality-based. The underlying recommender code uses "element"/"field_name" terminology; the CLI/API layer renames these to "tag" at the boundary.
-
-## Filter Parsing (`filters.py`)
-
-`parse_filters()` handles `key:value` and `key:"quoted value"` syntax. Returns `dict[str, str]` passed as query params. Date filter keys (listed in `DATE_FILTER_KEYS` — e.g. `since`, `created-at`, `created-at-start`, `publish-date-end`) accept keywords `today`, `yesterday`, `tomorrow`. Sponsorship date fields (`created-at`, `publish-date`, `purchase-date`, `send-date`) each expose three filter shapes: bare `<field>:<date>` matches within that date/period, and `<field>-start:` / `<field>-end:` give inclusive lower/upper bounds (both sides inclusive; partial dates expand to the whole period). Empty-string values result in `IS NULL` queries on the backend.
-
 ## Auth Flow (`auth/`)
 
 - **PKCE + Auth0**: Browser-based login with localhost callback server (`login.py`)
-- **Token Storage** (`token_store.py`): OS keyring primary, `~/.config/tl/credentials.json` fallback (0o600)
+- **Token Storage** (`token_store.py`): OS keyring primary, `~/.config/tl/credentials.json` fallback (chmod 0o600)
 - **Env override**: `TL_API_KEY` env var takes priority over keyring (for CI)
 - **Auto-refresh**: `TLClient` refreshes expired tokens on 401
 
@@ -52,6 +43,8 @@ TTY-aware: Rich tables in terminal, JSON when piped. Flags: `--json`, `--csv`, `
 The CLI integrates with AI coding agents via skills, commands, agents, and hooks.
 
 - **Claude Code** - `tl setup claude`
+- **Gemini** - `tl setup gemini`
+- **Codex** - `tl setup codex`
 - **OpenCode** - `tl setup opencode`
 
 This repo is also a Claude Code plugin, and can directly be installed as one.
@@ -60,8 +53,7 @@ This repo is also a Claude Code plugin, and can directly be installed as one.
 
 - **`tl`** — the main skill for querying ThoughtLeaders data. Default for any sponsorship / channel / brand / upload / report question.
 - **`tl-keyword-research`** — invoke whenever the user wants to find videos or channels by **content keywords** (topics, concepts, niches) that aren't covered by a curated recommender tag, OR to validate that a candidate channel's content actually touches a given topic. Returns `{operator, keywords:[{keyword,count}]}` from a ranked ES probe over `title` / `summary` / `transcript`; the caller then runs the actual content search with the surviving high-count terms. **Do not compose keyword sets by hand for `tl db es` content searches — delegate to this skill first.** See `skills/tl/SKILL.md` → *Channel & video discovery* for the four-path decision tree and when to use this vs the recommender / raw SQL.
-- **`tl-report-builder`** — invoke when the user wants to build, refine, or save a platform report (campaign config, FilterSet, columns, widgets). Multi-phase flow: routing → schema + validation → columns → widgets.
-- **`tl-import`**, **`tl-save-report`**, **`adapt-tl-data`** — narrower workflows; the skill files document their own triggers.
+- **`tl-import`**, **`tl-save-report`**, **`adapt-tl-data`**, **`tl-views-guarantee`** — narrower workflows; the skill files document their own triggers.
 
 ### Skill content boundaries
 
@@ -73,21 +65,6 @@ Skills under `skills/` are split into a `SKILL.md` and one or more `references/*
 
 When adding or updating skill content, place the fact in its single home and link from the others. Do not duplicate or "quick-recap" content across files — recaps are the highest drift surface.
 
-#### Anti-pattern: skill-local schema references
-
-When a dependent skill (e.g. `tl-report-builder`) needs to reference a schema fact (table layout, columns, fetch SQL, hallucinated-column markers), **link to the canonical home in `skills/tl/references/`** — do not create a new `<skill>/references/*.md` file that mirrors or paraphrases that content.
-
-Concrete regression marker: an earlier branch added `skills/tl-report-builder/references/data_plane.md` to consolidate the `thoughtleaders_topics` fetch query out of inline tool text. That had the right *shape* (don't restate schema in tool prose) but the wrong *home* — it forked schema facts into a parallel reference file that would silently drift from `skills/tl/references/postgres-schema.md`. The fix was to land the columns + fetch SQL + regression markers in `postgres-schema.md` (and upstream in `tl-data/references/postgres-schema.md`), delete the local file, and rewire the references via Markdown links.
-
-Rule of thumb: if you are about to write *"here's the SQL to query this table"* or *"these columns don't exist on this table"* anywhere outside `skills/tl/references/`, stop. Add the fact to the canonical reference, then link to the anchor. Same for business facts and the glossary.
-
-Skill-local `references/*.md` ARE appropriate when the content is **skill-shaped**, not schema-shaped:
-- Column metadata for a specific report type (sortable columns, formula templates) — `tl-report-builder/references/columns_*.md`
-- JSON schemas for tool-specific request/response shapes — `tl-report-builder/references/*_schema.json`
-- Disambiguation tables, defaults, and pitfall catalogues that exist only in this skill's flow — `tl-report-builder/references/report_glossary.md`
-
-If you are unsure whether a fact is schema-shaped or skill-shaped, ask: "would another TL skill (analyst, finance, mbn-outreach) ever need this fact?" If yes, it's schema/business-shaped — promote it to the canonical home.
-
 ## API Response Envelope
 
 All list endpoints return: `{ results, total, limit, offset, usage: { credits_charged, credit_rate, balance_remaining }, _breadcrumbs }`.
@@ -109,9 +86,11 @@ The version string is defined in three files and all three must be updated toget
 - `.claude-plugin/plugin.json` — `"version": "x.y.z"`
 - `src/tl_cli/__init__.py` — `__version__ = "x.y.z"`
 
-## Important Constraint
+## Creating a release
 
-`tl snapshots video` requires `--channel` flag — Firebolt queries without a channel partition are unbounded.
+A "release" means using the `gh` command to create a release on GitHub, named like the current package version number.
+
+Warn the user if they are creating a release and the latest commit didn't bump the version number, and ask for confirmation before releasing.
 
 ## Coding
 
@@ -119,14 +98,19 @@ The version string is defined in three files and all three must be updated toget
 * Do not let server implementation details into skill files (anything under `skills/`). Skills describe *what the CLI does* from the user's seat — observable command surface, inputs, outputs, examples. Do not say "the server enforces X", "the API validates Y on its side", "the backend rejects Z" — those are mechanism notes that drift the moment the server changes. State the user-visible behaviour ("unknown keys come back as 400") without naming where it's enforced.
 * **All `import` and `from X import Y` statements live at the top of the Python module file** — after the module docstring, before any code. No inline imports inside function bodies, no lazy imports for "speed" or "optional dependency" reasons. `from __future__ import …` goes at the very top (Python requires that). The only legitimate inline-import exception is **platform-conditional imports** that cannot succeed on the other platform (e.g. `import msvcrt` on Linux, `import termios`/`tty` on Windows) — those stay inside their `if sys.platform == …:` guard. If a circular-import problem makes a top-level import impossible, fix the circular dependency rather than working around it with an inline import.
 
+# Updating
+
+The `tl update --force` command will force an update of the `thoughtleaders-cli` package.
+The auto-update feature keeps the package updated, by checking (cached) on each command invocation.
+
 # Git commit rules
 
 Do not reference internal architecture of the ThoughtLeaders app in commit messages.
 
-When a feature is purely server-side but changes the data the CLI receives (e.g. adding, removing, or renaming a field on a response, changing a credit rate, expanding an enum), make a forced empty commit on the tl-cli repo (`git commit --allow-empty`) describing the change. This keeps the CLI repo's history a complete log of what users see, even when no client code had to change.
+When a feature is purely server-side but changes the data the CLI receives (e.g. adding, removing, or renaming a field on a response, changing a credit rate, expanding an enum), make a forced empty commit on the tl-cli repo (`git commit --allow-empty`) describing the change. This keeps the CLI repo's history a complete log of what users see, even when no client code had to change. The `tl changelog` command will read this log to show to the users.
 
 # Be aware of tests
 
-For every feature or change, explicitly consider whether tests need to be added or updated — new endpoint, new model field, new CLI command, new validation rule, new error path, anything that changes user-visible behaviour. Don't ship a feature without asking "what test covers this?" If no test does and the surface is non-trivial, write one. This applies across all repos involved in the change (server-side changes that ripple into the CLI need both server tests and CLI tests updated).
+For every feature or change, explicitly consider whether tests need to be added or updated, on this repo or on the server repo — new endpoint, new model field, new CLI command, new validation rule, new error path, anything that changes user-visible behaviour. Don't ship a feature without asking "what test covers this?" If no test does and the surface is non-trivial, write one. This applies across all repos involved in the change (server-side changes that ripple into the CLI need both server tests and CLI tests updated).
 
-Be sure to check if tests need to be updated when changing any data structures or function names, in all repos involved in the change.
+Be sure to check if tests need to be updated when changing any data structures or function names, in all repos involved in the change

{thoughtleaders_cli-0.6.55 → thoughtleaders_cli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thoughtleaders-cli
-Version: 0.6.55
+Version: 0.7.0
 Summary: ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligence
 Project-URL: Homepage, https://thoughtleaders.io
 Project-URL: Repository, https://github.com/ThoughtLeaders-io/thoughtleaders-cli
@@ -37,7 +37,7 @@ ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligenc
 ### For account managers and sales
 
 - **Pipeline reporting on the fly.** *"How many deals did we close in Q1?"*, *"What's my weighted pipeline by sales owner?"*, *"Which proposals are stuck in `pending` for more than 14 days?"* — one raw SQL or one structured command, instead of waiting on a dashboard.
-- **Brand intelligence in seconds.** *"What channels does Nike sponsor?"*, *"Which brands sponsor `MrBeast`?"*, *"What's Holafly's sponsorship history through us vs. through everyone?"* — answers are one `tl brands history` or one `tl db es` call away.
+- **Brand intelligence in seconds.** *"What channels does Nike sponsor?"*, *"Which brands sponsor `MrBeast`?"*, *"What's Holafly's sponsorship history through us vs. through everyone?"* — answers are one `tl db es` call away.
 - **Vetting candidates before a pitch.** Look up a channel by ID, name, YouTube URL, or `@handle`; pull its adspots, audience demographics, evergreenness score, and detected sponsor history before drafting the IO.
 - **Pre-flight before booking.** Confirm MSN/TPP membership, integration availability, and persona/plan eligibility for a brand profile with one SQL join.
 
@@ -66,6 +66,7 @@ ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligenc
 - [jq](https://stedolan.github.io/jq/)
 - [ripgrep](https://github.com/BurntSushi/ripgrep)
 - [duckdb](https://duckdb.org/)
+- [yt-dlp](https://github.com/yt-dlp/yt-dlp)
 
 For automated installs on MacOS, prefer installing Homebrew and use the pipx package manager, but ask the user if they have the admin access (sudo) password first. If not, proceed by using `uv` and installing everything locally.
 
@@ -170,8 +171,7 @@ tl recommender brands-for-channel 12345          # Brands most likely to sponsor
 
 # Brand intelligence
 tl brands show Nike
-tl brands history Nike                # Detected sponsorships from ES
-tl brands history-stats Nike          # Aggregate roll-up (totals, first/last seen, top channels)
+tl brands find Nike                   # Resolve a string → single brand id
 
 # Search videos and transcripts via Elasticsearch
 tl db es '{"size":20,"query":{"term":{"channel.id":12345}},"_source":["title","views"]}'
@@ -196,7 +196,7 @@ tl balance
 
 # Health check — auth, connectivity, version, latency, and required external tools.
 # Run this first when something feels off; it surfaces token expiry,
-# missing `jq`/`rg`/`duckdb`, and slow endpoints in one snapshot.
+# missing `jq`/`rg`/`duckdb`/`yt-dlp`, and slow endpoints in one snapshot.
 tl doctor
 ```
 
@@ -276,9 +276,10 @@ Each agent discovers the skill automatically and uses it when you ask about spon
 
 The plugin ships several focused skills (installed by all the `tl setup *` commands):
 
-- **`tl`** — the data-analyst skill. Defaults to raw database queries via `tl db pg|fb|es` for anything non-trivial; uses the structured `tl <resource> show` / `find` / `similar` / `history` commands for single-record lookups and the special cases they were built for (similarity search, ID resolution, sponsorship history). Comes with full schema references for Postgres, Elasticsearch, and Firebolt under `references/`.
+- **`tl`** — the data-analyst skill. Defaults to raw database queries via `tl db pg|fb|es` for anything non-trivial; uses the structured `tl <resource> show` / `find` / `similar` commands for single-record lookups and similarity / ID-resolution special cases. Comes with full schema references for Postgres, Elasticsearch, and Firebolt under `references/`.
 - **`tl-report-builder`** — builds TL reports (channels / brands / sponsorships / videos) from natural-language requests. Produces an in-chat preview by default; saves a real campaign when the user is explicit ("save", "create the report").
 - **`tl-import`** / **`bulk-import`** — superuser-only; bulk-add or exclude lists of channels, brands, videos, or sponsorships against a report.
+- **`tl-views-guarantee`** — sizes a multi-video sponsorship buy for a channel, returning the video bundle size, views guarantee, and likelihood to hit.
 
 ## Output Formats
 

{thoughtleaders_cli-0.6.55 → thoughtleaders_cli-0.7.0}/README.md

@@ -9,7 +9,7 @@ ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligenc
 ### For account managers and sales
 
 - **Pipeline reporting on the fly.** *"How many deals did we close in Q1?"*, *"What's my weighted pipeline by sales owner?"*, *"Which proposals are stuck in `pending` for more than 14 days?"* — one raw SQL or one structured command, instead of waiting on a dashboard.
-- **Brand intelligence in seconds.** *"What channels does Nike sponsor?"*, *"Which brands sponsor `MrBeast`?"*, *"What's Holafly's sponsorship history through us vs. through everyone?"* — answers are one `tl brands history` or one `tl db es` call away.
+- **Brand intelligence in seconds.** *"What channels does Nike sponsor?"*, *"Which brands sponsor `MrBeast`?"*, *"What's Holafly's sponsorship history through us vs. through everyone?"* — answers are one `tl db es` call away.
 - **Vetting candidates before a pitch.** Look up a channel by ID, name, YouTube URL, or `@handle`; pull its adspots, audience demographics, evergreenness score, and detected sponsor history before drafting the IO.
 - **Pre-flight before booking.** Confirm MSN/TPP membership, integration availability, and persona/plan eligibility for a brand profile with one SQL join.
 
@@ -38,6 +38,7 @@ ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligenc
 - [jq](https://stedolan.github.io/jq/)
 - [ripgrep](https://github.com/BurntSushi/ripgrep)
 - [duckdb](https://duckdb.org/)
+- [yt-dlp](https://github.com/yt-dlp/yt-dlp)
 
 For automated installs on MacOS, prefer installing Homebrew and use the pipx package manager, but ask the user if they have the admin access (sudo) password first. If not, proceed by using `uv` and installing everything locally.
 
@@ -142,8 +143,7 @@ tl recommender brands-for-channel 12345          # Brands most likely to sponsor
 
 # Brand intelligence
 tl brands show Nike
-tl brands history Nike                # Detected sponsorships from ES
-tl brands history-stats Nike          # Aggregate roll-up (totals, first/last seen, top channels)
+tl brands find Nike                   # Resolve a string → single brand id
 
 # Search videos and transcripts via Elasticsearch
 tl db es '{"size":20,"query":{"term":{"channel.id":12345}},"_source":["title","views"]}'
@@ -168,7 +168,7 @@ tl balance
 
 # Health check — auth, connectivity, version, latency, and required external tools.
 # Run this first when something feels off; it surfaces token expiry,
-# missing `jq`/`rg`/`duckdb`, and slow endpoints in one snapshot.
+# missing `jq`/`rg`/`duckdb`/`yt-dlp`, and slow endpoints in one snapshot.
 tl doctor
 ```
 
@@ -248,9 +248,10 @@ Each agent discovers the skill automatically and uses it when you ask about spon
 
 The plugin ships several focused skills (installed by all the `tl setup *` commands):
 
-- **`tl`** — the data-analyst skill. Defaults to raw database queries via `tl db pg|fb|es` for anything non-trivial; uses the structured `tl <resource> show` / `find` / `similar` / `history` commands for single-record lookups and the special cases they were built for (similarity search, ID resolution, sponsorship history). Comes with full schema references for Postgres, Elasticsearch, and Firebolt under `references/`.
+- **`tl`** — the data-analyst skill. Defaults to raw database queries via `tl db pg|fb|es` for anything non-trivial; uses the structured `tl <resource> show` / `find` / `similar` commands for single-record lookups and similarity / ID-resolution special cases. Comes with full schema references for Postgres, Elasticsearch, and Firebolt under `references/`.
 - **`tl-report-builder`** — builds TL reports (channels / brands / sponsorships / videos) from natural-language requests. Produces an in-chat preview by default; saves a real campaign when the user is explicit ("save", "create the report").
 - **`tl-import`** / **`bulk-import`** — superuser-only; bulk-add or exclude lists of channels, brands, videos, or sponsorships against a report.
+- **`tl-views-guarantee`** — sizes a multi-video sponsorship buy for a channel, returning the video bundle size, views guarantee, and likelihood to hit.
 
 ## Output Formats
 

thoughtleaders_cli-0.7.0/agents/youtube-comment-classifier.md

@@ -0,0 +1,50 @@
+---
+name: youtube-comment-classifier
+description: >
+  Classifies a batch of YouTube comments as organic vs bot/spam/template for
+  the channel-authenticity skill's fake-engagement detection. Use when you
+  have a JSON array of scraped comments and need a fast, cheap per-comment
+  authenticity judgment. Returns strict JSON only.
+model: haiku
+tools: Read
+color: yellow
+---
+
+# YouTube Comment Authenticity Classifier
+
+You judge whether YouTube comments come from a real, engaged human audience or
+from engagement padding (bots, comment farms, generic filler). You are used by
+the `channel-authenticity` skill to vet channels before ThoughtLeaders books a
+paid sponsorship, so false "organic" verdicts cost real money — be skeptical.
+
+## Input
+
+A JSON array of objects: `[{"i": <int>, "text": "<comment>", "author": "<handle>"}, ...]`
+The user message contains ONLY this array (possibly large). Channel context
+(niche/language) may be provided in a leading line — use it if present.
+
+## Labels (choose exactly one per comment)
+
+- **organic** — specific, on-topic, references the actual video/creator,
+  asks a real question, shares a relevant experience, natural language with
+  normal variation. Mild praise that names something specific counts.
+- **generic-template** — vague praise that could be pasted on any video:
+  "nice video", "great content", "thanks for sharing", "first", lone emoji
+  strings, "love it ❤️". On-language but contentless.
+- **bot-like** — off-topic, off-language for the channel, gibberish,
+  random-looking handle + 1–3 word body, repeated near-identical phrasing,
+  engagement bait.
+- **promotional** — self-promo, "check out my channel", links, services.
+- **spam** — scams, adult/crypto bait, malicious or nonsensical repetition.
+
+When torn between organic and generic-template, prefer generic-template
+unless the comment clearly engages with the specific video.
+
+## Output — STRICT
+
+Return ONLY a JSON array, no prose, no markdown fence:
+
+`[{"i": 0, "label": "organic"}, {"i": 1, "label": "bot-like"}, ...]`
+
+One object per input comment, same `i` values, same length. No extra keys.
+If the input is empty, return `[]`.

{thoughtleaders_cli-0.6.55 → thoughtleaders_cli-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "thoughtleaders-cli"
-version = "0.6.55"
+version = "0.7.0"
 description = "ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligence"
 readme = "README.md"
 license = "MIT"

thoughtleaders_cli-0.7.0/skills/channel-authenticity/.gitignore

@@ -0,0 +1,2 @@
+# Generated at runtime by peer_cohort.py — niche engagement medians, cached per run.
+references/peer-cohort-cache.json

thoughtleaders_cli-0.7.0/skills/channel-authenticity/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: channel-authenticity
+description: >
+  Detect non-organic views / fake engagement / bot comments on a YouTube
+  channel before booking (or after delivering) a sponsorship. Use when asked
+  to vet a channel, check if views/comments are real, investigate suspicious
+  engagement, audit a sponsorship delivery, or whenever someone shares a
+  YouTube channel/handle/URL and asks "is this real / safe to buy an ad on".
+  Triggers: "fake views", "bot comments", "non-organic", "is this channel
+  legit", "vet this channel", "engagement looks off", "audit this sponsorship".
+---
+
+# Channel Authenticity
+
+Takes a channel (handle / URL / numeric id / name) — or `adlink:<id>` for a
+sponsorship drill-down — and returns a 0–100 authenticity score plus ranked
+red-flag findings. Built and calibrated from real bought-view and comment-farm
+investigations.
+
+## Hard rules
+
+- **One mode. Every run does everything.** No flags, no opt-in tiers. Groups
+  A, B, and C all run, every time.
+- **Comment scraping (Group C) is mandatory and never skipped.** Metrics and
+  view-curves can be hand-waved ("the algorithm", "we ran ads"); reading what
+  the audience actually says is the only direct proof. A run without it is
+  invalid.
+- **Data access is CLI-only.** Everything goes through `tl_cli.py` and the
+  `tl` CLI (`tl db pg/fb/es`, `tl channels similar`).
+- Do all data processing with the "utf-8" encoding explicitly in all scripts
+  you create.
+
+## Setup check
+
+```bash
+cd .claude/skills/channel-authenticity/scripts
+python3 tl_cli.py preflight        # must print "OK"
+```
+If this errors with `cli_unavailable`, tell the user to run `tl auth login`
+(or set `TL_API_KEY`). Comment scraping additionally needs `yt-dlp`
+(`pip install yt-dlp`) — it uses the android InnerTube client so **no cookies
+or API key are required**.
+
+## How to run (three phases — a classifier subagent sits between two CLI passes)
+
+**Phase 1 — collect.** From the `scripts/` dir:
+```bash
+python3 analyze_channel.py "<handle|url|id|name|adlink:ID>"
+```
+This runs Groups A + B + C(rule-based), scrapes ≥10 latest longforms
+(+ highest-view + most-recently-sponsored), and prints a JSON envelope with
+`state_path`, `llm_batch_path`, and `llm_batch_size`.
+
+If the ref matches **multiple channels** (common for names with localized
+dupes), Phase 1 exits (code 4) with `{"error":"ambiguous_channel",
+"candidates":[{id,name,subscribers}…]}` instead of guessing. Show the
+candidates to the user — they're ordered by subscriber count, highest first
+(the most likely intended) — let them pick, then re-run Phase 1 with that
+numeric id.
+
+**Phase 2 — classify comments (run the subagent TWICE).** Read
+`llm_batch_path` (a JSON array of `{i, text, author}`) and send it to the
+`youtube-comment-classifier` agent via the **Agent tool**
+(`subagent_type: youtube-comment-classifier`) **twice** — two separate calls on
+the same batch. Prepend one context line: `channel niche: cat
+<content_category>, language <language>` (both values are in the envelope).
+Each call returns a strict JSON array
+`[{"i":N,"label":"organic|generic-template|bot-like|promotional|spam"}]`; save
+each reply verbatim to its own file (e.g. `/tmp/ca_llm1.json`,
+`/tmp/ca_llm2.json`).
+
+Why twice: single-pass LLM labeling wobbles ±10pts, so finalize majority-votes
+the two passes to keep the reported organic share stable. Sophisticated
+AI-comment farms read as clean English at normal volume — only the classifier
+catches them, so this pass is essential.
+
+If the batch is empty (channel had almost no comments), skip the subagent and
+pass an empty array `[]` — near-zero comments is itself the loudest signal,
+and Group C already penalizes it.
+
+**Phase 3 — finalize** (pass both classifier files):
+```bash
+python3 analyze_channel.py --finalize <state_path> /tmp/ca_llm1.json /tmp/ca_llm2.json
+```
+This applies the LLM verdict, computes the composite score, writes the final
+JSON + markdown report to `/tmp`, and prints the report. Present that report
+to the user (it's already formatted — peer comparison, group scores, ranked
+flags, verdict).
+
+## Scoring (see references/scoring.md)
+
+Three groups, each scored 0–100 independently (start at 100, subtract fixed
+per-flag penalties). **Final = simple mean of the three.** Two hard
+overrides force `FRAUD_LIKELY` (score capped at 39) regardless of the mean:
+(1) Group C — non-organic audience (<30% organic from the classifier, or a
+dead comment section); (2) Group B — concealed/misrepresented performance
+(≥2 sold+published sponsored videos deleted/unlisted, or one with ≥5k views;
+or ≥3 high-view videos scrubbed with ≥15% of tracked views gone).
+
+Bands: ≥90 CLEAN · ≥70 MINOR_FLAGS · ≥40 MIXED · <40 FRAUD_LIKELY.
+
+## What each group checks
+
+- **Group A — engagement & peer ratios** (`engagement_ratios.py`,
+  `peer_cohort.py`): like/comment rates measured against a niche-matched peer
+  baseline, plus audience-size sanity checks across longforms vs shorts.
+- **Group B — view-curve anomalies + video integrity** (`view_curves.py`,
+  `anomaly_detector.py`, `video_integrity.py`): view-over-time curves that
+  don't behave like organic growth (bursts without engagement, guarantee
+  cliffs at round numbers, frozen likes, subs flat while views surge), plus
+  intent-aware detection of deleted/unlisted videos used to conceal or
+  misrepresent performance (benign re-uploads are excluded).
+- **Group C — comment content** (`comment_scraper.py`, `comment_analyzer.py`
+  + classifier subagent): whether the comments are a real, engaged audience —
+  scarcity vs views, templating and near-duplicates, language mismatch,
+  bot-handle patterns, and the classifier's organic-share verdict.
+
+Full catalogue + thresholds: `references/red-flags.md`. The exact `tl` queries
+each check issues live in the scripts; the underlying channel/video/adlink
+schema is documented in the `tl` skill (`skills/tl/references/`).
+
+## After a run
+
+Offer to log the verdict (channel, score, top flags, date) to a "Channel
+Vetting Log" sheet via the `gws` skill if the user wants an audit trail.
+If you discover a new robust signal, add it to `references/red-flags.md` and
+a penalty to `references/scoring.md` (self-improvement).

thoughtleaders_cli-0.7.0/skills/channel-authenticity/references/comment-patterns.md

@@ -0,0 +1,45 @@
+# Comment patterns
+
+The generic-template phrase library and handle regexes used by
+`comment_analyzer.py`. Extend as new padding patterns show up; keep the code
+list (`GENERIC` in `comment_analyzer.py`) and this doc in sync.
+
+## Generic-template phrases (case-insensitive substring/exact)
+
+```
+nice video, great video, great content, thanks for sharing, first,
+love this, love it, keep it up, keep going, awesome, amazing, good job,
+well done, very nice, so good, best video, informative, helpful,
+thank you so much, wow, super, 👍, 🔥, ❤, great work, nice one,
+good video, very helpful, excellent
+```
+
+A comment counts as generic if its lowercased, punctuation-stripped form is
+exactly one of these OR is ≤25 chars and contains one. Lone emoji strings are
+caught separately by the emoji-only check.
+
+## Bot-handle regex
+
+- `^@?[a-z]+[-_]?[0-9]{4,}$` — letters then 4+ digits (YouTube
+  auto-suffix style, e.g. `@viewer8821`, `@john_doe4417`). High-signal in bulk.
+
+> Note: YouTube now appends short suffixes to many *real* handles too, so
+> bot-handle share is a **supporting** signal (penalty 15), never decisive on
+> its own. The decisive comment signals are scarcity and LLM-not-organic.
+
+## Language
+
+Channel `language == 'en'`: a comment "matches" if ≥60% of its alphabetic
+chars are ASCII letters. Emoji/number-only comments are excluded from the
+denominator (handled by emoji-only / length checks instead). For non-English
+channels the language check is skipped (we lack reliable per-language
+baselines — revisit if we onboard many non-en channels).
+
+## What good looks like (contrast)
+
+Real audiences on a tech channel reference specifics ("the 72→82 jump
+convinced me", "where is part 1 and 2a?"), ask operational questions, argue,
+and reply to each other. Padding is short, vague, off-language, emoji-heavy,
+or planted product mentions ("X was built specifically for…", "signed up just
+now with the launch code"). The Haiku classifier exists to catch the planted-
+promotional class that keyword rules miss.

thoughtleaders_cli-0.7.0/skills/channel-authenticity/references/peer-cohort.md

@@ -0,0 +1,47 @@
+# Peer cohort
+
+Group A's like:view / comment:view thresholds are **relative to a
+niche-matched peer baseline**, not absolute — engagement norms vary wildly by
+niche (gaming ≠ finance ≠ tech tutorials), so a fixed cutoff would
+false-flag low-engagement-but-honest niches and miss high-engagement niches
+being inflated.
+
+## How the cohort is built (`peer_cohort.py`)
+
+1. **Preferred:** `tl channels similar <id> --limit 24` (the recommender).
+   Best niche match.
+2. **Fallback** (recommender empty): PG cohort —
+   same `content_category` + `language`, `is_active`, `reach` within ±50%,
+   `last_published` within 60 days, excluding the subject channel.
+3. For up to 12 peers, pull each peer's last 10 longforms via `tl db es`,
+   require ≥5,000 aggregate views and ≥3 videos (skip dead peers).
+4. Baseline = **median** of peers' like-rate and comment-rate, plus the 25th
+   percentile for context.
+
+A subject channel flags when its longform rate is **< 0.4× the peer median**.
+0.4× is intentionally generous — we only fire on gross deviation, not normal
+variance. (The origin fraud case ran 0.008× the median; real channels cluster
+0.7–1.5×.)
+
+## Caching
+
+Result cached in `peer-cohort-cache.json` keyed by
+`content_category|language|reach_bucket`, TTL 30 days. Buckets:
+`<10k, 10-50k, 50-150k, 150-500k, 500k-1m, 1-5m, 5m+`. This avoids re-spending
+recommender credits and re-querying ES on every run. Force a rebuild by
+deleting the cache file or calling `get_baseline(ch, refresh=True)`.
+
+## Last-resort fallback
+
+If no usable peers at all (rare — niche too small / all peers dead), a generic
+English-tech floor is used (`like 2%, comment 0.25%`) and `source` is recorded
+as `fallback-generic` in the metrics so the report consumer knows the
+baseline was weak. Prefer widening the reach band over trusting this.
+
+## Caveats
+
+- The PG fallback uses `content_category` which is coarse; the recommender
+  (`tl channels similar`) is materially better — prefer it.
+- Reach buckets are wide on purpose (engagement scales sub-linearly with
+  size); don't narrow them without re-checking the false-positive rate on a
+  known-clean channel.

thoughtleaders_cli-0.7.0/skills/channel-authenticity/references/red-flags.md

@@ -0,0 +1,77 @@
+# Red-flag catalogue
+
+Every signal the skill checks, why it matters, and the threshold. Codes match
+the `flags[].code` in the JSON output. Real cases are referenced by anonymized
+label only.
+
+## Group A — engagement & peer ratios (`engagement_ratios.py`)
+
+| code | trigger | why |
+|---|---|---|
+| `A_like_rate_vs_peers` | longform like:view < 0.4× peer-cohort median | Paid/bot views don't like. Origin case: 0.027% vs 3.4% peer median (125×). |
+| `A_comment_rate_vs_peers` | longform comment:view < 0.4× peer median | Same logic for comments. Origin case: 78× below. |
+| `A_views_to_subs` | avg longform views > 20% of subs | Healthy 1–15%. Origin case 28%. Implies non-subscriber/external traffic. |
+| `A_longform_shorts_gap` | shorts like-rate ≥ 5× longform like-rate (shorts ≥0.3%) | Organic shorts + dead longforms ⇒ longforms are the promoted units. The smoking gun on the origin case (20×). |
+| `A_organic_floor` | ≥ half of longforms exceed 5× the median-short view count | Non-viral shorts ≈ true audience size. Origin case median short = 688 views vs 180k longform. |
+| `A_per_video_outliers` | ≥⅓ of longforms >1.5σ below the channel's own like:view mean | One real audience produces consistent ratios; promoted videos don't. |
+
+Peer baseline: niche-matched (`tl channels similar`, fallback PG cohort:
+same content_category+language, active, reach ±50%, published <60d), median
+of each peer's last-10-longform like/comment rates. Cached 30 days.
+
+## Group B — view-curve time-series (`anomaly_detector.py`)
+
+| code | trigger | why |
+|---|---|---|
+| `B_burst_without_engagement` | a Δ-segment with Δviews/day > 3× rolling mean, >5k views, and segment like-rate < ½ lifetime | Real virality brings likes; injected views don't. |
+| `B_engagement_incoherence` | Pearson r(Δviews, Δlikes+Δcomments) < 0.2 over the curve | Organic videos: views and engagement move together (r>0.6). Fraud: decoupled. |
+| `B_guarantee_cliff` | plateau within 5% of a round number (50k/100k/250k/500k/1M…) by age ≤60 then flat | A bought-view case: bought to a 500k guarantee, cliffed at 581k. |
+| `B_slow_start_late_spike` | views@2 < 25th-pctile-ish (< 0.15× final) AND views@10/views@2 > 8 | Paid traffic switched on days after publish — classic bought-view signature. |
+| `B_latelife_drip_frozen_likes` | age ≥20 segment with >3k new views but ≤1 new like | Post-publish ad campaigns drip views with zero engagement. Seen on every video of the origin case. |
+| `B_subs_flat_while_views_surge` | < 30 new subs per 100k channel views over snapshot window | A bought-view case: 27 subs / 580k views. Viewers don't convert ⇒ not real interest. |
+
+Interpolation (`view_curves.py`) is self-contained (linear + log bracket
+interpolation, per-segment deltas) — no external dependency.
+
+### Group B add-on — video integrity (`video_integrity.py`)
+
+Deletion/unlisting is **not** a signal by itself — channels legitimately
+re-upload and clean house. The signal is deletion used to **conceal or
+misrepresent performance**. Source: ES `offline_since` (exists ⇒ video gone)
+and `content_aspects` containing `'unlisted'`. Intent is inferred from
+view count, age-at-removal, and whether the video was a paid sponsorship.
+
+| code | trigger | why |
+|---|---|---|
+| `B_sponsored_video_concealed` | a SOLD+PUBLISHED adlink's video is now offline/unlisted | Brand paid, ad went live, delivery then hidden. Bad-faith + finance/delivery alarm. Hard-fail if ≥2, or one with ≥5k views. |
+| `B_high_view_video_scrub` | offline video(s) above the channel's high-view bar (max of 50k or 25% of median) | You don't delete a 2M-view video by accident. Penalty scales by the **share of tracked views** gone, not raw count (big channels always shed a few old high-view videos): ≥15% → −25 critical; ≥3% → −12 warning; <3% → recorded, not penalized. Hard-fail only if ≥3 videos AND ≥15% of views vanished. |
+| `B_unlisted_with_traffic` | unlisted video still carrying ≥20k views | Hidden from channel page/subscribers while accruing views — running content the organic audience never sees. |
+
+Benign (recorded in metrics, **not** penalized): removed ≤7d after publish,
+<5k views, non-sponsored (re-upload/mistake — e.g. a 713-view video pulled
+2 days after publish).
+
+## Group C — comment content (`comment_analyzer.py` + Haiku subagent)
+
+| code | trigger | why |
+|---|---|---|
+| `C_comment_scarcity` | viewer comments < 15% of a 1-per-2,000-views floor (scraped ≥50k views) | The single loudest signal. Origin case: ~21 comments across ~1.8M scraped views. Measured on freshly-scraped comments so it can't be a stale count. |
+| `C_language_mismatch` | <60% of comments in channel language (en channels) | Off-language comment farms — e.g. off-language/emoji junk flooding an English channel. |
+| `C_generic_templates` | >40% generic ("nice video", lone emoji…) | Padding. Library in `comment-patterns.md`. |
+| `C_length_uniform` | ≥70% ≤5 words AND median <8 words | Bots cluster short; real audiences have a long tail. |
+| `C_emoji_only` | >25% emoji-only / no real text | Filler. |
+| `C_bot_usernames` | >30% handles match `^@?[a-z]+[-_]?\d{4,}$` **AND** LLM organic share < 55% | YouTube's own default handles match this pattern too, so it's only a tell when the audience is independently suspect — fires as corroboration in the LLM step, never on format alone. |
+| `C_near_duplicates` | largest token-Jaccard>0.7 cluster >10% | Templated posting. |
+| `C_low_reply_ratio` | <5% of top comments have any reply | Real audiences converse. |
+| `C_no_creator_engagement` | creator hearts 0 comments | Creator ignores a section they know is fake. |
+| `C_commenter_churn` | <2% commenters appear on >1 video | No recurring fanbase; throwaway accounts. |
+| `C_time_clustered` | >50% of comments in first hour on a weeks-old video | Burst posting. |
+| `C_llm_not_organic` | Haiku classifier <50% organic | Catches subtle patterns rules miss. <30% ⇒ hard override → FRAUD_LIKELY. |
+
+## Contributing new signals
+
+Found a robust new tell? Add a row here, add a penalty + severity to the
+relevant `PENALTIES` dict in the script, and document the penalty in
+`scoring.md`. Keep thresholds evidence-based, but **reference cases by
+anonymized label only — never a channel name, id, or handle** (this skill
+ships in a public repo).