thoughtleaders-cli 0.6.38__tar.gz → 0.6.40__tar.gz

{thoughtleaders_cli-0.6.38 → thoughtleaders_cli-0.6.40}/.claude-plugin/plugin.json

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

{thoughtleaders_cli-0.6.38 → thoughtleaders_cli-0.6.40}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thoughtleaders-cli
-Version: 0.6.38
+Version: 0.6.40
 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.38 → thoughtleaders_cli-0.6.40}/pyproject.toml

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

{thoughtleaders_cli-0.6.38 → thoughtleaders_cli-0.6.40}/skills/tl/SKILL.md

@@ -151,44 +151,46 @@ Note that if you're working on Windows, you need to set up UTF-8 in the console,
 
 ### Data queries
 ```bash
-tl sponsorships list [filters...]      # Sponsorships — list curve, mult 1.0
-tl sponsorships show <id>              # Sponsorship detail (2 credits)
-tl sponsorships create --channel <id> --brand <id>  # Create proposal (free)
-tl sponsorships update <id> '<json>'   # Update a sponsorship (2 credits)
-tl deals list [filters...]             # Shortcut: agreed-upon sponsorships (status:deal); same curve as sponsorships list
-tl deals show <id>                     # Deal detail (2 credits)
-tl matches list [filters...]           # Shortcut: possible brand-channel pairings (status:match); same curve
-tl matches show <id>                   # Match detail (2 credits)
-tl matches create --channel <id> --brand <id>  # Create match (free)
-tl proposals list [filters...]         # Shortcut: proposed matches (status:proposal); same curve
-tl proposals show <id>                 # Proposal detail (2 credits)
-tl proposals create --channel <id> --brand <id>  # Create proposal (free)
-tl uploads list [filters...]           # Video uploads from ES — list curve, mult 1.0
-tl uploads show <id>                   # Upload detail (2 credits)
-tl channels show <id-or-name>          # Channel detail (2 credits; accepts numeric ID or name) — for channel search use raw SQL on thoughtleaders_channel
-tl channels update <id> '<json>'       # Update a channel (2 credits)
-tl channels history <id-or-name>       # Sponsorship history (5 credits/result, linear)
-tl channels similar <id-or-name>       # Similarity recommender (25 credits flat; Intelligence plan)
-tl brands show <id-or-name>            # Brand detail (1 credit)
-tl brands history <id-or-name>         # Sponsorship history (5 credits/result, linear)
+tl sponsorships list [filters...]      # Sponsorships
+tl sponsorships show <id>              # Sponsorship detail
+tl sponsorships create --channel <id> --brand <id>  # Create proposal
+tl sponsorships update <id> '<json>'   # Update a sponsorship
+tl deals list [filters...]             # Shortcut: agreed-upon sponsorships (status:deal)
+tl deals show <id>                     # Deal detail
+tl matches list [filters...]           # Shortcut: possible brand-channel pairings (status:match)
+tl matches show <id>                   # Match detail
+tl matches create --channel <id> --brand <id>  # Create match
+tl proposals list [filters...]         # Shortcut: proposed matches (status:proposal)
+tl proposals show <id>                 # Proposal detail
+tl proposals create --channel <id> --brand <id>  # Create proposal
+tl uploads list [filters...]           # Video uploads from ES
+tl uploads show <id>                   # Upload detail
+tl channels show <id-or-name>          # Channel detail (accepts numeric ID or name) — for channel search use raw SQL on thoughtleaders_channel
+tl channels find <query>               # Resolve a string to {id, name}; accepts name/slug, YouTube URL/handle/ID, video URL (queues a scrape if no match)
+tl channels update <id> '<json>'       # Update a channel
+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 (5 credits flat)
+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 (25 credits flat)
-tl recommender tags [query]            # List similarity tag names — categories, demographics, formats (free)
-tl recommender top-channels "<tag>"    # Top channels loaded on a similarity tag (25 credits; Intelligence)
-tl recommender top-profiles "<tag>"    # Top brand profiles loaded on a similarity tag (25 credits)
-tl recommender top-brands "<tag>"      # Top brands (deduped from profiles) loaded on a similarity tag (25 credits)
-tl recommender inspect-channel <ref>   # Show a channel's similarity-profile breakdown (25 credits; Intelligence)
-tl recommender inspect-brand <ref>     # Show a brand profile's ideal similarity-profile breakdown (25 credits; Intelligence)
-tl recommender similar-to-profile <id> # Channels closest to a brand profile's ideal profile (25 credits; Intelligence)
+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)
+tl recommender top-profiles "<tag>"    # Top brand profiles loaded on a similarity tag
+tl recommender top-brands "<tag>"      # Top brands (deduped from profiles) loaded on a similarity tag
+tl recommender inspect-channel <ref>   # Show a channel's similarity-profile breakdown (Intelligence)
+tl recommender inspect-brand <ref>     # Show a brand profile's ideal similarity-profile breakdown (Intelligence)
+tl recommender similar-to-profile <id> # Channels closest to a brand profile's ideal profile (Intelligence)
 tl snapshots channel <id>              # Channel metrics over time (Firebolt-backed)
 tl snapshots video <id> --channel <id> # Video view curve (--channel required!)
 tl reports                             # List saved reports
-tl reports run <id>                    # Run a saved report (credits vary)
+tl reports run <id>                    # Run a saved report
 tl <entity> comment-list <id>          # List comments on a sponsorship/channel/brand/upload
-tl <entity> comment-add <id> "msg"     # Add a comment (free)
-tl <entity> comment-edit <comment-id> "msg"  # Edit own comment (author or superuser; free)
+tl <entity> comment-add <id> "msg"     # Add a comment
+tl <entity> comment-edit <comment-id> "msg"  # Edit own comment (author or superuser)
 ```
 
 **Credit costs are server-authoritative — run `tl describe` (overview) or `tl describe show <resource>` (one resource) to see the current rates and multipliers for every endpoint. Do not memorise rate values — they change.**
