thoughtleaders-cli 0.7.9__tar.gz → 0.7.11__tar.gz

{thoughtleaders_cli-0.7.9 → thoughtleaders_cli-0.7.11}/.claude-plugin/plugin.json

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

{thoughtleaders_cli-0.7.9 → thoughtleaders_cli-0.7.11}/AGENTS.md

@@ -53,7 +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-import`**, **`tl-save-report`**, **`adapt-tl-data`**, **`tl-views-guarantee`**, **`tl-top-partnerships`** — narrower workflows; the skill files document their own triggers. `tl-top-partnerships` is brand-user-facing: ranks a brand's sold sponsorships by live eCPM vs the sold-date projection and delivers a two-tab Google Sheet via `gws`.
+- **`tl-save-report`**, **`adapt-tl-data`**, **`tl-views-guarantee`**, **`tl-top-partnerships`** — narrower workflows; the skill files document their own triggers. `tl-top-partnerships` is brand-user-facing: ranks a brand's sold sponsorships by live eCPM vs the sold-date projection and delivers a two-tab Google Sheet via `gws`.
 
 ### Skill content boundaries
 

{thoughtleaders_cli-0.7.9 → thoughtleaders_cli-0.7.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thoughtleaders-cli
-Version: 0.7.9
+Version: 0.7.11
 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
@@ -280,8 +280,6 @@ The plugin ships several focused skills (installed by all the `tl setup *` comma
 - **`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-keyword-research`** — broadens and ranks content-search keywords by Elasticsearch document count before a `tl db es` content search, so finding videos or channels by topic isn't bottlenecked on hand-guessed terms.
 - **`tl-save-report`** — persists the result set from an in-chat exploration session as a saved TL report ("save this as a report", "turn this into a campaign").
-- **`tl-report-builder`** — builds a brand-new TL report config from scratch (channels / brands / sponsorships / videos) through a guided multi-phase flow. Manual-invocation-only: reach it via `/tl-report-builder` or by naming it explicitly — natural-language report requests route to `tl`, `tl-save-report`, or `tl-import` instead.
-- **`tl-import`** / **`bulk-import`** — superuser-only; bulk-add or exclude lists of channels, brands, videos, or sponsorships against a report.
 - **`tl-channel-authenticity`** — vets a YouTube channel for non-organic views and bot/spam comments before booking (or after delivering) a sponsorship.
 - **`tl-views-guarantee`** — sizes a multi-video sponsorship buy for a channel, returning the video bundle size, views guarantee, and likelihood to hit.
 - **`tl-top-partnerships`** — brand-user performance report. Ranks a brand's sold sponsorships by live eCPM vs the sold-date projection, aggregates per channel, and delivers a two-tab Google Sheet ("By Deal" / "By Channel") via `gws`. Uses only public CLI commands (`tl whoami`, `tl sponsorships list`).

{thoughtleaders_cli-0.7.9 → thoughtleaders_cli-0.7.11}/README.md

@@ -252,8 +252,6 @@ The plugin ships several focused skills (installed by all the `tl setup *` comma
 - **`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-keyword-research`** — broadens and ranks content-search keywords by Elasticsearch document count before a `tl db es` content search, so finding videos or channels by topic isn't bottlenecked on hand-guessed terms.
 - **`tl-save-report`** — persists the result set from an in-chat exploration session as a saved TL report ("save this as a report", "turn this into a campaign").
-- **`tl-report-builder`** — builds a brand-new TL report config from scratch (channels / brands / sponsorships / videos) through a guided multi-phase flow. Manual-invocation-only: reach it via `/tl-report-builder` or by naming it explicitly — natural-language report requests route to `tl`, `tl-save-report`, or `tl-import` instead.
-- **`tl-import`** / **`bulk-import`** — superuser-only; bulk-add or exclude lists of channels, brands, videos, or sponsorships against a report.
 - **`tl-channel-authenticity`** — vets a YouTube channel for non-organic views and bot/spam comments before booking (or after delivering) a sponsorship.
 - **`tl-views-guarantee`** — sizes a multi-video sponsorship buy for a channel, returning the video bundle size, views guarantee, and likelihood to hit.
 - **`tl-top-partnerships`** — brand-user performance report. Ranks a brand's sold sponsorships by live eCPM vs the sold-date projection, aggregates per channel, and delivers a two-tab Google Sheet ("By Deal" / "By Channel") via `gws`. Uses only public CLI commands (`tl whoami`, `tl sponsorships list`).

{thoughtleaders_cli-0.7.9 → thoughtleaders_cli-0.7.11}/pyproject.toml

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

{thoughtleaders_cli-0.7.9 → thoughtleaders_cli-0.7.11}/skills/tl/SKILL.md

@@ -9,7 +9,7 @@ description: |
 
 ## Core Principles
 
-Run the `tl` CLI to query ThoughtLeaders' sponsorship platform data. Use it to answer questions about deals, channels, brands, uploads, metrics, etc. Use raw database queries via `tl db pg|fb|es` for everything.
+Run the `tl` CLI to query ThoughtLeaders' sponsorship platform data. Use it to answer questions about deals, channels, brands, uploads, metrics, etc. Use raw database queries via `tl db pg|fb|es` for everything. One exception: resolving a named channel or brand (name, YouTube URL, @handle, video URL) to an ID is always `tl channels find` / `tl brands find` — never `ILIKE` on names.
 
 If doing a database query, follow this recipe:
 
@@ -25,13 +25,13 @@ If doing a database query, follow this recipe:
   ```bash
   tl db pg "SELECT id, weighted_price FROM thoughtleaders_adlink
             WHERE publish_status = 3 AND price > 5000
