thoughtleaders-cli 0.6.51__tar.gz → 0.6.53__tar.gz

{thoughtleaders_cli-0.6.51 → thoughtleaders_cli-0.6.53}/.claude-plugin/plugin.json

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

{thoughtleaders_cli-0.6.51 → thoughtleaders_cli-0.6.53}/AGENTS.md

@@ -117,7 +117,7 @@ The version string is defined in three files and all three must be updated toget
 
 * Do not reference internal architecture of the ThoughtLeaders app in comments or skills. Specifially: do not reference internal table names, field names, API endpoints, Python modules or functions (including the sanitizer).
 * 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.
-* Place all imports at the start of the Python module file
+* **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.
 
 # Git commit rules
 

{thoughtleaders_cli-0.6.51 → thoughtleaders_cli-0.6.53}/PKG-INFO

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

{thoughtleaders_cli-0.6.51 → thoughtleaders_cli-0.6.53}/pyproject.toml

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

{thoughtleaders_cli-0.6.51 → thoughtleaders_cli-0.6.53}/skills/tl/SKILL.md

@@ -140,7 +140,14 @@ Unless the user specifically asks for running a specific report or showing the r
 3. **Decide the method of discovery**: If the user want to explore certain topics, use the recommender commands. If it's more about filtering, construct a query for PG or ES.
 4. **Always use --json**: Parse JSON output for multi-step analysis.
 5. **Chain commands**: For complex questions, chain multiple `tl` commands, shell commands, and other tools.
-6. **Format results**: When the user asks for a list or tabular data, present the results as a well-formatted markdown table. Pick the most relevant columns and use clear headers. Sort the result by relevant criteria - if the user asked for "top performers", order by the performance metric; if the user asked for "most recent", sort by the pertinent date desc. When the result is tabular, ask the user if they want to save the list as a report, and invoke the `tl-save-report` skill.
+6. **Format results**: When the user asks for a list or tabular data, present the results as a well-formatted markdown table. Pick the most relevant columns and use clear headers. Sort the result by relevant criteria - if the user asked for "top performers", order by the performance metric; if the user asked for "most recent", sort by the pertinent date desc.
+7. **Always offer to save the result as a report — if the rows fit a report type.** A "fits a report type" result is a table whose rows are **channels**, **brands**, **videos / uploads**, or **sponsorships / deals**. When that's the case, after the table close the reply with a save offer — don't wait for the user to ask. Suggested phrasing (adapt the noun to the entity):
+
+   > *Want me to save this as a saved TL report you can come back to? Say "save it as a report" and I'll ask whether you want a filter-style report (predicates re-evaluated on every run) or a list-style report (these exact IDs frozen).*
+
+   If the user says yes (or uses any of the save-trigger phrases, like `save it`, `save the list`, `make a report`, `persist this`, `turn this into a campaign`, `I want to come back to this`), invoke the `tl-save-report` skill — it owns the filter-vs-list decision flow, the FilterSet mapping, and the `tl reports create` / `tl reports save-list` save call. **Don't try to compose the report config yourself**; hand off to the skill.
+
+   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.
 
@@ -181,10 +188,6 @@ tl channels history <id-or-name>       # Sponsorship history
 tl channels similar <id-or-name>       # Similarity recommender (Intelligence plan)
 tl brands show <id-or-name>            # Brand detail
 tl brands find <query>                 # Resolve a string to {id, name}; matches name, slug, domain, or keyword
-tl brands history <id-or-name>         # Sponsorship history
-tl brands history <query> --channel <id>  # Brand mentions on specific channel
-tl brands history-stats <id-or-name>   # Aggregate roll-up: counts, total/avg/median views, first/last seen, by-year, top channels
-tl brands history-stats <q> --channel <id>  # Same roll-up, narrowed to one channel
 tl brands similar <id-or-name>         # Find similar brands via similarity search
 tl recommender tags [query]            # List similarity tag names — categories, demographics, formats
 tl recommender top-channels "<tag>"    # Top channels loaded on a similarity tag (Intelligence)
