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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thoughtleaders-cli
-Version: 0.9.0
+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.0.dist-info → thoughtleaders_cli-0.9.2.dist-info}/RECORD

@@ -1,11 +1,11 @@
-tl_cli/__init__.py,sha256=WON3A0H0emJM2B6Ak3Xo0tqVj-FCAsVFPLYnijGTurc,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
 tl_cli/filters.py,sha256=Yjj04lONGGmtCAIYN5i6KD12mAnUKEZ7i9heeWtdj7o,2952
 tl_cli/hints.py,sha256=cT8kuDtkAZqwXkc2RV0Yg_abofK-g9UiXwTTBunX78U,1557
-tl_cli/main.py,sha256=A_8b2SQjBKATxrjO7AGC5Ab1QWlP35gGo4TWzYZtlOM,5806
-tl_cli/query_history.py,sha256=tj9AxI2ADoC8a92Oacoyuljtqc_PPzA6o2X0Adhs2N8,3336
+tl_cli/main.py,sha256=1f0Hs43fzIVeOtIbb5oGIyyPFDSJ6NdVQYjumt0CIx0,5908
+tl_cli/query_history.py,sha256=vA5avDU1DBZDWSb-w2ZxEZxV2MD21cqwzfYjXawOWZI,5540
 tl_cli/self_update.py,sha256=zLPCSzPQTHRAcTZTBBopRxAs5Bg-B7Ag_7PxfN94QOI,18800
 tl_cli/auth/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tl_cli/auth/commands.py,sha256=CkCaKFb-xUwhCeIL92EC4-odiaSpLI1bmgg5tDCrclM,7387
@@ -13,7 +13,7 @@ tl_cli/auth/login.py,sha256=AxdQ8LOZd1uZhFXPyaiGB_Hk0RiVuX7t37gkjgoEOCM,11568
 tl_cli/auth/pkce.py,sha256=4Q6Ip-TeZFNG9c3swXNi4gH7mdMkltKa62gZZNybt8U,658
 tl_cli/auth/token_store.py,sha256=TcZnUol4-8r0jMEJhOPmABCX12_5RkAln2xfWPNdmHk,3275
 tl_cli/client/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-tl_cli/client/errors.py,sha256=KcTIieHtiEeBBDXTtEBSWsMcx2qaQskMyc_2_0l9WM4,2597
+tl_cli/client/errors.py,sha256=HEAEeFIgw_n_ZE9bkRRw6OPyqmwGhixzNN2bAxYj7wg,3246
 tl_cli/client/http.py,sha256=pUJYYuT0q92_SwqCuMj3ozBthvchKuKL9v9U_eCQv20,4164
 tl_cli/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tl_cli/commands/_comments_common.py,sha256=x91WPSpDdV8AwE8Mwx4VtZQKWXBufsnBnC1lFD0Tzys,4522
@@ -23,11 +23,12 @@ tl_cli/commands/bulk_import.py,sha256=d4y1k_lD52LPJcCqXxEmyHIqcIwomZgbjqs1_QxPje
 tl_cli/commands/changelog.py,sha256=D1PtDdHpawTlWqUHjKzVmv9yXLSU915UVmI3dZzEwyA,4241
 tl_cli/commands/channels.py,sha256=gs6jHaxi6WjB3D8jnJETFVvkTXpqzlWR-W4JkBeG3oY,20406
 tl_cli/commands/credits.py,sha256=2xCht2e420LmaFBKNdKoMz8GlTh31qSWSlJAnVzoZic,7308
-tl_cli/commands/db.py,sha256=JaiXLMB_ROkLS-ca6QHyMt-z2lrZlDlj6xqyralIKjQ,7209
+tl_cli/commands/db.py,sha256=fPqqw5m561Tx-JkRR-RE_b_otSIMtTwPMUI0neqiyZ8,8997
 tl_cli/commands/deals.py,sha256=ZK9yneInsC6DXoCPS65oyLoVR0eRW1xdRlEN7oRp1pc,2174
 tl_cli/commands/describe.py,sha256=3lURv4NllM5qPeMEBbejrIxiMzsyTwpJIz211-wuGCU,12362
 tl_cli/commands/doctor.py,sha256=KUKglwhMc7B26XXy_3M0LkHu7wqfFO5T0YPHO1SH1VY,9024
 tl_cli/commands/matches.py,sha256=K5o6B8FLECp7825dU4W3X8n-wuXvGJz57xpQPXeXQ-0,2886
