thoughtleaders-cli 0.6.4__tar.gz → 0.6.6__tar.gz

{thoughtleaders_cli-0.6.4 → thoughtleaders_cli-0.6.6}/.claude-plugin/plugin.json

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

{thoughtleaders_cli-0.6.4 → thoughtleaders_cli-0.6.6}/AGENTS.md

@@ -1,6 +1,6 @@
 # Project Overview
 
-**tl-cli** is a Python CLI for querying ThoughtLeaders sponsorship data (sponsorships, channels, brands, uploads, snapshots, reports, vector recommender). Built with Typer + Rich + httpx. Designed as an "agent-first tool" — the CLI handles structured commands and output, while the user's AI agent (Claude) provides intelligence.
+**tl-cli** is a Python CLI for querying ThoughtLeaders sponsorship data (sponsorships, channels, brands, uploads, snapshots, reports, recommender). Built with Typer + Rich + httpx. Designed as an "agent-first tool" — the CLI handles structured commands and output, while the user's AI agent (Claude) provides intelligence.
 
 # Architecture
 
@@ -20,7 +20,7 @@ When adding a new data command, follow this pattern. See `sponsorships.py` for t
 
 `deals`, `matches`, and `proposals` are shortcut commands that delegate to sponsorships' `do_list`/`do_show`/`do_create` with a pre-set status filter. They reject explicit `status:` filters — users should use `tl sponsorships list` for finer-grained status filtering.
 
-`recommender` (`commands/recommender.py`) wraps the vector-recommender API at `/api/cli/v1/recommender/*` — `tags` (free), `top-channels` / `top-profiles` / `top-brands`, `inspect-channel`, `inspect-brand`, `similar-to-profile` (all 50 credits flat, Intelligence-gated). The three `top-*` URLs share one server resolver; `top-brands` dedupes the underlying profile rows by brand. Channel→channel and brand→brand similarity stay on `tl channels similar` / `tl brands similar`. When updating the SKILL or examples, prefer steering category/topic discovery (e.g. "Cooking channels") to `tl recommender top-channels "<tag>"` rather than `WHERE content_category = <code>` SQL — the recommender is ranked, not equality-based. The underlying recommender code uses "element"/"field_name" terminology; the CLI/API layer renames these to "tag" at the boundary.
+`recommender` (`commands/recommender.py`) wraps the recommender API at `/api/cli/v1/recommender/*` — `tags` (free), `top-channels` / `top-profiles` / `top-brands`, `inspect-channel`, `inspect-brand`, `similar-to-profile` (all 25 credits flat, Intelligence-gated). The three `top-*` URLs share one server resolver; `top-brands` dedupes the underlying profile rows by brand. Channel→channel and brand→brand similarity stay on `tl channels similar` / `tl brands similar`. When updating the SKILL or examples, prefer steering category/topic discovery (e.g. "Cooking channels") to `tl recommender top-channels "<tag>"` rather than `WHERE content_category = <code>` SQL — the recommender is ranked, not equality-based. The underlying recommender code uses "element"/"field_name" terminology; the CLI/API layer renames these to "tag" at the boundary.
 
 ## Filter Parsing (`filters.py`)
 

