thoughtleaders-cli 0.9.1__py3-none-any.whl → 0.9.2__py3-none-any.whl

{thoughtleaders_cli-0.9.1.dist-info → thoughtleaders_cli-0.9.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thoughtleaders-cli
-Version: 0.9.1
+Version: 0.9.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

{thoughtleaders_cli-0.9.1.dist-info → thoughtleaders_cli-0.9.2.dist-info}/RECORD

@@ -1,4 +1,4 @@
-tl_cli/__init__.py,sha256=kO0_472YL4gIPvshUU0kbi2plhyCiGXM81g9JnGAfm4,112
+tl_cli/__init__.py,sha256=SS6LM2unjLV5RGfYCqFk1Gy1oudZaGmAocUwDxSiB4A,112
 tl_cli/_completions.py,sha256=kOyEUqC26vbYvyXWi513WX8fF73qQLR5WWuRSe_wqyk,164
 tl_cli/_typer_utils.py,sha256=ZiZsCVmEznPvBw-dYbr3tu3zWZ0iN6kjoQmK3gMqD28,860
 tl_cli/config.py,sha256=UV_OYTXuQnAIqbi_oVCXx0hhIdZWR678RRapVv51UwQ,1859
@@ -39,9 +39,9 @@ tl_cli/commands/sponsorships.py,sha256=PdWCm9E4mrs_qlHtckMp99JmuRP94hthlqoWMi0k4
 tl_cli/commands/uploads.py,sha256=Tf9tqAEm9FGe3A7sr_EDX9OzdNInCmrWNr10wWGuMUo,1526
 tl_cli/commands/whoami.py,sha256=aUXwBRwh1vAGrvz8CKGfHYtEOKJCIDfwrGesKAwYZMk,7866
 tl_cli/output/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-tl_cli/output/formatter.py,sha256=zWwcg4yovMXLaduxu8skpDjPVLTaGZAmwtYwjpZDg1w,22766
+tl_cli/output/formatter.py,sha256=2FOsZb9aGcjKAGvumtEyS63cjIk47JcQGNM0K7Gpdp8,23413
 tl_cli/_plugin/.claude-plugin/marketplace.json,sha256=l56PMmyjfGXNGlV30wRyOAe74B6gJNCVNCxgsBbSNxc,446
-tl_cli/_plugin/.claude-plugin/plugin.json,sha256=IbYvnic6z19jxk6jUTB6vK8WN_EXdvYjf5iaqRHPxiE,466
+tl_cli/_plugin/.claude-plugin/plugin.json,sha256=MlM05A2LBDupXFroa0AsFQ5Yf1ouQa79wgfhXMt6yeA,466
 tl_cli/_plugin/agents/keyword-context-classifier.md,sha256=8Pk6WqJKuF-ERkBh54Aa-9t60CvjdOIH0RurFlG-T7I,4325
 tl_cli/_plugin/agents/keyword-entity-resolver.md,sha256=fOAeTZa2-h7te8dEXLFcmiL2tj6IXwnQ0ChUrym3yFc,5619
 tl_cli/_plugin/agents/keyword-relevance-validator.md,sha256=uPUqobAVT7xq-brRHtNaFSTns-lYyCu3MwTuU5tn538,3127
@@ -51,11 +51,11 @@ tl_cli/_plugin/hooks/hooks.json,sha256=FSWibw1xAjA-suFV3fR8btIb2kQ82LQ08otTr-Npm
 tl_cli/_plugin/hooks/scripts/load-tl-skill.mjs,sha256=EBsyZ-caei-CBJsRtqzJXJs_20O3H22MuVmDpu96umo,805
 tl_cli/_plugin/hooks/scripts/post-usage.sh,sha256=WVvZLkZik6lbeZ20Kh-wgm4JkRFHFN0Uwl4C8S3Y0sY,759
 tl_cli/_plugin/hooks/scripts/pre-check.sh,sha256=inHopPXQ9h-KRcHuebEIQ-1EZmsTaHhAAMCFQ0MyiEQ,820
-tl_cli/_plugin/skills/tl/SKILL.md,sha256=Z4-X3Q8jpDvAGnj7lz6Oi0HUgOPOue063aA26qCHenc,67231
-tl_cli/_plugin/skills/tl/references/business-glossary.md,sha256=7WRLaNAAXbkaAWP9S7sai0ZX5JhRViPBvryND1NU1jk,18632
-tl_cli/_plugin/skills/tl/references/elasticsearch-schema.md,sha256=FTGqtQNgddZP5KZdzsxAL6udAJjr79dUNz_4Aj9G_fo,13028
+tl_cli/_plugin/skills/tl/SKILL.md,sha256=A-hdUWXeJKd8fDlhe3qOVd1s1a64E77wldTAQKa-TTs,66805
+tl_cli/_plugin/skills/tl/references/business-glossary.md,sha256=YZ_UWygtAZB8Mfh9NPG2ld0OnmgknSBzBOpVZwN-wzs,19287
+tl_cli/_plugin/skills/tl/references/elasticsearch-schema.md,sha256=x7ZUYGbR6FJG02BSA9BjveoiC4X-7VsYxhLPBK4IH_c,23195
 tl_cli/_plugin/skills/tl/references/firebolt-schema.md,sha256=tysPKBxqQFRzfKi2vmEhHXn8PGaznep7yaKwSWZY3Jo,11110
-tl_cli/_plugin/skills/tl/references/postgres-schema.md,sha256=NYzt3Mk8aDPZGFtQHqUpcM7CUwfEoi5zavcrWHKJf0s,23726
+tl_cli/_plugin/skills/tl/references/postgres-schema.md,sha256=weZOzXUmkRsr4JYxv8qBWO0QMkEkUmKGlkUYjygd0Ro,27711
 tl_cli/_plugin/skills/tl-channel-authenticity/.gitignore,sha256=EMeiIlgw10A-WzjTnENZs8jXAH9n2wT0Bn3vQ7tOP-E,121
 tl_cli/_plugin/skills/tl-channel-authenticity/SKILL.md,sha256=4vVIJu7DXjyahvuCWSeYQL2_H2KILKh7s5RyX-fBjpY,6289
 tl_cli/_plugin/skills/tl-channel-authenticity/references/comment-patterns.md,sha256=ne-2mSDxJDKb8HswRltvEIEh7iDDWckDqnWmdFQBbrI,2035
@@ -75,24 +75,24 @@ tl_cli/_plugin/skills/tl-channel-authenticity/scripts/score.py,sha256=LwhTMf9eyO
 tl_cli/_plugin/skills/tl-channel-authenticity/scripts/tl_cli.py,sha256=Mu__ZzcELuQBPJ8Ia6GiLbW1ZtqI1aQklBeRPAw9JNk,9045
 tl_cli/_plugin/skills/tl-channel-authenticity/scripts/video_integrity.py,sha256=Pj9cZkFHX-fwfmkSjicy_B04fQ3TW3gLrGliHwCwX5g,11120
 tl_cli/_plugin/skills/tl-channel-authenticity/scripts/view_curves.py,sha256=wx4cgi_HSOBDEy9bI_8RGnAFpY8q8xHOlF7DYojmi0c,4447
-tl_cli/_plugin/skills/tl-keyword-research/SKILL.md,sha256=231DpakmFsrYrxoo8Pra1O6k-W2X8r4wVIzCCjpdkRo,38257
-tl_cli/_plugin/skills/tl-keyword-research/references/elasticsearch-content-search.md,sha256=78EuEoqLKJcGDTIIzwN8nx-dAvDxwYkWo60Zs5-rd5Y,23069
-tl_cli/_plugin/skills/tl-keyword-research/references/help.md,sha256=mhOsHiNjWPvx7G937YDrIGmOCCPS63Qh3Obdm2Ww43o,6758
-tl_cli/_plugin/skills/tl-keyword-research/scripts/build_report.py,sha256=1wjDRmOPjYrn0pOQgkcqTpSxWsOqn3Xib8oiefVgTrM,22175
+tl_cli/_plugin/skills/tl-keyword-research/SKILL.md,sha256=wvLvlumbR5fDxL-PZAqRDu7azYl4MXe1A5vOBn8YghE,38264
+tl_cli/_plugin/skills/tl-keyword-research/references/elasticsearch-content-search.md,sha256=fsXbpI3DPtkOnPEquB11Efur665o963RDN4-WIJCRJs,24263
+tl_cli/_plugin/skills/tl-keyword-research/references/help.md,sha256=yTmoU-Z6rPDjprbDa09nePoON0jnRSh_FVc7lqu1XGs,6802
+tl_cli/_plugin/skills/tl-keyword-research/scripts/build_report.py,sha256=oHCYfhFc006QhAv17R5uahpOMk38N1_YH_Cn6QMhQg4,22136
 tl_cli/_plugin/skills/tl-keyword-research/scripts/expand_entities.py,sha256=yYRfGRTl762Kvpv1xH_3nDZfShaX8BHoTRtmHyCsLk8,10886
 tl_cli/_plugin/skills/tl-keyword-research/scripts/fetch_context.py,sha256=dn4n-WPjz4lib42hrDxrTN_xwqy1GZDpURE-IE6OKkg,6877
-tl_cli/_plugin/skills/tl-keyword-research/scripts/probe.py,sha256=rm5mEOTN5gJmrWdvE2iH_rU02natUSuJ4lH2XWHh-bU,27694
+tl_cli/_plugin/skills/tl-keyword-research/scripts/probe.py,sha256=eWmN8406QgrAcK_gvxNn63TX_NuF7Qk-X_CYK_MdMdU,28270
 tl_cli/_plugin/skills/tl-keyword-research/scripts/search_channels.py,sha256=qoe70bfpSWujO12eFP-OnfrqwbI7FgWTP_9aWavw3-U,23189
 tl_cli/_plugin/skills/tl-keyword-research/scripts/search_videos.py,sha256=Q_fYr1BzrMr5nh9wC1ruBJuIQFzNBkkBnYNMmsSEnc4,14568
 tl_cli/_plugin/skills/tl-keyword-research/scripts/select_keywords.py,sha256=eiavZfs-i2zAarR4k1_RT5wgqCr21T42S0AmwrXQid8,9359
-tl_cli/_plugin/skills/tl-save-report/SKILL.md,sha256=GC0kdX5W6gAR2nhsuiVlpTdW2aBlwJxmIyqyxFJb-aY,37102
+tl_cli/_plugin/skills/tl-save-report/SKILL.md,sha256=peAdgudSuSbj6Xj8P1ek9J-hRNS45DE7XOvUttKdUXs,37240
 tl_cli/_plugin/skills/tl-save-report/references/columns_brands.md,sha256=H5G308GOzMWvWw6smkPGdb2CBuuxkrojCpJgWS9X4sA,3559
 tl_cli/_plugin/skills/tl-save-report/references/columns_channels.md,sha256=g57ET_VI611lB7fVrGwYFvTDqMkNB63OmmfrnbMZF1I,4684
 tl_cli/_plugin/skills/tl-save-report/references/columns_content.md,sha256=Y9YL5sm7zK44vSHTXOV4NY7nSOcJ9i3D0HFCo1g63WU,3466
 tl_cli/_plugin/skills/tl-save-report/references/columns_sponsorships.md,sha256=I--uUuluGz2xBfOCaUq7fc3nrSSSpjB3PdT50GmOY7g,4918
 tl_cli/_plugin/skills/tl-save-report/references/intelligence_filterset_schema.json,sha256=RDzJO6WSTKWpTVgp2AZOP7-TcIq0ox5wIFGazb2ZDto,18498
 tl_cli/_plugin/skills/tl-save-report/references/intelligence_widget_schema.json,sha256=cxdlzmkt5WoI20zGsq_4qENTc6Ral9_vI5YTx2yzf-g,11503
-tl_cli/_plugin/skills/tl-save-report/references/report_glossary.md,sha256=otErNWOIn_S9kI-tW032vUViN2tCC5rTB18vo8mtwLg,12100
+tl_cli/_plugin/skills/tl-save-report/references/report_glossary.md,sha256=YkUxEkUVui9HVC45BYBoyKVuyc_sLmf2GkSAEksmzW0,12165
 tl_cli/_plugin/skills/tl-save-report/references/sortable_columns.json,sha256=4X878VptWmS1ETfKZSXJ3U0E0lOw4JtVXsZTVHTsPUc,7571
 tl_cli/_plugin/skills/tl-save-report/references/sponsorship_filterset_schema.json,sha256=Ip97J_BeC6EbEowT5PvO3QxrCsB2sc2IWm_c0M0xXLw,11739
 tl_cli/_plugin/skills/tl-save-report/references/sponsorship_widget_schema.json,sha256=PXEhZzRTNl94fFHpsBuo4Gop-Mdveg6GCaIm-ZGhBns,9587
@@ -101,8 +101,8 @@ tl_cli/_plugin/skills/tl-top-partnerships/SKILL.md,sha256=jOMMr40XRnAZv-oRLeyKJT
 tl_cli/_plugin/skills/tl-top-partnerships/scripts/top_partnerships.py,sha256=OqhoyvFe1zrtrStChcam7oPYgFnSbGHC3WAgLhLIC3w,13738
 tl_cli/_plugin/skills/tl-views-guarantee/SKILL.md,sha256=IH7q1WJDWri9TWJMiga1FMGJO_GKSbWwaDS6CVNZ9c0,9270
 tl_cli/_plugin/skills/tl-views-guarantee/scripts/vg.py,sha256=Qp5poinHEqh9374anq0bLtlxj2YL6ipBicaT960-Cws,15825
-thoughtleaders_cli-0.9.1.dist-info/METADATA,sha256=3vV95hmDYiy5h2psbKwDcbqmuSUOgXG1sNEmjRLhjL4,19083
-thoughtleaders_cli-0.9.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-thoughtleaders_cli-0.9.1.dist-info/entry_points.txt,sha256=umZp-1BkGkHDG0bNZXpTXrjwW0HGf9IDFN40eAWuuvg,39
-thoughtleaders_cli-0.9.1.dist-info/licenses/LICENSE,sha256=RUfdfLsn6jygiyrnnVUHt6r4IPwr2rbDm9Kixgtu8fo,1071
-thoughtleaders_cli-0.9.1.dist-info/RECORD,,
+thoughtleaders_cli-0.9.2.dist-info/METADATA,sha256=peW38EK69xvAHI_7RdN-jNT_K79f2bCbV4k7DjyT8Z0,19083
+thoughtleaders_cli-0.9.2.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+thoughtleaders_cli-0.9.2.dist-info/entry_points.txt,sha256=umZp-1BkGkHDG0bNZXpTXrjwW0HGf9IDFN40eAWuuvg,39
+thoughtleaders_cli-0.9.2.dist-info/licenses/LICENSE,sha256=RUfdfLsn6jygiyrnnVUHt6r4IPwr2rbDm9Kixgtu8fo,1071
+thoughtleaders_cli-0.9.2.dist-info/RECORD,,

{thoughtleaders_cli-0.9.1.dist-info → thoughtleaders_cli-0.9.2.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.30.1
+Generator: hatchling 1.31.0
 Root-Is-Purelib: true
 Tag: py3-none-any

tl_cli/__init__.py

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

tl_cli/_plugin/.claude-plugin/plugin.json

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

tl_cli/_plugin/skills/tl/SKILL.md

@@ -242,21 +242,19 @@ tl channels update 12345 '{"demographic_male_share": 62}'
 tl channels update 12345 '{"demographic_geo": {"US": 60, "UK": 12, "CA": 8}}'
 tl channels update 12345 '{"demographic_male_share": 55, "demographic_usa_share": 70}'
 tl channels update 12345 '{"outreach_email": "press@creator.com"}'
-tl channels update 12345 '{"all_emails": {"press@creator.com": {"timestamp": "2026-06-25T12:00:00+00:00", "source": "manual"}}}'
 tl channels update 12345 '{"media_selling_network_join_date": "2026-01-15"}'
 ```
 
-**Channel contact emails.** Besides demographics, `tl channels update` accepts two
-contact fields:
+**Channel contact emails.** Besides demographics, `tl channels update` accepts one
+contact field:
 
 - **`outreach_email`** — the channel's primary outreach address (a single email string, or `null`).
-- **`all_emails`** — the channel's full email archive. It is **not** a free-form blob: it's
-  a JSON object keyed by email address, each value an object `{"timestamp": <ISO-8601 datetime>, "source": <string>}`.
-  `timestamp` must parse as ISO-8601 (e.g. `"2026-06-25T12:00:00+00:00"`); `source` records
-  where the address came from. Known `source` values: `outreach_email` (the address that was
-  the primary outreach email, archived when the channel was blacklisted), `google_search`,
-  `scheduled_rescrape`. Use a descriptive token such as `manual` for hand-added entries.
-  An edit **replaces** the whole `all_emails` object, so include every entry you want to keep.
+
+The channel's full email archive (`all_emails` — a JSON object keyed by email address,
+each value recording when and where the address was found) is **not editable here**;
+sending it returns a 400. It is append-only: new addresses are added with the
+internal CLI's `tl-internal channels add-email` command (superuser-only), which never
+modifies or removes existing entries.
 
 **MSN membership.** `tl channels update` also accepts **`media_selling_network_join_date`** —
 the date the channel joined the Media Selling Network, as a `YYYY-MM-DD` string. This date is

tl_cli/_plugin/skills/tl/references/business-glossary.md

@@ -97,7 +97,7 @@ Vocabulary that AMs use about channels, mapped to the actual DB encoding. Most o
 | **Brand on a deal** | `adlink → advertiser_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." |
+| **Channel quality score** *(internal-only)* | `sponsorship_score` on the indexed channel doc + `thoughtleaders_channel.sponsorship_score` (PG) | TL-internal sponsorship track-record score, range 0–10: blends how many distinct brands sponsored the channel over the past 2 years (40%) with how many of them booked repeatedly (60%). Scores below 5 read as little/no track record (the low range is deliberately compressed). **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
 
@@ -107,6 +107,7 @@ AMs use "PV" loosely. There are three different DB fields, each meaning somethin
 |---------|----------|---------------------|
 | **PV (channel baseline)** | `thoughtleaders_channel.projected_views` | 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. |
+| **PV (video, at upload)** — the web app's "video projected views" | `projected_views` on the ES **video** doc | The channel's format-specific PV **frozen when TL first indexed the video** (never updated afterwards). Compare to the channel's current PV to see growth/decline since the upload, or to the video's actual `views` to see over/under-performance vs expectation. See the ES schema reference for the calculation. |
 | **VG (View Guarantee)** | `thoughtleaders_adlink.views_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.projected_views`. 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`.
@@ -120,7 +121,7 @@ Two derived metrics on the indexed channel doc that AMs use to qualify a channel
 | **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"`).
+Both metrics live on the **channel docs** in the search index — not on video docs (the embedded `channel.*` object on video docs carries no metrics). 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
 

tl_cli/_plugin/skills/tl/references/elasticsearch-schema.md

@@ -35,107 +35,121 @@ The `doc_type` join field distinguishes video uploads ("articles") from channel
 
 #### Upload/video Fields (selected — 73 total)
 
-Filter with `{"term": {"doc_type": "article"}}`.
+Filter with `{"term": {"doc_type": "article"}}`. Coverage percentages are live `exists` counts (July 2026, ~676M video docs) — they drift slowly as the index grows.
 
 | Field | Type | Description |
 |-------|------|-------------|
 | `id` | keyword | Video/article ID. Compound form `<channel_id>:<youtube_id>` (matches PG `adlink.article_id` and ES `_id`). |
-| `title` | text | Video title |
-| `description` | text | Video description |
-| `content` | text | Full content/transcript text (plain text; not always populated) |
-| `transcript` | text | Raw transcript — stored as YouTube timed-text **XML**, not plain text (see note below) |
-| `transcript_language` | keyword | Transcript language code |
-| `summary` | text | AI-generated summary |
-| `publication_date` | date | When video was published |
-| `discovery_time` | date | When TL discovered/indexed it |
-| `url` | object | Video URL |
-| `image_url` | object | Thumbnail URL |
-| `views` | long | View count |
-| `total_views` | long | Total views |
-| `projected_views` | long | Projected views |
-| `likes` | long | Like count |
-| `comments` | integer | Comment count |
-| `engagement` | long | Engagement metric |
-| `duration` | integer | Duration in seconds |
-| `duration_live` | integer | Live stream duration |
-| `duration_longform` | integer | Long-form duration |
-| `duration_shorts` | integer | Shorts duration |
-| `content_type` | keyword | longform / short / live |
-| `content_category` | keyword | Content category |
-| `content_aspects` | keyword | Content features/aspects |
-| `language` | keyword | Content language |
-| `country` | keyword | Creator country |
-| `format` | keyword | Platform format |
-| `hashtags` | keyword | Hashtags used |
-| `face_on_screen` | boolean | Whether creator shows face |
+| `title` | text | Video title (~100%) |
+| `description` | text | ⚠️ **Does not exist on video docs** — `exists` matches 0 of ~676M (verified). The video's description text lives in `summary`; `description` is a channel-doc field (the channel's "About this channel" text). |
+| `content` | text | ⚠️ **Podcast episodes only** — the episode's show-notes/body text from the podcast feed (often HTML fragments). ~7% of docs overall; effectively absent on YouTube videos (~256k legacy docs holding flat transcript prose, and 0 YouTube docs since 2025). Never search it for YouTube content — use `summary` / `transcript`. |
+| `transcript` | text | Raw transcript — stored as YouTube timed-text **XML**, not plain text (see note below). ~57% of docs; present on both longform and shorts. |
+| `transcript_language` | keyword | Language code of the caption track the transcript came from (present when `transcript` is) |
+| `summary` | text | ⚠️ **Misleading name — this is the video's creator-written description** (the text under the video: promo links, hashtags, timestamps, subscribe blocks), NOT an AI summary. Verified by sampling old and recent docs. ~86% of docs. This is *the* field for searching video-description text. |
+| `evergreenness` | float | Per-video evergreen score: `(views at age 180d − views at age 30d) / views at age 30d`. ≥ 1 = evergreen (views at day 180 are at least double the day-30 views). Only computed for videos with ≥ 5,000 views published since 2022 (~16% of docs). |
+| `publication_date` | date | When the video was published (~100%) |
+| `discovery_time` | date | When TL first indexed the video. Only ~39% of docs — absent on older docs. |
+| `url` | keyword | Watch/episode URL. **Stored-only: retrievable in `_source` but not searchable** (`exists`/`term` match 0 docs). |
+| `image_url` | keyword | Thumbnail URL on podcast docs; absent on YouTube video docs. Stored-only, not searchable. |
+| `views` | long | View count at the last metrics update (~92%) |
+| `projected_views` | long | **The channel's projected views for this video's format, frozen at the time TL first indexed the video** (~45%) — the web app's "video projected views". TL's prediction of views at age = 30 days, computed **only from the channel's recent uploads of the same content type** (a short's value comes from the channel's shorts, a longform video's from its longform uploads — never mixed): ≥ 4 same-format videos' day-30 views, median-anchored with outliers trimmed. **Never updated after first index**, so it's a snapshot: compare it to the channel doc's current `impression*` to see whether the channel grew or declined since the upload, and to the video's `views` to see whether the video over- or under-performed expectations. Caveats: the format bucket at stamp time is duration-based (≤ 60s → shorts projection; anything longer — including live streams — gets the longform projection), and for channels added to TL after the fact "first indexed" is discovery time, not the publish date. |
+| `likes` | long | Like count (~87%) |
+| `comments` | integer | Comment count (~67%) |
+| `duration` | integer | Video duration in seconds (~100%) |
+| `content_type` | keyword | `longform` / `short` / `live` — the complete value set. ~71% of docs; older docs have none (missing ≠ longform). Podcast/RSS docs have no `content_type`. |
+| `content_aspects` | keyword | Flags: `podcast`, `paid_promotion`, `unlisted` — the complete value set. Only ~2.6% of docs carry any. |
+| `hashtags` | keyword | Hashtags from the video description, stored **without the leading `#`** and lowercase (e.g. `marchmadness`); non-Latin tags appear percent-encoded (`%D0%B0…`) (~32%) |
+| `channel` | object | Embedded channel subset: `channel.id`, `channel.content_category`, `channel.format`, `channel.publication_id`, `channel.country`, `channel.language` — no text fields, no metrics. This is where a video's language/country/format/category live (top-level `language`, `country`, `format`, `content_category` exist only on channel docs). |
+
+⚠️ **Channel-doc fields that look like video fields but match 0 video docs:** `total_views`, `engagement`, `duration_live`/`duration_longform`/`duration_shorts`, `language`, `country`, `format`, `content_category`, `face_on_screen`. They live on channel docs (see below); on video docs use the embedded `channel.*` subset where available.
 
 #### Brand Mention Fields
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `brand_mentions` | nested | Full brand mention objects |
-| `all_brand_mentions` | keyword | All brand IDs mentioned |
-| `sponsored_brand_mentions` | keyword | Sponsored brand IDs |
-| `organic_brand_mentions` | keyword | Organic brand IDs |
-| `banner_ads` | object | Banner ad data |
-| `not_sponsored_by` | object | Explicitly not sponsored by |
+| `brand_mentions` | nested | Detected brand-mention objects (`id`, `type` organic/sponsored, `field`, `snippet`, `start_ts`/`end_ts`, `position`, `probability`, `detection_tool`) (~12%). Being `nested`, it must be queried with a `nested` query — a plain `{"exists": {"field": "brand_mentions"}}` matches 0 docs. |
+| `all_brand_mentions` | keyword | Brand IDs with any mention — the union of sponsored + organic (~12%) |
+| `sponsored_brand_mentions` | keyword | Brand IDs with a sponsored mention |
+| `organic_brand_mentions` | keyword | Brand IDs with an organic mention |
+| `not_sponsored_by` | object | Brand IDs marked as explicitly *not* sponsoring this video. **Not searchable** (`exists` matches 0 docs). |
 
 #### Channel Fields
 