+tl_cli/commands/profiles.py,sha256=nnfp96iKFxnj_We73t8NUGgL-1F_x2H2XG2QM0brXy8,2109
 tl_cli/commands/proposals.py,sha256=IXx9DsR7lPWRM4QvKB65t7xKNAK3H6ax9LIlIj8ydEs,2945
 tl_cli/commands/recommender.py,sha256=BZfviKAPhpZah0zaSyH5RDa23fG8QAkUnG5FDhOdi4I,21324
 tl_cli/commands/reports.py,sha256=7CL2atr0Y4XSE8U8kbuZ5-M-m3E9PKNZ0N_0Fbd_OkQ,26388
@@ -38,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=dWJgDJ55hRXjdV6whx5paU2eHpiLeAD61fysOKhPP9g,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
@@ -49,12 +50,12 @@ tl_cli/_plugin/agents/youtube-comment-classifier.md,sha256=S5lr_htA98FIX0su8FJ2n
 tl_cli/_plugin/hooks/hooks.json,sha256=FSWibw1xAjA-suFV3fR8btIb2kQ82LQ08otTr-NpmFw,835
 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=E9KeuXy6yeHEBOnOFW4hDW-Et-Dbp1Oh--3WXKfOX78,898
-tl_cli/_plugin/skills/tl/SKILL.md,sha256=yXyzaRL_GvQK2jQwHA-1ECk9GaIl-J-oAY9nWfm6JBU,66518
-tl_cli/_plugin/skills/tl/references/business-glossary.md,sha256=1aeSOL4OVvazAylmKJgqCvd9Iyh-FvXtE_r7TioEJgA,18385
-tl_cli/_plugin/skills/tl/references/elasticsearch-schema.md,sha256=FTGqtQNgddZP5KZdzsxAL6udAJjr79dUNz_4Aj9G_fo,13028
-tl_cli/_plugin/skills/tl/references/firebolt-schema.md,sha256=ywQNHrS5qwbng0e5wbZfyb5p5OUyhtByQJRr9WnQOgg,10665
-tl_cli/_plugin/skills/tl/references/postgres-schema.md,sha256=x61eR6gPZbfBwNaLL7fq3bPZRk-tU98PMCK6RtOoCU4,23625
+tl_cli/_plugin/hooks/scripts/pre-check.sh,sha256=inHopPXQ9h-KRcHuebEIQ-1EZmsTaHhAAMCFQ0MyiEQ,820
+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=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
@@ -74,34 +75,34 @@ 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=hGY-C451V1JTpRZ0haT5EbP9iKcvk7OQExziQ26m5_I,37098
+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=C8Ll59MT0cE_WZNYNmImvMhVyDcMnNdF25L-NilKyGo,11752
+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
 tl_cli/_plugin/skills/tl-save-report/references/widgets.md,sha256=LrqRyvZHOXVF15FglkeYh6io7f3cYmZEpH00WhEJWKw,9881
 tl_cli/_plugin/skills/tl-top-partnerships/SKILL.md,sha256=jOMMr40XRnAZv-oRLeyKJTku_st_3ErFn3QS_0dzZ8Q,6612
 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.0.dist-info/METADATA,sha256=5VZgzAKtq6SoV5ilzjUoSulaS-rxGrvU9h36uIpuL3A,19083
-thoughtleaders_cli-0.9.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-thoughtleaders_cli-0.9.0.dist-info/entry_points.txt,sha256=umZp-1BkGkHDG0bNZXpTXrjwW0HGf9IDFN40eAWuuvg,39
-thoughtleaders_cli-0.9.0.dist-info/licenses/LICENSE,sha256=RUfdfLsn6jygiyrnnVUHt6r4IPwr2rbDm9Kixgtu8fo,1071
-thoughtleaders_cli-0.9.0.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.0.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.0"
+__version__ = "0.9.2"

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

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

tl_cli/_plugin/hooks/scripts/pre-check.sh

@@ -20,11 +20,9 @@ if ! tl auth status --quiet 2>/dev/null; then
   exit 0  # Don't block, just warn
 fi
 