{thoughtleaders_cli-0.6.4 → thoughtleaders_cli-0.6.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thoughtleaders-cli
-Version: 0.6.4
+Version: 0.6.6
 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
@@ -83,7 +83,7 @@ tl uploads show 1174310:0BehkmVa7ak
 
 # Search channels via raw SQL — `tl db pg` against thoughtleaders_channel
 # (run `tl schema pg` once to confirm the live column set).
-# NOTE: For topic / category discovery, prefer the vector recommender over
+# NOTE: For topic / category discovery, prefer the recommender over
 # `content_category` equality — `tl recommender top-channels "<tag>"`
 # returns channels ranked by how strongly they load on the topic, not just
 # rows where the single category code matches exactly.
@@ -101,22 +101,22 @@ tl db pg "SELECT id, channel_name FROM thoughtleaders_channel
 tl channels show 12345
 tl channels show "Economics Explained"
 
-# Find similar channels (vector recommender, 50 credits, Intelligence plan).
+# Find similar channels (recommender, 25 credits, Intelligence plan).
 # msn: is tri-state (default msn:yes): yes = MSN only, no = non-MSN only, both = no filter.
 # tpp: is tri-state (default tpp:both): yes = TPP only, no = non-TPP only, both = no filter.
 # Same ID-or-name resolution rules as `channels show`.
 tl channels similar 12345 --limit 10
 tl channels similar "Tremending girls" min-score:0.85 --limit 5
 
-# Vector recommender — discovery by category/demographic tag (Intelligence plan).
-# `tags` is free; `top`, `inspect-*`, and `similar-to-profile` cost 50 credits flat.
+# Recommender — discovery by category/demographic tag (Intelligence plan).
+# `tags` is free; `top-*`, `inspect-*`, `similar-to-profile`, and `similar-brands-to-channel` cost 25 credits flat.
 tl recommender tags                              # List every tag (free)
 tl recommender tags cooking                      # Search tag names by substring
 tl recommender top-channels "Cooking" msn:yes --limit 50  # Top channels for a tag
 tl recommender top-profiles "Cooking" mbn:yes --limit 30  # Top brand profiles (one brand → potentially multiple profiles)
 tl recommender top-brands "Cooking" --limit 30            # Top brands (deduped from profiles)
 tl recommender inspect-channel 12345             # Per-tag breakdown of a channel's vector
-tl recommender inspect-brand Nike                # Per-tag breakdown of a brand's ideal vector
+tl recommender inspect-brand Nike                # Per-tag breakdown of a brand's ideal profile
 tl recommender similar-to-profile 842            # Channels closest to a brand profile
 
 # Brand intelligence

{thoughtleaders_cli-0.6.4 → thoughtleaders_cli-0.6.6}/README.md

@@ -56,7 +56,7 @@ tl uploads show 1174310:0BehkmVa7ak
 
 # Search channels via raw SQL — `tl db pg` against thoughtleaders_channel
 # (run `tl schema pg` once to confirm the live column set).
-# NOTE: For topic / category discovery, prefer the vector recommender over
+# NOTE: For topic / category discovery, prefer the recommender over
 # `content_category` equality — `tl recommender top-channels "<tag>"`
 # returns channels ranked by how strongly they load on the topic, not just
 # rows where the single category code matches exactly.
@@ -74,22 +74,22 @@ tl db pg "SELECT id, channel_name FROM thoughtleaders_channel
 tl channels show 12345
 tl channels show "Economics Explained"
 
-# Find similar channels (vector recommender, 50 credits, Intelligence plan).
+# Find similar channels (recommender, 25 credits, Intelligence plan).
 # msn: is tri-state (default msn:yes): yes = MSN only, no = non-MSN only, both = no filter.
 # tpp: is tri-state (default tpp:both): yes = TPP only, no = non-TPP only, both = no filter.
 # Same ID-or-name resolution rules as `channels show`.
 tl channels similar 12345 --limit 10
 tl channels similar "Tremending girls" min-score:0.85 --limit 5
 
-# Vector recommender — discovery by category/demographic tag (Intelligence plan).
-# `tags` is free; `top`, `inspect-*`, and `similar-to-profile` cost 50 credits flat.
+# Recommender — discovery by category/demographic tag (Intelligence plan).
+# `tags` is free; `top-*`, `inspect-*`, `similar-to-profile`, and `similar-brands-to-channel` cost 25 credits flat.
 tl recommender tags                              # List every tag (free)
 tl recommender tags cooking                      # Search tag names by substring
 tl recommender top-channels "Cooking" msn:yes --limit 50  # Top channels for a tag
 tl recommender top-profiles "Cooking" mbn:yes --limit 30  # Top brand profiles (one brand → potentially multiple profiles)
 tl recommender top-brands "Cooking" --limit 30            # Top brands (deduped from profiles)
 tl recommender inspect-channel 12345             # Per-tag breakdown of a channel's vector
-tl recommender inspect-brand Nike                # Per-tag breakdown of a brand's ideal vector
+tl recommender inspect-brand Nike                # Per-tag breakdown of a brand's ideal profile
 tl recommender similar-to-profile 842            # Channels closest to a brand profile
 
 # Brand intelligence

{thoughtleaders_cli-0.6.4 → thoughtleaders_cli-0.6.6}/agents/tl-analyst.md

@@ -16,7 +16,7 @@ For anything beyond a trivially simple lookup, write a single raw query against
 - **Elasticsearch (`tl db es`)** — transcript / brand-mention text search, video-level aggregations, demographic country-share filters that compose with content predicates.
 - **Firebolt (`tl db fb`)** — custom time-series shapes (multi-channel growth comparisons, milestone-age slices). For default shapes, prefer `tl snapshots`.
 
-Reserve structured commands for: single-record `show` by ID, plain filtered `list` with one or two filters that the structured vocabulary already supports, `tl channels similar` / `tl brands similar` (vector KNN), `tl reports run`, and `tl snapshots`.
+Reserve structured commands for: single-record `show` by ID, plain filtered `list` with one or two filters that the structured vocabulary already supports, `tl channels similar` / `tl brands similar` (similarity search), `tl reports run`, and `tl snapshots`.
 
 One raw query beats N paginated structured walks stitched in `jq`/Python — on cost, latency, and the ES `from+size = 10000` cap.
 
@@ -69,7 +69,7 @@ Then suggest `tl comments add <id> "..."` for each.
 ### Multi-step research (mix raw + similarity)
 "Find channels similar to the ones Nike sponsors and compare their pricing"
 1. `tl db pg` to find the top channels Nike has sponsored (one aggregation, ranked).
-2. `tl channels similar <top-channel-id> --json --limit 20` per seed — vector KNN is server-side and has no SQL equivalent. The `msn:` filter is tri-state with default `msn:yes` (MSN channels only); use `msn:both` to broaden, `msn:no` for non-MSN only.
+2. `tl channels similar <top-channel-id> --json --limit 20` per seed — similarity search is server-side and has no SQL equivalent. The `msn:` filter is tri-state with default `msn:yes` (MSN channels only); use `msn:both` to broaden, `msn:no` for non-MSN only.
 3. Union + dedupe + compile comparison table.
 
 ### Report comparison (saved reports)

{thoughtleaders_cli-0.6.4 → thoughtleaders_cli-0.6.6}/docs/architecture.md

@@ -50,10 +50,10 @@ All data commands use explicit subcommands: `list`, `show`, `create`/`add`. Runn
 | `tl uploads show <id> [<id>...]` | Show upload detail(s) by ID |
 | `tl channels show <id-or-name>` | Channel detail, including active adspots with price/cost/CPM |
 | `tl channels history <id-or-name>` | Sponsorship history (videos with detected sponsors) |
-| `tl channels similar <id-or-name>` | Vector-similarity recommender. 50 credits; Intelligence plan. Tri-state `msn:` (default `yes`) and `tpp:` (default `both`) filters. Ambiguous names return 400 + candidates list. Hidden `look-alike` alias. |
+| `tl channels similar <id-or-name>` | Similarity recommender. 25 credits; Intelligence plan. Tri-state `msn:` (default `yes`) and `tpp:` (default `both`) filters. Ambiguous names return 400 + candidates list. Hidden `look-alike` alias. |
 | `tl brands show <brand>` | Brand intelligence report |
 | `tl brands history <brand> [--channel <id>]` | Brand sponsorship history; videos where the brand was detected |
-| `tl brands similar <brand>` | Find similar brands (profile vector KNN, 50 credits) |
+| `tl brands similar <brand>` | Find similar brands (similarity search, 25 credits) |
 | `tl snapshots channel <id>` | Channel metrics over time (Firebolt channel_metrics) |
 | `tl snapshots video <id> --channel <id>` | Video view curve (Firebolt article_metrics, --channel required) |
 | `tl comments list <adlink-id>` | List comments on a sponsorship (free) |

{thoughtleaders_cli-0.6.4 → thoughtleaders_cli-0.6.6}/pyproject.toml

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

{thoughtleaders_cli-0.6.4 → thoughtleaders_cli-0.6.6}/skills/tl/SKILL.md

@@ -95,11 +95,28 @@ When querying sponsorship bookings, query by `status:sold` and filter the the da
 
 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 vector 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 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.
 
 ## Workflow
 
-At the start of session, always run a `tl help` command to find out which commands are available, and the `tl whoami` command to find out what you have access to.
+At the start of session, always run `tl --help` to find out which command groups are available, and `tl whoami` to find out what you have access to.
+
+### How to discover commands and subcommands
+
+The CLI exposes three different discovery surfaces — pick by what you actually need:
+
+| You want to know… | Run |
+|---|---|
+| Top-level command groups (`sponsorships`, `channels`, `db`, `recommender`, etc.) | `tl --help` |
+| Subcommands of a group (`tl recommender` → `tags`, `top-channels`, `inspect-brand`, …) | `tl <group> --help` (e.g. `tl recommender --help`, `tl db --help`) |
+| Arguments and flags for a specific leaf command | `tl <group> <subcommand> --help` (e.g. `tl recommender top-channels --help`) |
+| Fields, filters, credit rates for a **data resource** (sponsorships, uploads, snapshots, reports, comments, recommender) | `tl describe show <resource> --json` |
+| The live PG/ES/Firebolt schema for raw `tl db` queries | `tl schema pg` / `tl schema es` / `tl schema fb` |
+
+Notes:
+- Use `--help` everywhere — there is no separate `tl help` command. `tl help` returns "No such command 'help'".
+- **`tl describe show channels`** and **`tl describe show brands`** intentionally do not list fields/filters — channel and brand search live in raw SQL (`tl db pg`) and the recommender, not in a structured list endpoint. They print a notice steering you there.
+- `--help` describes **CLI shape**; `tl describe` describes **data shape**. They don't overlap.
 
 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.
 
@@ -132,18 +149,18 @@ tl uploads list [filters...]           # Video uploads from ES — list curve, m
 tl uploads show <id>                   # Upload detail (2 credits)
 tl channels show <id-or-name>          # Channel detail (2 credits; accepts numeric ID or name) — for channel search use raw SQL on thoughtleaders_channel
 tl channels history <id-or-name>       # Sponsorship history (5 credits/result, linear)
-tl channels similar <id-or-name>       # Vector-similarity recommender (50 credits flat; Intelligence plan)
+tl channels similar <id-or-name>       # Similarity recommender (25 credits flat; Intelligence plan)
 tl brands show <id-or-name>            # Brand detail (1 credit)
 tl brands history <id-or-name>         # Sponsorship history (5 credits/result, linear)
 tl brands history <query> --channel <id>  # Brand mentions on specific channel
-tl brands similar <id-or-name>         # Find similar brands via profile vector KNN (50 credits flat)
-tl recommender tags [query]            # List vector tag names — categories, demographics, formats (free)
-tl recommender top-channels "<tag>"    # Top channels loaded on a vector tag (50 credits; Intelligence)
-tl recommender top-profiles "<tag>"    # Top brand profiles loaded on a vector tag (50 credits)
-tl recommender top-brands "<tag>"      # Top brands (deduped from profiles) loaded on a vector tag (50 credits)
-tl recommender inspect-channel <ref>   # Show a channel's feature-vector breakdown (50 credits; Intelligence)
-tl recommender inspect-brand <ref>     # Show a brand profile's ideal-vector breakdown (50 credits; Intelligence)
-tl recommender similar-to-profile <id> # Channels closest to a brand profile's ideal vector (50 credits; Intelligence)
+tl brands similar <id-or-name>         # Find similar brands via similarity search (25 credits flat)
+tl recommender tags [query]            # List similarity tag names — categories, demographics, formats (free)
+tl recommender top-channels "<tag>"    # Top channels loaded on a similarity tag (25 credits; Intelligence)
+tl recommender top-profiles "<tag>"    # Top brand profiles loaded on a similarity tag (25 credits)
+tl recommender top-brands "<tag>"      # Top brands (deduped from profiles) loaded on a similarity tag (25 credits)
+tl recommender inspect-channel <ref>   # Show a channel's similarity-profile breakdown (25 credits; Intelligence)
+tl recommender inspect-brand <ref>     # Show a brand profile's ideal similarity-profile breakdown (25 credits; Intelligence)
+tl recommender similar-to-profile <id> # Channels closest to a brand profile's ideal profile (25 credits; Intelligence)
 tl snapshots channel <id>              # Channel metrics over time — list curve, mult 1.2 (Firebolt-backed)
 tl snapshots video <id> --channel <id> # Video view curve — list curve, mult 1.2 (--channel required!)
 tl reports                             # List saved reports — list curve, mult 1.3
@@ -196,7 +213,7 @@ Structured commands are still the right tool for: single-record `show` by ID, pl
 | 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 (vector KNN, server-implemented) | `tl channels similar`, `tl brands similar` |
+| Channel/brand similarity (server-implemented similarity search) | `tl channels similar`, `tl brands similar` |
 | Saved reports | `tl reports`, `tl reports run` |
 | Time-series view-curve / channel growth (default shape with interpolation) | `tl snapshots channel`, `tl snapshots video` |
 
@@ -289,7 +306,7 @@ See [references/business-glossary.md](references/business-glossary.md) for reven
 | **AdLink INSERT** with custom price/cost/owner/`weighted_price`/`created_where` | **Unavailable** — `tl sponsorships create` exists but only creates a free *proposal* between a channel and a brand. The `tl db pg` sanitizer accepts SELECT only — no INSERT/UPDATE. | Done in the app or by a human with DB access. |
 | 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` (vector KNN, server-implemented). |
+| 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 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). |
@@ -325,14 +342,14 @@ Date filters accept keywords: `today`, `yesterday`, `tomorrow`.
 
 #### Channel discovery — recommender first, raw SQL second
 
-For category- or demographic-driven discovery, **use the vector recommender, not `content_category` SQL.** The recommender ranks channels by how strongly they load on a category/demographic tag (cosine-style 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."
+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."
 
 ```bash
 # Discover the right tag name first (free)
 tl recommender tags cooking
 tl recommender tags "usa"
 
-# Top channels & profiles loaded on a vector tag (50 credits; Intelligence)
+# Top channels & profiles loaded on a similarity tag (25 credits; 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
@@ -434,7 +451,7 @@ tl reports run 42 --json
 
 "Find Cooking channels with US-heavy mobile audiences":
 ```bash
-# Use the vector recommender for the topic, then narrow with structured filters / SQL on the IDs.
+# Use the recommender for the topic, then narrow with structured filters / SQL on the IDs.
 tl recommender top-channels "Cooking" msn:yes --limit 100 --json \
   | jq -r '.results[].channel_id' \
   | paste -sd, - \
@@ -452,7 +469,7 @@ tl recommender top-channels "Cooking" msn:yes --limit 100 --json \
 tl sponsorships list status:sold primary-device:mobile min-us-share:60 --json
 ```
 
-"Find channels similar to one I know" (vector-similarity recommender, 50 credits per call):
+"Find channels similar to one I know" (similarity recommender, 25 credits per call):
 ```bash
 tl channels similar 29834 --limit 10                         # by ID (defaults to msn:yes, tpp:both)
 tl channels similar "Tremending girls" --limit 5             # by unique name
@@ -464,16 +481,16 @@ tl channels similar 29834 min-subs:1000000 exclude:477487 --limit 15  # client-s
 ```
 **Both `tl channels show` and `tl channels similar` accept either a numeric channel ID or a channel name.** Name arguments are case-insensitive partial matches; if more than one active channel matches, the command prints a candidates table (channel_id, subscribers, name) and exits 1 so you can retry with a specific ID. The `msn` filter on `similar` is tri-state: `yes` (only MSN channels — the default), `no` (only non-MSN channels), `both` (no MSN filter). `tl channels look-alike` is a hidden alias for `similar` that matches the internal "look-alike channels" terminology.
 
-"Browse the vector recommender" (categories, demographics, formats — `tl recommender tags` is free):
+"Browse the recommender" (categories, demographics, formats — `tl recommender tags` is free):
 ```bash
 tl recommender tags                                            # Full tag list (free)
 tl recommender tags cooking                                    # Search tag names by substring
-tl recommender top-channels "Cooking" msn:yes --limit 50       # Top channels loaded on a tag (50 credits)
+tl recommender top-channels "Cooking" msn:yes --limit 50       # Top channels loaded on a tag (25 credits)
 tl recommender top-profiles "Cooking" --limit 30               # Top brand profiles for the tag
 tl recommender top-brands "USA share" mbn:yes --limit 30       # Top brands (deduped) — demographic tag, MBN only
 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 vector
-tl recommender similar-to-profile 842 --limit 30               # Channels closest to a brand profile's ideal 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
 ```
 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.4 → thoughtleaders_cli-0.6.6}/skills/tl/references/elasticsearch-schema.md