-Filter with `{"term": {"doc_type": "channel"}}`.
+Filter with `{"term": {"doc_type": "channel"}}`. ~45.5M channel docs (July 2026); coverage percentages below are live `exists` counts against that total.
 
 Contains a denormalized subset of the PostgreSQL channel data.
 
-### Channel fields
+⚠️ **Channel docs are duplicated** — one channel id can appear as several identical docs (a well-known channel showed 8+ copies). Doc counts ≠ channel counts; dedupe with `collapse` on `id` or aggregate with `cardinality`.
+
+⚠️ **Legacy field names** — PostgreSQL and Firebolt renamed these, Elasticsearch did not. Raw ES queries must use the old names; the new names match **0 docs** (verified live, they fail silently):
+
+| ES (use this) | PG `thoughtleaders_channel` | Firebolt `channel_metrics` |
+|---|---|---|
+| `reach` | `subscribers` | `subscribers` |
+| `impression` / `impression_live` / `impression_shorts` | `projected_views*` | `projected_views` |
+| `is_tl_channel` | `is_tpp` | — |
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `name` | text | Channel name |
-| `channel` | object | Channel metadata (nested on article docs) |
-| `reach` | long | Subscriber count. ⚠️ NOT ad-industry "reach" (unique audience exposed) — this is the channel's subscriber count. |
-| `impression` | long | Projected views per longform video — forward-looking estimate. ⚠️ NOT actual views and NOT ad-industry "impressions"; for actual views see `total_views` / the video docs. |
-| `impression_live` | long | Projected views per live stream (forward-looking estimate) |
-| `impression_shorts` | long | Projected views per short (forward-looking estimate) |
-| `is_tl_channel` | boolean | TPP partner channel |
-| `is_active` | boolean | Channel is active |
-| `media_selling_network_join_date` | date | MSN join date |
-| `has_outreach_email` | boolean | Has outreach email |
-| `outreach_email` | text | Contact email |
-| `social_links` | text | Social media links |
-| `male_share` | byte | Male audience % |
-| `usa_share` | byte | US audience % |
-| `sponsorship_price` | scaled_float | Sponsorship price |
-| `sponsorship_score` | scaled_float | Sponsorship quality score |
-| `evergreenness` | float | Evergreen score |
-| `evergreenness_live` | scaled_float | Live evergreen score |
-| `evergreenness_longform` | scaled_float | Longform evergreen score |
-| `evergreenness_shorts` | scaled_float | Shorts evergreen score |
-| `trend` | float | Growth trend |
-| `trend_live` | scaled_float | Live trend |
-| `trend_shorts` | scaled_float | Shorts trend |
-| `posts_per_90_days` | integer | Upload frequency |
-| `posts_per_90_days_live` | integer | Live frequency |
-| `posts_per_90_days_shorts` | integer | Shorts frequency |
-| `fulfillment_rate` | scaled_float | Fulfillment rate |
-| `renewal_rate` | scaled_float | Renewal rate |
-| `metrics_update_period` | byte | How often metrics update |
-| `offline_since` | date | When channel went offline |
+| `name` | text | Channel display name (~100%) |
+| `description` | text | The channel's creator-written YouTube "About this channel" text (~97%): usually first-person, links, promo. Especially worth investigating if it contains creator contact information. |
+| `description.domains` | text | Same "About this channel" text, additionally indexed so **website domains are searchable as single terms** — `{"term": {"description.domains": "patreon.com"}}` matches channels whose About text *links to* patreon.com anywhere (including inside full URLs), while plain topic words match identically to `description` (verified: same counts). This is the field the platform's `channel_description` report filter actually searches. |
+| `reach` | long | Subscriber count (~98%). ⚠️ NOT ad-industry "reach" (unique audience exposed) — this is the channel's subscriber count. Same data as PG `thoughtleaders_channel.subscribers` / Firebolt `channel_metrics.subscribers`. |
+| `impression` | long | TL's projected views per longform video at age = 30 days — computed only from the channel's recent **longform** videos' day-30 views (≥ 4 required; median-anchored, outliers trimmed) (~27%). This is the channel's *current* projection; a video doc's `projected_views` is the same quantity frozen when that video was first indexed — diff them to see channel growth/decline since the upload. ⚠️ NOT actual views and NOT ad-industry "impressions"; for actual views see `total_views` / the video docs. |
+| `impression_live` | long | Projected views per live stream at age = 30 days, from the channel's live streams only (~6%) |
+| `impression_shorts` | long | Projected views per short at age = 30 days, from the channel's shorts only (~21%) |
+| `total_views` | long | Lifetime actual views across the channel (~68%) |
+| `engagement` | long | Views-per-comment ratio over the channel's last 30 days of uploads: `sum(views) / sum(comments)`, rounded (~25%). **Lower = more engaged audience** (fewer views per comment). Not an engagement count. |
+| `duration_longform` | integer | Average longform video duration in seconds, over the channel's uploads from the trailing 365 days (~46%) |
+| `duration_shorts` | integer | Average short duration, same window (~32%) |
+| `duration_live` | integer | Average live-stream duration, same window (~11%) |
+| `is_tl_channel` | boolean | TPP partner channel (100%) |
+| `is_active` | boolean | Channel is active (100%) |
+| `media_selling_network_join_date` | date | MSN join date; non-null = MSN member (~1%) |
+| `has_outreach_email` | boolean | Has contact email (100%) |
+| `outreach_email` | text | Contact email (~45%) |
+| `social_links` | text | Flat array of the channel's profile URLs (~47%), e.g. `["https://twitter.com/…", "https://instagram.com/…", "https://discord.gg/…"]`. Source is a per-platform map plus a catch-all `_other` map for unrecognized platforms; in ES all of it is flattened into this one URL array (the `_other` URLs are folded in, the platform names are dropped). Occasional stray entries (bare emails, nested arrays) exist. |
+| `male_share` | byte | Male audience % — only ~1.6% of channel docs have demographic data |
+| `usa_share` | byte | US audience % — same ~1.6% coverage |
+| `device` | object | Audience device demographics where known: `device.primary` (most common device) and `device.share` (per-device % map). Very sparse (~0.2%). |
+| `sponsorship_price` | scaled_float | Estimated price of a sponsored video on this channel, from **TL's sponsorship calculator** (~27%). Inputs: the channel's last-30-day views and comments, fulfillment rate, renewal rate, and longform evergreenness. Recomputed on the channel's regular metrics-update cycle, so it moves as the channel's data changes. |
+| `sponsorship_score` | scaled_float | TL-internal sponsorship track-record score, **range 0–10, higher = better** (~96%). Blends how many distinct brands sponsored the channel in the last 2 years (40%) with how many of them booked repeatedly (60%). The scale is deliberately skewed: raw low scores are compressed below 5, so **< 5 reads as weak/no track record and ≥ 5 as a real one**. Internal-only — don't quote the raw decimal externally (see business glossary). |
+| `evergreenness` | float | ⚠️ **Dead — 0 docs.** Use the per-format fields below. |
+| `evergreenness_longform` | scaled_float | Median per-video evergreenness of the channel's longform uploads from the trailing 365 days (~24%). Per-video evergreenness = `(views@180d − views@30d) / views@30d`; ≥ 1 = evergreen (day-180 views at least double day-30). Recomputed on the metrics-update cycle. |
+| `evergreenness_shorts` | scaled_float | Same, for shorts (~20%) |
+| `evergreenness_live` | scaled_float | Same, for live streams (~4%) |
+| `trend` | float | View-trend angle for longform uploads (~13%). Positive = growing views. |
+| `trend_shorts` | scaled_float | View-trend angle for shorts (~12%) |
+| `trend_live` | scaled_float | View-trend angle for live streams (~3%). There is **no `trend_longform`** — the longform trend is the bare `trend`. |
+| `posts_per_90_days` | integer | Longform uploads per 90 days, normalized from the trailing 365 days (~96%) |
+| `posts_per_90_days_shorts` | integer | Shorts per 90 days (~67%) |
+| `posts_per_90_days_live` | integer | Live streams per 90 days (~67%) |
+| `fulfillment_rate` | scaled_float | Share of the channel's longform uploads (trailing 365 days) that carry a sponsored mention (~40%) |
+| `renewal_rate` | scaled_float | Rate at which the channel's sponsoring brands come back (~96%) |
+| `metrics_update_period` | byte | ⚠️ Vestigial — populated on only ~2,300 docs (~0.005%). |
+| `offline_since` | date | ⚠️ **Dead — 0 docs.** Use `is_active`. |
+| `content_category` | integer | TL's own content-category code, 1–22 (~94%). **Not YouTube's categories** — see the category map in `postgres-schema.md`. |
+| `format` | integer | Platform format code (100%): 1 = Newsletter, 3 = Podcast, **4 = YouTube**, 5 = Blog, 7 = Twitch, 8 = TikTok, 9 = Instagram, 10 = LinkedIn. |
+| `face_on_screen` | boolean | ThoughtLeaders-sourced flag: whether the creator shows their face on screen when doing brand sponsorships (~1% of channel docs). |
 
 #### AI & Enrichment Fields
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `ai` | object | AI-generated metadata |
-| `applied_enrichments` | keyword | Which enrichments have been applied |
-| `article_category` | object | Categorization data |
+| `ai` | object | **Channel docs only** (0 video docs). Holds exactly the three AI-generated fields below (~93% of channel docs). |
+| `ai.description` | text | AI-generated third-person channel profile, always in English regardless of the channel's language (~93%) |
+| `ai.topic_descriptions` | text | AI-generated prose paragraph describing the channel's content topics. A **single string, not an array**. Only ~37% of channel docs — absence means "not yet generated", not "off-topic". |
+| `ai.brand_safety` | keyword | Brand-safety letter grade `A`–`F` (~93%; A ≈ 91% of graded channels) |
+| `applied_enrichments` | keyword | Enrichment names applied to the video (e.g. `brand_extractor`) |
+| `article_category` | object | ⚠️ **Dead — 0 docs.** |
 
 #### System Fields
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `@timestamp` | date | Index timestamp |
+| `@timestamp` | date | Index/update timestamp (~92% of video docs) |
 | `doc_type` | join | Parent-child join (channel→video) |