@@ -418,7 +421,7 @@ Load these on demand — don't read all upfront. Pick the one(s) relevant to the
 |---|---|---|
 | Arbitrary read-only `SELECT` on Postgres | **Available** via `tl db pg`. | SELECT-only, mandatory `LIMIT ≤ 500` + `OFFSET`, only certain SQL forms are allowed. See `references/postgres-schema.md`. |
 | Cross-reference helpers ("channels proposed to brand X", "channels sponsored by MBN brands in last N days") | **Available** via `tl db pg`. | Write the join: `thoughtleaders_adlink` ↔ `adspot` ↔ `channel` ↔ `profile` ↔ `profile_brands` ↔ `brand`. Filter by `publish_status` for proposed/sold and by date range as needed. See `references/postgres-schema.md` for the exact column names. |
-| **AdLink INSERT** with custom price/cost/owner/`weighted_price`/`created_where` | **Unavailable** — `tl sponsorships create` exists but only creates a free *proposal* between a channel and a brand. The `tl db pg` sanitizer accepts SELECT only — no INSERT/UPDATE. | Done in the app or by a human with DB access. |
+| **AdLink INSERT** with custom price/cost/owner/`weighted_price`/`created_where` | **Unavailable** — `tl sponsorships create` exists but only creates a *proposal* between a channel and a brand. The `tl db pg` sanitizer accepts SELECT only — no INSERT/UPDATE. | Done in the app or by a human with DB access. |
 | Pre-insert validation queries (joining `adspot ↔ channel ↔ profile ↔ org` to confirm MSN, integration=1, persona, plan) | **Available** via `tl db pg`. | One SELECT joining the four tables. Use `thoughtleaders_channel.media_selling_network_join_date IS NOT NULL` for MSN, `thoughtleaders_adspot.integration = 1` for mention adspots, `thoughtleaders_profile.persona` for the persona code (see persona constants in `references/postgres-schema.md`). |
 | Firebolt cross-table or join queries; filtering on non-indexed columns in WHERE | **Unavailable** — not accepted. | Fetch a wider slice keyed on `channel_id` (and optionally `id`), filter the rest in `jq`/Python. |
 | ES `query_string`, `regexp`, `wildcard`, `fuzzy`, `more_like_this`, parent/child joins; any `script_*`; multiple aggregations in one body | **Unavailable** — not accepted. | Rewrite using `term`/`terms`/`match`/`bool`/`nested`. For multi-agg dashboards, run multiple `tl db es` calls and combine client-side. For "similar"-style queries, try `tl channels similar` / `tl brands similar` (server-implemented similarity search). |
@@ -595,9 +598,102 @@ tl db pg "SELECT al.id, al.weighted_price, al.purchase_date, b.name AS brand
           LIMIT 500 OFFSET 0" --json
 ```
 
-### "What channels does Nike sponsor?":
+### Brand sponsorship history — what channels does Nike sponsor?
+
+Resolve the brand to an ID, then probe ES for articles where the brand appears in `sponsored_brand_mentions`. Channel names live in PG (the ES article doc only carries `channel.id`), so the third call joins them in.
+
+```bash
+# 1. Resolve "Nike" → brand ID
+tl brands find Nike --json   # → results[0].id, say 21416
+
+# 2. Recent sponsored videos for that brand (sorted by publication_date desc)
+tl db es '{
+  "size": 50,
+  "track_total_hits": true,
+  "query": {"bool": {"filter": [
+    {"term": {"doc_type": "article"}},
+    {"term": {"sponsored_brand_mentions": "21416"}}
+  ]}},
+  "sort": [{"publication_date": "desc"}],
+  "_source": ["title", "channel.id", "publication_date", "views"]
+}' --json > /tmp/nike_history.json
+
+# 3. Resolve channel.id → channel_name (one PG round-trip for the whole page)
+jq -r '[.results[].channel.id] | unique | map(tostring) | join(",")' /tmp/nike_history.json \
+  | xargs -I CH_IDS tl db pg "SELECT id, channel_name FROM thoughtleaders_channel WHERE id IN (CH_IDS)" --json
+
+# Narrow to a single channel:
+tl db es '{
+  "size": 50,
+  "track_total_hits": true,
+  "query": {"bool": {"filter": [
+    {"term": {"doc_type": "article"}},
+    {"term": {"sponsored_brand_mentions": "21416"}},
+    {"term": {"channel.id": 5607}}
+  ]}},
+  "sort": [{"publication_date": "desc"}],
+  "_source": ["title", "publication_date", "views"]
+}'
+
+# Was the video a TL-brokered deal? Cross-check ES video_id against AdLink.article_id:
+tl db pg "SELECT article_id FROM thoughtleaders_adlink
+          WHERE article_id IN ('1247603:8LskGvKUA9I', '1247603:abc123')"
+```
+
+### Brand sponsorship roll-up — totals, first/last seen, top channels, by-year
+
+The same ES filter (`doc_type=article` + `sponsored_brand_mentions=<id>`) with `size:0` + aggregations replaces a roll-up call. ES accepts **one aggregation total per request** (top-level + sub-aggs all count), so what would be a single server-side roll-up here splits into a few `tl db es` calls and one client-side join.
+
 ```bash
