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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thoughtleaders-cli
-Version: 0.5.0
+Version: 0.5.2
 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:
@@ -173,8 +173,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.5.2}/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:
@@ -146,8 +146,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.2/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.5.2}/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.5.2}/commands/tl.md

@@ -10,8 +10,8 @@ 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
 

{thoughtleaders_cli-0.5.0 → thoughtleaders_cli-0.5.2}/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,15 +49,26 @@ 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
@@ -75,10 +88,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 +119,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 +140,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 +149,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 +193,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 +202,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 +305,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 +339,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 +349,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 +465,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 +530,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.5.2}/pyproject.toml

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

{thoughtleaders_cli-0.5.0 → thoughtleaders_cli-0.5.2}/skills/tl/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tl
-description: Query and analyze ThoughtLeaders business data using the `tl` CLI — structured resource commands (sponsorships, deals, channels, brands, uploads, snapshots, reports) plus raw PostgreSQL / Elasticsearch / Firebolt access via `tl db pg|fb|es`. Triggers on questions about deals, sponsorships, pipeline, revenue, brands, channels, MSN, TPP, uploads/videos, transcripts, brand mentions, view-curves, sales numbers, reports, or any cross-source business analysis ("how many deals", "pipeline report", "weighted pipeline", "channel data", "brand lookup", "view curve", "find mentions of", "investigate this video", "query the database"). Use structured tl commands — you ARE the AI layer, not tl ask.
+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 the structured resource commands (sponsorships, deals, channels, brands, uploads, snapshots, reports) only for trivially simple lookups (single-record show by ID, plain filtered lists). Triggers on questions about deals, sponsorships, pipeline, revenue, brands, channels, MSN, TPP, uploads/videos, transcripts, brand mentions, view-curves, sales numbers, reports, or any cross-source business analysis ("how many deals", "pipeline report", "weighted pipeline", "channel data", "brand lookup", "view curve", "find mentions of", "investigate this video", "query the database"). You ARE the AI layer — do not use `tl ask`.
 ---
 
 # ThoughtLeaders Data Analyst
@@ -9,9 +9,35 @@ You have access to the `tl` CLI which queries ThoughtLeaders' sponsorship platfo
 
 ## Core Principles
 
-**You are the intelligence layer.** Use structured `tl` commands, not `tl ask`. The `tl ask` command is a server-side LLM fallback for users without Claude — but the user has you. Translate their questions into the right `tl` commands.
+**You are the intelligence layer.** Don't use `tl ask` — that's a server-side LLM fallback for users without Claude. Translate the user's question into the right `tl` invocation yourself.
 
-Always run `tl describe show <resource>` before running a query against that resource. For raw-db queries, use `tl schema pg|fb|es` to get the database schemas.
+**Default to raw database queries.** For anything beyond a trivially simple lookup, reach for `tl db pg|fb|es` first. The structured `tl <resource>` commands (`sponsorships list`, `channels show`, `brands history`, etc.) are convenient shorthands for single-record lookups and plain filtered lists — but the moment the question involves joins, aggregations, multi-condition filtering, or anything you'd otherwise post-process client-side, the right tool is a single raw query. One server-side aggregation beats N paginated client-side roll-ups on cost, latency, and the `from+size = 10000` ES cap.
+
+Decision rule:
+
+- **Trivially simple** (use a structured command): "show sponsorship 12345", "list deals for Nike", "show channel 5607", "run report 42".
+- **Anything else** (use `tl db pg|fb|es`): aggregations, joins, conditions the structured filters don't expose, comparing across resources, computing rates / shares / percentiles, anything that would otherwise need a paginated walk + client-side reduce.
+
+Always run `tl describe show <resource>` before using a structured command, and `tl schema pg|fb|es` before writing a raw query.
+
+**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`) into `jq`, `yq`, `rg`, or `duckdb` 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}'
+  ```
+- **`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.
+  ```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
+  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.
 
 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.
 
@@ -135,7 +161,7 @@ The marginal per-row cost is exactly proportional to `mult` — a 1.4× resource
 
 ### Raw queries (`tl db`)
 