-| `es_index_tag` | object | Index routing metadata |
+| `es_index_tag` | keyword | Publication-period tag: quarterly from 2019 (`2025-q2`), yearly 2016–2018 (`2017`), `2015-and-before` for older. **Stored-only — not searchable** (`exists`/`term` match 0 docs). |
 
 ## Common Query Patterns
 
@@ -170,7 +184,9 @@ tl db es '{
 }'
 ```
 
-### Full-text search on title/description/summary/content
+### Full-text search on title/summary/transcript
+
+(`summary` = the video's creator-written description. `description` field is not pupulated for articles, and `content` is podcast-only — see the field table.)
 
 ```bash
 tl db es '{
@@ -178,7 +194,7 @@ tl db es '{
   "query": {
     "multi_match": {
       "query": "ergonomic keyboard review",
-      "fields": ["title^3", "description", "summary", "content"]
+      "fields": ["title^3", "summary", "transcript"]
     }
   },
   "_source": ["title", "channel.id", "publication_date"]
@@ -201,7 +217,7 @@ tl db es '{
 }'
 ```
 
-### Single top-level aggregation (only one aggregation per request is accepted)
+### Aggregation example (aggregations are bounded — see *Accepted query bodies* above)
 
 ```bash
 tl db es '{
@@ -245,9 +261,11 @@ Repeat until a page comes back short (`next_search_after` is absent on an empty
 
 `text` fields on article docs (`title`, `summary`, `transcript`) appear to use the `standard` analyzer (tokenize + lowercase, no stemmer, no English-possessive filter), so inflections, plurals, and possessives are each indexed as distinct terms. For example: `bitcoin` (4,466,300) vs `bitcoins` (489,262). For stemming-style recall, expand the query side with a `bool.should` over the variants.
 
+One consequence: URLs in article fields tokenize on punctuation (`substack.com` → `substack`, `com`), so you can't term-match a domain there. The exception is the channel-doc `description.domains` subfield, where whole domains are single searchable terms — use it to find channels by a linked domain (see the channel field table).
+
 ## Transcript field format
 
-The `transcript` field's `_source` is **YouTube timed-text caption XML**, not plain prose. Each caption cue is a `<text start="…" dur="…">` element wrapped in `<transcript>`, and the inner text is **double HTML-entity-encoded** (an apostrophe is `&amp;#39;`, i.e. an escaped `&#39;`):
+The `transcript` field's `_source` is **YouTube timed-text caption XML**, not plain prose. Each caption cue is a `<text start="…" dur="…">` element wrapped in `<transcript>`. The inner text is HTML-entity-encoded — on older docs **double-encoded** (an apostrophe is `&amp;#39;`, i.e. an escaped `&#39;`), on recent docs single-encoded (`&apos;`):
 
 ```xml
 <?xml version="1.0" encoding="utf-8" ?>
@@ -255,7 +273,7 @@ The `transcript` field's `_source` is **YouTube timed-text caption XML**, not pl
 ```
 
 - **Searching is unaffected** — the field is analyzed as `text`, so `match` / `match_phrase` queries hit the words directly regardless of the markup. The XML only matters when you retrieve and read the raw `_source`.
-- **For plain prose**, either use the `content` field (plain text, but not always populated) or strip the markup yourself, e.g. `jq -r '.results[0].transcript' | sed -E 's/<[^>]+>/ /g'` and then unescape entities twice (the encoding is doubled).
+- **For plain prose**, strip the markup yourself, e.g. `jq -r '.results[0].transcript' | sed -E 's/<[^>]+>/ /g'`, then unescape entities (twice on older docs). Don't reach for the `content` field — it's podcast-only and absent on YouTube docs.
 
 ## Notes & gotchas
 
@@ -263,5 +281,6 @@ The `transcript` field's `_source` is **YouTube timed-text caption XML**, not pl
 - **Add a `publication_date` range filter** whenever the question is time-bounded — the alias is fixed, so this is the only way to narrow the search.
 - `sponsored_brand_mentions` and `organic_brand_mentions` are keyword arrays — use `term` queries.
 - For brand mention details (position, snippet, detection_tool), the data is in the `brand_mentions` nested field.
+- **Stored-only fields** — retrievable in `_source` but invisible to `exists`/`term`/`match` (queries on them silently match 0 docs): `url`, `image_url`, `es_index_tag`, `not_sponsored_by`.
 - **`publication_id` is deprecated** — don't use for joins.
 - No write access. The CLI only exposes `_search` against `tl-platform-*`.

tl_cli/_plugin/skills/tl/references/postgres-schema.md

@@ -126,11 +126,22 @@ A deal is **committed** when it is SOLD, or OPEN with `brand_approval_status` in
 
 ### `thoughtleaders_brand`
 
+> 🚨 **Columns that DO NOT exist on `thoughtleaders_brand` — common hallucinations:**
+> - ❌ `domain` / `url` — the website column is `website`.
+> - ❌ `brand_name` — it's plain `name` here (unlike channel, which prefixes its display fields).
+> - ❌ `is_active` — brands have no active/inactive flag; every row is live.
+> - ❌ `sponsored_topics` (or similar topic columns) — the closest fields are `keywords` and `ai_description`.
+> - ❌ `organization_id` — org lives on profile, not brand (see Key Relationships below).
+
 | Column | Type | Description |
 |--------|------|-------------|
 | `id` | int | Primary key |
-| `name` | varchar | Brand name |
+| `name` | varchar | Brand name. ⚠️ Plain `name`, not `brand_name`. |
 | `description` | text | Brand description |
+| `website` | varchar | Brand website URL. ⚠️ The column is `website`, NOT `domain`. |
+| `slug` | varchar | TL-platform slug |
+| `keywords` | varchar | Topic/detection keywords for the brand |
+| `ai_description` | JSONB | AI-generated descriptive info about the brand |
 | `creator_id` | int FK | User who created it |
 
 #### Junction Tables
@@ -169,14 +180,14 @@ A channel can have multiple adspots (different sellers: talent manager, direct,
 | `subscribers` | bigint | Subscriber count. |
 | `media_selling_network_join_date` | date/timestamptz | When the channel joined the MSN. **MSN membership = this column IS NOT NULL.** |
 | `is_tpp` | boolean | True = TPP channel — TL's closest-partner channels (~144 at 100k+ subscribers), a strict subset of MSN. Prefer when booking: fastest response, easiest to close. ⚠️ **This is not the MSN flag.** For MSN, use `media_selling_network_join_date IS NOT NULL`. |
-| `content_category` | int | Content category code (1–22), as assigned by YouTube. This assignment is too unreliable, do not use it for discovering channels. **For topic/category discovery, prefer `tl recommender top-channels "<tag>"` |
+| `content_category` | int | TL's own content-category code (1–22) — **not YouTube's categories**: 1 Backend Development, 2 Design, 3 Entrepreneurship, 4 Frontend Development, 5 Lifestyle, 6 Marketing, 7 Mobile Development, 8 Sales, 9 Travel, 10 Business, 11 Photography, 12 General Knowledge, 13 Personal Finance, 14 News & Politics, 15 Technology, 16 Gaming, 17 Food, 18 Sports, 19 How To & Crafts, 20 Entertainment, 21 Health & Fitness, 22 Music. The assignment is too unreliable for discovery — do not use it to find channels by topic. **For topic/category discovery, prefer `tl recommender top-channels "<tag>"` |
 | `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`). This is often the cleanest answer to "geography" questions on sponsorships. May be NULL or blank. |
 | `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. |
 | `last_published` | date | Date of the channel's most recently seen 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 (range 0-10, higher is better, if below 5, the channel is low quality). Useful as a tiebreaker when ranking candidate channels. |
 | `ai_description` | JSON | Descriptive information about a channel. Contains fields such as `description`, `audience`, `topic_descriptions`, and `brand_safety`. Useful as a regex-target for thematic filtering when the recommender results are too coarse (e.g. filtering "technology" down to actual tech reviewers via keywords like `tech|gadget|review|software`). |
-| `evergreenness` | float | Evergreen score |
+| `evergreenness` | float | Longform evergreen score: median per-video `(views@180d − views@30d) / views@30d` over the channel's trailing-year uploads; ≥ 1 = evergreen (day-180 views at least double day-30). In ES this lands on the channel doc as `evergreenness_longform`. |
 | `demographic_usa_share` | smallint (0–100) | Percentage of the channel's audience based in the US. Convenience for the common "is this a US-heavy channel?" filter — pre-computed from `demographic_geo['US']`. NULL when the channel has no demographic data. |
 | `demographic_male_share` | smallint (0–100) | Percentage of the channel's audience that's male. `female_share = 100 - demographic_male_share` (no separate column). NULL when the channel has no demographic data. |
 | `demographic_age_median_value` | varchar | The age-bucket label (e.g. `25-34`) corresponding to the median of `demographic_age`, pre-computed on save. Indexed; cheap to filter on. NULL when there's no age data. |
@@ -290,7 +301,42 @@ JOIN thoughtleaders_profile p ON p.user_id = adspot.publisher_id
 ```
 Joining `adspot.publisher_id → profile.id` directly mixes ID spaces and returns garbage.
 
-## `thoughtleaders_profile` persona constants
+## Key columns for the `thoughtleaders_profile` table
+
+The profile is the account record for a person/company on the platform. Every brand-side query hops through it (`adlink.advertiser_profile_id → profile → profile_brands → brand`), which makes it the most-joined table after the sponsorships themselves.
+
+> 🚨 **Columns that DO NOT exist on `thoughtleaders_profile` — common hallucinations:**
+> - ❌ `name` / `email` — the person's name and email live on `auth_user` (join via `user_id`: `first_name`, `last_name`, `email`). The company name is `organization_name`, denormalized onto the profile.
+> - ❌ `auth_user_id` — the FK column is `user_id`.
+> - ❌ `brand_id` — a profile can have several brands; join `thoughtleaders_profile_brands` on `profile_id`.
+> - ❌ `is_tpp` — that's a channel attribute; a profile's channels come via `thoughtleaders_profile_channels`.
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `id` | int | Primary key. ⚠️ NOT the same ID space as `auth_user.id` — never join a `*_id` pointing at users to `profile.id` directly. |
+| `user_id` | int FK | → `auth_user.id` (the person's name and email live there) |
+| `organization_id` | int FK | → `thoughtleaders_organization.id` |
+| `organization_name` | varchar | Denormalized company/organization display name |
+| `persona` | int | Account persona (see constants below) |
+| `is_advertiser` | boolean | Buyer (brand) side capability flag |
+| `is_publisher` | boolean | Seller (channel) side capability flag |
+| `owner_sales_id` | int FK | → `auth_user.id` — TL-side sales owner for this profile |
+| `owner_advertiser_id` | int FK | → `auth_user.id` — TL-side brand account owner |
+| `owner_publisher_id` | int FK | → `auth_user.id` — on advertiser profiles: the adops user in charge |
+| `media_buying_network_join_date` | date | MBN (brand-side buying network) join date. **MBN membership = this column IS NOT NULL.** ⚠️ Don't confuse with the channel's `media_selling_network_join_date` (MSN — the channel-side network). |
+| `superuser_notes` | text | Internal TL notes about the profile |
+| `buying_preference_*` | various | The brand's buying preferences (audience age/gender/geo shares, face-on-screen, custom instructions) |
+
+**Profile with the person's name and email:**
+```sql
+SELECT p.id, u.first_name, u.last_name, u.email, p.organization_name
+FROM thoughtleaders_profile p
+JOIN auth_user u ON u.id = p.user_id
+WHERE p.organization_id = 123
+LIMIT 50 OFFSET 0
+```
+
+### `thoughtleaders_profile` persona constants
 
 | Value | Label |
 |-------|-------|
@@ -298,7 +344,7 @@ Joining `adspot.publisher_id → profile.id` directly mixes ID spaces and return
 | 2 | Creator |
 | 3 | Talent Manager |
 | 4 | Media Agency |
-| 5 | Creator Service |
+| 5 | Other |
 
 ## `thoughtleaders_profile_channels` (Profile ↔ Channel M2M)
 

tl_cli/_plugin/skills/tl-keyword-research/SKILL.md

@@ -563,8 +563,8 @@ raw `|`/`+`/`-` are literal text in a link; `*`/`~` are rejected, enumerate
 variants first), and emits:
 
 - `filter_set` — platform shape (`keywords`, `keyword_operator`,
-  `content_fields`, per-group field/exclude maps). Fields are **ContentField
-  enum names** (`title`, `summary`, `transcript`, `channel_description`,
+  `content_fields`, per-group field/exclude maps). Fields are **recognized
+  content field names** (`title`, `summary`, `transcript`, `channel_description`,
   `channel_topic_description`, …) — unknown names fail loudly.
 - `report_link` — paste-ready URL that opens the report with the filter applied
   (no saved record, no credits). **The default thing to hand the user.**

tl_cli/_plugin/skills/tl-keyword-research/references/elasticsearch-content-search.md

@@ -13,7 +13,7 @@ The content alias holds **both** article docs and channel docs, distinguished by
 
 | `doc_type` | ~count | what it is | descriptive text fields |
 |---|---|---|---|
-| `article` | ~670M | one video / upload | `title`, `summary`, `transcript`, `content` |
+| `article` | ~670M | one video / upload | `title`, `summary`, `transcript` (or in case of podcast records, `content`) |
 | `channel` | ~44M | one whole channel | `name`, `description`, `ai.description`, `ai.topic_descriptions` |
 
 **Always scope by `doc_type`** or your counts silently mix videos and channels:
@@ -49,9 +49,9 @@ level filters on `format` 4 alone.
 
 **Article docs** (`doc_type: article`):
 - `title` — video title. Strongest relevance signal (see weighting).
-- `summary` — AI-generated summary of the video.
+- `summary` — **the video's creator-written description** (the text under the video: promo links, hashtags, subscribe blocks). Misleading name — it is NOT an AI summary. This is the main field for searching video description text.
 - `transcript` — raw transcript. Stored as timed XML (`<text start="..." dur="...">`), so a transcript hit carries timestamps if you parse it.
-- `content` — full content/transcript text.
+- `content` — ⚠️ podcast episodes' only;  usually show notes text or rarely transcripts; effectively absent on YouTube docs. Don't search for YouTube content.
 - `content_type` — `longform` | `short` | `live`. The default probe scope is
   `longform` (best sponsorable-content signal).
 - `channel` — object with `id`, `content_category`, `country`, `language`, `format` (NO descriptive text — see channel docs for that). `format` 4 = YouTube.
@@ -60,8 +60,8 @@ level filters on `format` 4 alone.
 **Channel docs** (`doc_type: channel`):
 - `name` — channel name.
 - `description` — the channel's own (YouTube) description.
-- `ai.description` — AI-written channel description.
-- `ai.topic_descriptions` — AI-written description of the channel's topics. **This is the "topic description" field** — prefer it for channel-fit validation; it's a focused, on-topic summary.
+- `ai.description` — AI-written channel description: third-person, always English regardless of the channel's language (~93% of channel docs).
+- `ai.topic_descriptions` — AI-written description of the channel's topics, a **single prose string, not an array**. **This is the "topic description" field** — prefer it for channel-fit validation; it's a focused, on-topic summary. ⚠️ Only ~37% of channel docs have it — a no-match here doesn't prove the channel is off-topic.
 - `ai.brand_safety` — letter grade (A–F).
 - `content_category`, `country`, `language`, `format`, `reach` (subscribers), `total_views`, `sponsorship_price`, `sponsorship_score`, `outreach_email`, `social_links`, `is_tl_channel`.
 
@@ -70,35 +70,42 @@ level filters on `format` 4 alone.
 > `is_tl_channel`→`is_tpp`; the Elasticsearch index **keeps the old names**.
 > Every ES `_source` / `term` / `range` / `sort` on channel docs must use
 > `reach`, `impression`/`impression_live`/`impression_shorts`, `is_tl_channel`.
-> Do not "fix" a probe to the new names — it silently returns nulls. Skill
+> Do not "fix" a probe to the new names — it silently returns nulls (verified
+> live: `subscribers`, `projected_views`, `is_tpp` each match **0** docs). Skill
 > *output* uses the new vocabulary (`subscribers`, `is_tpp`); the translation
 > point is `search_channels.py`'s sponsorability block.
 
-### ContentField names for the deliverable vs ES field names for probes
+### Content field names for the deliverable vs ES field names for probes
 
-The platform FilterSet / report link uses **ContentField enum** names; raw
+The platform FilterSet / report link uses its own **content field** names; raw
 `tl db es` probes use the **actual ES field paths**. They differ for channel
 fields — map them:
 
-| ContentField (filter set / report link) | ES field path (probe query) | doc_type |
+| Content field (filter set / report link) | ES field path (probe query) | doc_type |
 |---|---|---|
 | `title` | `title` | article |
 | `summary` | `summary` | article |
 | `transcript` | `transcript` | article |
 | `content` | `content` | article |
 | `channel.channel_name` | `name` | channel |
-| `channel_description` | `description` | channel |
+| `channel_description` | `description.domains` | channel |
 | `channel_description_ai` | `ai.description` | channel |
 | `channel_topic_description` | `ai.topic_descriptions` | channel |
 | `hashtags` | `hashtags` | article |
 
-Use ES paths in `probe.py` / raw queries; use ContentField names in
+Use ES paths in `probe.py` / raw queries; use content field names in
 `build_report.py` / the report link. `build_report.py` rejects any `content_fields`
-value that isn't a ContentField enum name, so passing a raw ES path (e.g.
+value that isn't a recognized content field name, so passing a raw ES path (e.g.
 `ai.topic_descriptions`) fails loudly rather than silently mis-filtering.
