thoughtleaders-cli 0.6.44__tar.gz → 0.6.46__tar.gz

{thoughtleaders_cli-0.6.44 → thoughtleaders_cli-0.6.46}/.claude-plugin/plugin.json

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

{thoughtleaders_cli-0.6.44 → thoughtleaders_cli-0.6.46}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thoughtleaders-cli
-Version: 0.6.44
+Version: 0.6.46
 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

{thoughtleaders_cli-0.6.44 → thoughtleaders_cli-0.6.46}/pyproject.toml

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

{thoughtleaders_cli-0.6.44 → thoughtleaders_cli-0.6.46}/skills/tl/SKILL.md

@@ -1,41 +1,47 @@
 ---
 name: tl
 description: |
-  Query and analyze ThoughtLeaders business data using the `tl` CLI. Default to raw database queries via `tl db pg|fb|es` for anything non-trivial (joins, aggregations, multi-condition filters, anything that would otherwise need post-processing).  Use this skill for ANALYTICAL questions about channels, brands and sponsorships: counts, metrics, trends, time-series, distributions, single-record drill-downs, revenue / pipeline-weighting math, view-curve analysis, cross-source business questions. Examples: "How many deals did we close last quarter?", "What's the weighted pipeline by sales owner?", "Show me the view curve for video X", "Find mentions of Surfshark in transcripts", "Investigate this video".
+  Query and analyze YouTube sponsorship data using the `tl` CLI. Use this skill for data exploration and questions about channels, brands and sponsorships: counts, metrics, trends, time-series, distributions, single-record drill-downs, revenue / pipeline-weighting math, view-curve analysis, cross-source business questions. Examples: "How many deals did we close last quarter?", "What's the weighted pipeline by sales owner?", "Show me the view curve for video X", "Find mentions of Surfshark in transcripts", "Investigate this video".
 ---
 
 # ThoughtLeaders Data Analyst
 
-Run the `tl` CLI to query ThoughtLeaders' sponsorship platform data. Use it to answer questions about deals, channels, brands, uploads, metrics, etc.
-
 ## Core Principles
 
-**Default to raw database queries.** For anything beyond a trivially simple lookup, reach for `tl db pg|fb|es`. Avoid the structured `tl <resource>` commands (`sponsorships list`, `channels show`, `brands history`, etc.).
-
-Always run `tl schema pg|fb|es` before writing a raw query.
+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.
 
-**When you only need the schema of one table, you MUST call `tl schema pg <table>` (or `tl schema fb <table>`) — never the unscoped form**, to reduce token counts. ES has no per-table form (the index is a single document shape) — `tl schema es` is the only call there.
+Always run `tl schema pg|fb|es` before writing a raw query. When you only need the schema of one table, you MUST call `tl schema pg <table>` (or `tl schema fb <table>`). Avoid calling the unscoped form, to reduce token counts. ES has no per-table form (the index is a single document shape), so `tl schema es` is the only call there.
 
-**Process data with shell tools, not your context window.** Don't pull large result sets into your reasoning context just to filter, sort, count, or extract a field — that wastes tokens and slows you down. Pipe `tl … --json` (or `--csv`, or `--toon`) into `jq`, `yq`, `rg`, or `duckdb`, as appropriate, and read only the answer back. Pick the tool by shape:
+**Process data with shell tools, not your context window.** Don't pull large result sets into your reasoning context just to filter, sort, count, or extract a field - that wastes tokens and slows you down. Pipe `tl … --json` (or `--csv`, or `--toon`) into `jq`, `yq`, `rg`, or `duckdb`, as appropriate, and read only the answer back. Pick the tool by shape:
 
 - **`jq`** — filter, project, and transform JSON. The default for `tl … --json` post-processing.
   ```bash
-  tl sponsorships list status:sold --json | jq '.results[] | select(.price > 5000) | {id, brand, price}'
+  tl db pg "SELECT id, weighted_price FROM thoughtleaders_adlink
+            WHERE publish_status = 3 AND price > 5000
+            LIMIT 500 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.
+- **`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[^.]*"
   ```
 - **`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
