thoughtleaders-cli 0.6.56__tar.gz → 0.7.0__tar.gz

{thoughtleaders_cli-0.6.56 → thoughtleaders_cli-0.7.0}/.claude-plugin/plugin.json

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

{thoughtleaders_cli-0.6.56 → thoughtleaders_cli-0.7.0}/AGENTS.md

@@ -1,6 +1,6 @@
 # Project Overview
 
-**tl-cli** is a Python CLI for querying ThoughtLeaders sponsorship data (sponsorships, channels, brands, uploads, snapshots, reports, recommender). Built with Typer + Rich + httpx. Designed as an "agent-first tool" — the CLI handles structured commands and output, while the user's AI agent (Claude) provides intelligence.
+**tl-cli** is a Python CLI for querying ThoughtLeaders sponsorship data (sponsorships, channels, brands, uploads, snapshots, reports, recommender). Built with Typer + Rich + httpx. Designed as an "AI agent-first tool" — the CLI handles data commands and output, while the user's AI agent (Claude) provides decision making.
 
 # Architecture
 
@@ -11,25 +11,16 @@
 ## Command Pattern (all data commands follow this)
 
 Every data command in `src/tl_cli/commands/` uses explicit Typer subcommands:
-- `list` — list/search with `key:value` filters as positional args
 - `show` — detail view by ID
 - `history` — historical data list
 - `create` / `add` — create new records (where applicable)
 
 When adding a new data command, follow this pattern. See `sponsorships.py` for the reference implementation.
 
-`deals`, `matches`, and `proposals` are shortcut commands that delegate to sponsorships' `do_list`/`do_show`/`do_create` with a pre-set status filter. They reject explicit `status:` filters — users should use `tl sponsorships list` for finer-grained status filtering.
-
-`recommender` (`commands/recommender.py`) wraps the recommender API at `/api/cli/v1/recommender/*` — `tags` (free), `top-channels` / `top-profiles` / `top-brands`, `inspect-channel`, `inspect-brand`, `similar-to-profile` (all 25 credits flat, Intelligence-gated). The three `top-*` URLs share one server resolver; `top-brands` dedupes the underlying profile rows by brand. Channel→channel and brand→brand similarity stay on `tl channels similar` / `tl brands similar`. When updating the SKILL or examples, prefer steering category/topic discovery (e.g. "Cooking channels") to `tl recommender top-channels "<tag>"` rather than `WHERE content_category = <code>` SQL — the recommender is ranked, not equality-based. The underlying recommender code uses "element"/"field_name" terminology; the CLI/API layer renames these to "tag" at the boundary.
-
-## Filter Parsing (`filters.py`)
-
-`parse_filters()` handles `key:value` and `key:"quoted value"` syntax. Returns `dict[str, str]` passed as query params. Date filter keys (listed in `DATE_FILTER_KEYS` — e.g. `since`, `created-at`, `created-at-start`, `publish-date-end`) accept keywords `today`, `yesterday`, `tomorrow`. Sponsorship date fields (`created-at`, `publish-date`, `purchase-date`, `send-date`) each expose three filter shapes: bare `<field>:<date>` matches within that date/period, and `<field>-start:` / `<field>-end:` give inclusive lower/upper bounds (both sides inclusive; partial dates expand to the whole period). Empty-string values result in `IS NULL` queries on the backend.
-
 ## Auth Flow (`auth/`)
 
 - **PKCE + Auth0**: Browser-based login with localhost callback server (`login.py`)
-- **Token Storage** (`token_store.py`): OS keyring primary, `~/.config/tl/credentials.json` fallback (0o600)
+- **Token Storage** (`token_store.py`): OS keyring primary, `~/.config/tl/credentials.json` fallback (chmod 0o600)
 - **Env override**: `TL_API_KEY` env var takes priority over keyring (for CI)
 - **Auto-refresh**: `TLClient` refreshes expired tokens on 401
 