-When a structured `tl <resource>` command can answer the question, prefer it — authoritative, role-scoped, paginated, breadcrumbed. Drop down to `tl db pg|fb|es` only when the high-level command can't express what you need.
+`tl db pg|fb|es` is the default tool. Reach for it whenever the question is anything beyond a trivially simple lookup — and use the structured commands only for those trivial cases (single-record `show`, plain filtered `list`). Don't paginate-and-reduce in your head when one SQL or ES body would do it server-side.
 
 ```bash
 tl db pg "<SELECT ...>"     # PostgreSQL — read-only SELECT
@@ -145,27 +171,28 @@ tl db es "<JSON body>"      # Elasticsearch — search bodies against the server
 
 All three honour `--json`/`--csv`/`--md`/`--toon` and accept `-` to read from stdin (`cat q.sql | tl db fb -`). They share the list-curve at `mult=1.4` (raw queries, no role scoping, wider blast radius).
 
-**Reach for raw queries — don't simulate them client-side.** The structured `list` commands are great for filtered records. The moment the question turns into **aggregation, joining, or complex multi-condition filtering**, switch to `tl db`:
+Reasons to write a raw query (the common case):
 
-- **Aggregations** (counts, sums, avgs, group-bys, percentiles, time histograms) — push them into a single `tl db es` agg query or `tl db pg` `GROUP BY`. One server-side aggregation is faster, cheaper (one call vs N pages), and avoids the `from+size=10000` deep-pagination cap in ES.
-- **Joins** — "X plus the related Y" belongs in `tl db pg` once it ships. Until then, doing the join client-side via two paginated structured walks is a workaround — flag it as such.
-- **Complex filtering** the structured filter vocabulary can't express (compound boolean, `NOT IN`/`EXISTS`, `WHERE col IS NULL` on hidden fields, mixed range + enum + text predicates) — write it as one query rather than over-fetching and post-filtering.
+- **Aggregations** (counts, sums, avgs, group-bys, percentiles, time histograms) — one `tl db pg` `GROUP BY` or `tl db es` agg body, not a paginated walk + Python reduce.
+- **Joins / cross-table data** — `tl db pg` returns brand+channel+deal in one row instead of two structured walks stitched in `jq`.
+- **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 stay best for: single-record lookups (`tl <resource> show`), role-scoped filtered lists with simple filters, and anything where breadcrumbs/role-scoping matter.
+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).
 
 | Need | Use |
 |---|---|
-| Single-record detail lookup | `tl <resource> show <id>` |
-| Simple filtered list of records | Structured `tl <resource> list` |
-| Channel/brand similarity, history | `tl channels similar / history`, `tl brands similar / history` |
+| **Aggregations** (counts, sums, group-by, histograms, percentiles) | **`tl db pg` `GROUP BY`** or **`tl db es` agg query** |
+| **Joins / cross-table data** | **`tl db pg`** |
+| **Multi-condition filtering** the structured filters can't express | **`tl db pg` / `tl db es`** |
+| **Fields the structured commands don't expose** (raw `publish_status`, `weighted_price`, `media_selling_network_join_date`, etc.) | **`tl db pg`** |
+| 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 (vector KNN, server-implemented) | `tl channels similar`, `tl brands similar` |
 | Saved reports | `tl reports`, `tl reports run` |
-| Time-series view-curve / channel growth (default shape) | `tl snapshots channel`, `tl snapshots video` |
-| **Aggregations** (counts, sums, group-by, histograms, percentiles) | **`tl db es` agg query** or **`tl db pg` `GROUP BY`** — do not paginate-and-roll-up client-side |
-| **Joins / cross-table data** | **`tl db pg`** — single SQL query beats two paginated structured walks |
-| **Complex filtering** the structured filters can't express | **`tl db pg` / `tl db es`** rather than over-fetching and post-filtering |
-| 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` |
-| Anything requiring a Postgres column the structured commands don't expose | `tl db pg` |
+| Time-series view-curve / channel growth (default shape with interpolation) | `tl snapshots channel`, `tl snapshots video` |
 
 #### `tl db es` — Elasticsearch
 

{thoughtleaders_cli-0.5.0 → thoughtleaders_cli-0.5.2}/src/tl_cli/__init__.py

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