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

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

@@ -1,6 +1,6 @@
 {
   "name": "tl-cli",
-  "version": "0.6.44",
+  "version": "0.6.45",
   "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.45}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thoughtleaders-cli
-Version: 0.6.44
+Version: 0.6.45
 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.45}/pyproject.toml

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

{thoughtleaders_cli-0.6.44 → thoughtleaders_cli-0.6.45}/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 (usuakky by filters in the `tl db` query, but could be from similarity 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,35 @@ 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.
+The CLI has shortcut commands for each type: `tl matches`, `tl proposals`, `tl deals`. These are aliases for `tl sponsorships` with filtering 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.
+  - 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.
 - **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 +105,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, query by `status:sold` and filter the the date range only by `purchase_date`. Otherwise, query for `status:sold` and filter by `created_at`.
 
 ## 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
 
@@ -144,20 +152,30 @@ Prefer writing Python code, shell code, or `jq` commands that fetche or analysis
 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.
 
 ### 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 +195,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
@@ -306,7 +326,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 +337,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 +454,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."
@@ -511,8 +519,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 +528,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 +543,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 +603,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 +635,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.45}/src/tl_cli/__init__.py

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

{thoughtleaders_cli-0.6.44 → thoughtleaders_cli-0.6.45}/src/tl_cli/commands/_comments_common.py

