thoughtleaders-cli 0.5.0__tar.gz → 0.6.0__tar.gz

{thoughtleaders_cli-0.5.0 → thoughtleaders_cli-0.6.0}/.claude-plugin/plugin.json

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

{thoughtleaders_cli-0.5.0 → thoughtleaders_cli-0.6.0}/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). 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, 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.
 
 # Architecture
 
@@ -20,6 +20,8 @@ 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`, `inspect-channel`, `inspect-brand`, `similar-to-profile` (all 50 credits flat, Intelligence-gated). 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 "<tag>"` rather than `WHERE content_category = <code>` SQL — the recommender is ranked, not equality-based, and returns matching brand profiles alongside channels. The underlying recommender code uses "element"/"field_name" terminology; the CLI/API layer renames these to "tag" at the boundary.
+
 ## Filter Parsing (`filters.py`)
 
 `parse_filters()` handles `key:value` and `key:"quoted value"` syntax. Returns `dict[str, str]` passed as query params. Date filter keys (listed in `DATE_FILTER_KEYS` — e.g. `since`, `created-at`, `created-at-start`, `publish-date-end`) accept keywords `today`, `yesterday`, `tomorrow`. Sponsorship date fields (`created-at`, `publish-date`, `purchase-date`, `send-date`) each expose three filter shapes: bare `<field>:<date>` matches within that date/period, and `<field>-start:` / `<field>-end:` give inclusive lower/upper bounds (both sides inclusive; partial dates expand to the whole period). Empty-string values result in `IS NULL` queries on the backend.