-            LIMIT 500 OFFSET 0" --json \
+            LIMIT 10000 OFFSET 0" --json \
     | jq '.results[] | {id, price: .weighted_price}'
   ```
 - **`yq`** — same idea for YAML/TOML, useful when reading config files or `--md` blocks.
 - **`rg`** — fast text search across CLI output, transcripts, and the codebase. Better than `grep` for searching large `--csv` exports or transcript dumps from ES.
   ```bash
-  tl db es '{"size":500,"query":{"term":{"channel.id":5607}},"_source":["id","transcript"]}' --json | rg -o "NordVPN[^.]*"
+  tl db es '{"size":10000,"query":{"term":{"channel.id":5607}},"_source":["id","transcript"]}' --json | rg -o "NordVPN[^.]*"
   ```
 - **`duckdb`** — embedded analytical SQL over CSV/JSON files. Use when you need joins, aggregations, or window functions across multiple `tl` exports without spinning up a database.
   ```bash
@@ -42,13 +42,13 @@ If doing a database query, follow this recipe:
             JOIN thoughtleaders_brand b ON b.id = pb.brand_id
             WHERE al.publish_status = 3
               AND al.purchase_date >= '2026-01-01'
-            LIMIT 500 OFFSET 0" --csv > deals.csv
+            LIMIT 10000 OFFSET 0" --csv > deals.csv
   duckdb -c "SELECT brand, SUM(price) AS revenue FROM 'deals.csv' GROUP BY brand ORDER BY revenue DESC LIMIT 10"
   ```
 
 The pattern is always: server-side narrowing first (usually by filters in the `tl db` query, but could be from similarity / recommender searches), then shell tool to shape the result, then read only the final summary into context. If `tl doctor` reports any of these as missing, ask the user to install them.
 
-Always assume there will be more than 1 page of results. You MUST always pass `LIMIT` and `OFFSET` to every `tl db pg|fb|es` query (and use the response envelope's `next_offset` / breadcrumbs to walk forward) so the entire data set is retrieved. The maximum number of rows per page is present in the output of `whoami`.
+Always assume there will be more than 1 page of results. You MUST always pass `LIMIT` and `OFFSET` to every `tl db pg|fb|es` query (and use the response envelope's `next_offset` / breadcrumbs to walk forward) so the entire data set is retrieved. Prefer large pages (up to the engine's cap) to minimize round-trips; the per-engine page-size caps are documented in each engine's schema reference under `references/`.
 
 **Counts, totals, and breakdowns: aggregate in the query engine — never page through records to count them.** A "how many / total / average / per-X" question is ONE aggregation query, not N pages of rows summed in your head:
 - `tl db pg` — `SELECT COUNT(*) …`, or `SELECT col, COUNT(*) AS n … GROUP BY col ORDER BY n DESC`. Also `SUM`/`AVG`/`MIN`/`MAX`/`date_trunc`. Returns one/few rows regardless of table size. (`LIMIT`/`OFFSET` still required — an aggregate is one row, so `LIMIT 1 OFFSET 0` is fine.)
@@ -95,7 +95,8 @@ Other key concepts:
 - **MBN** (Media Buying Network) — the brand-side counterpart to MSN: brand profiles that have opted in to receive proposed sponsorships. A profile is in the MBN group if the `profile.media_buying_network_join_date` field is not null.
 - **TPP** (ThoughtLeaders Partner Program, a.k.a. "TL channels") — the ~170 channels TL has the closest working relationship with. A channel is in the TPP group if `channel.is_tl_channel` is True. **Prefer TPP channels when booking**: they respond fastest, are the easiest to close, and don't need an outreach round-trip — treat them as immediately bookable. TPP is a strict subset of MSN, so the same booking rules (one active mention adspot, etc.) apply.
 - **`demographics_updated_at`** (on channels) — If non-null, the channel has demographics screenshots on file. If null, no demographics screenshots have been uploaded. Use this to check whether a channel has demographics data from screenshots.
-- **`impression`** (on channels) — projected views per video on that channel. Forward-looking estimate. May be null when not yet computed.
+- **`reach`** (on channels) — subscriber count. ⚠️ Despite the name, this is NOT ad-industry "reach" (unique audience exposed). There is no `subscribers` field — `reach` is it.
+- **`impression`** (on channels) — projected views per video on that channel. Forward-looking estimate. May be null when not yet computed. ⚠️ NOT actual views and NOT ad-industry "impressions" (ads served).
 - **`views`** (on sponsorships) — actual view count of the sold and published sponsored video, accessible when `article_id` is set.
 - **`impressions_guarantee`** (on sponsorships) — projected/guaranteed impressions for the sponsorship. Numeric.
 - **Sponsorship detail fields** (returned by `tl sponsorships show <id> --json`) — the detail payload includes `integration` (raw int), `publish_count`, `common_name`, `outreach_email`, nested `publisher` (`first_name`, `last_name`, `email`), nested `brand_contact` (`first_name`, `last_name`, `email`), and `brand.organization_name`. Use these when generating IOs, contracts, or outreach.
@@ -147,7 +148,7 @@ Unless the user specifically asks for running a specific report or showing the r
 
 1. **Discover first**: Use `tl schema pg`, `tl schema es`, and `tl schema fb` to find information about the main database (pg), the articles / uploads database (es), and the channel metrics database (fb).
 2. **Check credits**: Run `tl balance --json` before expensive queries. Warn the user if a query will cost many credits.
-3. **Decide the method of discovery**: If the user want to explore certain topics, use the recommender commands. If it's more about filtering, construct a query for PG or ES.
+3. **Decide the method of discovery**: If the user named a specific channel, brand, or creator (a name, YouTube URL, @handle, or video URL), resolve it to an ID with `tl channels find` / `tl brands find` before anything else. If the user wants to explore certain topics, use the recommender commands. If it's more about filtering, construct a query for PG or ES.
 4. **Always use --json**: Parse JSON output for multi-step analysis.
 5. **Chain commands**: For complex questions, chain multiple `tl` commands, shell commands, and other tools.
 6. **Format results**: When the user asks for a list or tabular data, present the results as a well-formatted markdown table. Pick the most relevant columns and use clear headers. Sort the result by relevant criteria - if the user asked for "top performers", order by the performance metric; if the user asked for "most recent", sort by the pertinent date desc.
@@ -445,7 +446,7 @@ If unsure about what information to find where, read the [references/postgresql-
 | Pre-insert validation queries (joining `adspot ↔ channel ↔ profile ↔ org` to confirm MSN, integration=1, persona, plan) | **Available** via `tl db pg`. | One SELECT joining the four tables. Use `thoughtleaders_channel.media_selling_network_join_date IS NOT NULL` for MSN, `thoughtleaders_adspot.integration = 1` for mention adspots, `thoughtleaders_profile.persona` for the persona code (see persona constants in `references/postgres-schema.md`). |
 | Firebolt cross-table or join queries; filtering on non-indexed columns in WHERE | **Unavailable** — not accepted. | Fetch a wider slice keyed on `channel_id` (and optionally `id`), filter the rest in `jq`/Python. |
 | ES `query_string`, `regexp`, `wildcard`, `fuzzy`, `more_like_this`, parent/child joins; any `script_*`; multiple aggregations in one body | **Unavailable** — not accepted. | Rewrite using `term`/`terms`/`match`/`bool`/`nested`. For multi-agg dashboards, run multiple `tl db es` calls and combine client-side. For "similar"-style queries, try `tl channels similar` / `tl brands similar` (server-implemented similarity search). |
-| ES deep pagination beyond `from+size = 10,000` | **Unavailable** via raw — `scroll` and `pit` aren't allowlisted; `search_after` is allowed but `from` is still capped. | Use `search_after` with `sort` to walk past 10k. For huge sweeps, narrow with `publication_date` ranges. |
+| ES deep pagination beyond `from+size = 10,000` | **Unavailable** — `scroll`, `pit`, and `search_after` aren't allowlisted; hits past the first 10,000 of a query are unreachable. | A single `size: 10000` page covers everything reachable. For bigger sweeps, slice into `publication_date` range windows of <10k hits each. |
 | ES index introspection (`_cat/indices`, mappings) | **Unavailable** — only `_search` is wired. | Read [references/elasticsearch-schema.md](references/elasticsearch-schema.md). It's manually maintained — update it when you discover new fields. |
 | Schema introspection on Postgres (`information_schema.columns`, `pg_class`, …) | **Partial** — catalog-resolving casts and many `pg_*` helpers are blocked. | Use `tl schema pg` for the live table/column listing, or read [references/postgres-schema.md](references/postgres-schema.md). |
 
@@ -485,7 +486,7 @@ tl channels find "MrBeast"
 tl brands find "NordVPN"
 ```
 