@@ -211,6 +213,86 @@ tl channels update 12345 '{"demographic_male_share": 55, "demographic_usa_share"
 
 Each call costs 2 credits. If a request is rejected with a 400, the response body names the offending key — read it and retry with a smaller body. If the user wants to edit something the API rejects, the change has to be made in the app or by a human with DB access.
 
+### 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.
+
+#### Creating a sponsorship
+
+`tl sponsorships create` always creates the adlink in **proposed** status. Use the `tl matches create` or `tl proposals create` shortcuts when you specifically want a `matched` adlink or want a clearer log of intent — they share the same backend and accept the same flags.
+
+```bash
+# Minimum: channel ID + brand ID. Creates a proposal (publish_status=PREVIEW=0).
+tl sponsorships create --channel 5607 --brand 11459
+
+# Optional price (USD):
+tl sponsorships create --channel 5607 --brand 11459 --price 2500
+
+# Short flags:
+tl sponsorships create -c 5607 -b 11459 -p 2500
+
+# JSON body — same shape as the server expects. Use this form when the
+# fields come from another tool, or when scripting:
+tl sponsorships create '{"channel_id": 5607, "brand_id": 11459, "price": 2500}'
+
+# Capture the new adlink id for follow-up update calls:
+tl sponsorships create -c 5607 -b 11459 --json | jq -r '.results[0].sponsorship_id'
+
+# Shortcuts (delegated to the same server endpoint with a preset status):
+tl matches create -c 5607 -b 11459      # creates with publish_status=matched (7)
+tl proposals create -c 5607 -b 11459    # creates with publish_status=proposed (0)
+```
+
+Required: `--channel/-c <int>`, `--brand/-b <int>` (or the equivalent keys in the JSON body). Optional: `--price/-p <float>`, `--json`, `--toon`. **JSON and command-line flags are mutually exclusive on `tl sponsorships create` — pass one form or the other, never both.** The JSON body accepts `channel_id`, `brand_id`, `price`, and optionally `status`; defaults to `status: "proposed"` if omitted. Returns the created adlink with a `tl sponsorships show <id>` hint.
+
+The adlink is owned by the **brand's** advertiser profile (not the calling user's profile) and its `list` FK is set to the requested brand — so the new sponsorship appears under the brand's pipeline, not the AM's.
+
+#### Vetting (state transitions via `tl sponsorships update`)
+
+After a sponsorship exists, `tl sponsorships update <id> '<json>'` is the single CLI lever for moving it through the funnel. The interesting transitions for vetting are below — pass `publish_status` as a string label (the integer code also works but the label is clearer for both humans and the audit log).
+
+| Action | Command | What it means |
+|---|---|---|
+| **Accept** (either side, in negotiation) | `tl sponsorships update <id> '{"publish_status": "pending"}'` | Moves the adlink to `PENDING` — both sides are working it but it's not yet sold. |
+| **Mark sold** (deal finalised) | `tl sponsorships update <id> '{"publish_status": "sold"}'` | Final commercial step. Sets purchase semantics server-side. |
+| **Reject — Advertiser side** | `tl sponsorships update <id> '{"publish_status": "advertiser_reject"}'` | Maps to `DENY` ("Rejected by Advertiser"). Use when the *brand* turns the offer down. |
+| **Reject — Publisher side** | `tl sponsorships update <id> '{"publish_status": "publisher_reject"}'` | Maps to `REJECT` ("Rejected by Publisher"). Use when the *channel* turns the offer down. |
+| **Reject — Agency** | `tl sponsorships update <id> '{"publish_status": "agency_reject"}'` | When an agency intermediary kills the deal. |
+
+**Choosing the right rejection label** — match the label to the side actually rejecting:
+
+- The CLI caller is acting for / on behalf of an **Advertiser** (Brand) → use `advertiser_reject`.
+- The CLI caller is acting for / on behalf of a **Publisher** (Channel) → use `publisher_reject`.
+- If you don't know which side, ask before running the update — the two labels are not interchangeable downstream (they drive different reporting and different KPIs).
+
+**`rejection_reason` is mandatory whenever you set `publish_status` to any rejection label** (`advertiser_reject`, `publisher_reject`, or `agency_reject`). Do not issue a rejection update without it — a rejection with no reason is treated as an incomplete record by downstream reporting and AM workflows. If the user hasn't given you a reason, ask before running the update. Add `rejection_reason_details` whenever the user gives you more context — it's free-form supporting text and is fine to omit when the short `rejection_reason` is self-evident.
+
+```bash
+tl sponsorships update 98765 '{
+  "publish_status": "advertiser_reject",
+  "rejection_reason": "off-brand audience",
+  "rejection_reason_details": "Brand wants 18-34 male; channel skews 35-54 female"
+}'
+```
+
+Full set of `publish_status` labels the CLI accepts: `proposed`, `unavailable`, `pending`, `sold`, `advertiser_reject`, `publisher_reject`, `proposal_approved`, `matched`, `outreach`, `agency_reject`. Numeric codes (0–9) are also accepted but labels are preferred.
+
+#### Worked example: propose → reject
+
+```bash
+# 1. Create the proposal and capture its id.
+sid=$(tl sponsorships create -c 5607 -b 11459 -p 2500 --json | jq -r '.results[0].sponsorship_id')
+
+# 2. Later, the brand declines. rejection_reason is mandatory.
+tl sponsorships update "$sid" '{
+  "publish_status": "advertiser_reject",
+  "rejection_reason": "budget cut for Q3"
+}'
+
+# 3. Verify final state.
+tl sponsorships show "$sid" --json | jq '{id, status, rejection_reason}'
+```
+
 ### Raw queries (`tl db`)
 
 `tl db pg|fb|es` is the default tool. Reach for it whenever the question is anything beyond a trivially simple lookup — and use the structured commands only for those trivial cases (single-record `show`, plain filtered `list`). Don't paginate-and-reduce in your head when one SQL or ES body would do it server-side.