-# For list commands without explicit limit, suggest adding one
-if [[ "$COMMAND" =~ ^tl[[:space:]]+(deals|uploads|channels|brands)[[:space:]] ]]; then
-  if [[ ! "$COMMAND" =~ limit: ]] && [[ ! "$COMMAND" =~ --limit ]]; then
-    echo "HINT: Consider adding a limit to control credit usage (e.g., limit:50)" >&2
-  fi
-fi
+# NOTE: no "add a limit" hint here. List commands are server-limited by
+# default and typically cost far below the warning-worthy range, so the
+# hint was pure noise for agents (it fired on every unlimited list call
+# regardless of cost).
 
 exit 0

tl_cli/_plugin/skills/tl/SKILL.md

@@ -229,37 +229,45 @@ tl <entity> comment-edit <comment-id> "msg"  # Edit own comment (author or super
 ```bash
 tl sponsorships update <id> '<json>'   # Edit a sponsorship (adlink)
 tl channels update <id> '<json>'       # Edit a channel
+tl profiles update <id> '<json>'       # Edit a brand/publisher profile (superuser only)
 ```
 
 Examples:
 ```bash
 tl sponsorships update 98765 '{"publish_status": "sold"}'
 tl sponsorships update 98765 '{"publish_status": 3}'
+tl profiles update 8871 '{"superuser_notes": "VIP account — always cc the AM lead"}'
+tl profiles update 8871 '{"superuser_notes": null}'
 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
 itself the membership flag: set it to add the channel to MSN (it then reads as `is_msn` and
 appears in MSN-filtered queries), or send `null` to remove the channel from the network.
 
+**Profile notes.** `tl profiles update` (superuser only) edits a brand/publisher profile's
+**`superuser_notes`** — the internal free-text notes field on the customer record
+(`thoughtleaders_profile.superuser_notes`, max 2500 chars). Send a string to set, `null` to
+clear. This is currently the only editable profile field; anything else returns a 400 listing
+the editable surface. Use it for account-handling notes meant for the internal team — it is
+never shown to the customer.
+
 ### Creating and vetting sponsorships
 
 This is the end-to-end workflow for proposing a sponsorship, then moving it through the funnel as the two sides respond. Three create commands plus `tl sponsorships update` cover every state transition the CLI exposes.

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

@@ -69,6 +69,7 @@ Maps business terms to database concepts.
 | `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 |
+| `superuser_notes` | `profile` | Internal free-text account-handling notes on the customer record (max 2500 chars). Team-facing only — never shown to the customer. Superusers can edit it through the CLI (see SKILL.md → "Updating records"). |
 
 **Key insight:** Ownership exists on both `profile` (account-level) and `adlink` (deal-level). For revenue attribution, always use `adlink.owner_sales_id`.
 
@@ -96,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
 
@@ -106,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`.
@@ -119,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/firebolt-schema.md

@@ -33,10 +33,12 @@ Drop to `tl db fb` only when you need a shape `tl snapshots` doesn't produce (cu
 - **SELECT only.** No DDL/DML/transactions/SET/locks.
 - **Single table.** No JOIN, CTE (`WITH`), subquery, set operation, or `LATERAL`.
 - **Only known tables:** `article_metrics`, `channel_metrics`. Other names return `UNKNOWN_TABLE`.
+- **Constant-only probes are allowed:** `SELECT 1` (no FROM, no column references) works as a connectivity check. Anything naming a column or `*` still needs a FROM.
 - **WHERE/HAVING may only reference indexed columns** (`channel_id`/`id` for `article_metrics`; `id` for `channel_metrics`). Filtering by `age`, `publication_date`, `view_count`, `duration`, `scrape_date`, etc. in WHERE returns `NON_INDEXED_FILTER:<col>`. Apply those constraints client-side after fetching.
 - **Leading index column must be equality-or-IN-filtered with literals** (`channel_id = 1` or `channel_id IN (1,2,3)`). Without it: `MISSING_INDEXED_FILTER`.
 - **Trivial-aggregation exception:** a SELECT whose projected expressions are all aggregates and which has no GROUP BY / HAVING may omit WHERE entirely. Use only for tiny sanity checks.
 - **No mandatory LIMIT/OFFSET** — but Firebolt will time out on bad plans, so keep the leading-index filter selective.
+- **Errors carry the real diagnostic.** A query that Firebolt itself rejects (unknown column, syntax error) comes back as a 400 with Firebolt's own error description, plus a rename hint where one is known. Common trap: `channel_metrics` has `subscribers`, not the older `reach`.
 
 ## Tables