-If finding channels and brands fail, try variation on the name with or without whitespace.
+`tl channels find` resolves spacing/typo variants on its own ("Deco Destiny" → "DecoDestiny") via YouTube lookups and fuzzy similarity matching — no need to retry with hand-made name variations. A real channel that isn't in the index yet gets queued for analysis automatically (the response says to check back in ~24 hours). A plain "Not found" means even YouTube couldn't find it — treat that as the answer.
 
 **Path 2. Curated tag / category / demographic** — user named a topic that maps cleanly to a recommender tag (`"Cooking"`, `"Tech"`, `"USA share"`, content categories, format hints). Use the recommender — it ranks channels by how strongly they load on a tag, returning ranked similarity scores instead of forcing exact equality. It also returns matching brand profiles alongside the channels — useful when the user wants to know "who buys this kind of inventory."
 
@@ -559,7 +560,7 @@ For per-country share beyond the recommender's "USA share" tag, use the `demogra
 
 **MSN status (`media_selling_network_join_date`) is scrubbed from the advertiser sandbox view.** Raw SQL can't filter on it from an advertiser context. For MSN-only / non-MSN lookups, run the same raw SQL with `media_selling_network_join_date IS [NOT] NULL` from a context that has access to it (full-access role), or rely on the recommender's MSN-aware filters: `tl recommender top-channels "<tag>" msn:yes|no|all`.
 