-  tl deals list purchase-date-start:2026-01 --csv > deals.csv
+  tl db pg "SELECT al.id, b.name AS brand, al.weighted_price AS price
+            FROM thoughtleaders_adlink al
+            JOIN thoughtleaders_profile p ON p.id = al.creator_profile_id
+            JOIN thoughtleaders_profile_brands pb ON pb.profile_id = p.id
+            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
   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 (filter in the `tl db` query or the structured filters), 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 — `tl-internal setup` installs all four by default.
+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 — `tl-internal setup` installs all four by default.
 
-Always assume there will be more than 1 page of results. You MUST always use `--limit` and `--offset` options in the `tl list` commands to retrieve the entire data set (all pages, until the total records are fetched). You must also always use pagination in scripts you write to collect results. The maximum number of results per page is 500.
+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 500.
 
 Retry after 5 seconds if the server returns a "connection denied" or a "server error" on any request.
 
@@ -49,7 +55,7 @@ This section defines business terminology. Any other skill files, command, and p
 
 ThoughtLeaders is a sponsorship marketplace connecting **Brands** (advertisers / media buyers) with **Channels** (YouTube creators, podcasters / media sellers).
 
-The centre of the data model is **Sponsorships** — business relationships between brands and channels. Sponsorships have a funnel of types, from broad to narrow:
+The centre of the data model are **Sponsorships** — business relationships between brands and channels. Sponsorships statuses form a sales funnel, from broad to narrow:
 
 - **Sponsorships** — the broadest category, encompassing all stages, stored in the `thoughtleaders_adlink` table.
   - **Matches** — possible brand-channel pairings that ThoughtLeaders thinks could work
@@ -58,33 +64,33 @@ The centre of the data model is **Sponsorships** — business relationships betw
 
 Sponsorships are sometimes called "Ads" or "Ad campaigns". **"AdLink"** is another name for the same thing — it's the term the database uses (`thoughtleaders_adlink`) and shows up across internal code, schema docs, and AM Slack threads. Treat "sponsorship" and "adlink" as interchangeable; the user-facing word is "sponsorship," the engineering/DB word is "adlink."
 
-The CLI has shortcut commands for each type: `tl matches`, `tl proposals`, `tl deals`. These filter `tl sponsorships` by status.
-
 Other key concepts:
+- **Channels** — YouTube channels, but could also be podcasts
+- **Brands** — Entities (usually companies / organizations, but could be narrowed down to individual brands of a company)
 - **Uploads** — YouTube videos indexed from Elasticsearch
 - **Snapshots** — historical time-series metrics for channels and videos (Firebolt)
 - **Reports** — saved report configurations that can be re-run
-- **Comments** — notes attached to sponsorships
-- **Adspots** — types of ads a channel carries (e.g. mention, dedicated video, product placement). Returned by `tl channels show`; each carries price/cost.
-- **Profiles** — per-organization actors that own sponsorship records on behalf of either side of a deal. A profile is buyer-side or seller-side:
+- **Comments** — notes attached to sponsorships, channels, or brands
+- **Adspots** — types of ads a channel is willing to publish (e.g. mention, dedicated video, product placement). Returned by `tl channels show`; each carries price/cost.
+- **Profiles** — actors that own sponsorship records on behalf of either side of a deal. A profile is either buyer-side or seller-side:
   - *Buyer-side (brand) profiles* — represent a sponsoring brand. Each brand profile has an M2M link to at most one `Brand` record (which are the actual advertiser identities). On a sponsorship, `creator_profile` is the buyer-side profile.
   - *Seller-side (publisher) profiles* — attached to a `Publication`, which in turn owns one or more `Channel` records. A channel's adspots therefore inherit ownership through `channel.publication.profile`.
   - **How to tell them apart** — three signals on the `thoughtleaders_profile` row, used in this order:
     1. **`persona`** (canonical) — `1=Brand`, `4=Media Agency`, `3=Talent Manager` are buyer-side; `2=Creator`, `5=Creator Service` are seller-side. May be null on legacy rows.
     2. **`is_advertiser` / `is_publisher`** booleans — feature flags; either or both can be true for staff-style profiles, but on normal user profiles they reliably mark side.
   - Org scoping for sponsorships is profile-mediated: a sponsorship belongs to your org if **either** `creator_profile.organization` (brand side) **or** `ad_spot.channel.publication.profile.organization` (publisher side) matches yours.