-(One asymmetry to know: probe counts on the bare `description` field are
-approximate for the `channel_description` ContentField — the delivered filter
-does not match exactly the same text.)
+
+The `channel_description` content field targets `description.domains` — the
+"About this channel" text additionally indexed so **whole domains are single
+searchable terms** (verified live: `patreon.com` matches every channel whose
+About-this-channel text links to patreon.com, including inside full URLs,
+which bare `description` probes
+undercount since URLs there tokenize into word pieces). For domain-shaped
+keywords (e.g. `substack.com`), probe against `description.domains`, not bare
+`description`.
 
 ### The report link / FilterSet keyword grammar (NOT simple_query_string)
 
@@ -152,6 +159,10 @@ Verified live (topic level, all-time): `fable 5` = `fable-5` = **1,215** docs;
 `fable5` = **94**; `fable five` = **118**; `fablefive` = **1**. Four different
 document populations — collapsing them in your head silently drops coverage.
 
+(One exception to the punctuation-split rule: the channel-doc
+`description.domains` subfield keeps whole domains as single terms —
+`patreon.com` is one token there. See the content field mapping above.)
+
 **Rule:** for any candidate carrying a number, version, model name, or anything
 that could be written solid vs spaced vs hyphenated, **probe each spelling as its
 own candidate** (spaced, solid, hyphenated, spelled-out, and the handle/hashtag
@@ -420,7 +431,7 @@ id and read `ai.topic_descriptions` / `ai.description`:
 Or run the probe with `--level channel` to search channel docs directly.
 
 **Channel-field probes approximate the delivered filter, they don't equal it.**
-A delivered filter keyword targeting a channel ContentField
+A delivered filter keyword targeting a channel content field
 (`channel_topic_description`, `channel_description`, …) matches **articles**
 whose channel matches — its result counts are videos. Raw probes can't run
 that parent-child join (the join query types are not accepted), so you probe

tl_cli/_plugin/skills/tl-keyword-research/references/help.md

@@ -100,7 +100,7 @@ stages, nothing dropped without telling you.
 | "one video per channel" | dedupes the trend feed to each channel's best match |
 | "only channels that cover it repeatedly" | focuses the channel table on the recurring tier (default threshold: 3+ matching uploads; say a number to change it) |
 | "last 6 months" (recency) | changes the 12-month window used for "still active" checks |
-| "title matches only" | restricts a keyword to titles — the cleanest field — instead of titles+descriptions+transcripts |
+| "title matches only" | restricts a keyword to titles — the cleanest field — instead of the default titles + video descriptions (the `summary` field) + transcripts |
 | "exclude [sense/word]" | adds an exclusion, scoped so it doesn't over-cut |
 | "broaden it" / "narrow it to X" | changes topic breadth mid-run |
 | "save it as a report" | persists a named, shareable report |

tl_cli/_plugin/skills/tl-keyword-research/scripts/build_report.py

@@ -97,17 +97,17 @@ REPORT_TYPES = {
     "channels": ("thoughtleaders", 3),
 }
 
-# Valid ContentField enum values (what the FilterSet / report link accept). Both
+# Valid content field names (what the FilterSet / report link accept). Both
 # article and channel fields are allowed on any report type — cross-field search
 # (a topic in the video AND in the channel description) is intentional. We
-# validate only that fields are real enum values, to catch typos / wrong names.
+# validate only that fields are recognized names, to catch typos / wrong names.
 VALID_CONTENT_FIELDS = {
     "content", "title", "summary", "transcript", "channel.channel_name", "hashtags",
     "channel_description", "channel_description_ai", "channel_topic_description",
     "channel_outreach_email", "channel_social_links",
 }
 
-# Default content fields (ContentField enum values) by report type.
+# Default content fields by report type.
 DEFAULT_FIELDS = {
     "videos": ["title", "summary", "transcript"],
     "content": ["title", "summary", "transcript"],
@@ -419,15 +419,15 @@ def main():
     for g in groups:
         g["text"] = str(g["text"]).strip()
 
-    # Validate every content field is a real ContentField enum value (catches
-    # typos / ES-path names like 'ai.topic_descriptions' used by mistake).
+    # Validate every content field is a recognized name (catches typos /
+    # ES-path names like 'ai.topic_descriptions' used by mistake).
     used_fields = set(default_fields)
     for g in groups:
         used_fields.update(g.get("content_fields") or [])
     unknown = sorted(f for f in used_fields if f not in VALID_CONTENT_FIELDS)
     if unknown:
         sys.exit(
-            f"unknown content_fields {unknown}; use ContentField enum values "
+            f"unknown content_fields {unknown}; use recognized content field names "
             f"(e.g. title, summary, transcript, channel_description, "
             f"channel_topic_description) — not raw ES paths. Valid: {sorted(VALID_CONTENT_FIELDS)}"
         )

tl_cli/_plugin/skills/tl-keyword-research/scripts/probe.py

@@ -37,8 +37,16 @@ import subprocess
 import sys
 
 # Article-level (doc_type:article) text fields vs channel-level (doc_type:channel).
+# `summary` holds the video's creator-written description (links, hashtags, promo)
+# — not an AI summary. Article-level `description` is empty and `content` is
+# podcast-only; neither belongs in these lists.
 TOPIC_FIELDS = ["title", "summary", "transcript"]
-CHANNEL_FIELDS = ["name", "description", "ai.description", "ai.topic_descriptions"]
+# `description.domains` alongside plain `description`: the delivered report
+# filter searches `description.domains`, which matches domain-shaped terms
+# (e.g. "patreon.com") that plain `description` undercounts (URLs there
+# tokenize into word pieces) — probing both keeps counts faithful to what
+# the delivered filter will actually match.
+CHANNEL_FIELDS = ["name", "description", "description.domains", "ai.description", "ai.topic_descriptions"]
 
 # The channel-identity field per level — used both to `collapse` samples to
 # distinct channels and to count distinct channels via a cardinality agg.

tl_cli/_plugin/skills/tl-save-report/SKILL.md

@@ -238,7 +238,7 @@ When in doubt, OR. Under AND, expand the keyword set conservatively — every ke
 
 | `report_type` | Default `content_fields` | When to expand |
 | --- | --- | --- |
-| 1 (CONTENT) | `["title", "summary", "content"]` (video-level text) | Add `["transcript"]` only if the user explicitly mentioned "transcript" / "spoken-word" / "creators saying". |
+| 1 (CONTENT) | `["title", "summary"]` (video title + the creator-written video description) | Add `["transcript"]` only if the user explicitly mentioned "transcript" / "spoken-word" / "creators saying". Add `["content"]` only for podcast-focused reports — it's the podcast show-notes field, absent on YouTube docs. |
 | 2 (BRANDS) | `["title", "summary"]` (brand-mention surfaces) | Rarely expanded; brand reports aggregate over mentions, not deep text. |
 | 3 (CHANNELS) | **`["channel.channel_name", "channel_description"]` ONLY** on the first save | Add `channel_description_ai` + `channel_topic_description` only if the narrow set obviously misses channels the session matched. The AI-summarised fields catalogue every topic a channel has *ever* touched — they answer *"has this channel ever mentioned X"* (too broad for discovery) rather than *"is this channel ABOUT X"* (what `channel_name` + `channel_description` answer). Field selection is the bigger dial; keyword pruning is the fine-tune. |
 | 8 (SPONSORSHIPS) | n/a — keyword fields are inert for type 8 | Sponsorships filter by relations, not content text. Don't emit `keywords` / `keyword_operator` / `content_fields` at all for type 8. |

tl_cli/_plugin/skills/tl-save-report/references/report_glossary.md

@@ -123,7 +123,7 @@ The `publish_status` set is `{3, 4, 5, 7, 9, 10}` (3 Sold, 4 Rejected by Brand,
 
 | User intent | Fields | Why |
 |---|---|---|
-| Match keywords in video transcripts/titles | `content_fields` includes `content`, `title`, `transcript` | Standard type 1 |
+| Match keywords in video transcripts/titles | `content_fields` includes `title`, `transcript` (add `summary` for the video's description text; `content` is podcast-only) | Standard type 1 |
 | Match channel descriptions only | `content_fields = ["channel_description", "channel_description_ai", "channel_topic_description"]` | Standard type 3 |
 | Different keywords need different fields | `keyword_content_fields_map` (per-position) | E.g., brand name → `channel.channel_name`; topic → descriptions |
 | "But not X" | `keywords` includes `X` + `keyword_exclude_map["<index>"] = true` | Substring negation per-position |

tl_cli/output/formatter.py

@@ -94,11 +94,13 @@ def output(
         # Banner still goes to stderr so it surfaces even when stdout is
         # piped through `jq` or redirected to a file.
         _print_quota_notice(data)
+        _print_server_warnings(data)
         return
 
     if not results:
         err_console.print("[dim]No results found.[/dim]")
         _print_quota_notice(data)
+        _print_server_warnings(data)
         _print_usage(usage)
         return
 
@@ -118,6 +120,7 @@ def output(
 
     _print_pagination_notice(data)
     _print_quota_notice(data)
+    _print_server_warnings(data)
     _print_usage(usage)
     _print_breadcrumbs(breadcrumbs)
 
@@ -496,6 +499,17 @@ def _format_wait_clause(data: dict) -> str:
     return ""
 
 
+def _print_server_warnings(data: dict) -> None:
+    """Print advisory `_warnings` from the response envelope (stderr).
+
+    The server attaches these to queries that ran but did something
+    costly or fragile (e.g. a leading-wildcard ILIKE that scans a whole
+    table). Advisory only — the results are still valid.
+    """
+    for warning in data.get("_warnings") or []:
+        err_console.print(f"[bold yellow]Warning:[/bold yellow] [yellow]{warning}[/yellow]")
+
+
 def _print_quota_notice(data: dict) -> None:
     """Print a banner when the server signals a billing-quota refusal or
     truncation on a raw-DB call.
@@ -546,6 +560,7 @@ def output_pricing_estimate(data: dict, fmt: str) -> None:
     """
     if fmt == "json":
         print(_dump_json(data))
+        _print_server_warnings(data)
         _print_usage(data.get("usage"))
         return
 
@@ -595,6 +610,7 @@ def output_pricing_estimate(data: dict, fmt: str) -> None:
             sub.add_row(path, "column (per row)", f"{_fmt_credits(val)}/row")
         console.print(sub)
 
+    _print_server_warnings(data)
     _print_usage(data.get("usage"))