@@ -477,6 +559,21 @@ tl reports --json  # Find the report ID first
 tl reports run 42 --json
 ```
 
+"Look up a channel or brand from whatever the user pasted":
+```bash
+# Channel: accepts name, slug, YouTube channel URL, handle (@…), raw channel ID
+# (UC…), or any video URL. On ambiguity returns 400 with candidate {id, name};
+# on an unrecognised YouTube URL it queues a scrape and returns 404 with the
+# QueuedChannel record so the caller knows to retry later.
+tl channels find "https://www.youtube.com/@MrBeast"
+tl channels find "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
+tl channels find UCX6OQ3DkcsbYNE6H8uQQuVA
+
+# Brand: matches name, slug, website domain, or any keyword in kw/keywords.
+tl brands find nike.com
+tl brands find "Just Do It"
+```
+
 "Find Cooking channels with US-heavy mobile audiences":
 ```bash
 # Use the recommender for the topic, then narrow with structured filters / SQL on the IDs.

{thoughtleaders_cli-0.6.38 → thoughtleaders_cli-0.6.40}/skills/tl-report-builder/SKILL.md

@@ -13,6 +13,8 @@ description: |
 
   Save-intent variants ("save a campaign of …", "create the report …", "make a TL report for …") trigger auto-save; everything else previews. Off-taxonomy keywords ("crypto / Web3"), brand-exclusion logic ("not pitched to X"), demographic floors ("US audience ≥30%"), TPP/MSN scoping, and competitive-pitch shapes are all this skill's job — not the general `tl-cli:tl` data-analyst skill.
 