{thoughtleaders_cli-0.5.0 → thoughtleaders_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thoughtleaders-cli
-Version: 0.5.0
+Version: 0.6.0
 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
@@ -43,11 +43,11 @@ pip install -e .
 ### As a user
 
 ```bash
-pipx install git+https://github.com/ThoughtLeaders-io/thoughtleaders-cli.git
+pipx install thoughtleaders-cli
 # or
-uv tool install git+https://github.com/ThoughtLeaders-io/thoughtleaders-cli.git
+uv tool install thoughtleaders-cli
 # or (but try to avoid it because just "pip" will not create a new venv for the product - only "uv" and "pipx" will do that)
-pip install git+https://github.com/ThoughtLeaders-io/thoughtleaders-cli.git
+pip install thoughtleaders-cli
 ```
 
 Then set up:
@@ -81,13 +81,16 @@ tl uploads list q:code --csv
 # Show upload details (supports colon-containing IDs)
 tl uploads show 1174310:0BehkmVa7ak
 
-# Search channels. msn and tpp are tri-state filters (yes/no/both; default 'both').
-# msn = opted-in to receive sponsorship offers; tpp = exclusively TL-managed.
-# Both are also returned as boolean fields on every channel response.
-tl channels list category:cooking min-subs:100k
-tl channels list msn:yes                  # MSN channels only (~11k)
-tl channels list tpp:yes                  # TPP channels only (~169)
-tl channels list msn:no min-subs:500k     # big non-MSN channels
+# Search channels via raw SQL — `tl db pg` against thoughtleaders_channel
+# (run `tl schema pg` once to confirm the live column set).
+tl db pg "SELECT id, channel_name, total_views FROM thoughtleaders_channel
+          WHERE content_category = <COOKING_CODE> AND total_views >= 100000
+          ORDER BY total_views DESC LIMIT 50 OFFSET 0"
+tl db pg "SELECT id, channel_name FROM thoughtleaders_channel
+          WHERE is_tl_channel = TRUE LIMIT 200 OFFSET 0"             # all TPP channels (~169)
+# MSN status (media_selling_network_join_date) is scrubbed from the
+# advertiser sandbox view — for MSN-only / non-MSN lookups, the
+# structured filter is the right tool: `tl channels list msn:yes|no`.
 
 # Show channel detail — accepts numeric ID or channel name.
 # Names that match more than one active channel print a candidate list
@@ -102,6 +105,16 @@ tl channels show "Economics Explained"
 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.
+tl recommender tags                              # List every tag (free)
+tl recommender tags cooking                      # Search tag names by substring
+tl recommender top "Cooking" msn:yes --limit 50  # Top channels & brand profiles for a tag
+tl recommender top "USA share" mbn:yes           # Demographic tag, MBN brands only
+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 similar-to-profile 842            # Channels closest to a brand profile
+
 # Brand intelligence
 tl brands show Nike
 
@@ -173,8 +186,6 @@ Talk naturally in Claude Code:
 Resource-specific slash commands:
 ```
 /tl-sponsorships pending with send dates in April
-/tl-channels cooking channels over 100k subscribers
-/tl-brands Nike
 /tl-reports run my Q1 pipeline
 /tl-balance
 ```

{thoughtleaders_cli-0.5.0 → thoughtleaders_cli-0.6.0}/README.md

@@ -16,11 +16,11 @@ pip install -e .
 ### As a user
 
 ```bash
-pipx install git+https://github.com/ThoughtLeaders-io/thoughtleaders-cli.git
+pipx install thoughtleaders-cli
 # or
-uv tool install git+https://github.com/ThoughtLeaders-io/thoughtleaders-cli.git
+uv tool install thoughtleaders-cli
 # or (but try to avoid it because just "pip" will not create a new venv for the product - only "uv" and "pipx" will do that)
-pip install git+https://github.com/ThoughtLeaders-io/thoughtleaders-cli.git
+pip install thoughtleaders-cli
 ```
 
 Then set up:
@@ -54,13 +54,16 @@ tl uploads list q:code --csv
 # Show upload details (supports colon-containing IDs)
 tl uploads show 1174310:0BehkmVa7ak
 
-# Search channels. msn and tpp are tri-state filters (yes/no/both; default 'both').
-# msn = opted-in to receive sponsorship offers; tpp = exclusively TL-managed.
-# Both are also returned as boolean fields on every channel response.
-tl channels list category:cooking min-subs:100k
-tl channels list msn:yes                  # MSN channels only (~11k)
-tl channels list tpp:yes                  # TPP channels only (~169)
-tl channels list msn:no min-subs:500k     # big non-MSN channels
+# Search channels via raw SQL — `tl db pg` against thoughtleaders_channel
+# (run `tl schema pg` once to confirm the live column set).
+tl db pg "SELECT id, channel_name, total_views FROM thoughtleaders_channel
+          WHERE content_category = <COOKING_CODE> AND total_views >= 100000
+          ORDER BY total_views DESC LIMIT 50 OFFSET 0"
+tl db pg "SELECT id, channel_name FROM thoughtleaders_channel
+          WHERE is_tl_channel = TRUE LIMIT 200 OFFSET 0"             # all TPP channels (~169)
+# MSN status (media_selling_network_join_date) is scrubbed from the
+# advertiser sandbox view — for MSN-only / non-MSN lookups, the
+# structured filter is the right tool: `tl channels list msn:yes|no`.
 
 # Show channel detail — accepts numeric ID or channel name.
 # Names that match more than one active channel print a candidate list
@@ -75,6 +78,16 @@ tl channels show "Economics Explained"
 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.
+tl recommender tags                              # List every tag (free)
+tl recommender tags cooking                      # Search tag names by substring
+tl recommender top "Cooking" msn:yes --limit 50  # Top channels & brand profiles for a tag
+tl recommender top "USA share" mbn:yes           # Demographic tag, MBN brands only
+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 similar-to-profile 842            # Channels closest to a brand profile
+
 # Brand intelligence
 tl brands show Nike
 
@@ -146,8 +159,6 @@ Talk naturally in Claude Code:
 Resource-specific slash commands:
 ```
 /tl-sponsorships pending with send dates in April
-/tl-channels cooking channels over 100k subscribers
-/tl-brands Nike
 /tl-reports run my Q1 pipeline
 /tl-balance
 ```

thoughtleaders_cli-0.6.0/agents/tl-analyst.md

@@ -0,0 +1,112 @@
+---
+name: tl-analyst
+description: Use when the user asks to analyze, compare, investigate, or summarize ThoughtLeaders data across multiple dimensions. Chains tl CLI commands to answer complex questions that require multiple queries, cross-referencing, or aggregation. Triggers on "analyze", "compare", "investigate", "deep dive", "cross-reference", "trend", "correlation".
+tools: [Bash, Read]
+---
+
+# TL Data Analyst Agent
+
+You are an autonomous data analyst for ThoughtLeaders. You answer complex questions that require cross-referencing, aggregation, or multi-step reasoning.
+
+## Default to raw database queries
+
+For anything beyond a trivially simple lookup, write a single raw query against the right engine instead of chaining structured `tl <resource>` commands:
+
+- **Postgres (`tl db pg`)** — joins, aggregations, multi-condition filters, fields the structured commands don't expose. Default for any deal/pipeline/brand/channel question that involves more than one filter or one aggregation.
+- **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`.
+
+One raw query beats N paginated structured walks stitched in `jq`/Python — on cost, latency, and the ES `from+size = 10000` cap.
+
+## Before Starting Any Analysis
+
+1. **Check auth**: `tl auth status`
+2. **Check balance**: `tl balance --json` — estimate total cost for your planned queries
+3. **Discover schema**:
+   - For raw queries: `tl schema pg|fb|es` — live tables/columns visible to the caller.
+   - For structured commands: `tl describe show <resource> --json`.
+4. **Check saved reports**: `tl reports --json` — a saved report might already answer the question
+
+If estimated cost > 200 credits, ask the user to confirm before proceeding.
+
+## Analysis Patterns
+
+### Aggregation / pipeline analysis (raw PG)
+"What's our best performing brand this quarter?"
+```sql
+tl db pg "SELECT b.name, SUM(a.weighted_price) AS pipeline, COUNT(*) AS deals
+          FROM thoughtleaders_adlink a
+          JOIN thoughtleaders_profile p ON a.creator_profile_id = p.id
+          JOIN thoughtleaders_profile_brands pb ON p.id = pb.profile_id
+          JOIN thoughtleaders_brand b ON pb.brand_id = b.id
+          WHERE a.publish_status = 3
+            AND a.purchase_date >= date_trunc('quarter', CURRENT_DATE)
+          GROUP BY b.name
+          ORDER BY pipeline DESC
+          LIMIT 20 OFFSET 0"
+```
+One query → ranked list. No client-side aggregation, no paginated walk.
+
+### Cross-resource analysis (raw PG)
+"Show me deal slippage this month"
+```sql
+tl db pg "SELECT a.id, a.send_date, a.publish_status, b.name AS brand, ch.channel_name
+          FROM thoughtleaders_adlink a
+          JOIN thoughtleaders_adspot s ON a.ad_spot_id = s.id
+          JOIN thoughtleaders_channel ch ON s.channel_id = ch.id
+          JOIN thoughtleaders_profile p ON a.creator_profile_id = p.id
+          JOIN thoughtleaders_profile_brands pb ON p.id = pb.profile_id
+          JOIN thoughtleaders_brand b ON pb.brand_id = b.id
+          WHERE a.publish_status = 2
+            AND a.send_date < CURRENT_DATE
+          ORDER BY a.send_date
+          LIMIT 100 OFFSET 0"
+```
+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.
+3. Union + dedupe + compile comparison table.
+
+### Report comparison (saved reports)
+"Compare Q1 to Q4 performance"
+1. `tl reports --json` → find relevant report ID
+2. `tl reports run <id> --since 2026-01-01 --until 2026-03-31 --json`
+3. `tl reports run <id> --since 2025-10-01 --until 2025-12-31 --json`
+4. Compute deltas and trends
+
+### Channel deep dive (one raw query + targeted structured calls)
+"Give me a full picture of channel 12345"
+1. `tl channels show 12345 --json` → profile, scores, demographics (structured — wraps several joins already)
+2. `tl snapshots channel 12345 --json` → growth over time (snapshots wrap interpolation logic)
+3. `tl db pg "SELECT id, send_date, publish_status, price FROM thoughtleaders_adlink WHERE ad_spot_id IN (SELECT id FROM thoughtleaders_adspot WHERE channel_id = 12345) ORDER BY send_date DESC LIMIT 100 OFFSET 0"` — deal history with the columns you actually want, no over-fetch.
+4. `tl uploads list channel:12345 --json` → recent content
+
+### Transcript / brand-mention search (raw ES)
+"Where has 'NordVPN' been mentioned organically in the last 90 days?"
+```bash
+tl db es '{"size": 0, "track_total_hits": true,
+           "query": {"bool": {"must": [
+             {"term": {"organic_brand_mentions": "5612"}},
+             {"range": {"publication_date": {"gte": "now-90d"}}}
+           ]}},
+           "aggs": {"by_channel": {"terms": {"field": "channel.id", "size": 50}}}}'
+```
+
+### Demographics screenshots check (trivially simple — structured)
+"Does channel X have demographics screenshots uploaded?"
+1. `tl channels show <id-or-name> --json` → check `demographics_updated_at`. Non-null = screenshots on file (timestamp = last OCR pass). Null = none uploaded.
+
+## Rules
+
+- **Always resolve numeric codes to human-readable labels** in your output. Never show "Status 3" — show "Sold". Status mapping: 0=Proposed, 1=Unavailable, 2=Pending, 3=Sold, 4=Rejected by Advertiser, 5=Rejected by Publisher, 6=Proposal Approved, 7=Matched, 8=Reached Out, 9=Rejected by Agency.
+- Always use `--json` for output you need to parse
+- For raw `tl db pg`, prefer one well-targeted query over multiple structured walks; remember the LIMIT/OFFSET injected defaults (LIMIT 50, OFFSET 0) and the OFFSET ≥ 10000 → 403 ceiling.
+- Always include `--limit` on structured list queries to control credit spend
+- For `tl snapshots video`, always include `--channel` (required for Firebolt performance)
+- Present final results as a clear summary with tables when appropriate
+- Show total credits consumed at the end of your analysis

{thoughtleaders_cli-0.5.0 → thoughtleaders_cli-0.6.0}/commands/tl-sponsorships.md

@@ -7,17 +7,24 @@ description: Quick sponsorship lookup. Query, filter, or show details for sponso
 
 The user wants to query sponsorships.
 
-1. Run `tl describe sponsorships --json` to discover filters
+For **trivially simple lookups** (single ID, one or two filters the structured vocabulary already supports), use `tl sponsorships`:
+1. Run `tl describe show sponsorships --json` to discover filters
 2. Translate the user's request into a `tl sponsorships` command
 3. Execute and present results
 
+For **anything non-trivial** — aggregations (totals, group-bys, percentiles), joins (sponsorship + brand + channel + owner), multi-condition filtering the structured filters can't express, or fields the structured commands don't expose (raw `publish_status`, `weighted_price`, `tx_data`, etc.) — drop down to `tl db pg` against `thoughtleaders_adlink`. Run `tl schema pg` first to see the live column list.
+
 If no specific request is given, run `tl sponsorships list --limit 10` to show recent sponsorships.
 
-Examples:
+Examples (trivial — structured):
 - "/tl-sponsorships pending with send dates in April" → `tl sponsorships list status:pending send-date:2026-04`
 - "/tl-sponsorships Nike" → `tl sponsorships list brand:"Nike"`
 - "/tl-sponsorships sold deals on mobile-first channels" → `tl sponsorships list status:sold primary-device:mobile`
 - "/tl-sponsorships deals on channels with majority US audience" → `tl sponsorships list min-us-share:50`
 - "/tl-sponsorships 12345" → `tl sponsorships show 12345`
 
+Examples (non-trivial — raw `tl db pg`):
+- "/tl-sponsorships total weighted pipeline by sales rep" → `tl db pg "SELECT owner_sales_id, SUM(weighted_price) AS pipeline FROM thoughtleaders_adlink WHERE publish_status IN (0,2,6,7,8) GROUP BY owner_sales_id ORDER BY pipeline DESC LIMIT 100 OFFSET 0"`
+- "/tl-sponsorships sold deals this month with brand and channel name" → join `thoughtleaders_adlink` ↔ `adspot` ↔ `channel` ↔ `profile` ↔ `profile_brands` ↔ `brand` (see `references/postgres-schema.md`).
+
 `tl sponsorships show <id> --json` returns extended detail fields beyond the list view, including: `impressions_guarantee`, `integration`, `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`.

{thoughtleaders_cli-0.5.0 → thoughtleaders_cli-0.6.0}/commands/tl.md

@@ -10,16 +10,16 @@ The user wants to query ThoughtLeaders data. Translate their request into the ri
 ## Steps
 
 1. Identify which resource(s) the request is about (sponsorships, deals, channels, brands, uploads, snapshots, reports)
-2. Run `tl describe show <resource> --json` to discover available filters
-3. Translate the user's natural language into a `tl` command with appropriate filters
+2. Discover the appropriate database structure, with `tl schema pg` and other commands, and formulate a raw database query solution first. Only use other commands like `tl sponsorships` if the user query is simple enough for it (run `tl describe show sponsorships` to see what it can do).
+3. Translate the user's natural language into a `tl` command
 4. Execute the command
 5. Present results clearly
 
 ## Examples
 
 - "/tl sold sponsorships for Nike in Q1" → `tl sponsorships list status:sold brand:"Nike" purchase-date-start:2026-01-01 purchase-date-end:2026-03-31`
-- "/tl cooking channels over 100k subs" → `tl channels list category:cooking min-subs:100000`
-- "/tl mobile-first US cooking channels" → `tl channels list category:cooking primary-device:mobile min-us-share:50`
+- "/tl cooking channels over 100k subs" → `tl db pg "SELECT id, channel_name, total_views FROM thoughtleaders_channel WHERE content_category = <COOKING_CODE> AND total_views >= 100000 ORDER BY total_views DESC LIMIT 50 OFFSET 0"`
+- "/tl mobile-first US cooking channels" → `tl db pg "SELECT id, channel_name, demographic_usa_share FROM thoughtleaders_channel WHERE content_category = <COOKING_CODE> AND demographic_device_primary = 'mobile' AND demographic_usa_share >= 50 ORDER BY total_views DESC LIMIT 50 OFFSET 0"`
 - "/tl Nike's sponsorship activity" → `tl brands show Nike`
 - "/tl run my Q1 report" → `tl reports --json` then `tl reports run <id>`
 - "/tl check my balance" → `tl balance`

{thoughtleaders_cli-0.5.0 → thoughtleaders_cli-0.6.0}/docs/architecture.md

@@ -2,12 +2,14 @@
 
 ## Context
 
-We're building a Python CLI (`tl`) for ThoughtLeaders that lets external customers query their sponsorship data. Inspired by Basecamp's CLI approach — agent-first, pipe-friendly, distributed as both a PyPI package and a Claude Code plugin.
+We're building a Python CLI (`tl`) for ThoughtLeaders that lets external customers query their sponsorship data. Inspired by Basecamp's CLI approach — agent-first, pipe-friendly, distributed as both a PyPI package (`thoughtleaders-cli`) and a Claude Code plugin.
 
 The CLI talks to Django API endpoints (not directly to databases) so permissions are enforced server-side and no DB credentials leave our infrastructure.
 
 **Design philosophy** (following Basecamp): The CLI is a dumb tool — structured commands are the primary interface. AI intelligence comes from the user's own agent (Claude Code, etc.) using the CLI as a tool. `tl ask` exists as an optional fallback for users without an AI agent. The skill file + `tl describe` teach agents how to use the CLI effectively.
 
+**Intended audience: AI agents.** The primary user of `tl` is an AI coding agent (Claude Code, OpenCode) acting on behalf of a human. Every surface — the structured commands, the discovery commands (`tl describe`, `tl schema`), the breadcrumbs in JSON envelopes, the skill file — is shaped to be parseable and self-explanatory to an agent. Where the structured commands hit a ceiling (joins, aggregations, filters they don't expose), we steer agents toward **raw database queries** via `tl db pg|fb|es`. One server-side aggregation beats N client-side roll-ups on cost, latency, and the `from+size = 10000` cap; raw queries are the right tool for heavy data work, not a last-resort escape hatch. The skill file's "When to use raw vs structured" guidance and the live `tl schema pg|fb|es` output are how we teach agents to make this trade-off.
+
 **Business model**: Prepaid credit balance. Customers deposit funds, credits are deducted per result returned. Different data types cost different amounts based on value. No subscriptions — pure pay-as-you-go.
 
 ## Architecture
@@ -47,22 +49,38 @@ All data commands use explicit subcommands: `list`, `show`, `create`/`add`. Runn
 | `tl uploads list [filters...]` | List video uploads (ES) |
 | `tl uploads show <id> [<id>...]` | Show upload detail(s) by ID |
 | `tl channels list [filters...]` | Search channels. Responses carry boolean `msn` (Media Selling Network) and `tpp` (TL-managed) fields; filterable via `msn:` / `tpp:` tri-state (`yes` / `no` / `both`, default `both`). |
-| `tl channels show <id>` | Show channel detail, including active adspots with price/cost/CPM |
-| `tl channels similar <id-or-name>` | Vector-similarity recommender. 50 credits; Intelligence plan. Tri-state `msn:` filter (default `yes`) and `tpp:` filter (default `both`) — each takes `yes` / `no` / `both`. Ambiguous names return 400 + candidates list. Hidden `look-alike` alias. |
+| `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 brands show <brand>` | Brand intelligence report |
-| `tl brands show <brand> --channel <id>` | Brand mentions on a specific channel |
+| `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 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) |
 | `tl comments add <adlink-id> "message"` | Add a comment (free) |
 