@@ -52,6 +43,8 @@ TTY-aware: Rich tables in terminal, JSON when piped. Flags: `--json`, `--csv`, `
 The CLI integrates with AI coding agents via skills, commands, agents, and hooks.
 
 - **Claude Code** - `tl setup claude`
+- **Gemini** - `tl setup gemini`
+- **Codex** - `tl setup codex`
 - **OpenCode** - `tl setup opencode`
 
 This repo is also a Claude Code plugin, and can directly be installed as one.
@@ -60,8 +53,7 @@ This repo is also a Claude Code plugin, and can directly be installed as one.
 
 - **`tl`** — the main skill for querying ThoughtLeaders data. Default for any sponsorship / channel / brand / upload / report question.
 - **`tl-keyword-research`** — invoke whenever the user wants to find videos or channels by **content keywords** (topics, concepts, niches) that aren't covered by a curated recommender tag, OR to validate that a candidate channel's content actually touches a given topic. Returns `{operator, keywords:[{keyword,count}]}` from a ranked ES probe over `title` / `summary` / `transcript`; the caller then runs the actual content search with the surviving high-count terms. **Do not compose keyword sets by hand for `tl db es` content searches — delegate to this skill first.** See `skills/tl/SKILL.md` → *Channel & video discovery* for the four-path decision tree and when to use this vs the recommender / raw SQL.
-- **`tl-report-builder`** — invoke when the user wants to build, refine, or save a platform report (campaign config, FilterSet, columns, widgets). Multi-phase flow: routing → schema + validation → columns → widgets.
-- **`tl-import`**, **`tl-save-report`**, **`adapt-tl-data`** — narrower workflows; the skill files document their own triggers.
+- **`tl-import`**, **`tl-save-report`**, **`adapt-tl-data`**, **`tl-views-guarantee`** — narrower workflows; the skill files document their own triggers.
 
 ### Skill content boundaries
 
@@ -73,21 +65,6 @@ Skills under `skills/` are split into a `SKILL.md` and one or more `references/*
 
 When adding or updating skill content, place the fact in its single home and link from the others. Do not duplicate or "quick-recap" content across files — recaps are the highest drift surface.
 
-#### Anti-pattern: skill-local schema references
-
-When a dependent skill (e.g. `tl-report-builder`) needs to reference a schema fact (table layout, columns, fetch SQL, hallucinated-column markers), **link to the canonical home in `skills/tl/references/`** — do not create a new `<skill>/references/*.md` file that mirrors or paraphrases that content.
-
-Concrete regression marker: an earlier branch added `skills/tl-report-builder/references/data_plane.md` to consolidate the `thoughtleaders_topics` fetch query out of inline tool text. That had the right *shape* (don't restate schema in tool prose) but the wrong *home* — it forked schema facts into a parallel reference file that would silently drift from `skills/tl/references/postgres-schema.md`. The fix was to land the columns + fetch SQL + regression markers in `postgres-schema.md` (and upstream in `tl-data/references/postgres-schema.md`), delete the local file, and rewire the references via Markdown links.
-
-Rule of thumb: if you are about to write *"here's the SQL to query this table"* or *"these columns don't exist on this table"* anywhere outside `skills/tl/references/`, stop. Add the fact to the canonical reference, then link to the anchor. Same for business facts and the glossary.
-
-Skill-local `references/*.md` ARE appropriate when the content is **skill-shaped**, not schema-shaped:
-- Column metadata for a specific report type (sortable columns, formula templates) — `tl-report-builder/references/columns_*.md`
-- JSON schemas for tool-specific request/response shapes — `tl-report-builder/references/*_schema.json`
-- Disambiguation tables, defaults, and pitfall catalogues that exist only in this skill's flow — `tl-report-builder/references/report_glossary.md`
-
-If you are unsure whether a fact is schema-shaped or skill-shaped, ask: "would another TL skill (analyst, finance, mbn-outreach) ever need this fact?" If yes, it's schema/business-shaped — promote it to the canonical home.
-
 ## API Response Envelope
 
 All list endpoints return: `{ results, total, limit, offset, usage: { credits_charged, credit_rate, balance_remaining }, _breadcrumbs }`.
@@ -109,9 +86,11 @@ The version string is defined in three files and all three must be updated toget
 - `.claude-plugin/plugin.json` — `"version": "x.y.z"`
 - `src/tl_cli/__init__.py` — `__version__ = "x.y.z"`
 
-## Important Constraint
+## Creating a release
 
-`tl snapshots video` requires `--channel` flag — Firebolt queries without a channel partition are unbounded.
+A "release" means using the `gh` command to create a release on GitHub, named like the current package version number.
+
+Warn the user if they are creating a release and the latest commit didn't bump the version number, and ask for confirmation before releasing.
 
 ## Coding
 
@@ -119,14 +98,19 @@ The version string is defined in three files and all three must be updated toget
 * Do not let server implementation details into skill files (anything under `skills/`). Skills describe *what the CLI does* from the user's seat — observable command surface, inputs, outputs, examples. Do not say "the server enforces X", "the API validates Y on its side", "the backend rejects Z" — those are mechanism notes that drift the moment the server changes. State the user-visible behaviour ("unknown keys come back as 400") without naming where it's enforced.
 * **All `import` and `from X import Y` statements live at the top of the Python module file** — after the module docstring, before any code. No inline imports inside function bodies, no lazy imports for "speed" or "optional dependency" reasons. `from __future__ import …` goes at the very top (Python requires that). The only legitimate inline-import exception is **platform-conditional imports** that cannot succeed on the other platform (e.g. `import msvcrt` on Linux, `import termios`/`tty` on Windows) — those stay inside their `if sys.platform == …:` guard. If a circular-import problem makes a top-level import impossible, fix the circular dependency rather than working around it with an inline import.
 
+# Updating
+
+The `tl update --force` command will force an update of the `thoughtleaders-cli` package.
+The auto-update feature keeps the package updated, by checking (cached) on each command invocation.
+
 # Git commit rules
 
 Do not reference internal architecture of the ThoughtLeaders app in commit messages.
 
-When a feature is purely server-side but changes the data the CLI receives (e.g. adding, removing, or renaming a field on a response, changing a credit rate, expanding an enum), make a forced empty commit on the tl-cli repo (`git commit --allow-empty`) describing the change. This keeps the CLI repo's history a complete log of what users see, even when no client code had to change.
+When a feature is purely server-side but changes the data the CLI receives (e.g. adding, removing, or renaming a field on a response, changing a credit rate, expanding an enum), make a forced empty commit on the tl-cli repo (`git commit --allow-empty`) describing the change. This keeps the CLI repo's history a complete log of what users see, even when no client code had to change. The `tl changelog` command will read this log to show to the users.
 
 # Be aware of tests
 
-For every feature or change, explicitly consider whether tests need to be added or updated — new endpoint, new model field, new CLI command, new validation rule, new error path, anything that changes user-visible behaviour. Don't ship a feature without asking "what test covers this?" If no test does and the surface is non-trivial, write one. This applies across all repos involved in the change (server-side changes that ripple into the CLI need both server tests and CLI tests updated).
+For every feature or change, explicitly consider whether tests need to be added or updated, on this repo or on the server repo — new endpoint, new model field, new CLI command, new validation rule, new error path, anything that changes user-visible behaviour. Don't ship a feature without asking "what test covers this?" If no test does and the surface is non-trivial, write one. This applies across all repos involved in the change (server-side changes that ripple into the CLI need both server tests and CLI tests updated).
 
-Be sure to check if tests need to be updated when changing any data structures or function names, in all repos involved in the change.
+Be sure to check if tests need to be updated when changing any data structures or function names, in all repos involved in the change

{thoughtleaders_cli-0.6.56 → thoughtleaders_cli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thoughtleaders-cli
-Version: 0.6.56
+Version: 0.7.0
 Summary: ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligence
 Project-URL: Homepage, https://thoughtleaders.io
 Project-URL: Repository, https://github.com/ThoughtLeaders-io/thoughtleaders-cli
@@ -37,7 +37,7 @@ ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligenc
 ### For account managers and sales
 
 - **Pipeline reporting on the fly.** *"How many deals did we close in Q1?"*, *"What's my weighted pipeline by sales owner?"*, *"Which proposals are stuck in `pending` for more than 14 days?"* — one raw SQL or one structured command, instead of waiting on a dashboard.
-- **Brand intelligence in seconds.** *"What channels does Nike sponsor?"*, *"Which brands sponsor `MrBeast`?"*, *"What's Holafly's sponsorship history through us vs. through everyone?"* — answers are one `tl brands history` or one `tl db es` call away.
+- **Brand intelligence in seconds.** *"What channels does Nike sponsor?"*, *"Which brands sponsor `MrBeast`?"*, *"What's Holafly's sponsorship history through us vs. through everyone?"* — answers are one `tl db es` call away.
 - **Vetting candidates before a pitch.** Look up a channel by ID, name, YouTube URL, or `@handle`; pull its adspots, audience demographics, evergreenness score, and detected sponsor history before drafting the IO.
 - **Pre-flight before booking.** Confirm MSN/TPP membership, integration availability, and persona/plan eligibility for a brand profile with one SQL join.
 
@@ -66,6 +66,7 @@ ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligenc
 - [jq](https://stedolan.github.io/jq/)
 - [ripgrep](https://github.com/BurntSushi/ripgrep)
 - [duckdb](https://duckdb.org/)
+- [yt-dlp](https://github.com/yt-dlp/yt-dlp)
 
 For automated installs on MacOS, prefer installing Homebrew and use the pipx package manager, but ask the user if they have the admin access (sudo) password first. If not, proceed by using `uv` and installing everything locally.
 
@@ -170,8 +171,7 @@ tl recommender brands-for-channel 12345          # Brands most likely to sponsor
 
 # Brand intelligence
 tl brands show Nike
-tl brands history Nike                # Detected sponsorships from ES
-tl brands history-stats Nike          # Aggregate roll-up (totals, first/last seen, top channels)
+tl brands find Nike                   # Resolve a string → single brand id
 
 # Search videos and transcripts via Elasticsearch
 tl db es '{"size":20,"query":{"term":{"channel.id":12345}},"_source":["title","views"]}'
@@ -196,7 +196,7 @@ tl balance
 
 # Health check — auth, connectivity, version, latency, and required external tools.
 # Run this first when something feels off; it surfaces token expiry,
-# missing `jq`/`rg`/`duckdb`, and slow endpoints in one snapshot.
+# missing `jq`/`rg`/`duckdb`/`yt-dlp`, and slow endpoints in one snapshot.
 tl doctor
 ```
 
@@ -276,9 +276,10 @@ Each agent discovers the skill automatically and uses it when you ask about spon
 
 The plugin ships several focused skills (installed by all the `tl setup *` commands):
 
-- **`tl`** — the data-analyst skill. Defaults to raw database queries via `tl db pg|fb|es` for anything non-trivial; uses the structured `tl <resource> show` / `find` / `similar` / `history` commands for single-record lookups and the special cases they were built for (similarity search, ID resolution, sponsorship history). Comes with full schema references for Postgres, Elasticsearch, and Firebolt under `references/`.
+- **`tl`** — the data-analyst skill. Defaults to raw database queries via `tl db pg|fb|es` for anything non-trivial; uses the structured `tl <resource> show` / `find` / `similar` commands for single-record lookups and similarity / ID-resolution special cases. Comes with full schema references for Postgres, Elasticsearch, and Firebolt under `references/`.
 - **`tl-report-builder`** — builds TL reports (channels / brands / sponsorships / videos) from natural-language requests. Produces an in-chat preview by default; saves a real campaign when the user is explicit ("save", "create the report").
 - **`tl-import`** / **`bulk-import`** — superuser-only; bulk-add or exclude lists of channels, brands, videos, or sponsorships against a report.
+- **`tl-views-guarantee`** — sizes a multi-video sponsorship buy for a channel, returning the video bundle size, views guarantee, and likelihood to hit.
 
 ## Output Formats
 

{thoughtleaders_cli-0.6.56 → thoughtleaders_cli-0.7.0}/README.md

@@ -9,7 +9,7 @@ ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligenc
 ### For account managers and sales
 
 - **Pipeline reporting on the fly.** *"How many deals did we close in Q1?"*, *"What's my weighted pipeline by sales owner?"*, *"Which proposals are stuck in `pending` for more than 14 days?"* — one raw SQL or one structured command, instead of waiting on a dashboard.
-- **Brand intelligence in seconds.** *"What channels does Nike sponsor?"*, *"Which brands sponsor `MrBeast`?"*, *"What's Holafly's sponsorship history through us vs. through everyone?"* — answers are one `tl brands history` or one `tl db es` call away.
+- **Brand intelligence in seconds.** *"What channels does Nike sponsor?"*, *"Which brands sponsor `MrBeast`?"*, *"What's Holafly's sponsorship history through us vs. through everyone?"* — answers are one `tl db es` call away.
 - **Vetting candidates before a pitch.** Look up a channel by ID, name, YouTube URL, or `@handle`; pull its adspots, audience demographics, evergreenness score, and detected sponsor history before drafting the IO.
 - **Pre-flight before booking.** Confirm MSN/TPP membership, integration availability, and persona/plan eligibility for a brand profile with one SQL join.
 
@@ -38,6 +38,7 @@ ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligenc
 - [jq](https://stedolan.github.io/jq/)
 - [ripgrep](https://github.com/BurntSushi/ripgrep)
 - [duckdb](https://duckdb.org/)
+- [yt-dlp](https://github.com/yt-dlp/yt-dlp)
 
 For automated installs on MacOS, prefer installing Homebrew and use the pipx package manager, but ask the user if they have the admin access (sudo) password first. If not, proceed by using `uv` and installing everything locally.
 
@@ -142,8 +143,7 @@ tl recommender brands-for-channel 12345          # Brands most likely to sponsor
 
 # Brand intelligence
 tl brands show Nike
-tl brands history Nike                # Detected sponsorships from ES
-tl brands history-stats Nike          # Aggregate roll-up (totals, first/last seen, top channels)
+tl brands find Nike                   # Resolve a string → single brand id
 
 # Search videos and transcripts via Elasticsearch
 tl db es '{"size":20,"query":{"term":{"channel.id":12345}},"_source":["title","views"]}'
@@ -168,7 +168,7 @@ tl balance
 
 # Health check — auth, connectivity, version, latency, and required external tools.
 # Run this first when something feels off; it surfaces token expiry,
-# missing `jq`/`rg`/`duckdb`, and slow endpoints in one snapshot.
+# missing `jq`/`rg`/`duckdb`/`yt-dlp`, and slow endpoints in one snapshot.
 tl doctor
 ```
 
@@ -248,9 +248,10 @@ Each agent discovers the skill automatically and uses it when you ask about spon
 
 The plugin ships several focused skills (installed by all the `tl setup *` commands):
 
-- **`tl`** — the data-analyst skill. Defaults to raw database queries via `tl db pg|fb|es` for anything non-trivial; uses the structured `tl <resource> show` / `find` / `similar` / `history` commands for single-record lookups and the special cases they were built for (similarity search, ID resolution, sponsorship history). Comes with full schema references for Postgres, Elasticsearch, and Firebolt under `references/`.
+- **`tl`** — the data-analyst skill. Defaults to raw database queries via `tl db pg|fb|es` for anything non-trivial; uses the structured `tl <resource> show` / `find` / `similar` commands for single-record lookups and similarity / ID-resolution special cases. Comes with full schema references for Postgres, Elasticsearch, and Firebolt under `references/`.
 - **`tl-report-builder`** — builds TL reports (channels / brands / sponsorships / videos) from natural-language requests. Produces an in-chat preview by default; saves a real campaign when the user is explicit ("save", "create the report").
 - **`tl-import`** / **`bulk-import`** — superuser-only; bulk-add or exclude lists of channels, brands, videos, or sponsorships against a report.
+- **`tl-views-guarantee`** — sizes a multi-video sponsorship buy for a channel, returning the video bundle size, views guarantee, and likelihood to hit.
 
 ## Output Formats
 

{thoughtleaders_cli-0.6.56 → thoughtleaders_cli-0.7.0}/pyproject.toml

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

{thoughtleaders_cli-0.6.56 → thoughtleaders_cli-0.7.0}/skills/channel-authenticity/SKILL.md

@@ -25,10 +25,10 @@ investigations.
   view-curves can be hand-waved ("the algorithm", "we ran ads"); reading what
   the audience actually says is the only direct proof. A run without it is
   invalid.
-- **Data access is CLI-only.** Everything goes through `tl_cli.py` → the
-  `tl` CLI (`tl db pg/fb/es`, `tl channels similar`). No database credentials
-  are ever used. If the CLI isn't authenticated the skill fails fast with a
-  clear message.
+- **Data access is CLI-only.** Everything goes through `tl_cli.py` and the
+  `tl` CLI (`tl db pg/fb/es`, `tl channels similar`).
+- Do all data processing with the "utf-8" encoding explicitly in all scripts
+  you create.
 
 ## Setup check
 

thoughtleaders_cli-0.7.0/skills/channel-authenticity/scripts/_io_utf8.py

@@ -0,0 +1,53 @@
+"""Shared UTF-8 I/O setup for the channel-authenticity scripts.
+
+YouTube data is full of non-ASCII: channel names, comment text, emoji.
+On POSIX the default I/O encoding is already UTF-8, but on Windows the
+console and the default file encoding are the legacy code page (cp1252),
+so printing or writing that text raises ``UnicodeEncodeError`` (or
+silently mojibakes on read-back).
+
+Importing this module reconfigures ``stdout``/``stderr`` to UTF-8 on
+Windows (a no-op elsewhere, and idempotent), so every script that does
+``import _io_utf8`` can safely print Unicode. File reads/writes must
+still pass ``encoding="utf-8"`` explicitly — that's done at each call
+site — and child processes get ``child_env()`` so their stdio is UTF-8
+too. ``UTF8`` is exported for call sites that prefer the named constant.
+"""
+from __future__ import annotations
+
+import os
+import sys
+
+UTF8 = "utf-8"
+
+
+def _reconfigure_std_streams() -> None:
+    """Force stdout/stderr to UTF-8 on Windows. No-op on POSIX."""
+    if sys.platform != "win32":
+        return
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is None:
+            continue
+        try:
+            reconfigure(encoding=UTF8)
+        except (ValueError, OSError):
+            # Stream already detached / not reconfigurable (e.g. piped to a
+            # non-text sink) — leave it as-is rather than crash on import.
+            pass
+
+
+def child_env() -> dict[str, str]:
+    """``os.environ`` with UTF-8 forced, for subprocess children.
+
+    ``PYTHONUTF8=1`` enables UTF-8 mode for Python children; the
+    redundant ``PYTHONIOENCODING`` covers tools that read it directly.
+    Use as ``subprocess.run(..., env=child_env())``.
+    """
+    env = dict(os.environ)
+    env["PYTHONUTF8"] = "1"
+    env["PYTHONIOENCODING"] = UTF8
+    return env
+
+
+_reconfigure_std_streams()

{thoughtleaders_cli-0.6.56 → thoughtleaders_cli-0.7.0}/skills/channel-authenticity/scripts/analyze_channel.py

@@ -28,14 +28,16 @@ import sys
 import time
 from pathlib import Path
 
+import _io_utf8  # noqa: F401  (side effect: forces UTF-8 stdout/stderr on Windows)
 import anomaly_detector
 import comment_analyzer
 import engagement_ratios
 import resolve_channel
 import score as score_mod
-import tl_cli
 import video_integrity
 
+import tl_cli
+
 OUT_DIR = Path("/tmp")
 
 
@@ -74,8 +76,8 @@ def collect(ref: str) -> dict:
     }
     state_path = OUT_DIR / f"channel_authenticity_{cid}_{ts}.state.json"
     batch_path = OUT_DIR / f"channel_authenticity_{cid}_{ts}.llmbatch.json"
-    state_path.write_text(json.dumps(state, indent=2, default=str))
-    batch_path.write_text(json.dumps(gc.get("llm_batch", []), default=str))
+    state_path.write_text(json.dumps(state, indent=2, default=str), encoding="utf-8")
+    batch_path.write_text(json.dumps(gc.get("llm_batch", []), default=str), encoding="utf-8")
 
     return {
         "phase": "collect_done",
@@ -95,11 +97,11 @@ def collect(ref: str) -> dict:
 
 
 def finalize(state_path: str, llm_paths: list[str]) -> dict:
-    state = json.loads(Path(state_path).read_text())
+    state = json.loads(Path(state_path).read_text(encoding="utf-8"))
     passes: list[list[dict]] = []
     for lp in llm_paths:
         try:
-            c = json.loads(Path(lp).read_text())
+            c = json.loads(Path(lp).read_text(encoding="utf-8"))
             if isinstance(c, dict):
                 c = c.get("classifications", [])
             if c:
@@ -116,12 +118,12 @@ def finalize(state_path: str, llm_paths: list[str]) -> dict:
     ts = time.strftime("%Y%m%d-%H%M%S")
     final_json = OUT_DIR / f"channel_authenticity_{cid}_{ts}.final.json"
     report_md = OUT_DIR / f"channel_authenticity_{cid}_{ts}.report.md"
-    final_json.write_text(json.dumps(state, indent=2, default=str))
+    final_json.write_text(json.dumps(state, indent=2, default=str), encoding="utf-8")
 
     import report as report_mod
 
     md = report_mod.render(state)
-    report_md.write_text(md)
+    report_md.write_text(md, encoding="utf-8")
     return {"final_json": str(final_json), "report_md": str(report_md), "markdown": md}
 
 

{thoughtleaders_cli-0.6.56 → thoughtleaders_cli-0.7.0}/skills/channel-authenticity/scripts/anomaly_detector.py

@@ -11,9 +11,11 @@ from __future__ import annotations
 
 import statistics
 
-import tl_cli
+import _io_utf8  # noqa: F401  (side effect: forces UTF-8 stdout/stderr on Windows)
 import view_curves
 
+import tl_cli
+
 PENALTIES = {
     "B_burst_without_engagement": (25, "critical"),
     "B_engagement_incoherence": (25, "critical"),

{thoughtleaders_cli-0.6.56 → thoughtleaders_cli-0.7.0}/skills/channel-authenticity/scripts/comment_analyzer.py

@@ -18,6 +18,7 @@ import re
 import statistics
 from collections import Counter
 
+import _io_utf8  # noqa: F401  (side effect: forces UTF-8 stdout/stderr on Windows)
 import comment_scraper
 
 PENALTIES = {

{thoughtleaders_cli-0.6.56 → thoughtleaders_cli-0.7.0}/skills/channel-authenticity/scripts/comment_scraper.py

@@ -20,6 +20,8 @@ from __future__ import annotations
 
 import sys
 
+import _io_utf8  # noqa: F401  (side effect: forces UTF-8 stdout/stderr on Windows)
+
 
 def limit_for_views(views: int) -> int:
     if views >= 100_000:

{thoughtleaders_cli-0.6.56 → thoughtleaders_cli-0.7.0}/skills/channel-authenticity/scripts/engagement_ratios.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 
 import statistics
 
+import _io_utf8  # noqa: F401  (side effect: forces UTF-8 stdout/stderr on Windows)
 import peer_cohort
 
 # code -> (penalty, severity)

{thoughtleaders_cli-0.6.56 → thoughtleaders_cli-0.7.0}/skills/channel-authenticity/scripts/peer_cohort.py

@@ -15,6 +15,8 @@ import statistics
 import time
 from pathlib import Path
 
+import _io_utf8  # noqa: F401  (side effect: forces UTF-8 stdout/stderr on Windows)
+
 import tl_cli
 
 CACHE = Path(__file__).resolve().parent.parent / "references" / "peer-cohort-cache.json"
@@ -46,7 +48,7 @@ def _cache_key(channel: dict) -> str:
 def _load_cache() -> dict:
     if CACHE.exists():
         try:
-            return json.loads(CACHE.read_text())
+            return json.loads(CACHE.read_text(encoding="utf-8"))
         except json.JSONDecodeError:
             return {}
     return {}
@@ -54,7 +56,7 @@ def _load_cache() -> dict:
 
 def _save_cache(cache: dict) -> None:
     CACHE.parent.mkdir(parents=True, exist_ok=True)
-    CACHE.write_text(json.dumps(cache, indent=2, default=str))
+    CACHE.write_text(json.dumps(cache, indent=2, default=str), encoding="utf-8")
 
 
 def _peer_ids_via_cli(channel_id: int) -> list[int]:

{thoughtleaders_cli-0.6.56 → thoughtleaders_cli-0.7.0}/skills/channel-authenticity/scripts/report.py

@@ -2,6 +2,8 @@
 """Render the markdown narrative report from a finalized state dict."""
 from __future__ import annotations
 
+import _io_utf8  # noqa: F401  (side effect: forces UTF-8 stdout/stderr on Windows)
+
 SEV_ICON = {"critical": "🔴", "warning": "🟠", "info": "🟡"}
 VERDICT_ICON = {
     "CLEAN": "✅",
@@ -132,4 +134,5 @@ if __name__ == "__main__":
     import json
     import sys
 
-    print(render(json.load(open(sys.argv[1]))))
+    with open(sys.argv[1], encoding="utf-8") as fh:
+        print(render(json.load(fh)))

{thoughtleaders_cli-0.6.56 → thoughtleaders_cli-0.7.0}/skills/channel-authenticity/scripts/resolve_channel.py

@@ -19,6 +19,8 @@ from __future__ import annotations
 import json
 import sys
 
+import _io_utf8  # noqa: F401  (side effect: forces UTF-8 stdout/stderr on Windows)
+
 import tl_cli
 
 VIDEO_FETCH = 30  # how many recent of each content_type to pull

{thoughtleaders_cli-0.6.56 → thoughtleaders_cli-0.7.0}/skills/channel-authenticity/scripts/score.py

@@ -9,6 +9,8 @@ to "do not book" regardless of the mean.
 """
 from __future__ import annotations
 
+import _io_utf8  # noqa: F401  (side effect: forces UTF-8 stdout/stderr on Windows)
+
 BANDS = [
     (90, "CLEAN", "Safe to book at standard rates."),
     (70, "MINOR_FLAGS", "Book but note caveats to the AM."),
@@ -72,5 +74,6 @@ if __name__ == "__main__":
     import json
     import sys
 
-    d = json.load(open(sys.argv[1]))
+    with open(sys.argv[1], encoding="utf-8") as fh:
+        d = json.load(fh)
     print(json.dumps(composite(d["group_a"], d["group_b"], d["group_c"]), indent=2))

{thoughtleaders_cli-0.6.56 → thoughtleaders_cli-0.7.0}/skills/channel-authenticity/scripts/tl_cli.py

@@ -23,6 +23,8 @@ import os
 import shutil
 import subprocess
 
+import _io_utf8
+
 TL_BIN = os.environ.get("TL_CLI_BIN", "tl")
 
 
@@ -67,6 +69,9 @@ def _tl(args: list[str], *, input_text: str | None = None) -> str:
             input=input_text,
             capture_output=True,
             text=True,
+            encoding="utf-8",
+            errors="replace",
+            env=_io_utf8.child_env(),
             timeout=180,
         )
     except FileNotFoundError as exc:

{thoughtleaders_cli-0.6.56 → thoughtleaders_cli-0.7.0}/skills/channel-authenticity/scripts/video_integrity.py

@@ -29,6 +29,8 @@ from __future__ import annotations
 
 from datetime import date
 
+import _io_utf8  # noqa: F401  (side effect: forces UTF-8 stdout/stderr on Windows)
+
 import tl_cli
 
 PENALTIES = {

{thoughtleaders_cli-0.6.56 → thoughtleaders_cli-0.7.0}/skills/channel-authenticity/scripts/view_curves.py

@@ -15,6 +15,8 @@ from __future__ import annotations
 import math
 from dataclasses import dataclass
 
+import _io_utf8  # noqa: F401  (side effect: forces UTF-8 stdout/stderr on Windows)
+
 import tl_cli
 
 

{thoughtleaders_cli-0.6.56 → thoughtleaders_cli-0.7.0}/skills/tl/SKILL.md

@@ -151,11 +151,11 @@ Unless the user specifically asks for running a specific report or showing the r
 
    Skip the save offer when the result clearly doesn't fit a report type — a single scalar count, an aggregate roll-up across entity types, view-curve time series, schema introspection output, or anything that isn't a list of channels / brands / videos / sponsorships. A trailing offer on those would just be noise.
 
-Prefer writing shell code, `jq` commands, or `duckdb` commands that fetch or analysise large sets of data instead of analysing it yourself. On Mac and Linux, create temporary files in `/tmp` that can be analysed later in different ways. On Windows, create them in `%USERPROFILE%\AppData\Local\Temp`.  Before analysing a potentially large result set, first try fetching just a single result with `LIMIT 1` without `jq` etc, to see the shape of the data and any error messages.
+Prefer writing shell code, `jq` commands, or `duckdb` commands that fetch or analysise large sets of data instead of analysing it yourself. On Mac and Linux, create temporary files in `/tmp` that can be analysed later in different ways. On Windows, create them in the directory pointed to by the `%TEMP%` environment variable. When coding, do it in Python.
 
 ## Available Flows
 
-Note that if you're working on Windows, you must set up UTF-8 in the terminal with `PYTHONIOENCODING=utf-8 tl ...`, because all of these commands return UTF-8 data.
+Note that if you're working on Windows, you must set up UTF-8 because all commands take UTF-8 as inputs and output UTF-8 data. If using the `bash` tool, write commands using the Bash syntax, like `export PYTHONIOENCODING=utf-8 tl db es ...`.
 
 ### Data queries
 
@@ -465,6 +465,8 @@ tl channels find "MrBeast"
 tl brands find "NordVPN"
 ```
 
+If finding channels and brands fail, try variation on the name with or without whitespace.
+
 **Path 2. Curated tag / category / demographic** — user named a topic that maps cleanly to a recommender tag (`"Cooking"`, `"Tech"`, `"USA share"`, content categories, format hints). Use the recommender — it ranks channels by how strongly they load on a tag, returning ranked similarity scores instead of forcing exact equality. It also returns matching brand profiles alongside the channels — useful when the user wants to know "who buys this kind of inventory."
 
 ```bash
@@ -579,10 +581,6 @@ Users only see data their plan allows:
 - **Intelligence plan** required for `tl brands`, the full `tl recommender` surface, and `tl db es` access to full transcript / brand-mention data.
 - **Paid plan** required for `tl snapshots`.
 
-## Important: Status Labels
-
-When presenting sponsorship status data, always use human-readable labels — never raw codes. The `tl` CLI returns lowercase labels (`sold`, `pending`, `matched`, etc.) — capitalize them for display. Full mapping: proposed, unavailable, pending, sold, advertiser_reject → "Rejected by Advertiser", publisher_reject → "Rejected by Publisher", proposal_approved → "Proposal Approved", matched, outreach → "Reached Out", agency_reject → "Rejected by Agency".
-
 ## Important: Firebolt Snapshots
 
 `tl snapshots video` **always requires** `--channel`. Without it, the query scans 7.4 billion rows and times out. Always provide the channel ID.

{thoughtleaders_cli-0.6.56 → thoughtleaders_cli-0.7.0}/skills/tl/references/postgres-schema.md

@@ -191,12 +191,14 @@ A channel can have multiple adspots (different sellers: talent manager, direct,
 
 When composing `SELECT ... FROM thoughtleaders_channel ...`, do not improvise column names from semantic intuition — consult the output of `tl schema pg thoughtleaders_channel` or the column table above. The `tl schema` command is authoritative. Failed guesses return *"column '\<name\>' does not exist"* and cost a round-trip. Recurring problems:
 
+- Subscriber count is in the field named `reach`
+- Projected views is in the field named `impression`
 - ❌ **Suffix/qualifier variants of date columns** (e.g. an `_max` / `latest_` / `_date` form when the canonical column has neither). Date columns  use bare names.
 - ❌ **Platform-name-prefixed ID forms** (e.g. a platform-name prefix when the canonical column uses a neutral `external_` prefix). See the column table for the actual ID column.
 - ❌ **Bare-noun forms without the table-prefix** (e.g. `name` instead of `channel_name`). This table prefixes its display fields with `channel_` to avoid SQL keyword collisions and ambiguity in joins.
 - ❌ **User-facing-term forms used as SQL column names** (the user-facing word is sometimes different from the SQL column name; consult [business-glossary](business-glossary.md) for the canonical mapping when the two diverge).
 
-When the canonical column you need isn't obvious from the table above, consult `tl schema pg thoughtleaders_channel` or the above table first. Do **not** rely on a 400 to correct you, and do **not** fall back to `information_schema.columns` as the recovery path — that's a regression marker too.
+When the canonical column you need isn't obvious from the previous description, consult the output of `tl schema pg thoughtleaders_channel`. Do **not** rely on a 400 to correct you, and do **not** fall back to `information_schema.columns` as the recovery path — that's a regression marker too.
 
 ### Key columns for the `auth_user` table (Django Users)