+  **Post-save refinements default to ASKING** — when the user's follow-up arrives after a successful save AND the topic overlaps with the prior save (same brand / niche / report type), the skill MUST surface the choice between updating the existing report, saving a separate variant, or treating as a fresh save. Refinement vocabulary (*instead*, *change*, *add*, *limit*, *only*, *filter*, *make it X*, etc.) strengthens the trigger but its absence does NOT bypass it — topic overlap alone is enough to ask. Do NOT auto-create a new report on every refinement-shaped prompt in a session. **Note**: the CLI edit endpoint can only patch campaign-level fields (title, description, columns, widgets, etc.); FilterSet changes (keywords, filters, demographics, cross-references) cannot be updated in place — those route to "save as a new variant" instead. See "Editing a saved report" in the body for the routing decision table + mechanics.
+
   **Skip this skill** for:
   - counts, metrics, trends, single-record show-by-ID lookups, raw exploratory queries, or analytical questions that aren't shaped as "give me a list" → route to `tl-cli:tl`.
   - **explicit intent to import a list of identifiers into a report — existing or new.** The routing test is the **user's import intent**, NOT the mere presence of a list. A user can paste 50 channel URLs and want analysis, comparison, similar-channel discovery, or filtered lookup — those still belong here (or in `tl-cli:tl`), not in tl-import. They can also paste 50 URLs and want exactly those channels to land in a report as-given — that is import, route to `tl-cli:tl-import`. The deciding question: *"Would the user be satisfied if the listed entities simply ended up as the report's contents exactly as-given, no transformation?"* If yes → import intent → `tl-cli:tl-import`. If they expect filtering, analysis, similarity expansion, or any other transformation on top of the list → it's not import, keep it here.
@@ -213,6 +215,93 @@ Same architecture, different intent. The prompt is exploratory; the policy says
 
 If the user replies *"yes save it"* or *"save"* → run the save step (resolve a portable temp path → write → verify → invoke `tl reports create --config-file <that-exact-path> --yes`; see Save-or-preview policy step 1+2 for the full mechanics) using the **same config that's already in working memory**. Don't re-run Phases 1–4. The follow-up reply is just the takeaways + saved-report link.
 