-- **MSN** (Media Selling Network) — the ~11k YouTube channels that have opted in to receive sponsorship offers. A channels is in the MSN group if the `channel.media_selling_network_join_date` field is not null.
+- **MSN** (Media Selling Network) — the ~12k YouTube channels that have opted in to receive sponsorship offers. A channels is in the MSN group if the `channel.media_selling_network_join_date` field is not null.
 - **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 ~169 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 channel detail) — ISO timestamp of when demographic screenshots were last uploaded and processed via OCR. If non-null, the channel has demographics screenshots on file. If null, no screenshots have been uploaded. Use this to check whether a channel has demographics data from screenshots.
+- **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.
 - **`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; rounded to int in list output.
-- **Sponsorship detail fields** (returned by `tl sponsorships show <id> --json`) — in addition to the list-view columns, 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.
+- **`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.
 - **CPM** has two distinct meanings depending on level — pick the one the user actually wants:
   - **Channel CPM** = `(adspot.price / channel.impression) * 1000` — projected price per thousand projected views. Used for pricing decisions **before** a sponsorship is sold. Available for channels with active adspots via `tl channels show <channel_id>`.
   - **Sponsorship CPM** = calculated in either of two ways: if `views` is present, then CPM is `(sponsorship.price / sponsorship.views) × 1000`, meaning realized cost per thousand actual views, computed post-publication. If `views` is null, Compute from the sponsorship's `price` and the channel's `impression` fields.
-  - **CPM does not have a range filter.** To find sponsorships in a CPM range (e.g. "around $15"), fetch the record set with other filters first, then apply the CPM range in post-processing (jq, Python, etc.) on the returned `cpm` field. Plan queries and pagination accordingly — the server cannot reduce the result count based on CPM.
+  - Where possible, calculate the correct CPM in a SQL expression.
 - **Sponsorship dates** — each sponsorship has four distinct dates, useful for different queries:
   - **`created_at`** — when the sponsorship record was created in the system
   - **`purchase_date`** — when the sponsorship was purchased (i.e. when the deal was made); These make up bookings.
@@ -97,13 +103,13 @@ Users see data scoped by their organization and plan:
 - **Media sellers** see sponsorships where their org is the publisher. They see `cost` but never `price`.
 - **Intelligence plan** is required for accessing information not strictly related to the user's organisation.
 
-When querying sponsorship bookings, query by `status:sold` and filter the the date range only by `purchase_date`. Otherwise, query for state:sold by `created_at`.
+When querying sponsorship bookings, filter the rows with `publish_status = 3` (sold) and use `purchase_date` for the date range. For all-flow / not-yet-sold inclusive queries, drop the `publish_status` predicate and filter by `created_at` instead.
 
 ## Methodology
 
 Where possible, if searching for a sponsorship match between channels and brands, first search for what do similar brands sponsor / which brands is the channel usually sponsored by. The similarity judgement should be preferably based on similar topics, similar upload frequency, similar channel sizes, and only after all that, on demographics.
 
-Use the `tl channels similar` and `tl brands similar` commands to explore 1:1 similarity between known channels or brands. For category- or topic-driven discovery (e.g. "find me Cooking channels", "who scores high on USA share?"), use `tl recommender top-channels "<tag>"` (or `top-brands`/`top-profiles`) against the recommender — that's faster, ranked by category-strength. Run `tl recommender tags` to discover the valid tag names.
+Use the `tl channels similar` and `tl brands similar` commands to find channels or brands similar to a particular channel or brand. For category- or topic-driven discovery (e.g. "Find me Cooking channels", "Who scores high on USA share?"), use `tl recommender top-channels "<tag>"` (or `top-brands`/`top-profiles`) against the recommender — that's faster, ranked by category-strength. Run `tl recommender tags` to discover the valid tag names.
 
 ## Workflow
 
@@ -129,35 +135,44 @@ Notes:
 
 Unless the user specifically asks for running a specific report or showing the result of a specific report, find the data by using other, low-level commands.
 