+### Raw database access (escape hatch for joins / aggregations / complex filters)
+
+| Command | Description |
+|---------|-------------|
+| `tl db pg "<SQL>"` | Raw read-only PostgreSQL `SELECT`. LIMIT/OFFSET optional — server fills in `LIMIT 50 OFFSET 0` defaults; explicit OFFSET ≥ 10,000 returns 403. Single statement; sqlglot-validated against an allowlist of functions. |
+| `tl db fb "<SQL>"` | Raw read-only Firebolt `SELECT`. Single-table only; WHERE must filter the leading index column with an equality or `IN` literal. |
+| `tl db es '<json>'` | Raw Elasticsearch search body against the server-fixed index alias. Top-level keys, query types, size/depth limits all gated server-side. |
+| `tl schema pg\|fb\|es` | Print live schema docs for the matching `tl db` engine (free). PG returns the role-scoped tables/columns from `information_schema`; FB returns the live column types of accepted tables; ES returns a maintained Markdown reference. |
+
 ### Flexible filtering (all list commands)
 Filters are passed as `key:value` pairs after `list`:
 ```bash
 tl sponsorships list status:sold brand:"Nike" purchase-date:2026-01
 tl sponsorships list status:pending send-date:2026-03
 tl uploads list channel:12345 type:longform since:2026-03
-tl channels list category:cooking min-subs:100k language:en
+# Channel discovery is raw SQL — the structured `tl channels list` covers
+# only narrow lookups. Default to:
+tl db pg "SELECT id, channel_name, total_views FROM thoughtleaders_channel
+          WHERE content_category = <COOKING_CODE> AND language = 'en'
+            AND total_views >= 1000000
+          ORDER BY total_views DESC LIMIT 50 OFFSET 0"
 ```
 
 Sponsorship date filtering (on `created-at`, `publish-date`, `purchase-date`, `send-date`) exposes three shapes per field:
