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

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thoughtleaders-cli
-Version: 0.6.2
+Version: 0.6.4
 Summary: ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligence
 Project-URL: Homepage, https://thoughtleaders.io
 Project-URL: Repository, https://github.com/ThoughtLeaders-io/thoughtleaders-cli

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

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

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

@@ -56,7 +56,7 @@ The centre of the data model is **Sponsorships** — business relationships betw
   - **Proposals** — matches that have been proposed to both sides to consider
   - **Deals** — contractually agreed-upon sponsorships (sold), either in production or published
 
-Sponsorships are sometimes called "Ads" or "Ad campaigns". An obsolete name for "sponsorship" is an "adlink".
+Sponsorships are sometimes called "Ads" or "Ad campaigns". **"AdLink"** is another name for the same thing — it's the term the database uses (`thoughtleaders_adlink`) and shows up across internal code, schema docs, and AM Slack threads. Treat "sponsorship" and "adlink" as interchangeable; the user-facing word is "sponsorship," the engineering/DB word is "adlink."
 
 The CLI has shortcut commands for each type: `tl matches`, `tl proposals`, `tl deals`. These filter `tl sponsorships` by status.
 

thoughtleaders_cli-0.6.4/skills/tl/references/business-glossary.md

@@ -0,0 +1,243 @@
+# ThoughtLeaders Business Glossary
+
+Maps business terms to database concepts.
+
+## Revenue & Deal Lifecycle
+
+| Business Term | DB Concept | Notes |
+|--------------|------------|-------|
+| **Revenue / Sold ad** | `adlink.publish_status = 3` (SOLD) | Only status=3 counts as real revenue |
+| **Gross ads / Gross revenue** | `SUM(adlink.price)` where sold | Total advertiser spend |
+| **Net revenue / TL profit** | `price - cost` per adlink | What TL earns as a company |
+| **Cost** | `adlink.cost` | What the channel earns |
+| **Price** | `adlink.price` | What the advertiser pays |
+| **Closed-lost** | `publish_status IN (4, 5, 9)` | All three rejection statuses |
+| **Open opportunity** | `publish_status IN (0, 2, 6, 7, 8)` | Pipeline — not revenue, not lost |
+| **Proposal Approved** | `publish_status = 6` | AM approved to show to brand — NOT brand approval. Internal gate only. |
+| **Pending** | `publish_status = 2` | Brand has agreed — this is the real high-intent signal |
+| **Weighted pipeline** | `SUM(weighted_price)` for open opps | Pre-calculated on save |
+| **Ad is live** | `publish_date IS NOT NULL` | Until publish_date is set, ad is not on YouTube |
+| **Cancellation risk** | Sold but `publish_date IS NULL` | Sold deals without publish_date can still be canceled |
+
+## Performance Grade (`adlink.performance_grade`)
+
+| Value | Label | Description |
+|-------|-------|-------------|
+| 0 | Pending | Not yet graded (treat as NULL) |
+| 1 | Loser | Underperforming ad — do not renew |
+| 2 | Neutral | Mixed results — test one more time, ideally at a better rate. Second test determines if channel becomes Loser or Winner |
+| 3 | Winner | High-performing ad — should always be renewed |
+
+**Renewal logic:** All Winners should be renewed. Neutrals get one more test (ideally at a lower CPM), then reclassified as Winner or Loser.
+
+## View Guarantees
+
+| Field | Description |
+|-------|-------------|
+| `adlink.impressions_guarantee` | The number of views guaranteed for the ad (bigint). 0 or NULL = no guarantee. |
+| `adlink.view_guarantee_hit_date` | Timestamp when the guarantee was met. NULL = not yet hit or no guarantee. |
+| `adlink.projected_views_at_purchase_date` | Projected views at time of purchase (used for CPM estimation). |
+
+## Entities
+
+| Business Term | DB Table | Notes |
+|--------------|----------|-------|
+| **Deal / Sponsorship** | `thoughtleaders_adlink` | One brand ↔ channel placement |
+| **Brand** | `thoughtleaders_brand` | Advertiser entity (the buying-side brand) |
+| **Brand profile** | `thoughtleaders_profile` | Advertiser entity / account |
+| **Organization** | `thoughtleaders_organization` | Parent entity for profiles |
+| **Channel** | `thoughtleaders_channel` | YouTube channel |
+| **Ad Spot (Catalogue item)** | `thoughtleaders_adspot` | TL's catalogue of buyable placements. Price/cost on adspot are *list prices* only — each adlink (instance) can have completely different price/cost |
+| **Campaign** | `dashboard_campaign` | Groups multiple deals |
+
+## Ad Spots & Channels
+
+- A channel can have **multiple ad spots** because different people sell the same channel (talent manager, direct, multiple agencies)
+- Ad spots are the **catalogue** — adlinks are **instances** of catalogue items
+- Price/cost on adspot = list/catalog values; price/cost on adlink = actual deal values
+- **Only one active adspot with integration=mention per channel at any time** (MSN rule)
+
+## Ownership & Accountability
+
+| Field | Model | Meaning |
+|-------|-------|---------|
+| `owner_sales_id` | `adlink` | **Most important.** Person responsible for closing the deal and for the revenue. Final accountability. |
+| `owner_advertiser_id` | `adlink` | Brand-side owner for this specific deal |
+| `owner_publisher_id` | `adlink` | Channel-side owner for this specific deal |
+| `owner_advertiser_id` | `profile` | **Account owner.** Who owns the brand relationship overall. Often same person as owner_sales on adlinks, but not always. |
+| `owner_publisher_id` | `profile` | Channel relationship owner on the profile level |
+| `owner_sales_id` | `profile` | Sales owner at profile level |
+
+**Key insight:** Ownership exists on both `profile` (account-level) and `adlink` (deal-level). For revenue attribution, always use `adlink.owner_sales_id`.
+
+## MSN (Media Selling Network)
+
+- Channels where TL has **≥80% confidence** they can buy an ad tomorrow
+- Key data: **who is the contact** to buy the ad from
+- `thoughtleaders_channel.media_selling_network_join_date` = when channel joined MSN
+- `thoughtleaders_channel.is_tl_channel` = TPP/VIP channel (subset of MSN)
+- **Rule:** Only one active adspot with `integration=mention` per channel at any time
+- MSN quality depends on having current, accurate contact info
+
+## Channels & Audience
+
+Vocabulary that AMs use about channels, mapped to the actual DB encoding. Most of these are silent-wrong-name traps where the team term doesn't match the column name.
+
+| Business Term | DB Concept | Notes |
+|---------------|------------|-------|
+| **Subscribers** | `thoughtleaders_channel.reach` (bigint) | ⚠️ There is no `subscribers` column. The DB column is `reach`. |
+| **MSN member** | `media_selling_network_join_date IS NOT NULL` | Whole MSN pool. NOT `is_tl_channel = true` — that's the VIP subset only. |
+| **TPP / VIP channel** | `is_tl_channel = true` | The small VIP subset of MSN (~144 channels at 100k+ reach). Don't use as a general "MSN" proxy — silently drops ~98% of MSN. |
+| **Active channel** | `is_active = true AND last_published >= CURRENT_DATE - INTERVAL '120 days'` | Standard filter for "channel is live and posting." Always include `is_active = true` in channel queries. |
+| **Country / Geo of a deal** | `thoughtleaders_channel.country` (ISO 3166-1 alpha-2) | `thoughtleaders_adlink` has NO geo column. Geo for sponsorships almost always means the channel's country. |
+| **Language of a channel** | `thoughtleaders_channel.language` (short ISO 639 code) | ⚠️ Short ISO 639 codes — NOT BCP-47. Mostly 2-letter ISO 639-1 (`en`, `pt`, `hi`) for major languages; occasionally 3-letter ISO 639-2/3 (`arc`, `arz`, `ase`, `ceb`) for languages without a 2-letter code. Filtering with BCP-47 (`en-US`/`pt-BR`) returns zero. Don't assume `LENGTH(language) = 2`. |
+| **Brand on a deal** | `adlink → creator_profile_id → profile_brands.profile_id → profile_brands.brand_id → brand` | 3-table chain. There is NO direct `brand_id` on adlink. See [postgres-schema.md](postgres-schema.md). |
+| **Channel on a deal** | `adlink.ad_spot_id → adspot.channel_id → channel` | NO direct `channel_id` on adlink. |
+| **Brand-virgin / VPN-virgin (etc.)** | Channel has no `adlink` row joined to any of the target brand_ids | Used in candidate sourcing ("never sponsored by any VPN brand"). Caveat: only catches TL-brokered deals; channels that ran the brand directly (no TL involvement) appear "virgin" but aren't — cross-check ES `sponsored_brand_mentions` before final outreach. |
+| **Channel quality score** *(internal-only)* | `sponsorship_score` on the indexed channel doc + `thoughtleaders_channel.sponsorship_score` (PG) | TL-internal composite score combining engagement, fulfillment, and historical sponsorship performance. **Use it internally to rank/tiebreak candidates, but do NOT quote the raw decimal in AM-facing or external output** — the score isn't documented to AMs and the absolute value isn't meaningful without context. In AM-facing prose, translate to qualitative language: "top-quartile fit," "strongest quality score in the candidate set," "high sponsorship-quality signal." |
+
+## Projected Views (PV) — three related but distinct fields
+
+AMs use "PV" loosely. There are three different DB fields, each meaning something different:
+
+| AM Term | DB Field | What it actually is |
+|---------|----------|---------------------|
+| **PV (channel baseline)** | `thoughtleaders_channel.impression` | Channel-level "typical views per video" used as CPM denominator. ⚠️ Coverage and freshness vary; cross-check Firebolt longform median for hero-tier deals. |
+| **PV (deal-specific)** | `thoughtleaders_adlink.projected_views_at_purchase_date` | Snapshot of projected views at the moment the deal was sold. Use this for historical CPM analysis. |
+| **VG (View Guarantee)** | `thoughtleaders_adlink.impressions_guarantee` | The contractual minimum views the brand is guaranteed. 0/NULL = no guarantee. NOT the same as PV — VG is a contractual floor, PV is an estimate. |
+
+When an AM says "what's the PV on this channel?" — they almost always mean `channel.impression`. When they say "what was the PV on this deal?" — they mean `adlink.projected_views_at_purchase_date`. When they say "did we hit the VG?" — they mean `adlink.view_guarantee_hit_date IS NOT NULL`.
+
+## Channel Sponsorship Signals
+
+Two derived metrics on the indexed channel doc that AMs use to qualify a channel before pitching. Both are pre-aggregated in the search index, computed against historical sponsored-content patterns.
+
+| AM Term | Underlying field | Definition | What an AM does with it |
+|---------|------------------|------------|--------------------------|
+| **Fulfillment rate** | `fulfillment_rate` (channel doc, scaled_float) | The share of a channel's content that is sponsored — `sponsored / all` content over the measurement window, expressed as a fraction. Higher = the channel reliably delivers paid integrations. | Quality signal: a high fulfillment rate means past brands have actually run on this channel, not just been pitched. AMs use it to filter out "looks promising but never closes" channels. |
+| **Renewal rate** | `renewal_rate` (channel doc, scaled_float) | The rate at which a brand-channel sponsorship relationship repeats over time, computed from clusters of sponsorship deals between a single subject (channel or brand) and its linked entities, with date-distribution heuristics (default 365-day max interval). | Loyalty signal: a high renewal rate means brands keep coming back to this channel. AMs use it to identify "sticky" channels worth premium positioning, and to flag low-renewal channels as one-shots. |
+
+Both metrics live on the channel side of the indexed video docs (the `channel.*` nested object). Channel pages in TL's product surface these as quality scores; in AM-facing reports, you can quote them as percentages (`0.45 → "45% renewal rate"`).
+
+## Industry Terms vs TL Vocabulary
+
+Some MarTech-industry terms are **NOT used at TL.** When you encounter them in a question, prompt, or message — translate to TL-native vocabulary before querying or answering. If you see one of these on the left, swap to the right.
+
+| Industry term (don't use) | TL-native equivalent | Notes |
+|---------------------------|----------------------|-------|
+| **Flight** (a single ad-run instance) | **deal** / **sponsorship** / **adlink** | One row in `thoughtleaders_adlink`. "Every flight" → "every deal." |
+| **Flight** (a campaign time window) | **window** / **campaign window** | "60-day flight" → "60-day window." Or just specify dates. |
+| **Flight cadence** | **deal cadence** / **renewal cadence** | How often deals run on a channel. |
+| **Flight-over-flight** | **deal-over-deal** / **renewal-over-renewal** | Comparing successive deals on the same channel. |
+| **Post-flight** | **post-publish** / **post-deal** | After the deal/ad has run. |
+
+**General rule:** if you reach for an ad-industry term that isn't already in this glossary, check whether TL actually uses it before introducing it.
+
+## Infrastructure Terms — Translate Before User-Facing Output
+
+AMs and brand-facing readers don't know (or care) what Postgres, Elasticsearch, or Firebolt are. **When surfacing data in any AM-facing or external output, translate infrastructure names and column names to business language.** Internal engineering chats are the only place these raw terms belong.
+
+| Internal term (don't use in AM/external output) | AM-friendly translation | What it actually is |
+|---|---|---|
+| **PG** / **Postgres** / `thoughtleaders_*` table names / `tl db pg` invocations | **"our deals data"** / **"TL's deals book"** / **"our pipeline"** | The relational DB that holds deals, brands, channels, profiles — the source of truth for what TL has brokered |
+| **ES** / **Elasticsearch** / `tl-platform-*` indices / `tl db es` invocations | **"TL's YouTube content tracking"** / **"our video index"** / **"our scraped video data"** | The search index that holds tracked YouTube videos, brand mentions, transcripts — the wider market view |
+| **Firebolt** / `article_metrics` / `channel_metrics` / `tl db fb` invocations | **"historical metrics"** / **"view-curve data"** | The data warehouse that stores time-series snapshots — used for trend analysis |
+| `sponsored_brand_mentions` (ES field) | **"tracked sponsorships"** / **"logged sponsored mentions"** / **"sponsored videos we tracked"** | Per-video brand-ID tags showing which brands paid for that video |
+| `organic_brand_mentions` (ES field) | **"organic / unpaid mentions"** | Brand mentioned in a video without a paid sponsorship |
+| `publish_status = 3` | **"sold"** | Already in glossary; never write the integer to AMs |
+| `creator_profile_id` chain / 3-table join | **"the brand's record"** | Engineering plumbing for brand lookup; AMs just hear "the brand" |
+| `reach` (PG column) | **"subscribers"** | Already in glossary; AMs say subscribers, SQL says reach |
+| `impression` (PG column) | **"projected views"** / **"PV"** | Already in glossary; flagged for reliability caveats |
+
+### Common translations in context
+
+When you'd write internally → write this for an AM:
+
+| Internal phrasing | AM-friendly phrasing |
+|---|---|
+| "Pulling ES `sponsored_brand_mentions` for the market view" | "Cross-checking against our video tracking data" |
+| "ES has 11,304 sponsored mentions of Robinhood" | "Robinhood ran 11,304 sponsored videos in the last 12 months" |
+| "PG has 139 sold adlinks for brand_id=29332" | "We sold Investing.com 139 sponsorships" |
+| "Firebolt `article_metrics` 180-day longform median" | "Recent typical-video views over the last 6 months" |
+| "Filter on `publish_status=3` AND `purchase_date>=2025-01-01`" | "Sold deals since the start of 2025" |
+
+**General rule:** if a sentence mentions `tl db pg|fb|es` invocations, table names, column names, or integer codes, ask yourself — *would the AM Slack me a question using this language?* If no, translate. The infrastructure exists to serve the AM; the AM shouldn't have to know it exists.
+
+## Teams & Ownership
+
+### Brand-led Revenue (Sales / Account Management)
+
+These teams close deals and manage brand relationships. Revenue is attributed via `adlink.owner_sales_id`.
+
+**Emma's team:**
+| Person | auth_user.id | Owner field |
+|--------|-------------|-------------|
+| Emma | 11158 | `adlink.owner_sales_id` |
+| Orli | 2042 | `adlink.owner_sales_id` |
+| Eli | 20836 | `adlink.owner_sales_id` |
+| Grace | 20835 | `adlink.owner_sales_id` |
+| Mark | 23979 | `adlink.owner_sales_id` |
+| Abbie | 23978 | `adlink.owner_sales_id` |
+| Ariella | 23977 | `adlink.owner_sales_id` |
+
+**Nicole's team:**
+| Person | auth_user.id | Owner field |
+|--------|-------------|-------------|
+| Nicole | 9929 | `adlink.owner_sales_id` |
+| Maika | 5412 | `adlink.owner_sales_id` |
+| Yuval | 14252 | `adlink.owner_sales_id` |
+| Revital | 14251 | `adlink.owner_sales_id` |
+
+### Network Growth (SDR / Partnerships) — Pauline's team
+
+Responsible for growing the MSN (new channels) and MBN (new brands). SDR outreach on both sides.
+
+| Person | auth_user.id | Role | Owner field |
+|--------|-------------|------|-------------|
+| Pauline | 218 | Team lead | `adlink.owner_publisher_id` (channel handovers) |
+| Morgan | 5710 | Channel SDR | — |
+| Jen | 873 | Channel SDR | — |
+| Ruby Jean | 9011 | Channel SDR | — |
+| Molly | 11361 | Channel SDR | — |
+| Pierra | 11323 | Brand SDR | — |
+| Nian | 8795 | Brand SDR | — |
+
+### Ad Ops — Jody's team
+
+Manages getting sold ads published. `profile.owner_publisher_id` = ad ops manager of an account.
+
+| Person | auth_user.id | Owner field |
+|--------|-------------|-------------|
+| Jody | 71 | `profile.owner_publisher_id` (account-level ad ops owner) |
+| Kathleen | 9274 | `profile.owner_publisher_id` |
+| Shane | 18159 | `profile.owner_publisher_id` |
+| Kevin | 5799 | `profile.owner_publisher_id` |
+| Airis | 5804 | `profile.owner_publisher_id` |
+| Lara | 10743 | `profile.owner_publisher_id` |
+| Josh | 11592 | `profile.owner_publisher_id` |
+
+### Querying by team
+
+```sql
+-- Emma's team pipeline
+SELECT ... FROM thoughtleaders_adlink al
+WHERE al.owner_sales_id IN (11158, 2042, 20836, 20835, 23979, 23978, 23977)
+
+-- Nicole's team pipeline
+SELECT ... FROM thoughtleaders_adlink al
+WHERE al.owner_sales_id IN (9929, 5412, 14252, 14251)
+
+-- All brand-led revenue (both teams)
+SELECT ... FROM thoughtleaders_adlink al
+WHERE al.owner_sales_id IN (11158, 2042, 20836, 20835, 23979, 23978, 23977, 9929, 5412, 14252, 14251)
+
+-- Pauline's network growth team (channel SDRs)
+-- owner_publisher_id on adlink for channel-side work
+SELECT ... FROM thoughtleaders_adlink al
+WHERE al.owner_publisher_id IN (218, 5710, 873, 9011, 11361)
+
+-- Jody's ad ops team accounts (profile-level ownership)
+SELECT ... FROM thoughtleaders_profile p
+WHERE p.owner_publisher_id IN (71, 9274, 18159, 5799, 5804, 10743, 11592)
+```
+

{thoughtleaders_cli-0.6.2 → thoughtleaders_cli-0.6.4}/skills/tl/references/elasticsearch-schema.md

@@ -90,7 +90,21 @@ Raw mappings (read-only links — out of band, not via `tl`):
 | `banner_ads` | object | Banner ad data |
 | `not_sponsored_by` | object | Explicitly not sponsored by |
 
-#### Channel Fields (on video docs via `channel.id`, or on channel parent docs)
+#### Channel Fields
+
+> ⚠️ **The embedded `channel.*` object on video (article) docs is a denormalized SUBSET — NOT the full channel schema.** The full field list below exists only on **channel parent docs** (`doc_type: "channel"`). On article docs, `channel.*` contains at most **6 fields**: `id`, `country`, `language`, `content_category`, `format`, `publication_id`. **`reach`, `subscribers`, `impression`, `channel_name`, `sponsorship_score`, `is_tl_channel`, etc. are NOT on the embedded object.** Filtering article docs by `channel.reach` returns zero results silently — query the parent channel doc, or join PG `thoughtleaders_channel` for those fields.
+>
+> Also: `channel.country` is missing on ~14% of article docs even when `channel` itself exists, so a bare `{"term": {"channel.country": "US"}}` filter silently drops those rows. **A bare `exists` clause does NOT fix this** — in a filter context it also rejects missing values, just explicitly. To include the missing-country rows alongside US (treat them as "country unknown"), use a `should` split:
+> ```json
+> {"bool": {"should": [
+>   {"term": {"channel.country": "US"}},
+>   {"bool": {"filter": [{"exists": {"field": "channel.id"}}],
+>             "must_not": [{"exists": {"field": "channel.country"}}]}}
+> ], "minimum_should_match": 1}}
+> ```
+> To **separately count** the missing rows, use a `filters` aggregation with `exists` / `must_not exists` branches.
+
+The full table below applies to **channel parent docs only**:
 
 | Field | Type | Description |
 |-------|------|-------------|

{thoughtleaders_cli-0.6.2 → thoughtleaders_cli-0.6.4}/skills/tl/references/postgres-schema.md

@@ -42,7 +42,7 @@ The main deals table. Each row = one sponsorship deal between a brand and a YouT
 | `weighted_price_currency` | varchar | Always USD |
 | `cost` | numeric | Cost to TL |
 | `ad_spot_id` | int FK | → `thoughtleaders_adspot.id` |
-| `creator_profile_id` | int FK | → brand/advertiser profile |
+| `creator_profile_id` | int FK | → `thoughtleaders_profile.id` (the brand/advertiser's profile). ⚠️ The table is named `thoughtleaders_profile`, NOT `creator_profile` — the "creator_" prefix lives on the FK column, not the table. |
 | `owner_advertiser_id` | int FK | → `auth_user.id` (brand-side owner) |
 | `owner_publisher_id` | int FK | → `auth_user.id` (channel-side owner) |
 | `owner_sales_id` | int FK | → `auth_user.id` (sales rep) |
@@ -56,8 +56,8 @@ The main deals table. Each row = one sponsorship deal between a brand and a YouT
 | `draft_expected_date` | date | Expected draft delivery |
 | `actual_end_date` | timestamptz | Actual end date |
 | `scheduled_end_date` | timestamptz | Scheduled end date |
-| `rejection_reason` | int | Rejection reason code |
-| `rejection_reason_details` | text | Free-text rejection details |
+| `rejection_reason` | int | Rejection reason code (1–24). See "`rejection_reason` Constants" below for the code → label mapping. Set when `publish_status IN (4, 5, 9)` (closed-lost). |
+| `rejection_reason_details` | text | Free-text rejection details. Often empty (~78% of lost deals). When populated, contains AM/agency notes like *"english content only"*, *"isn't talking about stocks"*, *"channel does not exist"*. Use as supplementary context, not primary classification. |
 | `payment_status` | int | 0=Unpaid, 1=Paid |
 | `performance_grade` | int | Performance rating (see business-glossary) |
 | `article_id` | varchar | Compound `<channel_id>:<youtube_id>` — links to ES `_id` and ES `id` field |
@@ -82,6 +82,66 @@ The main deals table. Each row = one sponsorship deal between a brand and a YouT
 | -1 | CLIENT_SIDE_AVAILABLE | Client Side Available | — |
 | -2 | CLIENT_SIDE_TAKEN | Client Side Taken | — |
 
+#### `rejection_reason` Constants
+
+Source of truth: `thoughtleaders.models.AdLink.REJECTION_REASON` (Django `IntegerField` choices in the main `thoughtleaders` repo).
+
+**Storage model:** `thoughtleaders_adlink.rejection_reason` is an `IntegerField`. **Postgres stores only the integer code.** The labels live in the Django `IntegerField.choices` tuple in application code — they are NOT a queryable column or a join key. The integer is the only thing you can `WHERE` against; the labels below are display mappings only.
+
+The **Enum Label** column is the verbatim string from the Django choices tuple (some have typos / internal vocabulary). The **AM-friendly label** is the recommended phrasing for AM-facing reports and proposals — use it when surfacing rejection reasons in any human-readable output.
+
+**Grouping — be careful, codes 18–24 are NOT homogeneous:**
+- **Codes 1–9** — brand-side rejections (brand said no)
+- **Codes 10–17** — publisher-side rejections (channel said no)
+- **Code 18 (`DEMOGRAPHICS_NO_MATCH`)** — audience-fit mismatch. Neither side is "wrong"; the channel may be excellent but its audience doesn't align with the brand's target. Don't bucket as "channel quality."
+- **Codes 19, 21, 22, 24** (`NOT_BRAND_SAFE`, `HIGH_VOLATILITY`, `LOW_ENGAGEMENT`, `NO_FACE_ON_SCREEN`) — channel-quality / channel-performance signals (production and delivery).
+- **Code 20 (`POOR_BRAND_HISTORY`)** — **brand-quality**, NOT channel quality. The brand has a poor sponsorship track record (e.g., known to ghost / pay late / be difficult). Do not include when reporting on channel quality.
+- **Code 23 (`DUPLICATE_PROPOSAL`)** — **process/timing**, NOT channel quality. Channel was pitched too recently. Outreach-cadence issue.
+
+⚠️ Naïve "codes 18–24 = channel quality" bucketing will misattribute brand-quality (20), audience-fit (18), and process (23) failures to channel quality and skew rejection-rate analysis.
+
+| Code | Constant | Enum Label (verbatim from Django) | AM-friendly label |
+|------|----------|---------------------|-------------------|
+| 1 | OTHER | Other (brand) | Brand declined — other reason |
+| 2 | COMPETITOR | Channel works with competitor (brand) | Channel runs a competitor |
+| 3 | NO_MATCH | Doesn't fit together (brand) | Brand says channel isn't a fit |
+| 4 | DISLIKE | Doesn't like the channel | Brand doesn't want this channel |
+| 5 | PRICING | Price is unreasonable | Brand says price is too high |
+| 6 | WORKING_TOGETHER | Already working together with the channel | Already running with this channel |
+| 7 | TIMING | Timing is off (brand) | Brand timing — not now |
+| 8 | NO_RESPONSE | Channel did not respond | Channel never replied |
+| 9 | DO_NOT_CONTACT | Do not contact channel | Channel is on do-not-contact list |
+| 10 | PUBLISHER_OTHER | Other (publisher) | Channel declined — other reason |
+| 11 | PUBLISHER_COMPETITOR | Works with competitor (publisher) | Channel already runs the competitor |
+| 12 | PUBLISHER_NO_MATCH | Doesn't fit together (publisher) | Channel says brand isn't a fit |
+| 13 | PUBLISHER_DISLIKE | Doesn't like the brand | Channel doesn't want this brand |
+| 14 | PUBLISHER_PRICING | Brand Price is too low | Channel says price is too low |
+| 15 | PUBLISHER_WORKING_TOGETHER | Already working together with the brand | Channel already running with brand |
+| 16 | PUBLISHER_TIMING | Timing is off (publisher) | Channel timing — not now |
+| 17 | PUBLISHER_NO_RESPONSE | Brand did not respond | Brand never replied |
+| 18 | DEMOGRAPHICS_NO_MATCH | Demographics don't fit | Audience demographics don't match |
+| 19 | NOT_BRAND_SAFE | Not brand safe | Brand-safety concern |
+| 20 | POOR_BRAND_HISTORY | Poor brand sponsorship history | Brand has a poor sponsorship track record |
+| 21 | HIGH_VOLATILITY | High Volatility | Channel views are too volatile |
+| 22 | LOW_ENGAGEMENT | Low engagement/Low views | Low engagement or low views |
+| 23 | DUPLICATE_PROPOSAL | Duplicate proposal | Already pitched recently |
+| 24 | NO_FACE_ON_SCREEN | No face on screen | Channel doesn't show a host on screen |
+
+#### Which date column for which question?
+
+`thoughtleaders_adlink` has multiple timestamps. Picking the wrong one silently distorts trend analysis (e.g. grouping by `created_at` mixes outreach-blast batches with steady-state activity; grouping by `purchase_date` drops everything that didn't sell because rejected/pipeline rows have NULL `purchase_date`).
+
+| Question | Use |
+|---|---|
+| "How many deals **sold** in year X?" | `purchase_date` (only set on sold/transacted deals) |
+| "How many deals **created** in year X?" (incl. pipeline + lost) | `created_at` |
+| "How much was **active outreach** in window X?" | `outreach_date` (sparse — falls back to `created_at` if null) |
+| "When did the ad **go live on YouTube**?" | `publish_date` — null means not yet published; sold deals can still be canceled until this is set |
+| "Latest activity / pipeline aging" | `updated_at` |
+| "When was the deal **proposed/presented/rejected**?" | `proposal_approved_date` / `presented_date` / `rejected_date` (each only set when that stage was reached) |
+
+**Default for "deals over time" reporting:** `created_at` if you want all flow, `purchase_date` if you want only revenue.
+
 #### Pipeline Stages
 
 - **Active pipeline** = statuses with weight > 0: 0, 2, 6, 7, 8.
@@ -125,13 +185,50 @@ A channel can have multiple adspots (different sellers: talent manager, direct,
 | Column | Type | Description |
 |--------|------|-------------|
 | `id` | int | Primary key |
-| `channel_name` | varchar | Display name |
-| `external_channel_id` | varchar | YouTube channel ID (`UCxxxxxx`). ⚠️ There is NO `youtube_id` column. |
+| `channel_name` | varchar | Display name. ⚠️ The column is `channel_name`, NOT `name`. |
+| `external_channel_id` | varchar | YouTube channel ID (e.g., `UCxxxxxx`). ⚠️ There is NO `youtube_id` column — use this one. |
 | `url` | varchar | Channel URL |
-| `media_selling_network_join_date` | date/timestamptz | When channel joined MSN |
-| `is_tl_channel` | boolean | True = TPP/VIP channel |
+| `reach` | bigint | Subscriber count. ⚠️ There is NO `subscribers` column — `reach` is the subscriber count. Many internal docs and outputs use the word "subscribers"; in SQL, always query `reach`. |
+| `media_selling_network_join_date` | date/timestamptz | When channel joined MSN. **MSN membership = this column IS NOT NULL.** |
+| `is_tl_channel` | boolean | True = TPP/VIP channel (the small VIP subset, ~144 channels at 100k+ reach). ⚠️ **`is_tl_channel` is NOT the MSN flag.** Naive `WHERE is_tl_channel = true` as an "MSN filter" silently drops ~98% of the MSN pool (8,652 → 144 at 100k+). For MSN, use `media_selling_network_join_date IS NOT NULL`. |
+| `content_category` | int | Content category code (1–22). See "`content_category` Constants" below for the code → label mapping. ⚠️ **Data-quality notes:** (1) per-row category assignments are often inconsistent with the official label (e.g. cat 15 = Technology, but many top-`reach` channels in cat 15 are clearly Entertainment). (2) Several codes are essentially unused in practice — codes 1, 2, 4, 6, 7, 8, 9, 11, 13 (Backend Development, Design, Frontend Development, Marketing, Mobile Development, Sales, Travel, Photography, Personal Finance) return ~0 active high-reach channels. Most travel creators land under Lifestyle (5), not Travel (9). The label table below is authoritative; the per-row assignment is best-effort. **For topic/category discovery, prefer `tl recommender top-channels "<tag>"` (ranked) over `WHERE content_category = <code>` (equality). |
+| `is_active` | boolean | Whether the channel is active. ⚠️ **Always include `is_active = true` in channel queries** unless explicitly looking for archived rows. |
+| `country` | varchar | Channel's primary country (ISO 3166-1 alpha-2 code, e.g. `US`, `GB`, `BR`). Often the cleanest answer to "geo" questions on sponsorships (since adlink itself has no geo). May be NULL or blank on ~10% of channels. |
+| `language` | varchar | Primary content language. ⚠️ **Short ISO 639 codes — NOT BCP-47.** Mostly 2-letter ISO 639-1 (`en`, `pt`, `hi`) for major languages; occasionally 3-letter ISO 639-2/3 (`arc`, `arz`, `ase`, `ceb`) for languages without a 2-letter code. Filtering with `language = 'en-US'` returns zero rows. **Don't assume `LENGTH(language) = 2`** — that silently drops the 3-letter long-tail. May be NULL on ~10% of channels. |
+| `last_published` | date | Date of the channel's most recent video. Use for "is the channel still active?" filters — e.g. `last_published >= CURRENT_DATE - INTERVAL '120 days'`. |
+| `sponsorship_score` | double precision | TL-internal channel quality score (higher is better). Useful as a tiebreaker when ranking candidate channels. |
+| `description` | text | LLM-generated description of the channel. Sometimes useful as a regex-target for thematic filtering when the integer category is too coarse (e.g. filtering "Technology" cat 15 down to actual tech reviewers via keywords like `tech|gadget|review|software`). |
 | `evergreenness` | float | Cached evergreen score |
 
+#### `content_category` Constants
+
+Source of truth: `thoughtleaders.taxonomies.ContentCategory` (Django `IntEnum` in the main `thoughtleaders` repo).
+
+| Value | Constant | Pretty Label |
+|-------|----------|--------------|
+| 1 | BACKEND_DEVELOPMENT | Backend Development |
+| 2 | DESIGN | Design |
+| 3 | ENTREPRENEURSHIP | Entrepreneurship |
+| 4 | FRONTEND_DEVELOPMENT | Frontend Development |
+| 5 | LIFESTYLE | Lifestyle |
+| 6 | MARKETING | Marketing |
+| 7 | MOBILE_DEVELOPMENT | Mobile Development |
+| 8 | SALES | Sales |
+| 9 | TRAVEL | Travel |
+| 10 | BUSINESS | Business |
+| 11 | PHOTOGRAPHY | Photography |
+| 12 | GENERAL_KNOWLEDGE | General Knowledge |
+| 13 | PERSONAL_FINANCE | Personal Finance |
+| 14 | NEWS_POLITICS | News & Politics |
+| 15 | TECHNOLOGY | Technology |
+| 16 | GAMING | Gaming |
+| 17 | FOOD | Food |
+| 18 | SPORTS | Sports |
+| 19 | HOWTO | How To & Crafts |
+| 20 | ENTERTAINMENT | Entertainment |
+| 21 | HEALTH_FITNESS | Health & Fitness |
+| 22 | MUSIC | Music |
+
 ### `auth_user` (Django Users)
 
 Standard Django user table. Used for owner lookups.

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

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

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

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

thoughtleaders_cli-0.6.2/skills/tl/references/business-glossary.md

@@ -1,159 +0,0 @@
-# ThoughtLeaders Business Glossary
-
-Maps business terms to database concepts.
-
-## Revenue & Deal Lifecycle
-
-| Business Term | DB Concept | Notes |
-|--------------|------------|-------|
-| **Revenue / Sold ad** | `adlink.publish_status = 3` (SOLD) | Only status=3 counts as real revenue |
-| **Gross ads / Gross revenue** | `SUM(adlink.price)` where sold | Total advertiser spend |
-| **Net revenue / TL profit** | `price - cost` per adlink | What TL earns as a company |
-| **Cost** | `adlink.cost` | What the channel earns |
-| **Price** | `adlink.price` | What the advertiser pays |
-| **Closed-lost** | `publish_status IN (4, 5, 9)` | All three rejection statuses |
-| **Open opportunity** | `publish_status IN (0, 2, 6, 7, 8)` | Pipeline — not revenue, not lost |
-| **Proposal Approved** | `publish_status = 6` | AM approved to show to brand — NOT brand approval. Internal gate only. |
-| **Pending** | `publish_status = 2` | Brand has agreed — this is the real high-intent signal |
-| **Weighted pipeline** | `SUM(weighted_price)` for open opps | Pre-calculated on save |
-| **Ad is live** | `publish_date IS NOT NULL` | Until publish_date is set, ad is not on YouTube |
-| **Cancellation risk** | Sold but `publish_date IS NULL` | Sold deals without publish_date can still be canceled |
-
-## Performance Grade (`adlink.performance_grade`)
-
-| Value | Label | Description |
-|-------|-------|-------------|
-| 0 | Pending | Not yet graded (treat as NULL) |
-| 1 | Loser | Underperforming ad — do not renew |
-| 2 | Neutral | Mixed results — test one more time, ideally at a better rate. Second test determines if channel becomes Loser or Winner |
-| 3 | Winner | High-performing ad — should always be renewed |
-
-**Renewal logic:** All Winners should be renewed. Neutrals get one more test (ideally at a lower CPM), then reclassified as Winner or Loser.
-
-## View Guarantees
-
-| Field | Description |
-|-------|-------------|
-| `adlink.impressions_guarantee` | The number of views guaranteed for the ad (bigint). 0 or NULL = no guarantee. |
-| `adlink.view_guarantee_hit_date` | Timestamp when the guarantee was met. NULL = not yet hit or no guarantee. |
-| `adlink.projected_views_at_purchase_date` | Projected views at time of purchase (used for CPM estimation). |
-
-## Entities
-
-| Business Term | DB Table | Notes |
-|--------------|----------|-------|
-| **Deal / Sponsorship** | `thoughtleaders_adlink` | One brand ↔ channel placement |
-| **Brand** | `thoughtleaders_brand` | Advertiser entity (the buying-side brand) |
-| **Brand profile** | `thoughtleaders_profile` | Advertiser entity / account |
-| **Organization** | `thoughtleaders_organization` | Parent entity for profiles |
-| **Channel** | `thoughtleaders_channel` | YouTube channel |
-| **Ad Spot (Catalogue item)** | `thoughtleaders_adspot` | TL's catalogue of buyable placements. Price/cost on adspot are *list prices* only — each adlink (instance) can have completely different price/cost |
-| **Campaign** | `dashboard_campaign` | Groups multiple deals |
-
-## Ad Spots & Channels
-
-- A channel can have **multiple ad spots** because different people sell the same channel (talent manager, direct, multiple agencies)
-- Ad spots are the **catalogue** — adlinks are **instances** of catalogue items
-- Price/cost on adspot = list/catalog values; price/cost on adlink = actual deal values
-- **Only one active adspot with integration=mention per channel at any time** (MSN rule)
-
-## Ownership & Accountability
-
-| Field | Model | Meaning |
-|-------|-------|---------|
-| `owner_sales_id` | `adlink` | **Most important.** Person responsible for closing the deal and for the revenue. Final accountability. |
-| `owner_advertiser_id` | `adlink` | Brand-side owner for this specific deal |
-| `owner_publisher_id` | `adlink` | Channel-side owner for this specific deal |
-| `owner_advertiser_id` | `profile` | **Account owner.** Who owns the brand relationship overall. Often same person as owner_sales on adlinks, but not always. |
-| `owner_publisher_id` | `profile` | Channel relationship owner on the profile level |
-| `owner_sales_id` | `profile` | Sales owner at profile level |
-
-**Key insight:** Ownership exists on both `profile` (account-level) and `adlink` (deal-level). For revenue attribution, always use `adlink.owner_sales_id`.
-
-## MSN (Media Selling Network)
-
-- Channels where TL has **≥80% confidence** they can buy an ad tomorrow
-- Key data: **who is the contact** to buy the ad from
-- `thoughtleaders_channel.media_selling_network_join_date` = when channel joined MSN
-- `thoughtleaders_channel.is_tl_channel` = TPP/VIP channel (subset of MSN)
-- **Rule:** Only one active adspot with `integration=mention` per channel at any time
-- MSN quality depends on having current, accurate contact info
-
-## Teams & Ownership
-
-### Brand-led Revenue (Sales / Account Management)
-
-These teams close deals and manage brand relationships. Revenue is attributed via `adlink.owner_sales_id`.
-
-**Emma's team:**
-| Person | auth_user.id | Owner field |
-|--------|-------------|-------------|
-| Emma | 11158 | `adlink.owner_sales_id` |
-| Orli | 2042 | `adlink.owner_sales_id` |
-| Eli | 20836 | `adlink.owner_sales_id` |
-| Grace | 20835 | `adlink.owner_sales_id` |
-| Mark | 23979 | `adlink.owner_sales_id` |
-| Abbie | 23978 | `adlink.owner_sales_id` |
-| Ariella | 23977 | `adlink.owner_sales_id` |
-
-**Nicole's team:**
-| Person | auth_user.id | Owner field |
-|--------|-------------|-------------|
-| Nicole | 9929 | `adlink.owner_sales_id` |
-| Maika | 5412 | `adlink.owner_sales_id` |
-| Yuval | 14252 | `adlink.owner_sales_id` |
-| Revital | 14251 | `adlink.owner_sales_id` |
-
-### Network Growth (SDR / Partnerships) — Pauline's team
-
-Responsible for growing the MSN (new channels) and MBN (new brands). SDR outreach on both sides.
-
-| Person | auth_user.id | Role | Owner field |
-|--------|-------------|------|-------------|
-| Pauline | 218 | Team lead | `adlink.owner_publisher_id` (channel handovers) |
-| Morgan | 5710 | Channel SDR | — |
-| Jen | 873 | Channel SDR | — |
-| Ruby Jean | 9011 | Channel SDR | — |
-| Molly | 11361 | Channel SDR | — |
-| Pierra | 11323 | Brand SDR | — |
-| Nian | 8795 | Brand SDR | — |
-
-### Ad Ops — Jody's team
-
-Manages getting sold ads published. `profile.owner_publisher_id` = ad ops manager of an account.
-
-| Person | auth_user.id | Owner field |
-|--------|-------------|-------------|
-| Jody | 71 | `profile.owner_publisher_id` (account-level ad ops owner) |
-| Kathleen | 9274 | `profile.owner_publisher_id` |
-| Shane | 18159 | `profile.owner_publisher_id` |
-| Kevin | 5799 | `profile.owner_publisher_id` |
-| Airis | 5804 | `profile.owner_publisher_id` |
-| Lara | 10743 | `profile.owner_publisher_id` |
-| Josh | 11592 | `profile.owner_publisher_id` |
-
-### Querying by team
-
-```sql
--- Emma's team pipeline
-SELECT ... FROM thoughtleaders_adlink al
-WHERE al.owner_sales_id IN (11158, 2042, 20836, 20835, 23979, 23978, 23977)
-
--- Nicole's team pipeline
-SELECT ... FROM thoughtleaders_adlink al
-WHERE al.owner_sales_id IN (9929, 5412, 14252, 14251)
-
--- All brand-led revenue (both teams)
-SELECT ... FROM thoughtleaders_adlink al
-WHERE al.owner_sales_id IN (11158, 2042, 20836, 20835, 23979, 23978, 23977, 9929, 5412, 14252, 14251)
-
--- Pauline's network growth team (channel SDRs)
--- owner_publisher_id on adlink for channel-side work
-SELECT ... FROM thoughtleaders_adlink al
-WHERE al.owner_publisher_id IN (218, 5710, 873, 9011, 11361)
-
--- Jody's ad ops team accounts (profile-level ownership)
-SELECT ... FROM thoughtleaders_profile p
-WHERE p.owner_publisher_id IN (71, 9274, 18159, 5799, 5804, 10743, 11592)
-```
-