@@ -158,11 +158,9 @@ The full table below applies to **channel parent docs only**:
 ### Other indices
 
 - `tl-ingest` — ingestion queue. **Don't query.** Internal pipeline state.
-- `tl-feature-vectors-channel`, `tl-feature-vectors-channel-profile` — channel similarity vectors.
+- `tl-similarity-profiles-channel`, `tl-similarity-profiles-channel-profile` — channel similarity vectors.
 - `tl-vectors-brand-company-descriptions-*` — brand similarity vectors.
-- `tl-vectors-channel-audience-*`, `tl-vectors-channel-topic-descriptions-*`, `tl-vectors-channel-features` — channel feature vectors.
-
-Note: `knn` queries against vector indices are **not currently accepted** as a top-level key. For "find similar" results, use `tl channels similar` / `tl brands similar` — they wrap the vector search server-side.
+- `tl-vectors-channel-audience-*`, `tl-vectors-channel-topic-descriptions-*`, `tl-vectors-channel-features` — channel similarity profiles.
 
 ## Common Query Patterns
 

{thoughtleaders_cli-0.6.4 → thoughtleaders_cli-0.6.6}/skills/tl/references/firebolt-schema.md

@@ -116,7 +116,7 @@ Every Firebolt workflow has two steps:
 **Step 1 — get `channel_id` and (optionally) video IDs from PG/ES.**
 
 ```bash
-# Channels matching some category (vector recommender — preferred over content_category equality)
+# Channels matching some category (recommender — preferred over content_category equality)
 tl recommender top-channels "Tech" msn:yes --limit 50 --json \
   | jq '.results[].channel_id'
 

{thoughtleaders_cli-0.6.4 → thoughtleaders_cli-0.6.6}/src/tl_cli/__init__.py

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

{thoughtleaders_cli-0.6.4 → thoughtleaders_cli-0.6.6}/src/tl_cli/commands/brands.py

@@ -125,7 +125,7 @@ SIMILAR_COLUMN_CONFIG = {
 
 
 def _format_score(results: list[dict]) -> list[dict]:
-    """Convert raw cosine score (0.0-1.0) to percentage string."""
+    """Convert raw similarity score (0.0-1.0) to percentage string."""
     for row in results:
         score = row.get("score")
         if isinstance(score, (int, float)):
@@ -144,7 +144,7 @@ def similar_cmd(
 ) -> None:
     """Find brands similar to a given one (by ID or name).
 
-    Costs 50 credits per call. Intelligence plan required.
+    Costs 25 credits per call. Intelligence plan required.
 
     Examples:
         tl brands similar Nike

{thoughtleaders_cli-0.6.4 → thoughtleaders_cli-0.6.6}/src/tl_cli/commands/channels.py

@@ -93,7 +93,7 @@ def _handle_channel_api_error(e: ApiError) -> None:
 
 
 def _format_score(results: list[dict]) -> list[dict]:
-    """Convert raw cosine score (0.0-1.0) to percentage string for table/csv/md."""
+    """Convert raw similarity score (0.0-1.0) to percentage string for table/csv/md."""
     for row in results:
         score = row.get("score")
         if isinstance(score, (int, float)):
@@ -171,14 +171,14 @@ def similar_cmd(
 ) -> None:
     """Find channels similar to a given one (by id or name).
 
-    Costs 50 credits per call. Intelligence plan required. Results are
-    ranked by cosine similarity and enriched with subscribers, impression,
+    Costs 25 credits per call. Intelligence plan required. Results are
+    ranked by similarity and enriched with subscribers, impression,
     total_views, category, and the channel's representative CPM.
 
     Server-side filters (pushed to the recommender):
         language:<iso>      Restrict to a content language (default: en)
         msn:<true|false>    Restrict to Media Selling Network (default: true)
-        min-score:<0-1>     Minimum cosine similarity (default: 0.5)
+        min-score:<0-1>     Minimum similarity (default: 0.5)
 
     Client-side post-filters (applied after fetch):
         category:<code>     Keep only rows matching this content_category

{thoughtleaders_cli-0.6.4 → thoughtleaders_cli-0.6.6}/src/tl_cli/commands/describe.py

@@ -67,6 +67,17 @@ def show_cmd(
     """
     fmt = detect_format(json_output, False, False, toon_output)
 
+    if resource in {"channels", "brands"}:
+        notice = (
+            f"Examine the database schema with `tl schema pg` and then perform "
+            f"a `tl db pg` query on {resource}."
+        )
+        if fmt == "json":
+            print(json.dumps({"resource": resource, "notice": notice}, indent=2))
+        else:
+            console.print(notice)
+        return
+
     client = get_client()
     try:
         data = client.get(f"/describe/{resource}")

{thoughtleaders_cli-0.6.4 → thoughtleaders_cli-0.6.6}/src/tl_cli/commands/recommender.py

@@ -1,10 +1,11 @@
-"""tl recommender — Vector-recommender introspection and discovery.
+"""tl recommender — Recommender introspection and discovery.
 
-Surfaces the channel/profile feature-vector machinery that powers the
-"Recommender Insights" web view: list the vector tags (categories,
-demographics, formats, etc.), find the top channels and profiles loaded
-on a given tag, inspect a single channel or brand vector, or fetch
-channels similar to a brand profile's ideal vector.
+Surfaces the channel/profile similarity machinery that powers the
+"Recommender Insights" web view: list the similarity tags (categories,
+demographics, formats, etc.), find the top channels and profiles
+scoring high on a given tag, inspect a single channel or brand
+similarity profile, fetch channels similar to a brand's ideal profile,
+or fetch brands likely to sponsor a given channel.
 
 For 1:1 similarity use `tl channels similar` and `tl brands similar`.
 """
@@ -19,7 +20,7 @@ from tl_cli.client.http import get_client
 from tl_cli.filters import parse_filters
 from tl_cli.output.formatter import detect_format, output, output_single
 
-app = typer.Typer(help="Vector recommender (tags, top-channels/profiles/brands, vector inspection, profile→channel similarity)")
+app = typer.Typer(help="Recommender (similarity tags, top-channels/profiles/brands, similarity-profile inspection, profile→channel and channel→brand similarity)")
 
 
 TOP_CHANNEL_COLUMNS = ["value", "channel_id", "channel_name", "slug"]
@@ -46,7 +47,7 @@ def _handle_recommender_error(e: ApiError) -> None:
 
 @app.callback(invoke_without_command=True)
 def recommender(ctx: typer.Context) -> None:
-    """Vector recommender."""
+    """Recommender."""
     if ctx.invoked_subcommand is None:
         typer.echo(ctx.get_help())
 
@@ -59,10 +60,10 @@ def tags_cmd(
     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:
-    """List vector tag names (free).
+    """List similarity tag names (free).
 
     Use this to discover the tag names accepted by `tl recommender top`.
-    Each tag is one dimension of a channel/profile feature vector —
+    Each tag is one signal in a channel or brand similarity profile —
     e.g. content categories like "Cooking", demographic buckets like
     "Age 18-24", device shares, country shares.
 
@@ -81,7 +82,7 @@ def tags_cmd(
             data,
             fmt,
             columns=["group", "field_name"],
-            title="Recommender vector tags",
+            title="Similarity tags",
         )
     except ApiError as e:
         handle_api_error(e)
@@ -127,7 +128,7 @@ def _do_top(kind: str, tag: str, args: list[str], fmt: str, limit: int, columns:
 
 @app.command("top-channels")
 def top_channels_cmd(
-    tag: str = typer.Argument(..., help='Vector tag name (e.g. "Cooking", "Age 18-24"). Run `tl recommender tags` to discover valid names.'),
+    tag: str = typer.Argument(..., help='Similarity tag name (e.g. "Cooking", "Age 18-24"). Run `tl recommender tags` to discover valid names.'),
     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"),
@@ -135,9 +136,9 @@ def top_channels_cmd(
     toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
     limit: int = typer.Option(50, "--limit", "-l", help="Max results (1-100)"),
 ) -> None:
-    """Top channels loaded on a single vector tag.
+    """Top channels scoring high on a single similarity tag.
 
-    Costs 50 credits per call. Intelligence plan required.
+    Costs 25 credits per call. Intelligence plan required.
 
     Filters:
         msn:<yes|no|all>            MSN membership (default: all)
@@ -154,7 +155,7 @@ def top_channels_cmd(
 
 @app.command("top-profiles")
 def top_profiles_cmd(
-    tag: str = typer.Argument(..., help='Vector tag name (e.g. "Cooking", "Age 18-24"). Run `tl recommender tags` to discover valid names.'),
+    tag: str = typer.Argument(..., help='Similarity tag name (e.g. "Cooking", "Age 18-24"). Run `tl recommender tags` to discover valid names.'),
     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"),
@@ -162,9 +163,9 @@ def top_profiles_cmd(
     toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
     limit: int = typer.Option(50, "--limit", "-l", help="Max results (1-100)"),
 ) -> None:
-    """Top brand profiles loaded on a single vector tag.
+    """Top brand profiles scoring high on a single similarity tag.
 
-    Costs 50 credits per call. Intelligence plan required. Profiles can
+    Costs 25 credits per call. Intelligence plan required. Profiles can
     represent the same brand more than once (one brand → multiple
     profiles); use `top-brands` for brand-deduplicated results.
 
@@ -182,7 +183,7 @@ def top_profiles_cmd(
 
 @app.command("top-brands")
 def top_brands_cmd(
-    tag: str = typer.Argument(..., help='Vector tag name (e.g. "Cooking", "Age 18-24"). Run `tl recommender tags` to discover valid names.'),
+    tag: str = typer.Argument(..., help='Similarity tag name (e.g. "Cooking", "Age 18-24"). Run `tl recommender tags` to discover valid names.'),
     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"),
@@ -190,9 +191,9 @@ def top_brands_cmd(
     toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
     limit: int = typer.Option(50, "--limit", "-l", help="Max results (1-100)"),
 ) -> None:
-    """Top brands loaded on a single vector tag (deduplicated from profiles).
+    """Top brands scoring high on a single similarity tag (deduplicated from profiles).
 
-    Costs 50 credits per call. Intelligence plan required. Server-side
+    Costs 25 credits per call. Intelligence plan required. Server-side
     aggregates the underlying profile rows by brand, keeping the
     highest-scoring profile per brand.
 
@@ -216,10 +217,10 @@ def inspect_channel_cmd(
     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:
-    """Show a channel's feature vector grouped by category.
+    """Show a channel's similarity profile grouped by category.
 
-    Costs 50 credits per call. Intelligence plan required. Returns the
-    grouped sparse vector (active dimensions only) and the magnitude.
+    Costs 25 credits per call. Intelligence plan required. Returns the
+    active similarity tags grouped by category, plus the overall strength.
 
     Examples:
         tl recommender inspect-channel 12345
@@ -245,11 +246,11 @@ def inspect_brand_cmd(
     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:
-    """Show a brand profile's ideal feature vector grouped by category.
+    """Show a brand profile's ideal similarity profile grouped by category.
 
-    Costs 50 credits per call. Intelligence plan required. Resolves the
+    Costs 25 credits per call. Intelligence plan required. Resolves the
     brand to its (preferred MBN) profile and inspects that profile's
-    aggregated vector.
+    aggregated similarity tags.
 
     Examples:
         tl recommender inspect-brand 287
@@ -277,9 +278,9 @@ def similar_to_profile_cmd(
     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 profile's ideal vector.
+    """Channels closest to a brand profile's ideal similarity profile.
 
-    Costs 50 credits per call. Intelligence plan required. Channels the
+    Costs 25 credits per call. Intelligence plan required. Channels the
     brand has already worked with or been proposed are excluded.
 
     Filters:
@@ -312,3 +313,51 @@ def similar_to_profile_cmd(
         handle_api_error(e)
     finally:
         client.close()
+
+
+@app.command("similar-brands-to-channel")
+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:
+    """Brands most likely to sponsor a given channel.
+
+    Compares the channel's similarity profile against brand similarity
+    profiles and dedupes the results by brand. Costs 25 credits per call.
+    Intelligence plan required.
+
+    Filters:
+        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
+    """
+    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 {"mbn"}}
+    params["limit"] = str(limit)
+    encoded = urllib.parse.quote(channel_ref, safe="")
+    client = get_client()
+    try:
+        data = client.get(f"/recommender/channels/{encoded}/similar-brands", 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}%"
+        output(
+            data,
+            fmt,
+            columns=["score", "brand_id", "brand_name", "website", "mbn", "profile_id"],
+            title=f"Brands likely to sponsor channel {channel_ref}",
+            column_config={"score": {"justify": "right"}},
+        )
+    except ApiError as e:
+        _handle_recommender_error(e)
+    finally:
+        client.close()

{thoughtleaders_cli-0.6.4 → thoughtleaders_cli-0.6.6}/src/tl_cli/main.py

@@ -3,16 +3,11 @@
 Query sponsorship data, channels, brands, and intelligence.
 """
 
-import re
 import sys
 import traceback
-from pathlib import Path
-from typing import Optional
 
-import click
 import typer
 from rich.console import Console
-from rich.markdown import Markdown
 
 from tl_cli import __version__
 from tl_cli import config as tl_config
@@ -128,61 +123,6 @@ def update_command() -> None:
     raise typer.Exit()
 
 
-def _get_terminology() -> str | None:
-    """Extract the Terminology section from README.md.
-
-    Tries to locate README.md relative to the package source first,
-    then falls back to importlib.metadata.
-    """
-    try:
-        text = None
-        readme = Path(__file__).resolve().parent.parent.parent / "README.md"
-        if readme.is_file():
-            text = readme.read_text()
-        else:
-            from importlib.metadata import metadata
-            text = metadata("thoughtleaders-cli").get_payload()
-        if not text:
-            return None
-        match = re.search(r"^# Terminology\s*\n(.+?)(?=\n# |\Z)", text, re.DOTALL | re.MULTILINE)
-        if not match:
-            return None
-        return match.group(1).strip()
-    except Exception:
-        return None
-
-
-@app.command(name="help", hidden=True)
-def help_command(
-    ctx: typer.Context,
-    command: Optional[str] = typer.Argument(None, help="Command to show help for"),
-) -> None:
-    """Show help for the CLI or a specific command."""
-    root_ctx = ctx.parent
-    root_cmd = root_ctx.command
-
-    if command is None:
-        click.echo(root_cmd.get_help(root_ctx))
-        terminology = _get_terminology()
-        if terminology:
-            import shutil
-            term_width = shutil.get_terminal_size().columns
-            console = Console(width=int(term_width * 0.9))
-            console.print(Markdown(terminology))
-            console.print()
-        raise typer.Exit()
-
-    # Look up the subcommand
-    sub_cmd = root_cmd.get_command(root_ctx, command)
-    if sub_cmd is None:
-        click.echo(f"Unknown command: {command}", err=True)
-        raise typer.Exit(1)
-
-    sub_ctx = click.Context(sub_cmd, info_name=command, parent=root_ctx)
-    click.echo(sub_cmd.get_help(sub_ctx))
-    raise typer.Exit()
-
-
 def cli() -> None:
     """Entry point that wraps the Typer app with top-level error handling.
 

{thoughtleaders_cli-0.6.4 → thoughtleaders_cli-0.6.6}/uv.lock

@@ -388,7 +388,7 @@ wheels = [
 
 [[package]]
 name = "thoughtleaders-cli"
-version = "0.6.4"
+version = "0.6.6"
 source = { editable = "." }
 dependencies = [
     { name = "authlib" },