-**Anti-pattern: defaulting to `ILIKE` on `channel_name` for off-tag topic queries.** If the question is "channels about X" where X is a topic / concept / niche (not a literal substring you expect in channel names), reach for path 3 (`tl-keyword-research`), not `WHERE channel_name ILIKE '%X%'`. Channel-name `ILIKE` misses channels whose name doesn't literally contain X but whose content does; the keyword-research skill catches them via `title` / `summary` / `transcript`. Use `channel_name ILIKE` only when you actually expect the channel's name to contain the term (e.g. `"Crypto"` in `"My Happy Crypto"`) as a supplementary signal alongside path 3, not as a replacement for it.
+**Anti-pattern: defaulting to `ILIKE` on `channel_name` for off-tag topic queries.** If the question is "channels about X" where X is a topic / concept / niche (not a literal substring you expect in channel names), reach for path 3 (`tl-keyword-research`), not `WHERE channel_name ILIKE '%X%'`. Channel-name `ILIKE` misses channels whose name doesn't literally contain X but whose content does; the keyword-research skill catches them via `title` / `summary` / `transcript`. Use `channel_name ILIKE` only when you actually expect the channel's name to contain the term (e.g. `"Crypto"` in `"My Happy Crypto"`) as a supplementary signal alongside path 3, not as a replacement for it. And for a *named entity* — a specific creator or channel — don't start with `ILIKE` at all: run `tl channels find "<name>"` first (path 1). Fall back to `ILIKE` name variations only if the resolver finds nothing, and treat a clean "Not found" from the resolver as the likely answer (the channel probably isn't in the index) rather than a cue for ever-broader scans.
 
 ### Output flags
 - `--json` — structured JSON output format (use this for parsing)
@@ -617,7 +618,7 @@ tl db pg "SELECT al.id, al.weighted_price, al.purchase_date, b.name AS brand
           WHERE al.publish_status = 3
             AND al.purchase_date >= '2026-01-01'
           ORDER BY al.purchase_date DESC
-          LIMIT 500 OFFSET 0" --json
+          LIMIT 10000 OFFSET 0" --json
 ```
 
 ### Brand sponsorship history — what channels does Nike sponsor?
@@ -769,7 +770,7 @@ tl db pg "SELECT al.id, c.channel_name, c.demographic_device_primary, c.demograp
           WHERE al.publish_status = 3
             AND c.demographic_device_primary = 'mobile'
             AND c.demographic_usa_share >= 60
-          LIMIT 500 OFFSET 0" --json
+          LIMIT 10000 OFFSET 0" --json
 ```
 
 ### "Find channels similar to one I know" (similarity recommender):

{thoughtleaders_cli-0.7.9 → thoughtleaders_cli-0.7.11}/skills/tl/references/elasticsearch-schema.md

@@ -21,19 +21,19 @@ Output flags: `--json`, `--csv`, `--md`, `--toon`. The CLI flattens hits into ro
 
 See the output of `tl db es`" for the object schema. Highlights:
 
-- **Top-level keys** accepted: `query`, `aggs`/`aggregations`, `sort`, `_source`, `size`, `from`, `track_total_hits`, `highlight`, `fields`, `min_score`, `search_after`, `timeout`, `collapse`, `post_filter`. Anything else (incl. `scroll`, `pit`, `runtime_mappings`, `knn`) is not accepted.
-- `size` ≤ 500. `from + size` ≤ 10,000. Use `search_after` to page deeper.
+- **Top-level keys** accepted: `query`, `aggs`/`aggregations`, `sort`, `_source`, `size`, `from`, `track_total_hits`, `highlight`, `fields`, `min_score`, `timeout`, `collapse`, `post_filter`. Anything else (incl. `scroll`, `pit`, `search_after`, `runtime_mappings`, `knn`) is not accepted.
+- `size` ≤ 10,000. `from + size` ≤ 10,000 — hits beyond the first 10,000 of a query are unreachable; narrow the query (e.g. `publication_date` ranges) instead of paging deeper.
 - **Accepted query types** include `term`/`terms`/`match`/`bool`/`nested`/`range`/`exists`/`match_phrase`. `query_string`, `regexp`, `wildcard`, `fuzzy`, `more_like_this`, `has_child`, `has_parent`, `parent_id` are not accepted.
 - **No scripts** — any key whose name contains `script` is not accepted.
 - **At most one aggregation total** counted recursively (top-level + sub-agg = 2 = not accepted). Run multiple calls for multi-metric work.
 
 ### ElasticSearch document structure ("articles")
 
-The `doc_type.name` field in ES objects determins between records for video uploads and for channel data.
+The `doc_type` join field distinguishes video uploads ("articles") from channel data — channel docs are parents, article docs are their children. Filter with `{"term": {"doc_type": "article"}}` or `{"term": {"doc_type": "channel"}}`. ⚠️ Term-querying `doc_type.name` matches nothing — even though article docs' `_source` shows `doc_type` as an object with a `name` key, that's join-field syntax, not a queryable subfield.
 
 #### Upload/video Fields (selected — 73 total)
 
-Distinguished by `doc_type.name="article"`.
+Filter with `{"term": {"doc_type": "article"}}`.
 
 | Field | Type | Description |
 |-------|------|-------------|