-1. **Discover first**: Run `tl describe show <resource> --json` to learn available fields, filters, and credit costs before querying. 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 saved reports**: Run `tl reports --json` to see if the user has a saved report that already answers their question
-3. **Check credits**: Run `tl balance --json` before expensive queries. Warn the user if a query will cost many credits.
-4. **Query with filters**: Use `key:value` filter syntax for structured queries
-5. **Always use --json**: Parse JSON output for multi-step analysis.
-6. **Chain commands**: For complex questions, chain multiple `tl` commands
-7. **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.
+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.
+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. In this case, ask the user if they want to save the list as a report, and invoke the `tl-save-report` skill.
 
-Prefer writing Python code, shell code, or `jq` commands that fetche or analysise large sets of data, instead of analysing it yourself. Create temporary files in `/tmp` that can be analysed later in different ways. Before bulk data analysis by running `jq`, Python or Bash commands, first try fetching just a single result with `--limit 1` without `jq` etc, to see the shape of the data and any error messages.
+Prefer writing shell code, `jq` commands, or `duckdb` commands that fetch or analysise large sets of data instead of analysing it yourself. Create temporary files in `/tmp` that can be analysed later in different ways. Before analysing a potentially large result set, first try fetching just a single result with `LIMIT 1` without `jq` etc, to see the shape of the data and any error messages.
 
 ## Available Commands
 
-Note that if you're working on Windows, you need to set up UTF-8 in the console, because all of these commands return UTF-8 data.
+Note that if you're working on Windows, you must set up UTF-8 in the console, because all of these commands return UTF-8 data.
 
 ### Data queries
+
+**Filtered queries go through `tl db pg|fb|es`.** Write the SELECT/ES body yourself, and freely perform joins and aggregations. The show/create/update commands exist because they target a single record by ID. Where needed, write Python scripts or duckdb queries to join data from different databases.
+
+Filter-to-SQL examples (deals/matches/proposals all live on `thoughtleaders_adlink`, differentiated by `publish_status`):
+
+| Want | Raw-DB equivalent |
+| --- | --- |
+| All sponsorships matching filters | `tl db pg "SELECT … FROM thoughtleaders_adlink WHERE …"` |
+| Sold deals (`publish_status=3`) | `tl db pg "SELECT … FROM thoughtleaders_adlink WHERE publish_status = 3"` |
+| Matched (`publish_status=7`) | `tl db pg "SELECT … FROM thoughtleaders_adlink WHERE publish_status = 7"` |
+| Proposed (`publish_status=0`) | `tl db pg "SELECT … FROM thoughtleaders_adlink WHERE publish_status = 0"` |
+| Video uploads from ElasticSearch | `tl db es '{"size":N,"query":{"term":{"channel.id":<id>}}}'` |
+
+Single-record / mutation commands remain:
+
 ```bash
-tl sponsorships list [filters...]      # Sponsorships
 tl sponsorships show <id>              # Sponsorship detail
 tl sponsorships create --channel <id> --brand <id>  # Create proposal
 tl sponsorships update <id> '<json>'   # Update a sponsorship
-tl deals list [filters...]             # Shortcut: agreed-upon sponsorships (status:deal)
 tl deals show <id>                     # Deal detail
-tl matches list [filters...]           # Shortcut: possible brand-channel pairings (status:match)
 tl matches show <id>                   # Match detail
 tl matches create --channel <id> --brand <id>  # Create match
-tl proposals list [filters...]         # Shortcut: proposed matches (status:proposal)
 tl proposals show <id>                 # Proposal detail
 tl proposals create --channel <id> --brand <id>  # Create proposal
-tl uploads list [filters...]           # Video uploads from ES
 tl uploads show <id>                   # Upload detail
 tl channels show <id-or-name>          # Channel detail (accepts numeric ID or name) — for channel search use raw SQL on thoughtleaders_channel
 tl channels find <query>               # Resolve a string to {id, name}; accepts name/slug, YouTube URL/handle/ID, video URL (queues a scrape if no match)
@@ -177,7 +192,9 @@ tl recommender top-profiles "<tag>"    # Top brand profiles loaded on a similari
 tl recommender top-brands "<tag>"      # Top brands (deduped from profiles) loaded on a similarity tag
 tl recommender inspect-channel <ref>   # Show a channel's similarity-profile breakdown (Intelligence)
 tl recommender inspect-brand <ref>     # Show a brand profile's ideal similarity-profile breakdown (Intelligence)
-tl recommender similar-to-profile <id> # Channels closest to a brand profile's ideal profile (Intelligence)
+tl recommender channels-for-profile <id> # Find channels closest to a brand profile's ideal profile (Intelligence)
+tl recommender channels-for-brand <ref>  # Same as above but takes a brand ref; uses the brand's newest profile with a vector (Intelligence)
+tl recommender brands-for-channel <ref>  # Brands most likely to sponsor a channel; runs the channel's vector against the brand-profile index (Intelligence)
 tl snapshots channel <id>              # Channel metrics over time (Firebolt-backed)
 tl snapshots video <id> --channel <id> # Video view curve (--channel required!)
 tl reports                             # List saved reports
@@ -205,8 +222,6 @@ tl channels update 12345 '{"demographic_geo": {"US": 60, "UK": 12, "CA": 8}}'
 tl channels update 12345 '{"demographic_male_share": 55, "demographic_usa_share": 70}'
 ```
 