+### Editing a saved report (post-save refinement flow)
+
+When the user's follow-up after a successful save is a **refinement** of the report we just created — *"change X to Y"*, *"use Z instead"*, *"add an A column"*, *"sort by last published"*, *"rename the report"* — the right response depends on **what** the user wants to change. The CLI edit endpoint accepts only a narrow set of fields; FilterSet changes need a different path.
+
+**What `tl reports update` CAN edit today** (campaign-level fields only):
+
+- `title`, `description`, `report_type`, `type`
+- `columns`, `widgets`, `histogram_bucket_size`
+- `emoji`, `display_mode`
+- `owner`, `subscribers`, `link`
+- `webhook_url`, `notifications_on`, `message_template`
+
+**What `tl reports update` does NOT edit** (the backend explicitly rejects these — `CliReportEditView` docstring: *"Filterset edits are not supported here"*):
+
+- `filterset` and any of its fields (`keywords`, `keyword_groups`, `channels`, `brands`, `start_date`, `end_date`, `days_ago`, `msn_channels_only`, `creator_countries`, etc.)
+- `filters_json` (the catch-all containing `publish_status`, `ad_publish_status`, etc.)
+- `cross_references`
+
+The backend's `_reject_unknown_fields` validation is **atomic** — if the update payload contains any unsupported key (e.g. `filterset`), the WHOLE request returns HTTP 400, including any legitimate field edits in the same payload. The skill must therefore send ONLY editable fields in the patch, never the full working-memory config.
+
+**Routing decision** — what kind of refinement the user is asking for:
+
+| User wants to change | Editable via `tl reports update`? | Skill's action |
+|---|---|---|
+| Title, description, emoji, display mode | ✅ Yes | Update in place via the mechanics below |
+| Columns (add/remove/reorder) | ✅ Yes | Update in place |
+| Widgets, histogram bucket size | ✅ Yes | Update in place |
+| Subscribers, webhook, notifications | ✅ Yes | Update in place |
+| **Any filter field** — keywords, brands, channels, language, date range, MSN flag, demographics, cross_references, filters_json | ❌ **No** | **Cannot update in place.** Tell the user: *"The CLI edit endpoint can't patch FilterSet fields today (server-side limitation — `CliReportEditView`'s filterset path isn't wired up). I can save this as a new variant of the report instead — same shape with the filter change applied — and link it back to the original. OK to proceed?"* On confirmation: run Phase 1–4 with the prior config as the starting point + the user's filter delta, save as a NEW report. NOT an edit.
+
+**Recognition** — treat the follow-up as an edit candidate based on these signals:
+
+1. The most recent terminal action in this session was a successful `tl reports create` invocation. The resulting `report_id` and the full config it wrote are in working memory.
+2. The new prompt's topic overlaps with the prior save — same report type, same primary brand / niche / channel set, same competitive frame. (If the new prompt opens a fundamentally different topic, it's a new save.)
+3. The new prompt contains a **refinement signal** — broadly defined. Refinement signals include:
+   - **Refinement vocabulary**: *instead*, *change*, *swap*, *drop*, *add*, *tighter*, *broader*, *narrower*, *without*, *except*, *now with*, *but with*, *use … instead of …*
+   - **Filter / sort modifiers**: *filter*, *limit*, *only*, *remove*, *replace*, *include*, *exclude*, *sort by [field]*
+   - **"Make it X" framings**: *make it [country]-only*, *make it [category]-only*, *make it [demographic-shape]*
+   - **Partial-filter prompts** that name a single filter axis without naming a new topic: *"with AdSpot price < $2K"* after a save on the same niche
+
+**Decision rule** (not binary — ask when in doubt):
+
+| 1 (prior save) | 2 (topic overlap) | 3 (refinement signal) | Action |
+|---|---|---|---|
+| ✓ | ✓ | strongly fires | Post-save trigger fires (Follow-Up Interactions). Ask update vs. variant; default-highlight **update**. |
+| ✓ | ✓ | ambiguous OR absent | **Still ask** — topic overlap alone is reason enough to surface the choice. Default-highlight update; user can override to "save a separate variant" or "it's a new report." |
+| ✓ | ✗ | n/a | Different topic → treat as new save; no clarifier needed. |
+| ✗ | n/a | n/a | No prior save in working memory → standard preview/save flow; nothing to edit. |
+
+The failure mode the skill is preventing: silent auto-create on every refinement prompt, producing N duplicate reports instead of one updated report. A clarifier is one ignorable line if the user wanted a new variant anyway; the cost of getting it wrong is the duplicate.
+
+**Mechanics — when the user confirms "update the existing one" AND the change is in the editable-field whitelist above:**
+
+1. **Source the current config from working memory.** Recognition criterion 1 requires the prior save happened in this session, so the full config the skill emitted is still in working memory. **The CLI does NOT today expose a `tl reports show` / refetch command** — if for any reason the prior config is NOT in working memory (session was cleared, or the user is editing a report from a different session by ID), STOP and ask the user to (a) confirm the `report_id` and (b) describe the specific change. Do NOT guess at the current config.
+2. **Compose the patch — ONLY editable fields.** Build a JSON object containing **only the fields the user explicitly asked to change**, drawn exclusively from the editable-field whitelist (title, description, columns, widgets, histogram_bucket_size, emoji, display_mode, subscribers, webhook_url, notifications_on, message_template, report_type, type, owner, link). **Do NOT send the full working-memory config** — it contains `filterset`, `cross_references`, `filters_json`, and other create-only fields that the backend's `_reject_unknown_fields` validation will atomically 400 even if the user's actual edit is to a legitimate field like `columns`.
+3. **Resolve a portable temp path** for the patch JSON (same mechanics as save — `python -c "import tempfile, os; print(...)"`). Hard-coding `/tmp/` fails on Windows.
+4. **Write the patch and verify** — write the JSON to the resolved path, then `test -f <path>` before invoking the CLI.
+5. **Invoke the update** — `tl reports update <report_id> "$(cat <that-exact-path>)"`. The `update` command's second positional argument is a JSON object of fields to update (not a `--config-file` flag — that flag is only on `tl reports create`, not `update`). Passing inline as `'<json>'` breaks on apostrophes in brand names; the safe shape is `"$(cat <path>)"` against the verified temp file.
+6. **Reply** with the updated report's URL + a one-line summary of what changed (*"changed: columns added Y; description rewritten"*). Same wording rules as the save-success message — say "TL report" not "Campaign", say "report #N" not "Campaign #N".
+
+**Patch shape — what the JSON should and shouldn't contain:**
+
+```json
+// ✅ Correct: only editable fields the user changed
+{
+  "columns": { "channel_name": true, "subscribers": true, "last_published": true, "outreach_email": true },
+  "description": "Updated description text"
+}
+
+// ❌ Wrong: merged full config — `filterset` and `cross_references` will atomically 400 the request
+{
+  "title": "...", "description": "...", "filterset": {...}, "cross_references": [...], "columns": {...}
+}
+```
+
+**Anti-patterns to avoid** (real failure shape pinned here — agent has been observed producing four saves in eight minutes for what should have been one create + three updates; subsequent verification of the CLI edit endpoint surfaced additional constraints):
+
+- ❌ Running Phase 1–4 from scratch on a *non-filter* refinement (column/title/widget change). The phases trust working memory; rerunning them composes a parallel config rather than patching the existing one.
+- ❌ Calling `tl reports create` instead of `tl reports update` after a save when the new prompt is a column/widget/title refinement. Pick by intent shape, not by reflex.
+- ❌ Sending the full working-memory config as the `tl reports update` payload. The endpoint's `_reject_unknown_fields` validation is atomic — including `filterset`, `cross_references`, or `filters_json` in the payload 400s the WHOLE request, even if the user's actual edit was to a legitimate field like `columns`. Send ONLY editable fields.
+- ❌ Attempting to patch any FilterSet field (keywords, brands, channels, filters_json, msn_channels_only, demographics, date ranges, cross_references, etc.) via `tl reports update`. The backend explicitly rejects these — `CliReportEditView` docstring: *"Filterset edits are not supported here."* For FilterSet changes, route the user to "save as a new variant" (run Phase 1–4 with the prior config as starting point + the user's delta, save as a NEW report). Do NOT fabricate a working `tl reports update` call with a filterset payload.
+- ❌ Asserting that ALL editing is impossible (the opposite over-correction). Campaign-level fields — title, description, columns, widgets, histogram_bucket_size, emoji, display_mode, subscribers, webhook, notifications — ARE editable. Don't tell the user *"the CLI can't edit anything on a saved report"*; the truth is *"the CLI can edit these fields, not these others."*
+- ❌ Inventing a `tl reports show` command to refetch config. That command does not exist today; if config isn't in working memory, ask the user, don't fabricate a fetch step.
+- ❌ Passing the patch via a `--config-file` flag on `tl reports update`. That flag exists only on `tl reports create`. For `update`, the JSON goes as the second positional argument.
+
+When in doubt about whether a follow-up is an edit, a new variant, or a fresh save, ask. The clarifier is one ignorable line if the user wanted a new variant anyway; the cost of getting it wrong is a duplicate report or a 400 the user has to debug.
+
 What changes between save-mode and preview-mode:
 
 | | Save (explicit intent) | Preview (default) |
@@ -1641,6 +1730,7 @@ Every phase has explicit conditions where it must pause and ask the user, rather
 | **3** | No columns provided AND no clear intent | "I'll use [type]'s default set unless you want a different focus (outreach / discovery / sponsorship-pitch)" |
 | **4** | Aggregation/widget preferences need confirmation | "Default widgets for this report type are [list]; want to add/remove anything?" |
 | **4** | Final JSON-shape validation surfaced unresolved issues | "Can't ship config because [reason]. Fix [thing]?" |
+| **Post-save** | New prompt arrives after a successful save AND the topic overlaps with the prior save (same brand / niche / report type). Refinement signals strengthen the trigger but their absence does NOT bypass it when topic overlap is strong — refinement signals include vocabulary (*instead*, *change*, *swap*, *drop*, *add*, *tighter*, *broader*, *narrower*, *without*, *except*, *now with*, *but with*), filter/sort modifiers (*filter*, *limit*, *only*, *remove*, *replace*, *include*, *exclude*, *sort by …*), "make it X" framings, or partial-filter prompts that name a single filter axis without naming a new topic. | *"Looks like a refinement of the report you just created (#N — `<title>`). Update it in place, or save a separate variant?"* — default-highlight the update option; user can override. See "Editing a saved report" subsection above for the full mechanics. |
 
 Skills that follow up are skills users trust. Silent assumptions are silent regressions.
 

{thoughtleaders_cli-0.6.38 → thoughtleaders_cli-0.6.40}/src/tl_cli/__init__.py

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

thoughtleaders_cli-0.6.40/src/tl_cli/auth/commands.py

@@ -0,0 +1,130 @@
+"""Auth CLI commands: tl auth login/logout/status."""
+
+import time
+
+import typer
+from rich.console import Console
+from rich.prompt import Prompt
+
+from tl_cli.auth.finalize import finalize_signup
+from tl_cli.auth.login import login_browser, login_device_code
+from tl_cli.auth.token_store import KIND_API_KEY, StoredTokens, clear_tokens, load_tokens, save_tokens
+
+app = typer.Typer(help="Authentication commands")
+console = Console(stderr=True)
+
+
+@app.command("login", help="Log in to ThoughtLeaders.")
+def login_cmd() -> None:
+    """Log in to ThoughtLeaders.
+
+    The default flow opens a browser on this machine for OAuth2 (Auth0).
+    A device-code flow is available for headless environments, and a
+    pre-issued API key can be configured for CI/scripts.
+    """
+    console.print("[bold]How would you like to authenticate?[/bold]")
+    console.print(
+        "  [cyan]1[/cyan] — OAuth2 in a browser on this machine "
+        "[dim](default — opens a URL in the local browser)[/dim]"
+    )
+    console.print("  [cyan]2[/cyan] — Device code (use a browser on another device)")
+    console.print("  [cyan]3[/cyan] — API key (paste a pre-issued key; for CI / non-interactive use)")
+    console.print()
+    choice = Prompt.ask("Choose", choices=["1", "2", "3"], default="1", console=console)
+
+    if choice == "3":
+        _login_api_key()
+        return
+
+    if choice == "2":
+        login_device_code()
+    else:
+        login_browser()
+
+    finalize_signup()
+
+
+def _login_api_key() -> None:
+    """Store a user-supplied API key as the active credential.
+
+    No browser, no finalize call — the server has already issued this key
+    against an existing user/organization. The stored record is tagged
+    `kind=api_key` so the HTTP client sends `X-TL-Auth: API-KEY` on every
+    request. We immediately call /whoami to (a) verify the key is valid and
+    (b) capture the owning user's email for `tl auth status` output.
+    """
+    # Imported here to avoid pulling httpx/keyring into the module-level
+    # import graph when callers just want `tl auth logout` / `status`.
+    from tl_cli.client.errors import ApiError
+    from tl_cli.client.http import get_client
+
+    key = Prompt.ask("Paste your API key", console=console, password=True).strip()
+    if not key:
+        console.print("[red]No key provided.[/red]")
+        raise typer.Exit(1)
+
+    save_tokens(
+        StoredTokens(
+            access_token=key,
+            refresh_token=None,
+            expires_at=time.time() + 10 * 365 * 24 * 3600,
+            email=None,
+            kind=KIND_API_KEY,
+        )
+    )
+
+    client = get_client()
+    try:
+        data = client.get("/whoami")
+    except ApiError as e:
+        clear_tokens()
+        console.print(f"[red]API key rejected:[/red] {e.detail}")
+        raise typer.Exit(1)
+    finally:
+        client.close()
+
+    email = (data.get("user") or {}).get("email")
+    if not email:
+        clear_tokens()
+        console.print(
+            "[red]API key accepted but the server returned no email for the owning user.[/red] "
+            "This usually means the user record is incomplete — contact support."
+        )
+        raise typer.Exit(1)
+
+    save_tokens(
+        StoredTokens(
+            access_token=key,
+            refresh_token=None,
+            expires_at=time.time() + 10 * 365 * 24 * 3600,
+            email=email,
+            kind=KIND_API_KEY,
+        )
+    )
+    console.print(f"[green]API key stored.[/green] Authenticated as: {email}")
+
+
+@app.command("logout")
+def logout_cmd() -> None:
+    """Clear stored authentication tokens."""
+    clear_tokens()
+    console.print("[green]Logged out successfully.[/green]")
+
+
+@app.command("status")
+def status_cmd() -> None:
+    """Show current authentication status."""
+    tokens = load_tokens()
+    if not tokens:
+        console.print("[yellow]Not logged in.[/yellow] Run: tl auth login")
+        raise SystemExit(2)
+
+    if tokens.is_expired:
+        console.print(f"[yellow]Token expired.[/yellow] Logged in as: {tokens.email or 'unknown'}")
+        console.print("Run: tl auth login")
+        raise SystemExit(2)
+
+    if tokens.is_api_key:
+        console.print("[green]Authenticated[/green] via API key.")
+    else:
+        console.print(f"[green]Authenticated[/green] as: {tokens.email or 'unknown'}")

{thoughtleaders_cli-0.6.38 → thoughtleaders_cli-0.6.40}/src/tl_cli/auth/token_store.py

@@ -14,26 +14,44 @@ SERVICE_NAME = "tl-cli"
 FALLBACK_FILE = "credentials.json"
 
 
+KIND_BEARER = "bearer"
+KIND_API_KEY = "api_key"
+
+
 @dataclass
 class StoredTokens:
-    """Tokens stored in the keychain."""
+    """Auth credentials stored in the keychain.
+
+    `kind` distinguishes the OAuth2/Auth0 access-token flow ("bearer") from
+    a long-lived API key flow ("api_key"). API keys don't expire client-side
+    and have no refresh token — `refresh_token` and `expires_at` stay unset
+    in that case.
+    """
 
     access_token: str
     refresh_token: str | None
-    expires_at: float  # Unix timestamp
+    expires_at: float  # Unix timestamp; 0 for API keys
     email: str | None = None
+    kind: str = KIND_BEARER
 
     @property
     def is_expired(self) -> bool:
+        if self.kind == KIND_API_KEY:
+            return False
         # 5-minute buffer before actual expiry
         return time.time() > (self.expires_at - 300)
 
+    @property
+    def is_api_key(self) -> bool:
+        return self.kind == KIND_API_KEY
+
     def to_json(self) -> str:
         return json.dumps({
             "access_token": self.access_token,
             "refresh_token": self.refresh_token,
             "expires_at": self.expires_at,
             "email": self.email,
+            "kind": self.kind,
         })
 
     @classmethod
@@ -42,8 +60,9 @@ class StoredTokens:
         return cls(
             access_token=parsed["access_token"],
             refresh_token=parsed.get("refresh_token"),
-            expires_at=parsed["expires_at"],
+            expires_at=parsed.get("expires_at") or 0,
             email=parsed.get("email"),
+            kind=parsed.get("kind", KIND_BEARER),
         )
 
 

{thoughtleaders_cli-0.6.38 → thoughtleaders_cli-0.6.40}/src/tl_cli/client/http.py

@@ -67,15 +67,24 @@ class TLClient:
         return response.json()
 
     def _auth_headers(self) -> dict[str, str]:
-        """Get authorization headers from API key or stored tokens."""
-        # API key takes priority (for CI/scripts)
+        """Get authorization headers from API key env var or stored credentials."""
+        # API key env var takes priority (for CI/scripts)
         if self._config.api_key:
-            return {"Authorization": f"Bearer {self._config.api_key}"}
+            return {
+                "Authorization": f"Bearer {self._config.api_key}",
+                "X-TL-Auth": "API-KEY",
+            }
 
         tokens = load_tokens()
         if not tokens:
             raise ApiError(401, "Not authenticated. Run: tl auth login")
 
+        if tokens.is_api_key:
+            return {
+                "Authorization": f"Bearer {tokens.access_token}",
+                "X-TL-Auth": "API-KEY",
+            }
+
         if tokens.is_expired and tokens.refresh_token:
             tokens = refresh_access_token(tokens.refresh_token)
 

{thoughtleaders_cli-0.6.38 → thoughtleaders_cli-0.6.40}/src/tl_cli/commands/brands.py

@@ -1,5 +1,6 @@
 """tl brands — Brand detail and sponsorship history."""
 
+import json as _json
 import urllib.parse
 
 import typer
@@ -164,6 +165,39 @@ def history_stats_cmd(
         client.close()
 
 
+@app.command("find")
+def find_cmd(
+    query: str = typer.Argument(..., help="Brand name, slug, domain, or keyword"),
+) -> None:
+    """Resolve a string to a single brand and print {id, name} as JSON.
+
+    Searches across name, slug, website domain, and the brand's keyword
+    fields (kw + keywords). Ambiguous matches return an error with the
+    candidate IDs and names so the caller can pick a better query.
+
+    Examples:
+        tl brands find Nike
+        tl brands find nike.com
+        tl brands find https://www.nike.com/
+        tl brands find 21416
+    """
+    client = get_client()
+    try:
+        data = client.get("/brands/find", params={"q": query})
+        results = data.get("results", [])
+        record = results[0] if results else {}
+        print(_json.dumps({"id": record.get("id"), "name": record.get("name")}, ensure_ascii=False))
+    except ApiError as e:
+        if e.status_code == 400 and isinstance(e.raw, dict) and e.raw.get("candidates"):
+            err = Console(stderr=True)
+            err.print(f"[yellow]{e.detail}[/yellow]")
+            print(_json.dumps({"error": e.detail, "candidates": e.raw["candidates"]}, ensure_ascii=False))
+            raise typer.Exit(1)
+        handle_api_error(e)
+    finally:
+        client.close()
+
+
 SIMILAR_COLUMNS = ["score", "brand_id", "brand_name", "website", "mbn"]
 SIMILAR_COLUMN_CONFIG = {
     "score": {"justify": "right"},