@@ -80,7 +80,7 @@ Distinguished by `doc_type.name="article"`.
 
 #### Channel Fields
 
-Distinguished by `doc_type.name="channel"`.
+Filter with `{"term": {"doc_type": "channel"}}`.
 
 Contains a denormalized subset of the PostgreSQL channel data.
 
@@ -90,10 +90,10 @@ Contains a denormalized subset of the PostgreSQL channel data.
 |-------|------|-------------|
 | `name` | text | Channel name |
 | `channel` | object | Channel metadata (nested on article docs) |
-| `reach` | long | Subscriber count |
-| `impression` | long | View count |
-| `impression_live` | long | Live view count |
-| `impression_shorts` | long | Shorts view count |
+| `reach` | long | Subscriber count. ⚠️ NOT ad-industry "reach" (unique audience exposed) — this is the channel's subscriber count. |
+| `impression` | long | Projected views per longform video — forward-looking estimate. ⚠️ NOT actual views and NOT ad-industry "impressions"; for actual views see `total_views` / the video docs. |
+| `impression_live` | long | Projected views per live stream (forward-looking estimate) |
+| `impression_shorts` | long | Projected views per short (forward-looking estimate) |
 | `is_tl_channel` | boolean | TPP partner channel |
 | `is_active` | boolean | Channel is active |
 | `media_selling_network_join_date` | date | MSN join date |
@@ -215,25 +215,25 @@ tl db es '{
 
 For more dimensions, run multiple `tl db es` calls and join client-side.
 
-### Deep pagination via `search_after`
+### Deep sweeps — window by date, don't page past 10k
 
-```bash
-# First page — sort must include a tiebreaker on _id for stability
-tl db es '{
-  "size": 500,
-  "query": {"term": {"channel.id": 12345}},
-  "sort": [{"publication_date": "desc"}, {"_id": "asc"}]
-}'
+`from + size` is capped at 10,000 and cursor keys (`search_after`, `scroll`, `pit`) are not accepted, so hits beyond the first 10,000 of any one query are unreachable. For result sets bigger than that, slice the query into non-overlapping `publication_date` (or other range-field) windows, each under 10,000 hits, and sweep window by window:
 
-# Subsequent pages — pass the last hit's sort values as search_after
+```bash
+# One window — repeat with shifted date ranges until the full period is covered
 tl db es '{
-  "size": 500,
-  "query": {"term": {"channel.id": 12345}},
-  "sort": [{"publication_date": "desc"}, {"_id": "asc"}],
-  "search_after": ["2025-09-14", "12345:abc123"]
+  "size": 10000,
+  "track_total_hits": true,
+  "query": {"bool": {"filter": [
+    {"term": {"channel.id": 12345}},
+    {"range": {"publication_date": {"gte": "2025-01-01", "lt": "2025-04-01"}}}
+  ]}},
+  "sort": [{"publication_date": "asc"}]
 }'
 ```
 
+Check `total` per window — if a window exceeds 10,000, split it further.
+
 ## Text analyzer behavior
 
 `text` fields on article docs (`title`, `summary`, `transcript`) appear to use the `standard` analyzer (tokenize + lowercase, no stemmer, no English-possessive filter), so inflections, plurals, and possessives are each indexed as distinct terms. For example: `bitcoin` (4,466,300) vs `bitcoins` (489,262). For stemming-style recall, expand the query side with a `bool.should` over the variants.

{thoughtleaders_cli-0.7.9 → thoughtleaders_cli-0.7.11}/skills/tl/references/firebolt-schema.md

@@ -130,7 +130,7 @@ tl db pg "SELECT al.id, al.article_id, s.channel_id
           WHERE al.publish_status = 3
             AND b.name = 'Nike'
             AND al.article_id IS NOT NULL
-          LIMIT 500 OFFSET 0" --json \
+          LIMIT 10000 OFFSET 0" --json \
   | jq -r '.results[] | "\(.channel_id):\(.article_id)"'
 
 # Or videos via Elasticsearch content search

{thoughtleaders_cli-0.7.9 → thoughtleaders_cli-0.7.11}/skills/tl/references/postgres-schema.md

@@ -315,7 +315,7 @@ FROM thoughtleaders_adlink
 WHERE publish_status = 3
   AND purchase_date >= date_trunc('month', CURRENT_DATE)
 ORDER BY purchase_date DESC
-LIMIT 500 OFFSET 0
+LIMIT 10000 OFFSET 0
 ```
 
 **MSN channel joins this month:**
@@ -324,7 +324,7 @@ SELECT id, channel_name, media_selling_network_join_date
 FROM thoughtleaders_channel
 WHERE media_selling_network_join_date >= date_trunc('month', CURRENT_DATE)
 ORDER BY media_selling_network_join_date DESC