-Each call costs 2 credits. If a request is rejected with a 400, the response body names the offending key — read it and retry with a smaller body. If the user wants to edit something the API rejects, the change has to be made in the app or by a human with DB access.
-
 ### Creating and vetting sponsorships
 
 This is the end-to-end workflow for proposing a sponsorship, then moving it through the funnel as the two sides respond. Three create commands plus `tl sponsorships update` cover every state transition the CLI exposes.
@@ -306,7 +321,7 @@ Reasons to write a raw query (the common case):
 - **Multi-condition filtering** — compound boolean, `NOT IN`/`EXISTS`, `WHERE col IS NULL` on hidden fields, mixed range + enum + text predicates: write the SQL/ES body, don't over-fetch and post-filter.
 - **Fields the structured commands don't expose** — e.g. `media_selling_network_join_date` (only the `msn` boolean is surfaced), `weighted_price`, `tx_data`, raw `publish_status` integer, etc.
 
-Structured commands are still the right tool for: single-record `show` by ID, plain filtered `list` (one or two filters that the structured vocabulary already supports), saved `tl reports run`, and `tl snapshots channel|video` (these wrap interpolation logic you'd otherwise reimplement).
+Structured commands are still the right tool for: single-record `show` by ID, saved `tl reports run`, and `tl snapshots channel|video` (these wrap interpolation logic you'd otherwise reimplement). Anything that would have been a "filtered list" goes through `tl db pg|fb|es`.
 
 | Need | Use |
 |---|---|
@@ -317,8 +332,7 @@ Structured commands are still the right tool for: single-record `show` by ID, pl
 | Transcript / brand-mention search inside video content | **`tl db es`** (no structured equivalent for content text) |
 | Custom Firebolt shape (milestone-age slices, multi-channel growth comparisons) | **`tl db fb`** |
 | Single-record detail lookup by ID | `tl <resource> show <id>` |
-| Plain filtered list with one or two simple filters | `tl <resource> list` |
-| Channel/brand similarity (server-implemented similarity search) | `tl channels similar`, `tl brands similar` |
+| Channel/brand similarity (server-implemented similarity search) | `tl channels similar`, `tl brands similar`, `tl recommender ...` |
 | Saved reports | `tl reports`, `tl reports run` |
 | Time-series view-curve / channel growth (default shape with interpolation) | `tl snapshots channel`, `tl snapshots video` |
 
@@ -435,17 +449,6 @@ tl changelog since v0.4.10             # Notes from v0.4.10 to latest
 tl changelog --md > CHANGELOG.md       # Capture for a doc
 ```
 
-`tl changelog` summaries are LLM-generated server-side from full commit messages and cached per version, so repeat calls are fast and don't re-bill the LLM. The release date and a 2–4 sentence prose summary come back per version.
-
-### Filter syntax
-Structured list commands accept `key:value` filters (use them for trivially simple lookups):
-```bash
-tl sponsorships list status:sold brand:"Nike" purchase-date:2026-01
-tl uploads list channel:12345 type:longform
-```
-
-Date filters accept keywords: `today`, `yesterday`, `tomorrow`.
-
 #### Channel discovery — recommender first, raw SQL second
 
 For category- or demographic-driven discovery, **use the recommender, not `content_category` SQL.** The recommender ranks channels by how strongly they load on a category/demographic tag (similarity scores), instead of forcing exact equality on a single integer code. It also returns the matching brand profiles alongside the channels — useful when the user actually wants to know "who buys this kind of inventory."
@@ -455,7 +458,7 @@ For category- or demographic-driven discovery, **use the recommender, not `conte
 tl recommender tags cooking
 tl recommender tags "usa"
 
-# Top channels & profiles loaded on a similarity tag (25 credits; Intelligence)
+# Top channels & profiles loaded on a similarity tag (Intelligence)
 tl recommender top-channels "Cooking" msn:yes --limit 50
 tl recommender top-channels "Tech" --limit 30
 tl recommender top-brands "USA share" mbn:yes --limit 50
@@ -511,8 +514,8 @@ While analysing results, you must always examine the `results` field in the JSON
 
 Every query costs credits. Before running expensive queries:
 1. Check the credit rate: `tl describe show <resource> --json | jq '.credits'` and the user balance.
-2. **List endpoints (sponsorships/channels/uploads/snapshots/comments/reports/db) are priced non-linearly:** `cost = 1 + mult × 0.126 × n^1.2`, where `mult` is the per-resource complexity factor (1.0 for cheap reads, 1.2 for snapshots, 1.3 for reports, 1.4 for raw db). Detail/history/similar endpoints are linear (`rate × results`). See the table in the command list above.
-3. Estimate cost from the formula or the table; for non-list endpoints use `results × rate`.
+2. **Multi-row endpoints (snapshots, comments, reports, `tl db pg|fb|es`) are priced non-linearly:** `cost = 1 + mult × 0.126 × n^1.2`, where `mult` is the per-resource complexity factor (1.0 for cheap reads, 1.2 for snapshots, 1.3 for reports, 1.4 for raw db). Detail/history/similar endpoints are linear (`rate × results`).
+3. Estimate cost from the formula or the table; for non-row-priced endpoints use `results × rate`.
 4. If estimated cost is more than 10% of the remaining balance, ask the user to confirm the operation before running.
 
 ## Data Scoping
@@ -520,7 +523,7 @@ Every query costs credits. Before running expensive queries:
 Users only see data their plan allows:
 - **Media buyers** see deals where their org is the brand. They see `price` but never `cost`.
 - **Media sellers** see deals where their org is the publisher. They see `cost` but never `price`.
-- **Intelligence plan** required for `tl brands`, the full `tl recommender` surface, and full `tl uploads list`.
+- **Intelligence plan** required for `tl brands`, the full `tl recommender` surface, and `tl db es` access to full transcript / brand-mention data.
 - **Paid plan** required for `tl snapshots`.
 
 ## Important: Status Labels
@@ -535,7 +538,15 @@ When presenting sponsorship status data, always use human-readable labels — ne
 
 "Show me my sold sponsorships this quarter":
 ```bash
-tl deals list purchase-date-start:2026-01-01 --json
+tl db pg "SELECT al.id, al.weighted_price, al.purchase_date, b.name AS brand
+          FROM thoughtleaders_adlink al
+          JOIN thoughtleaders_profile p ON p.id = al.creator_profile_id
+          JOIN thoughtleaders_profile_brands pb ON pb.profile_id = p.id
+          JOIN thoughtleaders_brand b ON b.id = pb.brand_id
+          WHERE al.publish_status = 3
+            AND al.purchase_date >= '2026-01-01'
+          ORDER BY al.purchase_date DESC
+          LIMIT 500 OFFSET 0" --json
 ```
 
 "What channels does Nike sponsor?":
@@ -587,7 +598,14 @@ tl recommender top-channels "Cooking" msn:yes --limit 100 --json \
 
 "Show sold sponsorships targeting mobile US audiences":
 ```bash
-tl sponsorships list status:sold primary-device:mobile min-us-share:60 --json
+tl db pg "SELECT al.id, c.channel_name, c.demographic_device_primary, c.demographic_usa_share, al.weighted_price
+          FROM thoughtleaders_adlink al
+          JOIN thoughtleaders_adspot s ON s.id  = al.ad_spot_id
+          JOIN thoughtleaders_channel c ON c.id = s.channel_id
+          WHERE al.publish_status = 3
+            AND c.demographic_device_primary = 'mobile'
+            AND c.demographic_usa_share >= 60
+          LIMIT 500 OFFSET 0" --json
 ```
 
 "Find channels similar to one I know" (similarity recommender, 25 credits per call):
@@ -612,6 +630,23 @@ tl recommender top-brands "USA share" mbn:yes --limit 30       # Top brands (ded
 tl recommender top-channels "Tech" exclude-for-profile:842     # Drop channels already proposed for profile 842
 tl recommender inspect-channel 29834                           # Per-tag breakdown of a channel's vector
 tl recommender inspect-brand Nike                              # Per-tag breakdown of a brand's ideal profile
-tl recommender similar-to-profile 842 --limit 30               # Channels closest to a brand profile's ideal profile
+tl recommender channels-for-profile 842 --limit 30                  # Channels closest to a brand profile's ideal profile
+tl recommender channels-for-profile 842 msn:yes language:en          # Same, filtered to English MSN channels
+tl recommender channels-for-brand Nike --limit 30                    # Same, but takes a brand ref (uses the brand's newest profile with a vector)
+tl recommender channels-for-brand 6037 msn:yes language:en --limit 30
+tl recommender brands-for-channel 29834 --limit 30                   # Brands likely to sponsor this channel
+tl recommender brands-for-channel "MrBeast" mbn:yes --limit 30       # Same, restricted to MBN brand profiles
 ```
+
+**Filters on the recommender commands:**
+
+| Command | Filters |
+| --- | --- |
+| `top-channels` | `msn:<yes\|no\|all>` (default all), `exclude-for-profile:<id>` |
+| `top-profiles` | `mbn:<yes\|no\|all>` (default all), `exclude-for-channel:<id>` |
+| `top-brands` | `mbn:<yes\|no\|all>` (default all) |
+| `channels-for-profile` | `language:<iso>` (default `en`), `msn:<yes\|no>` (default `no`) |
+| `channels-for-brand` | same as `channels-for-profile` |
+| `brands-for-channel` | `mbn:<yes\|no\|all>` (default `all`) |
+
 Use `tl recommender top` for category/topic discovery (it's ranked) and `tl channels similar` / `tl brands similar` for 1:1 lookalike searches.

{thoughtleaders_cli-0.6.44 → thoughtleaders_cli-0.6.46}/skills/tl/references/firebolt-schema.md

@@ -120,9 +120,18 @@ Every Firebolt workflow has two steps:
 tl recommender top-channels "Tech" msn:yes --limit 50 --json \
   | jq '.results[].channel_id'
 
-# Or videos for a specific brand's deals (Postgres side, via tl sponsorships)
-tl deals list brand:"Nike" --json --limit 500 \
-  | jq -r '.results[] | select(.article_id != null) | "\(.channel_id):\(.article_id)"'
+# Or videos for a specific brand's deals (Postgres side, via raw SQL)
+tl db pg "SELECT al.id, al.article_id, s.channel_id
+          FROM thoughtleaders_adlink al
+          JOIN thoughtleaders_adspot s            ON s.id  = al.ad_spot_id
+          JOIN thoughtleaders_profile p           ON p.id  = al.creator_profile_id
+          JOIN thoughtleaders_profile_brands pb   ON pb.profile_id = p.id
+          JOIN thoughtleaders_brand b             ON b.id  = pb.brand_id
+          WHERE al.publish_status = 3
+            AND b.name = 'Nike'
+            AND al.article_id IS NOT NULL
+          LIMIT 500 OFFSET 0" --json \
+  | jq -r '.results[] | "\(.channel_id):\(.article_id)"'
 
 # Or videos via Elasticsearch content search
 tl db es '{