-tl brands history Nike --json
+# Totals + time range (one aggregation total — the four metric aggs are siblings under aggs and bill as a single body)
+tl db es '{
+  "size": 0,
+  "track_total_hits": true,
+  "query": {"bool": {"filter": [
+    {"term": {"doc_type": "article"}},
+    {"term": {"sponsored_brand_mentions": "21416"}}
+  ]}},
+  "aggs": {
+    "views_sum":  {"sum":   {"field": "views"}},
+    "views_avg":  {"avg":   {"field": "views"}},
+    "first_seen": {"min":   {"field": "publication_date"}},
+    "last_seen":  {"max":   {"field": "publication_date"}}
+  }
+}'
+
+# By-year breakdown (date_histogram only — no sub-agg, that would push over the one-agg cap)
+tl db es '{
+  "size": 0,
+  "query": {"bool": {"filter": [
+    {"term": {"doc_type": "article"}},
+    {"term": {"sponsored_brand_mentions": "21416"}}
+  ]}},
+  "aggs": {
+    "by_year": {"date_histogram": {
+      "field": "publication_date", "calendar_interval": "year",
+      "format": "yyyy", "min_doc_count": 1
+    }}
+  }
+}'
+
+# Top channels by sponsored-video count (terms agg only — for views per channel, run a second call per channel)
+tl db es '{
+  "size": 0,
+  "query": {"bool": {"filter": [
+    {"term": {"doc_type": "article"}},
+    {"term": {"sponsored_brand_mentions": "21416"}}
+  ]}},
+  "aggs": {
+    "by_channel": {"terms": {"field": "channel.id", "size": 10, "order": {"_count": "desc"}}}
+  }
+}'
+
+# TL-brokered deal count for the brand (PG, not ES — adlinks where the brand is on the creator profile)
+tl db pg "SELECT COUNT(*) AS tl_brokered
+          FROM thoughtleaders_adlink al
+          JOIN thoughtleaders_profile p  ON p.id = al.creator_profile_id
+          JOIN thoughtleaders_profile_brands pb ON pb.profile_id = p.id
+          WHERE pb.brand_id = 21416 AND al.article_id IS NOT NULL"
 ```
 
 ### "Compare view curves for two videos":

{thoughtleaders_cli-0.6.51 → thoughtleaders_cli-0.6.53}/skills/tl-report-builder/SKILL.md

@@ -1,12 +1,14 @@
 ---
 name: tl-report-builder
 description: |
-  Build TL reports from natural-language requests. Produces an in-chat preview (sample-rows table + filter summary + takeaways) by default, or auto-saves a TL report when the user's wording is explicit about it ("save", "create the report", "make a campaign for me to come back to"). Covers the four report types: content/videos (1), brands (2), channels (3), sponsorships/deals (8).
+  **MANUAL-INVOCATION-ONLY skill — do NOT auto-trigger on natural-language report requests.** This skill is invoked explicitly by the user (via the `/tl-report-builder` slash command, by naming the skill directly, or via some other unambiguous indication). Phrases like "build me a report", "make a campaign", "find me channels with filters Y", or "save this as a report" do NOT route here automatically. Those phrases go to other skills: the `tl` skill (for analysis / exploration of channels / brands / videos / sponsorships), `tl-save-report` (for persisting an in-chat session's result set as a saved report — filter-style or list-style), or `tl-import` (for adding identifiers to an existing report). This skill itself builds a brand-new TL report config from scratch through a heavy four-phase orchestration (routing → schema + validation → columns → widgets), covering the four report types: content/videos (1), brands (2), channels (3), sponsorships/deals (8). Only fire it when the user has explicitly chosen this path — there's almost always a lighter skill that's the right answer.
 
 ---
 
 # TL Report Builder Skill
 
+> **Manual invocation only.** This skill is heavy (four phases, multiple tool fires, sample validation against live data, FilterSet schema mapping). It is not the default for "I want a list of channels" or "save this as a report" — those are `tl` and `tl-save-report` respectively. Reach this skill only when the user has explicitly invoked it.
+
 Translate natural-language report requests into the campaign config JSON the TL dashboard accepts (a `Campaign` + `FilterSet` payload, ready to commit). The skill owns the orchestration end-to-end; sub-tools are invoked conditionally from within the Schema phase based on explicit criteria. Every phase may pause for follow-up interaction with the user when input is ambiguous, incomplete, or invalid.
 
 ## Core Objective

{thoughtleaders_cli-0.6.51 → thoughtleaders_cli-0.6.53}/skills/tl-report-builder/references/intelligence_filterset_schema.json

@@ -349,6 +349,21 @@
       "_tl_django_m2m": "FilterSet.exclude_brands via FilterSetExcludeBrand"
     },
 
+    "articles": {
+      "type": ["array", "null"],
+      "items": { "type": "string", "minLength": 3, "pattern": "^[0-9]+:[A-Za-z0-9_-]+$" },
+      "uniqueItems": true,
+      "description": "Resolved article (video / upload) IDs in the composite form `<channel_id>:<youtube_id>` (matches ES `_id`). M2M list — when populated, the report returns exactly these IDs, no filter logic. Used for list-style report-type-1 (CONTENT) reports.",
+      "_tl_django_m2m": "FilterSet.articles via FiltersetArticles"
+    },
+    "exclude_articles": {
+      "type": ["array", "null"],
+      "items": { "type": "string", "minLength": 3, "pattern": "^[0-9]+:[A-Za-z0-9_-]+$" },
+      "uniqueItems": true,
+      "description": "Article IDs to exclude (composite `<channel_id>:<youtube_id>` form). Pairs with a predicate-style FilterSet — useful for 'videos matching X, except these specific ones'.",
+      "_tl_django_m2m": "FilterSet.exclude_articles via FiltersetExcludeArticles"
+    },
+
     "networks": {
       "type": ["array", "null"],
       "items": { "type": "integer", "minimum": 1 },

thoughtleaders_cli-0.6.53/skills/tl-save-report/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: tl-save-report
+description: |
+  Save the results of an in-chat data-exploration session as a TL report. Triggers when the user wants to persist a channels / brands / videos (uploads) / sponsorships list or filtered set they've been working with — phrases like "save this as a report", "save the list", "turn this into a campaign", "persist this", "make a report from what you found", "save the result", "I want to come back to this". Asks the user up front whether to save it as a filter-style report (predicates re-evaluated against live data each run) or a list-style report (a frozen snapshot of the exact entity IDs from the session).
+---
+
+# tl-save-report
+
+Persist what the user has been exploring as a saved TL report. The skill assumes the data-exploration phase has already happened — the agent doesn't re-run queries, doesn't re-validate the result set, doesn't ask the user what they were looking for. Its single job is **config-from-session**: build a campaign config that captures the user's intent, post it via `tl reports create --config-file`.
+
+This is intentionally lighter than `tl-report-builder`. Report-builder runs a four-phase orchestration to TURN a natural-language request INTO a config; save-report TAKES a session that already produced data and writes that data out as a saved report. If the user is starting from scratch ("build me a list of …"), hand off to `tl-report-builder` — don't run save-report.
+
+## When to invoke
+
+**Invoke when** the user has been exploring data in the current session (running `tl db pg|fb|es` queries, structured `tl` commands, or both) and now wants to **save the result** as a report they can come back to. Trigger phrases include:
+
+- "save this as a report" / "save the list" / "save the result"
+- "turn this into a campaign" / "persist this"
+- "make a report from what you found"
+- "I want to come back to this" / "set up a report for these"
+
+The entity being saved must be one of: **channels**, **brands**, **videos / uploads / articles**, or **sponsorships / deals**.
+
+**Skip when**:
+
+- The user wants the report **built from scratch** from a natural-language request (no prior session exploration to capture) → hand off to `tl-report-builder`.
+- The user wants to **add to an existing report** (`"add these channels to report 1234"`) → hand off to `tl-import`.
+- The user only wants the data **shown / counted / analysed in chat** without saving → stay in `tl`; don't invoke this skill.
+
+## Step 1 — Detect the report type
+
+Match the session's primary entity to one of four report types:
+
+| Session entity | Report type | `report_type` code |
+| --- | --- | --- |
+| Channels | CHANNELS | `3` |
+| Brands | BRANDS | `2` |
+| Videos / uploads / articles | CONTENT | `1` |
+| Sponsorships / deals / adlinks | SPONSORSHIPS | `8` |
+
+If the session joined entities (e.g. channels with their recent sponsorships), pick the **one the user actually wants to save** and ask if unclear. The other side becomes either a column or a filter, not the report subject.
+
+## Step 2 — Ask: filter-style or list-style?
+
+This is the single most important decision; ask the user before assembling anything. Don't pick silently.
+
+**Suggested wording**:
+
+> Two ways to save this:
+>
+> • **Filter-style** — I map the criteria from this session (subscriber floor, content categories, keywords, date range, etc.) into the report's filters. The report stays live: every time someone re-runs it, the filters re-evaluate against current data and the result set refreshes.
+>
+> • **List-style** — I snapshot the exact entity IDs we found in this session. The list is frozen — it always shows these IDs, no filter logic. Useful when you've curated the set and don't want re-evaluation.
+>
+> Which do you want?
+
+The two styles differ in **which part of the FilterSet you populate**:
+
+- **Filter-style → predicate fields populated** (`keywords`, `min_reach`, `country`, dates, demographics, etc.). Through-table M2M fields stay empty.
+- **List-style → through-table M2M fields populated** (`channels` / `brands` / `articles` / `sponsorships`). Predicate fields stay empty.
+
+A hybrid (some predicates + some M2M IDs) is *legal* but rarely what the user asked for — confirm before mixing them.
+
+### When filter-style is the right answer
+
+Pick filter-style when the user's session was driven by criteria the platform's FilterSet can express directly — keyword searches over `title` / `summary` / `transcript` / channel description, attribute thresholds (`min_reach`, `min_views`, country / language), categorical scoping (content categories, demographics, MSN status), date ranges, similar-to-channels.
+
+When the user said something like *"channels in the cooking niche with >100K subs, all-time"* — the criteria map cleanly into a FilterSet, and the user almost certainly wants the report to keep refreshing as new channels meet the bar.
+
+### When list-style is the right answer
+
+Pick list-style when:
+
+- The session produced a **specifically curated set** the user wants frozen (manual review, similar-channel walks, cross-reference subtraction, sponsorship-history dedup) — *"these 14 channels are the ones we're pitching, save this exact list"*.
+- The session's **filters can't be mapped** into FilterSet fields cleanly (custom raw-SQL joins, multi-source aggregation in `jq`/`duckdb`, anything where the filter logic lived in the shell pipeline rather than in the platform schema). The honest move is list-style.
+- The user explicitly said *"snapshot"*, *"freeze"*, *"this exact list"*, *"don't re-evaluate"*.
+
+### Filter-style — mapping session criteria into the FilterSet
+
+The authoritative field catalogues live in the report-builder's references:
+
+- **Types 1 / 2 / 3** (CONTENT, BRANDS, CHANNELS): [`../tl-report-builder/references/intelligence_filterset_schema.json`](../tl-report-builder/references/intelligence_filterset_schema.json)
+- **Type 8** (SPONSORSHIPS): [`../tl-report-builder/references/sponsorship_filterset_schema.json`](../tl-report-builder/references/sponsorship_filterset_schema.json)
+
+Don't invent fields. The schema's keys are the only ones the platform accepts; unknown keys come back as `400 Invalid filterset.<field>`.
+
+Common mappings (use the schema file for the full list):
+
+| Session criterion | FilterSet field |
+| --- | --- |
+| Topic keywords (`"crypto"`, `"biohacking"`) | `keywords[]` + `keyword_operator` (`AND`/`OR`) + `content_fields[]` |
+| Subscriber floor | `min_reach` |
+| Views / impression floor | `min_views`, `min_impression` |
+| Content category | `content_categories[]` |
+| Country / language | `country`, `language` |
+| MSN-only | `msn_channels_only: true` |
+| Demographics (age / gender / geo) | `demographic_male_share`, `demographic_usa_share`, `demographic_geo`, etc. |
+| Publication date range | `start_date`, `end_date`, or `days_ago` |
+| Sponsorship date range (type 8) | `start_date` / `end_date` (send axis), `createdat_from` / `createdat_to` (created axis) |
+| Cross-reference (`"not pitched to brand X"`) | `cross_references[]` |
+| Similar-to-channels | `filters_json.similar_to_channels[]` |
+| Brand mention filter | `sponsored_brand_mentions[]` (via `filters_json`) |
+| Publish-status (sponsorships) | `publish_status` |
+
+If the session used filters that don't map cleanly, tell the user: *"I can't map [the specific predicate] into a FilterSet — the platform doesn't expose that field directly. Want to fall back to list-style for this report?"*
+
+### List-style — populating the M2M
+
+Collect the entity IDs from the session results into a single array and place them in the corresponding through-table M2M field:
+
+| Entity | FilterSet M2M field | ID shape | Exclude variant |
+| --- | --- | --- | --- |
+| Channels | `channels` | integer IDs | `exclude_channels` |
+| Brands | `brands` | integer IDs | `exclude_brands` |
+| Videos / uploads / articles | `articles` | composite string `<channel_id>:<youtube_id>` (matches ES `_id`) | `exclude_articles` |
+| Sponsorships | `sponsorships` | integer IDs (AdLink IDs) | `exclude_sponsorships` |
+
+**Article IDs are the composite string form**, not bare YouTube video IDs. If the session has YouTube IDs (`dQw4w9WgXcQ`) without channel prefixes, fetch `channel.id` for each via `tl db es` and rebuild the composite form before saving.
+
+All other FilterSet predicate fields stay empty (`null` or omitted). Populating both a predicate AND the M2M creates a hybrid filter — the platform will still accept it, but the result set then becomes "IDs in the M2M that ALSO pass the predicate", which is almost never what the user said they wanted. Confirm before mixing.
+
+The `exclude_*` variants pair with a separate predicate-style FilterSet — useful when the user said *"channels matching X, except these specific IDs"*. That's a hybrid by design; both halves get populated.
+
+## Step 3 — Title and description (mandatory)
+
+`tl reports create` rejects with HTTP 400 if either is missing — the validation regression has happened before. Always generate both:
+
+- **`report_title`** — ≤ 60 chars. Capture the niche or intent: *"TPP fintech channels — May 2026"*, *"Speedcubing channels — curated list"*, *"Q1 2026 sold sponsorships, beauty brands"*.
+- **`report_description`** — 1–3 sentences. Summarise what's in the report and how it was assembled. **Mention "filter-style" or "list-style" explicitly** so future readers know what they're looking at (list-style reports can look identical to filter-style ones from the dashboard if nobody documents the choice).
+
+Propose values and let the user edit. Don't ship blank strings.
+
+## Step 4 — Pick columns
+
+Use the type's default column set; agents shouldn't compose columns from scratch when the session didn't specify any. Defaults live in:
+
+- Type 1: [`../tl-report-builder/references/columns_content.md`](../tl-report-builder/references/columns_content.md)
+- Type 2: [`../tl-report-builder/references/columns_brands.md`](../tl-report-builder/references/columns_brands.md)
+- Type 3: [`../tl-report-builder/references/columns_channels.md`](../tl-report-builder/references/columns_channels.md)
+- Type 8: [`../tl-report-builder/references/columns_sponsorships.md`](../tl-report-builder/references/columns_sponsorships.md)
+
+If the session showed the user specific columns (`"show reach, subscribers, country"`), include those PLUS the type's required defaults. Validate that the `sort` value references a column that's actually present in the emitted `columns` dict — otherwise the report fails to render.
+
+For **custom columns** (computed formulas the user defined inline during the session), include them under `columns._custom` per the column-builder convention; consult the type's `columns_<type>.md` for the custom-column shape.
+
+## Step 5 — Pick widgets
+
+Use a default set per report type. Don't over-engineer — the user can refine via `tl reports update` after saving. Widget catalogues:
+
+- Types 1 / 2 / 3: [`../tl-report-builder/references/intelligence_widget_schema.json`](../tl-report-builder/references/intelligence_widget_schema.json)
+- Type 8: [`../tl-report-builder/references/sponsorship_widget_schema.json`](../tl-report-builder/references/sponsorship_widget_schema.json)
+
+Pick 4–6 widgets. For type 8 specifically, the schema's `_tl_axis_branching` rules pick the correct axis based on which date field the FilterSet populates (`send_date` for proposals, `purchase_date` for sold).
+
+For **list-style** reports the widgets still render — they aggregate over the frozen ID list. Pick the same defaults as filter-style; the user reading the saved report wants the dashboard view either way.
+
+## Step 6 — Assemble the config
+
+Final config shape (`Campaign` + `FilterSet` + columns + widgets):
+
+```json
+{
+  "type": 2,
+  "report_type": 1 | 2 | 3 | 8,
+  "report_title": "...",
+  "report_description": "...",
+  "filterset": { ... },
+  "columns": { ... },
+  "widgets": [ ... ],
+  "histogram_bucket_size": "month",
+  "sort": "-reach"
+}
+```
+
+`type=2` (DYNAMIC) is the campaign-model contract; don't change it.
+
+Write to a portable temp file and verify the file exists before saving:
+
+```bash
+TMP=$(mktemp -t tl-save-report-XXXX.json)
+cat > "$TMP" <<'EOF'
+{ ...config... }
+EOF
+ls -la "$TMP"   # verify before save
+```
+
+**Don't write the transport file under the user's project directory.** It's a transport, not a deliverable.
+
+## Step 7 — Save
+
+Two save paths, pick by style:
+
+**List-style — `tl reports save-list`** is the simpler path. It accepts an entity + ID file + title + description, builds the minimal config, and POSTs in one call. Skip steps 4–6 entirely when you take this route — the command's defaults handle them, and the user can refine later via `tl reports update`.
+
+```bash
+# Write the IDs (one per line — integers for channels/brands/sponsorships;
+# composite `<channel_id>:<youtube_id>` strings for articles).
+printf '5607\n12345\n67890\n' > "$IDS"
+
+tl reports save-list channels --ids-file "$IDS" \
+    --title "TPP fintech — May 2026 curated" \
+    --description "List-style: 3 channels hand-picked after the May 2026 review pass." \
+    --yes --json
+```
+
+**Filter-style — `tl reports create --config-file`** is the path that needs the full config (columns + widgets + sort built from steps 4–6):
+
+```bash
+tl reports create --config-file "$TMP" --yes --json
+```
+
+- `--yes` skips the confirmation prompt (the user already chose).
+- `--json` makes the response parseable so you can extract `report_url` and `campaign_id` cleanly.
+- `--config-file` (not `--config`) sidesteps shell-quoting issues with apostrophes / dollar signs / backticks in titles or keywords.
+
+On success the response envelope contains:
+
+```json
+{
+  "results": [{
+    "campaign_id": 12345,
+    "report_url": "/dashboard/reports/12345/",
+    "unresolved_names": []
+  }],
+  "usage": { "credits_charged": ..., "balance_remaining": ... }
+}
+```
+
+On failure (HTTP 4xx / 5xx): **surface the error verbatim**. Do NOT silently report success. Common failure modes:
+
+- `400 Missing required field: report_title` / `report_description` → you skipped step 3, go back.
+- `400 Invalid filterset.<field>` → the mapping in step 2 produced an unknown FilterSet field; check against the schema and remove the offending key.
+- `400 Invalid columns.<column>` → the chosen column isn't in the type's `columns_<type>.md` catalogue.
+- `403 Forbidden` → the user lacks the plan required for this report type (Intelligence for 1/2/3 in some orgs; check `tl whoami`).
+
+## Step 8 — Report back
+
+Echo the saved URL + ID, plus a follow-up offer for refinement:
+
+> Saved as report **12345**: https://app.thoughtleaders.io/dashboard/reports/12345/
+>
+> Want to refine the columns, widgets, title, or description? Tell me what to change and I'll run `tl reports update`.
+
+The follow-up offer matters because **FilterSet changes (keywords, demographics, M2M lists) can't be patched in place** via `tl reports update` — they require saving a new variant. Surface that limitation only if the user actually asks to change FilterSet fields.
+
+## Self-check before saving
+
+1. `report_title` is non-empty and ≤ 60 chars.
+2. `report_description` is non-empty, 1–3 sentences, explicitly says "filter-style" or "list-style".
+3. `report_type` matches the session's primary entity (1 / 2 / 3 / 8).
+4. `type` is `2` (DYNAMIC).
+5. `sort` references a column actually present in `columns`.
+6. **For filter-style**: no M2M `channels` / `brands` / `articles` / `sponsorships` populated unless the user explicitly asked for a narrow-to-these-IDs overlay (hybrid case).
+7. **For list-style**: no predicate fields (`keywords`, `min_reach`, dates, etc.) populated — the M2M is the entire filter.
+8. **For list-style with articles** (type 1): every entry in `filterset.articles` is the composite `<channel_id>:<youtube_id>` form, not a bare YouTube ID.
+9. Transport file written to a portable temp path (not the user's working directory) and verified to exist before `tl reports create`.
+
+## What this skill does NOT do
+
+- **No Phase 1–4 orchestration**, no AI-driven keyword research, no name resolution, no `sample_judge` validation pass. The session already produced the data — re-running discovery would be wasted effort. If the user comes in with a natural-language request and no prior session, that's `tl-report-builder`'s job, not this skill's.
+- **No editing of existing reports.** If the user wants to refine an already-saved report's columns, widgets, title, or description, run `tl reports update <id>` directly. For FilterSet refinements, the platform requires saving a new variant.
+- **No bulk-importing into an existing report.** That's `tl-import`'s role. Save-report only creates new reports.

{thoughtleaders_cli-0.6.51 → thoughtleaders_cli-0.6.53}/src/tl_cli/__init__.py

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

{thoughtleaders_cli-0.6.51 → thoughtleaders_cli-0.6.53}/src/tl_cli/commands/bulk_import.py

@@ -11,6 +11,7 @@ import time
 from pathlib import Path
 
 import typer
+from pytoon import encode as toon_encode
 from rich.console import Console
 
 from tl_cli.client.errors import ApiError, handle_api_error
@@ -59,6 +60,7 @@ def bulk_import_command(
     ids_file: str | None = typer.Option(None, "--ids-file", "-f", help="Path to file with one identifier per line. Omit to read from stdin."),
     exclude: bool = typer.Option(False, "--exclude", help="Mark these identifiers as excluded from the report instead of included"),
     json_output: bool = typer.Option(False, "--json", help="JSON output (default)"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
 ) -> None:
     """Bulk-import entities into a report.
 
@@ -113,7 +115,9 @@ def bulk_import_command(
         client.close()
 
     output = {"task_id": task_id, **result}
-    if json_output or not sys.stdout.isatty():
+    if toon_output:
+        sys.stdout.write(toon_encode(output) + "\n")
+    elif json_output or not sys.stdout.isatty():
         json.dump(output, sys.stdout, indent=2)
         sys.stdout.write("\n")
     else:

{thoughtleaders_cli-0.6.51 → thoughtleaders_cli-0.6.53}/src/tl_cli/commands/credits.py

@@ -18,6 +18,7 @@ import webbrowser
 from decimal import Decimal, InvalidOperation
 
 import typer
+from pytoon import encode as toon_encode
 from rich.console import Console
 from rich.prompt import Prompt
 from rich.table import Table
@@ -34,6 +35,7 @@ err = Console(stderr=True)
 @app.command("pricing")
 def pricing_cmd(
     json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
 ) -> None:
     """Show the credit-to-USD rate, minimum purchase, and starter balance.
 
@@ -48,6 +50,10 @@ def pricing_cmd(
     finally:
         client.close()
 
+    if toon_output:
+        print(toon_encode(data))
+        return
+
     if json_output:
         print(json.dumps(data, indent=2, default=str))
         return
@@ -150,9 +156,10 @@ def history_cmd(
     limit: int = typer.Option(25, "--limit", help="Max rows to show"),
     offset: int = typer.Option(0, "--offset", help="Offset for pagination"),
     json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
 ) -> None:
     """Show recent credit top-ups for your organization (free)."""
-    fmt = detect_format(json_output, False, False, False)
+    fmt = detect_format(json_output, False, False, toon_output)
     client = get_client()
     try:
         data = client.get("/credit-purchases", params={"limit": limit, "offset": offset})
@@ -166,6 +173,10 @@ def history_cmd(
         print(json.dumps(data, indent=2, default=str))
         return
 
+    if fmt == "toon":
+        print(toon_encode(data.get("results", [])))
+        return
+
     rows = data.get("results", [])
     if not rows:
         console.print("[dim]No credit purchases yet. Run `tl credits buy --amount-usd N`.[/dim]")