@@ -73,23 +73,25 @@ def register_comment_commands(app: typer.Typer, entity_type: str, entity_label:
     text (e.g. "sponsorship", "channel").
     """
 
-    @app.command("comment-list")
+    # `help=` is passed explicitly because Typer reads the function's
+    # `__doc__` for the per-subcommand help text, and `f"""…"""` as the
+    # first statement is a runtime f-string expression — not a docstring
+    # — so `__doc__` ends up None and the help column renders blank.
+    @app.command("comment-list", help=f"List comments on a {entity_label} (free, no credits).")
     def comment_list(
         entity_id: str = typer.Argument(..., help=f"{entity_label.capitalize()} ID"),
         json_output: bool = typer.Option(False, "--json", help="JSON output"),
         toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
     ) -> None:
-        f"""List comments on a {entity_label} (free, no credits)."""
         list_comments(entity_type, entity_id, json_output, toon_output)
 
-    @app.command("comment-add")
+    @app.command("comment-add", help=f"Add a comment to a {entity_label} (free, no credits).")
     def comment_add(
         entity_id: str = typer.Argument(..., help=f"{entity_label.capitalize()} ID"),
         message: str = typer.Argument(..., help="Comment text"),
         json_output: bool = typer.Option(False, "--json", help="JSON output"),
         toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
     ) -> None:
-        f"""Add a comment to a {entity_label} (free, no credits)."""
         add_comment(entity_type, entity_id, message, json_output, toon_output)
 
     @app.command("comment-edit")

{thoughtleaders_cli-0.6.44 → thoughtleaders_cli-0.6.45}/src/tl_cli/commands/brands.py

@@ -168,12 +168,20 @@ def history_stats_cmd(
 @app.command("find")
 def find_cmd(
     query: str = typer.Argument(..., help="Brand name, slug, domain, or keyword"),
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    csv_output: bool = typer.Option(False, "--csv", help="CSV output"),
+    md_output: bool = typer.Option(False, "--md", help="Markdown output"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
 ) -> None:
-    """Resolve a string to a single brand and print {id, name} as JSON.
+    """Resolve a string to a single brand.
 
     Searches across name, slug, website domain, and the brand's keyword
-    fields (kw + keywords). Ambiguous matches return an error with the
-    candidate IDs and names so the caller can pick a better query.
+    fields (kw + keywords). Default output is a pretty `id  name` line on
+    stdout; pass --json / --csv / --md / --toon for machine-readable
+    output (the JSON shape is `{"id": ..., "name": ...}`).
+
+    Ambiguous matches return an error with the candidate IDs and names so
+    the caller can pick a better query.
 
     Examples:
         tl brands find Nike
@@ -181,12 +189,26 @@ def find_cmd(
         tl brands find https://www.nike.com/
         tl brands find 21416
     """
+    fmt = detect_format(json_output, csv_output, md_output, toon_output)
     client = get_client()
     try:
         data = client.get("/brands/find", params={"q": query})
         results = data.get("results", [])
         record = results[0] if results else {}
-        print(_json.dumps({"id": record.get("id"), "name": record.get("name")}, ensure_ascii=False))
+        if fmt == "table":
+            bid = record.get("id")
+            name = record.get("name")
+            if bid is None:
+                Console(stderr=True).print("[yellow]No match.[/yellow]")
+                raise typer.Exit(1)
+            Console().print(f"[bold yellow]{bid}[/bold yellow]  {name}")
+        else:
+            output(
+                {"results": [{"id": record.get("id"), "name": record.get("name")}]},
+                fmt,
+                columns=["id", "name"],
+                title=f"Brand match for {query}",
+            )
     except ApiError as e:
         if e.status_code == 400 and isinstance(e.raw, dict) and e.raw.get("candidates"):
             _print_brand_find_candidates(e.detail, e.raw["candidates"])

{thoughtleaders_cli-0.6.44 → thoughtleaders_cli-0.6.45}/src/tl_cli/commands/channels.py

@@ -285,8 +285,12 @@ def update_cmd(
 @app.command("find")
 def find_cmd(
     query: str = typer.Argument(..., help="Name, slug, YouTube URL, handle, channel ID, or video URL"),
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    csv_output: bool = typer.Option(False, "--csv", help="CSV output"),
+    md_output: bool = typer.Option(False, "--md", help="Markdown output"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
 ) -> None:
-    """Resolve a string to a single channel and print {id, name} as JSON.
+    """Resolve a string to a single channel.
 
     Accepts:
       - A partial channel name or slug (ILIKE match)
@@ -296,6 +300,10 @@ def find_cmd(
       - A YouTube video URL — the video's channel is resolved via the
         platform's article index
 
+    Default output is a pretty `id  name` line on stdout. Pass --json /
+    --csv / --md / --toon for machine-readable output (the JSON shape is
+    `{"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.
@@ -306,12 +314,26 @@ def find_cmd(
         tl channels find https://www.youtube.com/watch?v=dQw4w9WgXcQ
         tl channels find UCX6OQ3DkcsbYNE6H8uQQuVA
     """
+    fmt = detect_format(json_output, csv_output, md_output, toon_output)
     client = get_client()
     try:
         data = client.get("/channels/find", params={"q": query})
         results = data.get("results", [])
         record = results[0] if results else {}
-        print(_json.dumps({"id": record.get("id"), "name": record.get("name")}, ensure_ascii=False))
+        if fmt == "table":
+            cid = record.get("id")
+            name = record.get("name")
+            if cid is None:
+                Console(stderr=True).print("[yellow]No match.[/yellow]")
+                raise typer.Exit(1)
+            Console().print(f"[bold cyan]{cid}[/bold cyan]  {name}")
+        else:
+            output(
+                {"results": [{"id": record.get("id"), "name": record.get("name")}]},
+                fmt,
+                columns=["id", "name"],
+                title=f"Channel match for {query}",
+            )
     except ApiError as e:
         if e.status_code == 400 and isinstance(e.raw, dict) and e.raw.get("candidates"):
             _print_channel_candidates(e.detail, e.raw["candidates"])
@@ -319,12 +341,10 @@ def find_cmd(
         if e.status_code == 404 and isinstance(e.raw, dict) and e.raw.get("queued"):
             err = Console(stderr=True)
             err.print(f"[yellow]{e.detail}[/yellow]")
-            print(_json.dumps({
-                "error": e.detail,
-                "queued": True,
-                "queued_channel_id": e.raw.get("queued_channel_id"),
-                "queued_url": e.raw.get("queued_url"),
-            }, ensure_ascii=False))
+            err.print(
+                f"  [dim]queued_channel_id={e.raw.get('queued_channel_id')}"
+                f"  queued_url={e.raw.get('queued_url')}[/dim]"
+            )
             raise typer.Exit(1)
         handle_api_error(e)
     finally:

{thoughtleaders_cli-0.6.44 → thoughtleaders_cli-0.6.45}/src/tl_cli/commands/recommender.py

@@ -268,8 +268,8 @@ def inspect_brand_cmd(
         client.close()
 
 
-@app.command("similar-to-profile")
-def similar_to_profile_cmd(
+@app.command("channels-for-profile")
+def channels_for_profile_cmd(
     profile_id: int = typer.Argument(..., help="Profile ID (numeric)"),
     args: list[str] = typer.Argument(None, help="Filters (key:value pairs)."),
     json_output: bool = typer.Option(False, "--json", help="JSON output"),
@@ -288,8 +288,8 @@ def similar_to_profile_cmd(
         msn:<yes|no>        Restrict to MSN channels (default: no)
 
     Examples:
-        tl recommender similar-to-profile 842
-        tl recommender similar-to-profile 842 msn:yes --limit 30
+        tl recommender channels-for-profile 842
+        tl recommender channels-for-profile 842 msn:yes --limit 30
     """
     fmt = detect_format(json_output, csv_output, md_output, toon_output)
     filters = parse_filters(args or [])
@@ -315,8 +315,63 @@ def similar_to_profile_cmd(
         client.close()
 
 
-@app.command("similar-brands-to-channel")
-def similar_brands_to_channel_cmd(
+@app.command("channels-for-brand")
+def channels_for_brand_cmd(
+    brand_ref: str = typer.Argument(..., help="Brand ID, name, slug, or domain (resolved via tl brands find)"),
+    args: list[str] = typer.Argument(None, help="Filters (key:value pairs)."),
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    csv_output: bool = typer.Option(False, "--csv", help="CSV output"),
+    md_output: bool = typer.Option(False, "--md", help="Markdown output"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
+    limit: int = typer.Option(20, "--limit", "-l", help="Max results (1-100)"),
+) -> None:
+    """Channels closest to a brand's ideal similarity profile.
+
+    Resolves the brand to its most-recently-created profile that has an
+    indexed search vector and runs the same KNN that
+    `channels-for-profile` uses. Costs 25 credits per call. Intelligence
+    plan required. Channels the brand has already worked with or been
+    proposed are excluded.
+
+    Filters:
+        language:<iso>      Content language (default: en)
+        msn:<yes|no>        Restrict to MSN channels (default: no)
+
+    Examples:
+        tl recommender channels-for-brand 6037
+        tl recommender channels-for-brand Nike msn:yes --limit 30
+    """
+    fmt = detect_format(json_output, csv_output, md_output, toon_output)
+    filters = parse_filters(args or [])
+    params = {k: v for k, v in filters.items() if k in {"language", "msn"}}
+    params["limit"] = str(limit)
+    encoded = urllib.parse.quote(brand_ref, safe="")
+    client = get_client()
+    try:
+        data = client.get(f"/recommender/brands/{encoded}/channels-for-profile", params=params)
+        for r in data.get("results", []):
+            score = r.get("score")
+            if isinstance(score, (int, float)) and fmt in ("table", "md"):
+                r["score"] = f"{score * 100:.1f}%"
+        title = f"Channels for brand {brand_ref}"
+        prof = data.get("profile") or {}
+        if prof.get("brand_name") and prof.get("id"):
+            title = f"Channels for {prof['brand_name']} (via profile {prof['id']})"
+        output(
+            data,
+            fmt,
+            columns=["score", "channel_id", "channel_name", "slug"],
+            title=title,
+            column_config={"score": {"justify": "right"}},
+        )
+    except ApiError as e:
+        handle_api_error(e)
+    finally:
+        client.close()
+
+
+@app.command("brands-for-channel")
+def brands_for_channel_cmd(
     channel_ref: str = typer.Argument(..., help="Channel ID (numeric) or name (partial match, must be unique)"),
     args: list[str] = typer.Argument(None, help="Filters (key:value pairs)."),
     json_output: bool = typer.Option(False, "--json", help="JSON output"),
@@ -335,8 +390,8 @@ def similar_brands_to_channel_cmd(
         mbn:<yes|no|all>    MBN membership of the underlying profile (default: all)
 
     Examples:
-        tl recommender similar-brands-to-channel 12345
-        tl recommender similar-brands-to-channel "MrBeast" mbn:yes --limit 30
+        tl recommender brands-for-channel 12345
+        tl recommender brands-for-channel "MrBeast" mbn:yes --limit 30
     """
     fmt = detect_format(json_output, csv_output, md_output, toon_output)
     filters = parse_filters(args or [])
@@ -361,3 +416,17 @@ def similar_brands_to_channel_cmd(
         _handle_recommender_error(e)
     finally:
         client.close()
+
+
+@app.command("similar-brands-to-channel", hidden=True)
+def similar_brands_to_channel_cmd(
+    channel_ref: str = typer.Argument(..., help="Channel ID (numeric) or name (partial match, must be unique)"),
+    args: list[str] = typer.Argument(None, help="Filters (key:value pairs)."),
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    csv_output: bool = typer.Option(False, "--csv", help="CSV output"),
+    md_output: bool = typer.Option(False, "--md", help="Markdown output"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
+    limit: int = typer.Option(20, "--limit", "-l", help="Max results (1-100)"),
+) -> None:
+    """Hidden alias for `brands-for-channel` (older name kept for back-compat)."""
+    brands_for_channel_cmd(channel_ref, args, json_output, csv_output, md_output, toon_output, limit)