-LIMIT 500 OFFSET 0
+LIMIT 10000 OFFSET 0
 ```
 
 **A specific sponsorship info with brand and channel name:**

{thoughtleaders_cli-0.7.9 → thoughtleaders_cli-0.7.11}/skills/tl-save-report/SKILL.md

@@ -56,7 +56,7 @@ The entity being saved must be one of: **channels**, **brands**, **videos / uplo
 
 **Skip when**:
 
-- The user wants to **add to an existing report** (`"add these channels to report 1234"`) → hand off to `tl-import`.
+- The user wants to **add to an existing report** (`"add these channels to report 1234"`) → use the `tl bulk-import` command, not this skill.
 - The user only wants the data **shown / counted / analysed in chat** without saving → stay in `tl`; don't invoke this skill.
 - The user wants to build a report **from scratch** with no prior session exploration to capture — that's a different shape of request (the user has a goal, not a result set). Run the appropriate `tl db pg|fb|es` queries to produce a result set first; then this skill takes over for the save.
 
@@ -524,4 +524,4 @@ The above maps the visible CLI output to the underlying cause — match on a sub
 
 - **No discovery-side work** — no keyword research, no live-data sample validation, no result-set re-evaluation. The session already produced the data; re-running discovery would be wasted effort. Name resolution (`tl brands find` / `tl channels find` to turn names into IDs before they land in the FilterSet) is the one exception — it's required by the FilterSet schema, not discovery. If the user comes in with no prior session, run the relevant `tl db pg|fb|es` queries first to produce a result set, then invoke this skill on the result.
 - **No editing of existing reports.** If the user wants to refine an already-saved report's columns, widgets, title, or description, run `tl reports update <id>` directly. For FilterSet refinements, the platform requires saving a new variant.
-- **No bulk-importing into an existing report.** That's `tl-import`'s role. Save-report only creates new reports.
+- **No bulk-importing into an existing report.** Use the `tl bulk-import` command for that. Save-report only creates new reports.

{thoughtleaders_cli-0.7.9 → thoughtleaders_cli-0.7.11}/src/tl_cli/__init__.py

@@ -1,3 +1,3 @@
 """ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligence."""
 
-__version__ = "0.7.9"
+__version__ = "0.7.11"

{thoughtleaders_cli-0.7.9 → thoughtleaders_cli-0.7.11}/src/tl_cli/commands/channels.py

@@ -296,7 +296,9 @@ def find_cmd(
     """Resolve a string to a single channel.
 
     Accepts:
-      - A partial channel name or slug (ILIKE match)
+      - A partial channel name or slug (substring match, falling back to
+        fuzzy similarity — spacing/typo variants like "Deco Destiny" still
+        resolve a channel named "DecoDestiny")
       - A YouTube channel URL (https://youtube.com/channel/UC...,
         https://youtube.com/@handle, /c/<name>, /user/<name>)
       - A raw YouTube channel ID (UC...) or @handle
@@ -308,8 +310,9 @@ def find_cmd(
     `{"id": ..., "name": ...}`).
 
     Ambiguous matches return an error with candidate IDs and names.
-    If the input is a YouTube URL and no channel matches, the URL is
-    queued for scraping; retry the command later.
+    If the input is a YouTube URL — or a name that YouTube resolves to
+    a channel not yet in the index — it is queued for analysis; check
+    back in about 24 hours.
 
     Examples:
         tl channels find "MrBeast"

{thoughtleaders_cli-0.7.9 → thoughtleaders_cli-0.7.11}/src/tl_cli/commands/reports.py

@@ -404,8 +404,8 @@ def create_report(
 
     With --config '<json>' or --config-file <path>, skips the orchestration
     pipeline and saves the provided config directly. Useful when an external
-    agent (e.g. the tl-report-builder Claude Code skill) has already produced a
-    validated config and you just want to persist it. Prefer --config-file when
+    agent has already produced a validated config and you just want to persist
+    it. Prefer --config-file when
     the config might contain apostrophes, dollar signs, or backticks — file
     transport sidesteps shell quoting entirely.
 
@@ -518,8 +518,7 @@ ENTITY_TO_REPORT_TYPE = {
 
 # FilterSet M2M field per entity is identical to the entity name, except
 # article IDs are composite strings (`<channel_id>:<youtube_id>`) and the
-# others are integers. See the FilterSet schema references in
-# skills/tl-report-builder/references/ for the catalogue.
+# others are integers.
 
 
 def _read_ids(path: str, entity: str) -> list:

{thoughtleaders_cli-0.7.9 → thoughtleaders_cli-0.7.11}/src/tl_cli/commands/setup.py

@@ -7,9 +7,12 @@ whenever either `gemini` or `codex` is on PATH. Behaviour follows the
 OpenCode pattern (full per-skill tree copy, .tl-version stamp).
 """
 
+import filecmp
 import json
+import os
 import shutil
 import subprocess
+import sys
 from pathlib import Path
 
 import typer
@@ -41,6 +44,19 @@ OPENCODE_SKILLS_DIR = Path.home() / ".config" / "opencode" / "skills"
 AGENTS_SKILLS_DIR = Path.home() / ".agents" / "skills"
 AGENTS_SKILLS_BINARIES = ("gemini", "codex")
 
+# Personal-command shim that keeps the short `/tl` invocation working when the
+# skills are provided (namespaced) by the installed plugin. Plugin skills and
+# commands are always invoked as `/tl-cli:<name>`; this one-file pointer in
+# ~/.claude/commands/ restores plain `/tl` without duplicating any skill
+# content, so plugin updates flow through automatically.
+TL_COMMAND_SHIM = """\
+---
+description: ThoughtLeaders data analyst — shortcut for the tl-cli plugin's tl skill
+---
+
+Invoke the `tl-cli:tl` skill with this request: $ARGUMENTS
+"""
+
 
 def _find_plugin_root() -> Path | None:
     """Locate the plugin assets directory.
@@ -61,8 +77,31 @@ def _find_plugin_root() -> Path | None:
 
 
 def _find_claude_binary() -> str | None:
-    """Find the claude binary on PATH."""
-    return shutil.which("claude")
+    """Find the claude binary on PATH, falling back to known install locations.
+
+    On Windows the Claude Code installers often don't end up on the PATH of
+    the shell running `tl` (stale PATH, PowerShell-only profile changes), so
+    after `shutil.which` we probe the documented install targets directly:
+    the native installer (`~/.local/bin`) and the npm global prefix.
+    """
+    found = shutil.which("claude")
+    if found:
+        return found
+    home = Path.home()
+    if sys.platform == "win32":
+        candidates = [
+            home / ".local" / "bin" / "claude.exe",
+            Path(os.environ.get("APPDATA", str(home / "AppData" / "Roaming"))) / "npm" / "claude.cmd",
+        ]
+    else:
+        candidates = [
+            home / ".local" / "bin" / "claude",
+            home / ".claude" / "local" / "claude",
+        ]
+    for candidate in candidates:
+        if candidate.is_file():
+            return str(candidate)
+    return None
 
 
 def _run_claude(args: list[str], claude_bin: str) -> tuple[bool, str]:
@@ -156,6 +195,50 @@ def _install_standalone_skills(plugin_root: Path) -> int:
     return count
 
 
+def _install_command_shim() -> Path:
+    """Write the `/tl` shim command to ~/.claude/commands/tl.md."""
+    CLAUDE_COMMANDS_DIR.mkdir(parents=True, exist_ok=True)
+    dst = CLAUDE_COMMANDS_DIR / "tl.md"
+    dst.write_text(TL_COMMAND_SHIM, encoding="utf-8")
+    return dst
+
+
+def _trees_identical(a: Path, b: Path) -> bool:
+    """True if two directory trees contain the same files with the same contents."""
+    a_files = sorted(p.relative_to(a) for p in a.rglob("*") if p.is_file())
+    b_files = sorted(p.relative_to(b) for p in b.rglob("*") if p.is_file())
+    if a_files != b_files:
+        return False
+    return all(filecmp.cmp(a / rel, b / rel, shallow=False) for rel in a_files)
+
+
+def _remove_matching_standalone_skills(plugin_root: Path) -> tuple[int, int]:
+    """Remove standalone copies in ~/.claude/skills/ that match the plugin's skills.
+
+    Earlier versions of `tl setup claude` copied every bundled skill into
+    ~/.claude/skills/. Now that the plugin provides them, those copies are
+    redundant — but a copy is only deleted when its tree is byte-identical
+    to the bundled skill, so user-modified copies are never touched.
+    Returns (removed, kept_modified).
+    """
+    removed = kept = 0
+    skills_src = plugin_root / "skills"
+    if not skills_src.is_dir():
+        return removed, kept
+    for skill_dir in skills_src.iterdir():
+        if not (skill_dir.is_dir() and (skill_dir / "SKILL.md").is_file()):
+            continue
+        standalone = CLAUDE_SKILLS_DIR / skill_dir.name
+        if not standalone.is_dir():
+            continue
+        if _trees_identical(skill_dir, standalone):
+            shutil.rmtree(standalone)
+            removed += 1
+        else:
+            kept += 1
+    return removed, kept
+
+
 def _bundled_skill_blurbs(plugin_root: Path) -> list[tuple[str, str]]:
     """Read (name, tl-blurb) for each bundled skill, for the setup summary.
 
@@ -192,18 +275,19 @@ def _bundled_skill_blurbs(plugin_root: Path) -> list[tuple[str, str]]:
 
 
 def _print_manual_instructions() -> None:
-    """Print manual install instructions when claude binary is not found."""
+    """Print manual install instructions when the plugin couldn't be installed."""
     console.print()
-    console.print("[yellow]Claude Code binary not found on PATH.[/yellow]")
+    console.print("[yellow]The Claude Code plugin could not be installed automatically.[/yellow]")
     console.print()
-    console.print("Install Claude Code first, then run these commands inside Claude Code:")
+    console.print(f"The skills were installed to {CLAUDE_SKILLS_DIR} instead — restart")
+    console.print("Claude Code and they will be available (e.g. [cyan]/tl[/cyan]).")
+    console.print()
+    console.print("To install the full plugin, run these commands inside Claude Code:")
     console.print()
     console.print(f"  [cyan]/plugin marketplace add {MARKETPLACE_SOURCE}[/cyan]")
     console.print(f"  [cyan]/plugin install {PLUGIN_KEY}[/cyan]")
     console.print()
-    console.print("Or start Claude Code with the plugin loaded directly:")
-    console.print()
-    console.print(f"  [cyan]claude --plugin-dir /path/to/tl-cli[/cyan]")
+    console.print("then re-run [cyan]tl setup claude[/cyan] to clean up the standalone copies.")
 
 
 @app.command("claude")
@@ -214,8 +298,10 @@ def setup_claude(
     """Install the TL CLI plugin for Claude Code.
 
     Registers the ThoughtLeaders marketplace, installs the tl-cli plugin,
-    and copies skills/commands to ~/.claude/ for short /tl invocation.
-    If the claude binary is not on PATH, prints manual instructions.
+    and adds a /tl shim command so the plugin's tl skill can be invoked
+    without the plugin namespace. Standalone skill copies in ~/.claude/skills
+    are only installed as a fallback when the plugin can't be installed;
+    unmodified copies left by earlier versions are removed.
 
     Examples:
         tl setup claude
@@ -249,10 +335,9 @@ def setup_claude(
     # Check claude binary
     claude_bin = _find_claude_binary()
     if not claude_bin:
-        # Still install standalone skills even without claude binary
-        console.print("  [yellow]![/yellow] claude binary not found on PATH")
+        # Fall back to standalone skill copies when the plugin can't be installed
+        console.print("  [yellow]![/yellow] claude binary not found")
         _install_standalone_skills_step(plugin_root)
-        console.print()
         _print_manual_instructions()
         raise SystemExit(1)
 
@@ -271,6 +356,7 @@ def setup_claude(
             _run_claude(["plugin", "marketplace", "update", MARKETPLACE_NAME], claude_bin)
         else:
             console.print(f"  [red]✗[/red] Marketplace registration failed: {output}")
+            _install_standalone_skills_step(plugin_root)
             _print_manual_instructions()
             raise SystemExit(1)
 
@@ -284,12 +370,20 @@ def setup_claude(
             console.print(f"  [green]✓[/green] Plugin already installed: {PLUGIN_KEY}")
         else:
             console.print(f"  [red]✗[/red] Plugin installation failed: {output}")
-            console.print("    Try running inside Claude Code:")
-            console.print(f"    [cyan]/plugin install {PLUGIN_KEY}[/cyan]")
+            _install_standalone_skills_step(plugin_root)
+            _print_manual_instructions()
             raise SystemExit(1)
 
-    # Step 3: Install standalone skills for short /tl invocation
-    _install_standalone_skills_step(plugin_root)
+    # Step 3: /tl shim command + cleanup of standalone copies from older versions
+    console.print("[bold]Installing /tl shortcut...[/bold]")
+    shim = _install_command_shim()
+    console.print(f"  [green]✓[/green] /tl command installed: {shim}")
+    removed, kept = _remove_matching_standalone_skills(plugin_root)
+    if removed:
+        console.print(f"  [green]✓[/green] Removed {removed} standalone skill(s) now provided by the plugin")
+    if kept:
+        console.print(f"  [yellow]![/yellow] Kept {kept} modified standalone skill(s) in {CLAUDE_SKILLS_DIR}")
+        console.print("    These differ from the plugin's versions and shadow nothing — remove manually if unwanted.")
 
     # Write version stamp
     version_dir = CLAUDE_PLUGINS_DIR / "tl-cli"
@@ -303,20 +397,20 @@ def setup_claude(
     blurbs = _bundled_skill_blurbs(plugin_root)
     width = max((len(name) for name, _ in blurbs), default=0)
     for name, blurb in blurbs:
-        console.print(f"  [cyan]/{name}[/cyan]{' ' * (width - len(name))}  — {blurb}")
+        console.print(f"  [cyan]/{PLUGIN_NAME}:{name}[/cyan]{' ' * (width - len(name))}  — {blurb}")
     console.print()
-    console.print("Try it:")
+    console.print("Try it (restart Claude Code first):")
     console.print("  [cyan]/tl Which channels did we sponsor in Q1?[/cyan]")
     console.print()
     console.print("[dim]To update, run: tl setup claude[/dim]")
 
 
 def _install_standalone_skills_step(plugin_root: Path) -> None:
-    """Install standalone skills and print status."""
-    console.print("[bold]Installing skills for /tl shortcut...[/bold]")
+    """Install standalone skills (plugin-less fallback) and print status."""
+    console.print("[bold]Installing standalone skills (plugin fallback)...[/bold]")
     count = _install_standalone_skills(plugin_root)
     if count > 0:
-        console.print(f"  [green]✓[/green] Installed {count} skills/commands to ~/.claude/")
+        console.print(f"  [green]✓[/green] Installed {count} skills/commands to {CLAUDE_HOME}")
     else:
         console.print("  [yellow]![/yellow] No skills found to install")
 
@@ -362,9 +456,19 @@ def _setup_noninteractive(fmt: str = "json") -> None:
         result["marketplace_registered"] = False
         result["plugin_installed"] = False
 
-    # Always install standalone skills
-    count = _install_standalone_skills(plugin_root)
-    result["standalone_skills_installed"] = count
+    if result["plugin_installed"]:
+        # Plugin provides the skills; install the /tl shim and clean up
+        # unmodified standalone copies left by earlier versions.
+        _install_command_shim()
+        removed, kept = _remove_matching_standalone_skills(plugin_root)
+        result["command_shim_installed"] = True
+        result["standalone_skills_installed"] = 0
+        result["standalone_skills_removed"] = removed
+        result["standalone_skills_kept_modified"] = kept
+    else:
+        # Fallback: standalone skill copies so Claude Code still gets /tl
+        result["command_shim_installed"] = False
+        result["standalone_skills_installed"] = _install_standalone_skills(plugin_root)
 
     # Write version stamp
     version_dir = CLAUDE_PLUGINS_DIR / "tl-cli"