thoughtleaders-cli 0.6.54__tar.gz → 0.6.56__tar.gz

{thoughtleaders_cli-0.6.54 → thoughtleaders_cli-0.6.56}/.claude-plugin/plugin.json

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

{thoughtleaders_cli-0.6.54 → thoughtleaders_cli-0.6.56}/API.md

@@ -172,7 +172,7 @@ print(get('/balance'))
 
 ## db pg
 
-`POST /raw/pg` — execute a read-only PostgreSQL `SELECT`. Sanitised: SELECT only, no DDL/DML/transactions, `LIMIT ≤ 500`, function allowlist (aggregates, window, string, JSON, math, date/time, array). `OFFSET ≥ 10 000` is rejected with `OFFSET_TOO_DEEP` — paginate with the response's `next_offset` instead.
+`POST /raw/pg` — execute a read-only PostgreSQL `SELECT`. Sanitised: SELECT only, no DDL/DML/transactions, `LIMIT ≤ 10,000`, function allowlist (aggregates, window, string, JSON, math, date/time, array). `OFFSET ≥ 10 000` is rejected with `OFFSET_TOO_DEEP` — paginate with the response's `next_offset` instead.
 
 Body: `{"query": "<sql>"}`.
 
@@ -212,11 +212,36 @@ print(post('/raw/pg', {'query': sql}))
 
 ### Pricing
 
-PG cost is **per-query**: a base rate plus a surcharge for every priced table and column referenced. Most tables/columns are free; sensitive ones (demographics, channel outreach emails) cost more. The `usage.credit_rate` you get back is the effective multiplier the server applied — it's not the static value from `tl describe`. The `pricing` sub-key, when present, breaks the rate into base/per-table/per-column components.
+PG cost is **per-query**: a base rate plus a multiplier extra for every expensive table referenced, plus a flat per-row charge for every expensive column read. Most tables/columns are free; sensitive ones (demographics, channel outreach emails) are expensive. The `usage.credit_rate` you get back is the effective multiplier the server applied — it's not the static value from `tl describe`. The `pricing` sub-key, when present, breaks the rate into base/per-table/per-column components.
+
+#### Pre-run cost estimate
+
+Send `{"query": "…", "pricing": true}` to `POST /raw/pg` (CLI: `tl db pg "…" --pricing`) for a dry run: the server runs `EXPLAIN` only — **no SELECT executes** — and returns a `pricing_estimate` object instead of `results`:
+
+```json
+{
+  "pricing_estimate": {
+    "base": 1.4,
+    "multiplier": 4.4,
+    "per_row_extra": 280.0,
+    "expensive_tables": {"thoughtleaders_channel": 3.0},
+    "expensive_columns": {"thoughtleaders_channel.outreach_email": 80.0},
+    "limit": 100,
+    "planner_estimated_rows": 1299016,
+    "estimated_cost_at_limit": 28140.26
+  },
+  "results": [],
+  "usage": {"credits_charged": 1, ...}
+}
+```
+
+`multiplier` and `per_row_extra` are exact; `estimated_cost_at_limit` is an **upper bound** computed at the query's effective `LIMIT` (the query can't return more rows than that). A dry run costs a flat **1 credit**.
+
+The same `{"pricing": true}` flag works on `POST /raw/fb` and `POST /raw/es`. Those backends are flat-rate (no per-table/column extras), so the estimate carries `multiplier` = the backend rate, `per_row_extra` = 0, empty expensive-item maps, and `limit` = the row ceiling (Firebolt `LIMIT`; Elasticsearch `size`, or the aggregation doc cap for agg queries). A Firebolt query with no `LIMIT` returns `limit`/`estimated_cost_at_limit` as `null` (unbounded). No query executes; flat 1 credit.
 
 ### Common rejections
 
-- `MISSING_LIMIT` / `LIMIT_TOO_HIGH` — always include `LIMIT N` with `N ≤ 500`.
+- `MISSING_LIMIT` / `LIMIT_TOO_HIGH` — always include `LIMIT N` with `N ≤ 10,000`.
 - `INSERT` / `UPDATE` / `DELETE` / `CREATE` / `DROP` — sanitiser is SELECT-only.
 - `LEAKY_CAST` — `::regclass`, `::regprocedure`, etc. are blocked.
 - `OFFSET_TOO_DEEP` — paginate via the next-page breadcrumb instead of jumping past 10 000.