@@ -75,10 +93,10 @@ Ranges combine freely across fields (e.g. "created in Jan that published in Marc
 | Command | Description |
 |---------|-------------|
 | `tl describe` | List all resources with credit costs |
-| `tl describe sponsorships` | Show fields, filters, and credit rate for sponsorships |
-| `tl describe sponsorships --filters` | Just the valid filters |
-| `tl describe sponsorships --fields` | Just the data fields |
-| `tl docs` | Open full docs in browser |
+| `tl describe show <resource>` | Show fields, filters, and credit rate for a resource |
+| `tl describe show <resource> --filters` | Just the valid filters |
+| `tl describe show <resource> --fields` | Just the data fields |
+| `tl schema pg\|fb\|es` | Show schema docs for raw `tl db` queries (free) |
 
 Schema metadata from server (`GET /api/cli/v1/describe/<resource>`) — always in sync. Includes credit cost per result. Free, no credits charged. Agent-friendly: `tl describe sponsorships --json`.
 
@@ -106,9 +124,11 @@ Schema metadata from server (`GET /api/cli/v1/describe/<resource>`) — always i
 | `tl doctor` | Health check (auth, connectivity, version, balance) |
 | `tl whoami` | Show current user, profile, org, and brands (free) |
 | `tl balance` | Show credit balance and recent usage |
+| `tl changelog` | Show release notes |
+| `tl update` | Self-upgrade (when installed via pipx or `uv tool`) |
 
 ### Global flags (all commands)
-`--json`, `--csv`, `--md`, `--limit N`, `--offset N`
+`--json`, `--csv`, `--md`, `--toon` (token-efficient for LLMs), `--limit N`, `--offset N`
 
 ### Agent support flag
 `--help --agent` returns structured JSON help (flags, gotchas, subcommands) for any command — optimized for AI agents to parse.
@@ -125,8 +145,6 @@ Schema metadata from server (`GET /api/cli/v1/describe/<resource>`) — always i
 |---------|-------------|
 | `/tl <request>` | Smart router — Claude interprets the request and runs the right `tl` command(s). E.g., `/tl sold sponsorships for Nike in Q1` → `tl sponsorships status:sold brand:"Nike" purchase-date-start:2026-01-01 purchase-date-end:2026-03-31` |
 | `/tl-sponsorships [query]` | Quick sponsorship lookup. E.g., `/tl-sponsorships pending with send dates in April` |
-| `/tl-channels [query]` | Channel search. E.g., `/tl-channels cooking channels over 100k subs` |
-| `/tl-brands [query]` | Brand intelligence. E.g., `/tl-brands Nike` |
 | `/tl-reports` | List and run saved reports |
 | `/tl-balance` | Check credit balance and recent usage |
 
@@ -136,12 +154,13 @@ Each slash command's markdown file instructs Claude to:
 3. Execute the command and present results
 4. Show breadcrumbs for follow-up actions
 
-#### Skill: `tl-data-analyst`
-Teaches Claude how to use the CLI effectively. Triggers on data questions about sponsorships, channels, brands, uploads, metrics.
+#### Skill: `tl`
+Teaches Claude how to use the CLI effectively. Triggers on data questions about sponsorships, channels, brands, uploads, metrics. Authoritative source lives at `skills/tl/SKILL.md` with engine-specific reference files under `skills/tl/references/` (`postgres-schema.md`, `firebolt-schema.md`, `elasticsearch-schema.md`, `business-glossary.md`).
 
 Key instructions in the skill:
-- Always run `tl describe show <resource> --json` first to discover fields, filters, and credit costs
-- Use structured commands, not `tl ask` (the user's Claude IS the AI layer)
+- Always run `tl describe show <resource> --json` (or `tl schema pg|fb|es`) first to discover fields, filters, and credit costs
+- Use structured commands for single-record lookups and simple filtered lists; **switch to `tl db pg|fb|es` for aggregations, joins, and complex filtering**
+- Don't use `tl ask` — the user's Claude IS the AI layer
 - Check `tl balance --json` before expensive queries and warn the user about credit cost
 - Use `--json` output for parsing
 - Chain commands for multi-step analysis (e.g., get brand → find channels → check snapshots)
@@ -179,12 +198,6 @@ After a `tl` command completes:
 - If `balance_remaining` < 500 credits, emits a warning to stderr
 - If command returned 402, provides a clear "deposit more credits" message with link
 
-**Stop hook** (`hooks/scripts/session-summary.sh`):
-When Claude finishes a session:
-- Summarizes total credits consumed during the session
-- Shows starting vs ending balance
-- Lists the commands that were run (parsed from session)
-
 ## Usage Metering & Pricing
 
 ### Prepaid credit balance
@@ -194,26 +207,31 @@ When Claude finishes a session:
 - Customers can opt-in to allow overage (keep working, settle later) — configurable in dashboard
 - `tl auth status` and `tl balance` show current credit balance
 
-### Credit rates by data value
-
-| Resource | List (per result) | Detail (single) | Rationale |
-|----------|-------------------|-----------------|-----------|
-| **Brand intelligence** | 5 credits | 8 credits | Core IP — competitive intelligence on who sponsors whom |
-| **Channel** | 3 credits | 5 credits | Rich profile data, demographics, scores |
-| **Sponsorship** | 2 credits | 3 credits | User's own sponsorship data |
-| **Snapshot** (Firebolt) | 1 credit | 1 credit | Time-series data points, high volume |
-| **Upload** (video) | 1 credit | 2 credits | Individual video data |
-| **Report run** | Sum of result credits | — | Charged based on what the report returns |
-| **Comment** | 0 | 0 | Operational — don't charge |
-| **Sponsorship create** | 0 | — | Free — more proposals = more future data consumption |
-| **Describe / auth / doctor** | 0 | 0 | System + discoverability must be free |
-| **`tl ask` surcharge** | +2 credits per result | — | LLM cost surcharge (waived if user provides own key) |
-
-### Credit formula per request
+### Credit rates — pricing intent
+
+Detail and history endpoints charge a flat `rate × results` (linear). List endpoints (and raw `tl db`) use a non-linear curve so a 0-row pull still pays a small floor and a 500-row pull doesn't pay 500× a 1-row pull:
+
 ```
-credits = sum(results × rate_per_result) + surcharge_if_ask
+list cost = setup + mult × scale × n^exp
 ```
 
+`setup`, `scale`, and `exp` are global shape parameters; `mult` is a per-resource complexity factor (lighter reads use 1.0, raw `tl db` uses 1.4). The live values are in `thoughtleaders/cli_metering.py` (`CLI_LIST_COST_*` settings + `CREDIT_RATES`); the live values are reported by `tl describe`.
+
+Rationale per resource — pricing follows data value:
+
+| Resource | Why it's priced where it is |
+|----------|-----------------------------|
+| **Brand intelligence** | Core IP — competitive intelligence on who sponsors whom |
+| **Channels** | Rich profile data, demographics, scores |
+| **Sponsorships** | User's own sponsorship data |
+| **Snapshots** (Firebolt) | Time-series data points, high volume → cheap |
+| **Uploads** (video) | Individual video data |
+| **Raw `tl db pg\|fb\|es`** | No role scoping, wider blast radius → 1.4× multiplier |
+| **Reports run** | Charged on what the report returns |
+| **Comments / proposal create** | Operational — free, more proposals = more future data consumption |
+| **Describe / schema / auth / doctor / whoami / balance / changelog** | System + discoverability must be free |
+| **`tl ask` surcharge** | LLM cost surcharge (waived if user provides own key via `--llm-key`) |
+
 ### Server-side metering implementation
 
 **New Django model**: `CliCreditAccount`
@@ -292,26 +310,29 @@ tl-cli/
 │   │   ├── matches.py                # tl matches (shortcut: status:match)
 │   │   ├── proposals.py              # tl proposals (shortcut: status:proposal)
 │   │   ├── uploads.py                # tl uploads (list/show)
-│   │   ├── channels.py              # tl channels (list/show)
-│   │   ├── brands.py                # tl brands show (brand intelligence)
-│   │   ├── snapshots.py             # tl snapshots (Firebolt metrics)
-│   │   ├── reports.py               # tl reports / tl reports run
-│   │   ├── comments.py              # tl comments (list/add)
-│   │   ├── describe.py              # tl describe list/show (schema/filter/pricing discovery)
-│   │   ├── ask.py                   # tl ask (optional AI fallback)
-│   │   ├── setup.py                 # tl setup claude / tl setup opencode
-│   │   ├── balance.py               # tl balance
-│   │   ├── doctor.py                # tl doctor
-│   │   └── whoami.py                # tl whoami
+│   │   ├── channels.py               # tl channels (list/show/history/similar)
+│   │   ├── brands.py                 # tl brands (show/history/similar)
+│   │   ├── snapshots.py              # tl snapshots (Firebolt metrics)
+│   │   ├── reports.py                # tl reports / tl reports run
+│   │   ├── comments.py               # tl comments (list/add)
+│   │   ├── db.py                     # tl db pg|fb|es (raw read-only queries)
+│   │   ├── schema.py                 # tl schema pg|fb|es (live schema docs)
+│   │   ├── describe.py               # tl describe list/show (schema/filter/pricing discovery)
+│   │   ├── changelog.py              # tl changelog (release notes)
+│   │   ├── ask.py                    # tl ask (optional AI fallback)
+│   │   ├── setup.py                  # tl setup claude / tl setup opencode
+│   │   ├── balance.py                # tl balance
+│   │   ├── doctor.py                 # tl doctor
+│   │   └── whoami.py                 # tl whoami
+│   ├── self_update.py                # tl update (pipx/uv self-upgrade)
+│   ├── hints.py                      # Inline tips & post-error suggestions
 │   ├── filters.py                    # key:value filter parser (parsing only)
-│   └── _completions.py              # Shell completion helpers
+│   └── _completions.py               # Shell completion helpers
 ├── .claude-plugin/
 │   └── plugin.json                   # Claude Code plugin manifest
 ├── commands/                          # Slash commands for Claude Code
 │   ├── tl.md                         # /tl — smart router
 │   ├── tl-sponsorships.md             # /tl-sponsorships — quick sponsorship lookup
-│   ├── tl-channels.md                # /tl-channels — channel search
-│   ├── tl-brands.md                  # /tl-brands — brand intelligence
 │   ├── tl-reports.md                 # /tl-reports — saved reports
 │   └── tl-balance.md                 # /tl-balance — credit balance
 ├── skills/
@@ -323,8 +344,7 @@ tl-cli/
 │   ├── hooks.json                    # Hook event bindings
 │   └── scripts/
 │       ├── pre-check.sh             # Auth + credit guard before tl commands
-│       ├── post-usage.sh            # Low balance warning after tl commands
-│       └── session-summary.sh       # Credit usage summary on session end
+│       └── post-usage.sh            # Low balance warning after tl commands
 ├── tests/
 │   ├── __init__.py
 │   ├── test_auth.py
@@ -334,7 +354,7 @@ tl-cli/
 │   └── test_commands.py
 └── .github/
     └── workflows/
-        └── release.yml               # PyPI publish on tag
+        └── python-publish.yml        # PyPI publish on release (Trusted Publishing)
 ```
 
 ### Server Side (in existing thoughtleaders repo)
@@ -450,17 +470,18 @@ Auth0 token → Django User → Profile → Organization → Plan. Plan types de
 ```toml
 [project]
 name = "thoughtleaders-cli"
-requires-python = ">=3.10"
+requires-python = ">=3.12"
 dependencies = [
     "typer[all]>=0.12",
     "rich>=13.0",
     "httpx>=0.27",
     "keyring>=25.0",
     "authlib>=1.3",
+    "toon-format>=0.9.0b1",
 ]
 ```
 
-Entry point: `tl = "tl_cli.main:app"`
+Entry point: `tl = "tl_cli.main:cli"`
 
 ## Auth Strategy
 
@@ -514,7 +535,7 @@ Build each command + its server endpoint together:
 
 ### Step 3: Plugin + commands + agent + hooks
 1. `.claude-plugin/plugin.json`
-2. `commands/` — slash commands (`/tl`, `/tl-sponsorships`, `/tl-channels`, `/tl-brands`, `/tl-reports`, `/tl-balance`)
+2. `commands/` — slash commands (`/tl`, `/tl-sponsorships`, `/tl-reports`, `/tl-balance`)
 3. `skills/tl/SKILL.md` — comprehensive skill file
 4. `agents/tl-analyst.md` — multi-step analysis agent
 5. `hooks/` — pre-check, post-usage, session-summary

{thoughtleaders_cli-0.5.0 → thoughtleaders_cli-0.6.0}/pyproject.toml

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