{thoughtleaders_cli-0.6.54 → thoughtleaders_cli-0.6.56}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thoughtleaders-cli
-Version: 0.6.54
+Version: 0.6.56
 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
@@ -210,7 +210,9 @@ tl describe show sponsorships --filters    # Available filters for sponsorships
 tl balance                                 # Your credit balance
 ```
 
-`tl db pg` is priced **per-query**: a base rate plus a surcharge for every priced table and column referenced. Sensitive fields (demographics, channel outreach emails) cost more. Run `tl describe show db --json` to see the live surcharge map, and check `usage.credit_rate` in the response envelope after a query to see what your query was actually charged.
+`tl db pg` is priced **per-query**: a base rate plus a multiplier extra for every expensive table referenced, plus a flat per-row charge for every expensive column read. Sensitive fields (demographics, channel outreach emails) are expensive. Run `tl describe show db --json` to see the live `pg_expensive` map, and check `usage.credit_rate` in the response envelope after a query to see what your query was actually charged.
+
+To preview a query's cost **before** running it, add `--pricing`: `tl db pg "SELECT … LIMIT 100" --pricing` runs only the planner's `EXPLAIN`, prints the cost breakdown and an upper-bound estimate (at the query's `LIMIT`), and costs a flat **1 credit** — the query itself never executes. Works with `--json` too. `--pricing` is also available on `tl db fb` and `tl db es`; those backends are flat-rate (no per-column charges), so the estimate is the volume curve at the query's row ceiling (`LIMIT` for Firebolt, `size` — or the aggregation doc cap — for Elasticsearch).
 
 # Terminology
 

{thoughtleaders_cli-0.6.54 → thoughtleaders_cli-0.6.56}/README.md

@@ -182,7 +182,9 @@ tl describe show sponsorships --filters    # Available filters for sponsorships
 tl balance                                 # Your credit balance
 ```
 
-`tl db pg` is priced **per-query**: a base rate plus a surcharge for every priced table and column referenced. Sensitive fields (demographics, channel outreach emails) cost more. Run `tl describe show db --json` to see the live surcharge map, and check `usage.credit_rate` in the response envelope after a query to see what your query was actually charged.
+`tl db pg` is priced **per-query**: a base rate plus a multiplier extra for every expensive table referenced, plus a flat per-row charge for every expensive column read. Sensitive fields (demographics, channel outreach emails) are expensive. Run `tl describe show db --json` to see the live `pg_expensive` map, and check `usage.credit_rate` in the response envelope after a query to see what your query was actually charged.
+
+To preview a query's cost **before** running it, add `--pricing`: `tl db pg "SELECT … LIMIT 100" --pricing` runs only the planner's `EXPLAIN`, prints the cost breakdown and an upper-bound estimate (at the query's `LIMIT`), and costs a flat **1 credit** — the query itself never executes. Works with `--json` too. `--pricing` is also available on `tl db fb` and `tl db es`; those backends are flat-rate (no per-column charges), so the estimate is the volume curve at the query's row ceiling (`LIMIT` for Firebolt, `size` — or the aggregation doc cap — for Elasticsearch).
 
 # Terminology
 

thoughtleaders_cli-0.6.56/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.54 → thoughtleaders_cli-0.6.56}/pyproject.toml

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

thoughtleaders_cli-0.6.56/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.6.56/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` → the
+  `tl` CLI (`tl db pg/fb/es`, `tl channels similar`). No database credentials
+  are ever used. If the CLI isn't authenticated the skill fails fast with a
+  clear message.
+
+## 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.6.56/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.6.56/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.6.56/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).

thoughtleaders_cli-0.6.56/skills/channel-authenticity/references/scoring.md

@@ -0,0 +1,96 @@
+# Scoring
+
+Deliberately simple (per the approved plan). Three check groups, each scored
+**independently 0–100**: start at 100, subtract the fixed per-flag penalty for
+every triggered flag, floor at 0. **Final score = simple mean of the three
+group sub-scores.** No weighting matrix, no bonuses, no per-group caps.
+
+```
+final = (A + B + C) / 3
+```
+
+## Verdict bands
+
+| score | verdict | advice |
+|---|---|---|
+| ≥ 90 | CLEAN | Safe to book at standard rates |
+| ≥ 70 | MINOR_FLAGS | Book but note caveats to the AM |
+| ≥ 40 | MIXED | Manual review; consider rate reduction |
+| < 40 | FRAUD_LIKELY | Do not book without senior sign-off + heavy discount |
+
+## Hard overrides
+
+If either trigger fires, the verdict is forced to **FRAUD_LIKELY** and the
+score capped at 39 regardless of the mean:
+
+1. **Group C — non-organic audience:** Haiku classifier organic share
+   **< 30%** (`group_c.hard_fail`), or an effectively dead comment section
+   (<8-viewer-comment early exit). Fake comments are the most direct proof of
+   a fake audience.
+2. **Group B — concealed/misrepresented performance** (`group_b.hard_fail`):
+   ≥2 sold+published sponsored videos offline/unlisted (or one with ≥5k
+   views); OR ≥3 high-view videos scrubbed AND ≥15% of all tracked views
+   gone. Using deletion to hide paid delivery or strike-bait is bad faith,
+   not housekeeping.
+
+Neither fires for benign deletion (low-view, young, non-sponsored re-uploads
+are excluded before scoring).
+
+## Penalties (authoritative list)
+
+Penalties live in each script's `PENALTIES` dict; this table mirrors them.
+Severity drives report ordering/icons only, not math.
+
+### Group A — `engagement_ratios.py`
+| code | penalty | severity |
+|---|---|---|
+| A_like_rate_vs_peers | 30 | critical |
+| A_comment_rate_vs_peers | 25 | critical |
+| A_longform_shorts_gap | 25 | critical |
+| A_views_to_subs | 15 | warning |
+| A_organic_floor | 15 | warning |
+| A_per_video_outliers | 10 | info |
+
+### Group B — `anomaly_detector.py` + `video_integrity.py`
+| code | penalty | severity |
+|---|---|---|
+| B_burst_without_engagement | 25 | critical |
+| B_engagement_incoherence | 25 | critical |
+| B_latelife_drip_frozen_likes | 20 | critical |
+| B_guarantee_cliff | 15 | warning |
+| B_slow_start_late_spike | 15 | warning |
+| B_subs_flat_while_views_surge | 15 | warning |
+| B_sponsored_video_concealed | 30 | critical |
+| B_high_view_video_scrub | 25 crit (≥15% views gone) / 12 warn (≥3%) / 0 (<3%) | scaled by view-share |
+| B_unlisted_with_traffic | 15 | warning |
+
+### Group C — `comment_analyzer.py`
+| code | penalty | severity |
+|---|---|---|
+| C_comment_scarcity | 35 | critical |
+| C_llm_not_organic | 30 | critical |
+| C_language_mismatch | 20 | critical |
+| C_generic_templates | 18 | warning |
+| C_bot_usernames | 15 | warning |
+| C_near_duplicates | 15 | warning |
+| C_length_uniform | 12 | warning |
+| C_commenter_churn | 12 | warning |
+| C_emoji_only | 10 | info |
+| C_low_reply_ratio | 8 | info |
+| C_sentiment_uniform | 8 | info |
+| C_time_clustered | 8 | info |
+
+`C_bot_usernames` is **conditional**: the auto-generated-handle share is always
+recorded as a metric, but the −15 only applies in the LLM step when organic
+share is also low (< 55%). YouTube's own default handles are letters+digits,
+so on a healthy-organic channel a high share is noise — it fires only as
+corroboration when the audience is independently suspect.
+
+Penalties intentionally let two criticals in a group drive it near zero — a
+channel with two independent strong fraud signals in one dimension should not
+score "mixed". Tune here as cases accumulate; record the reasoning in the
+commit message.
+
+## Reference result
+
+Origin fraud case (AI/coding channel): A=0, B=15, C=27 → **14.0 FRAUD_LIKELY**.