thoughtleaders-cli 0.7.10__tar.gz → 0.7.12__tar.gz

{thoughtleaders_cli-0.7.10 → thoughtleaders_cli-0.7.12}/.claude-plugin/plugin.json

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

{thoughtleaders_cli-0.7.10 → thoughtleaders_cli-0.7.12}/PKG-INFO

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

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

{thoughtleaders_cli-0.7.10 → thoughtleaders_cli-0.7.12}/skills/tl/SKILL.md

@@ -9,7 +9,7 @@ description: |
 
 ## Core Principles
 
-Run the `tl` CLI to query ThoughtLeaders' sponsorship platform data. Use it to answer questions about deals, channels, brands, uploads, metrics, etc. Use raw database queries via `tl db pg|fb|es` for everything.
+Run the `tl` CLI to query ThoughtLeaders' sponsorship platform data. Use it to answer questions about deals, channels, brands, uploads, metrics, etc. Use raw database queries via `tl db pg|fb|es` for everything. One exception: resolving a named channel or brand (name, YouTube URL, @handle, video URL) to an ID is always `tl channels find` / `tl brands find` — never `ILIKE` on names.
 
 If doing a database query, follow this recipe:
 
@@ -25,13 +25,13 @@ If doing a database query, follow this recipe:
   ```bash
   tl db pg "SELECT id, weighted_price FROM thoughtleaders_adlink
             WHERE publish_status = 3 AND price > 5000
-            LIMIT 500 OFFSET 0" --json \
+            LIMIT 10000 OFFSET 0" --json \
     | jq '.results[] | {id, price: .weighted_price}'
   ```
 - **`yq`** — same idea for YAML/TOML, useful when reading config files or `--md` blocks.
 - **`rg`** — fast text search across CLI output, transcripts, and the codebase. Better than `grep` for searching large `--csv` exports or transcript dumps from ES.
   ```bash
-  tl db es '{"size":500,"query":{"term":{"channel.id":5607}},"_source":["id","transcript"]}' --json | rg -o "NordVPN[^.]*"
+  tl db es '{"size":10000,"query":{"term":{"channel.id":5607}},"_source":["id","transcript"]}' --json | rg -o "NordVPN[^.]*"
   ```
 - **`duckdb`** — embedded analytical SQL over CSV/JSON files. Use when you need joins, aggregations, or window functions across multiple `tl` exports without spinning up a database.
   ```bash
@@ -42,13 +42,13 @@ If doing a database query, follow this recipe:
             JOIN thoughtleaders_brand b ON b.id = pb.brand_id
             WHERE al.publish_status = 3
               AND al.purchase_date >= '2026-01-01'
-            LIMIT 500 OFFSET 0" --csv > deals.csv
+            LIMIT 10000 OFFSET 0" --csv > deals.csv
   duckdb -c "SELECT brand, SUM(price) AS revenue FROM 'deals.csv' GROUP BY brand ORDER BY revenue DESC LIMIT 10"
   ```
 
 The pattern is always: server-side narrowing first (usually by filters in the `tl db` query, but could be from similarity / recommender searches), then shell tool to shape the result, then read only the final summary into context. If `tl doctor` reports any of these as missing, ask the user to install them.
 
-Always assume there will be more than 1 page of results. You MUST always pass `LIMIT` and `OFFSET` to every `tl db pg|fb|es` query (and use the response envelope's `next_offset` / breadcrumbs to walk forward) so the entire data set is retrieved. The maximum number of rows per page is present in the output of `whoami`.
+Always assume there will be more than 1 page of results. You MUST always pass `LIMIT` and `OFFSET` to every `tl db pg|fb|es` query (and use the response envelope's `next_offset` / breadcrumbs to walk forward) so the entire data set is retrieved. Prefer large pages (up to the engine's cap) to minimize round-trips; the per-engine page-size caps are documented in each engine's schema reference under `references/`.
 
 **Counts, totals, and breakdowns: aggregate in the query engine — never page through records to count them.** A "how many / total / average / per-X" question is ONE aggregation query, not N pages of rows summed in your head:
 - `tl db pg` — `SELECT COUNT(*) …`, or `SELECT col, COUNT(*) AS n … GROUP BY col ORDER BY n DESC`. Also `SUM`/`AVG`/`MIN`/`MAX`/`date_trunc`. Returns one/few rows regardless of table size. (`LIMIT`/`OFFSET` still required — an aggregate is one row, so `LIMIT 1 OFFSET 0` is fine.)
@@ -95,7 +95,8 @@ Other key concepts:
 - **MBN** (Media Buying Network) — the brand-side counterpart to MSN: brand profiles that have opted in to receive proposed sponsorships. A profile is in the MBN group if the `profile.media_buying_network_join_date` field is not null.
 - **TPP** (ThoughtLeaders Partner Program, a.k.a. "TL channels") — the ~170 channels TL has the closest working relationship with. A channel is in the TPP group if `channel.is_tl_channel` is True. **Prefer TPP channels when booking**: they respond fastest, are the easiest to close, and don't need an outreach round-trip — treat them as immediately bookable. TPP is a strict subset of MSN, so the same booking rules (one active mention adspot, etc.) apply.
 - **`demographics_updated_at`** (on channels) — If non-null, the channel has demographics screenshots on file. If null, no demographics screenshots have been uploaded. Use this to check whether a channel has demographics data from screenshots.
-- **`impression`** (on channels) — projected views per video on that channel. Forward-looking estimate. May be null when not yet computed.
+- **`reach`** (on channels) — subscriber count. ⚠️ Despite the name, this is NOT ad-industry "reach" (unique audience exposed). There is no `subscribers` field — `reach` is it.
+- **`impression`** (on channels) — projected views per video on that channel. Forward-looking estimate. May be null when not yet computed. ⚠️ NOT actual views and NOT ad-industry "impressions" (ads served).
 - **`views`** (on sponsorships) — actual view count of the sold and published sponsored video, accessible when `article_id` is set.
 - **`impressions_guarantee`** (on sponsorships) — projected/guaranteed impressions for the sponsorship. Numeric.
 - **Sponsorship detail fields** (returned by `tl sponsorships show <id> --json`) — the detail payload includes `integration` (raw int), `publish_count`, `common_name`, `outreach_email`, nested `publisher` (`first_name`, `last_name`, `email`), nested `brand_contact` (`first_name`, `last_name`, `email`), and `brand.organization_name`. Use these when generating IOs, contracts, or outreach.
@@ -147,7 +148,7 @@ Unless the user specifically asks for running a specific report or showing the r
 
 1. **Discover first**: Use `tl schema pg`, `tl schema es`, and `tl schema fb` to find information about the main database (pg), the articles / uploads database (es), and the channel metrics database (fb).
 2. **Check credits**: Run `tl balance --json` before expensive queries. Warn the user if a query will cost many credits.
-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.
+3. **Decide the method of discovery**: If the user named a specific channel, brand, or creator (a name, YouTube URL, @handle, or video URL), resolve it to an ID with `tl channels find` / `tl brands find` before anything else. If the user wants 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.
@@ -445,7 +446,7 @@ If unsure about what information to find where, read the [references/postgresql-
 | 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). |
-| ES deep pagination beyond `from+size = 10,000` | **Unavailable** via raw — `scroll` and `pit` aren't allowlisted; `search_after` is allowed but `from` is still capped. | Use `search_after` with `sort` to walk past 10k. For huge sweeps, narrow with `publication_date` ranges. |
+| ES deep pagination beyond `from+size = 10,000` | **Available** via `search_after` (stateless cursor); `scroll` and `pit` remain unavailable. | Sort with a unique tiebreaker (e.g. `id`), then pass the response envelope's `next_search_after` back as `search_after` in the next call, keeping `query`/`sort` identical and `from` at 0. See the ES reference's *Deep pagination* section. |
 | ES index introspection (`_cat/indices`, mappings) | **Unavailable** — only `_search` is wired. | Read [references/elasticsearch-schema.md](references/elasticsearch-schema.md). It's manually maintained — update it when you discover new fields. |
 | Schema introspection on Postgres (`information_schema.columns`, `pg_class`, …) | **Partial** — catalog-resolving casts and many `pg_*` helpers are blocked. | Use `tl schema pg` for the live table/column listing, or read [references/postgres-schema.md](references/postgres-schema.md). |
 
@@ -485,7 +486,7 @@ tl channels find "MrBeast"
 tl brands find "NordVPN"
 ```
 
-If finding channels and brands fail, try variation on the name with or without whitespace.
+`tl channels find` resolves spacing/typo variants on its own ("Deco Destiny" → "DecoDestiny") via YouTube lookups and fuzzy similarity matching — no need to retry with hand-made name variations. A real channel that isn't in the index yet gets queued for analysis automatically (the response says to check back in ~24 hours). A plain "Not found" means even YouTube couldn't find it — treat that as the answer.
 
 **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."
 
@@ -559,7 +560,7 @@ For per-country share beyond the recommender's "USA share" tag, use the `demogra
 
 **MSN status (`media_selling_network_join_date`) is scrubbed from the advertiser sandbox view.** Raw SQL can't filter on it from an advertiser context. For MSN-only / non-MSN lookups, run the same raw SQL with `media_selling_network_join_date IS [NOT] NULL` from a context that has access to it (full-access role), or rely on the recommender's MSN-aware filters: `tl recommender top-channels "<tag>" msn:yes|no|all`.
 
-**Anti-pattern: defaulting to `ILIKE` on `channel_name` for off-tag topic queries.** If the question is "channels about X" where X is a topic / concept / niche (not a literal substring you expect in channel names), reach for path 3 (`tl-keyword-research`), not `WHERE channel_name ILIKE '%X%'`. Channel-name `ILIKE` misses channels whose name doesn't literally contain X but whose content does; the keyword-research skill catches them via `title` / `summary` / `transcript`. Use `channel_name ILIKE` only when you actually expect the channel's name to contain the term (e.g. `"Crypto"` in `"My Happy Crypto"`) as a supplementary signal alongside path 3, not as a replacement for it.
+**Anti-pattern: defaulting to `ILIKE` on `channel_name` for off-tag topic queries.** If the question is "channels about X" where X is a topic / concept / niche (not a literal substring you expect in channel names), reach for path 3 (`tl-keyword-research`), not `WHERE channel_name ILIKE '%X%'`. Channel-name `ILIKE` misses channels whose name doesn't literally contain X but whose content does; the keyword-research skill catches them via `title` / `summary` / `transcript`. Use `channel_name ILIKE` only when you actually expect the channel's name to contain the term (e.g. `"Crypto"` in `"My Happy Crypto"`) as a supplementary signal alongside path 3, not as a replacement for it. And for a *named entity* — a specific creator or channel — don't start with `ILIKE` at all: run `tl channels find "<name>"` first (path 1). Fall back to `ILIKE` name variations only if the resolver finds nothing, and treat a clean "Not found" from the resolver as the likely answer (the channel probably isn't in the index) rather than a cue for ever-broader scans.
 
 ### Output flags
 - `--json` — structured JSON output format (use this for parsing)
@@ -617,7 +618,7 @@ tl db pg "SELECT al.id, al.weighted_price, al.purchase_date, b.name AS brand
           WHERE al.publish_status = 3
             AND al.purchase_date >= '2026-01-01'
           ORDER BY al.purchase_date DESC
-          LIMIT 500 OFFSET 0" --json
+          LIMIT 10000 OFFSET 0" --json
 ```
 
 ### Brand sponsorship history — what channels does Nike sponsor?
@@ -769,7 +770,7 @@ tl db pg "SELECT al.id, c.channel_name, c.demographic_device_primary, c.demograp
           WHERE al.publish_status = 3
             AND c.demographic_device_primary = 'mobile'
             AND c.demographic_usa_share >= 60
-          LIMIT 500 OFFSET 0" --json
+          LIMIT 10000 OFFSET 0" --json
 ```
 
 ### "Find channels similar to one I know" (similarity recommender):

{thoughtleaders_cli-0.7.10 → thoughtleaders_cli-0.7.12}/skills/tl/references/elasticsearch-schema.md

@@ -21,19 +21,20 @@ Output flags: `--json`, `--csv`, `--md`, `--toon`. The CLI flattens hits into ro
 
 See the output of `tl db es`" for the object schema. Highlights:
 
-- **Top-level keys** accepted: `query`, `aggs`/`aggregations`, `sort`, `_source`, `size`, `from`, `track_total_hits`, `highlight`, `fields`, `min_score`, `search_after`, `timeout`, `collapse`, `post_filter`. Anything else (incl. `scroll`, `pit`, `runtime_mappings`, `knn`) is not accepted.
-- `size` ≤ 500. `from + size` ≤ 10,000. Use `search_after` to page deeper.
+- **Top-level keys** accepted: `query`, `aggs`/`aggregations`, `sort`, `_source`, `size`, `from`, `search_after`, `track_total_hits`, `highlight`, `fields`, `min_score`, `timeout`, `collapse`, `post_filter`. Anything else (incl. `scroll`, `pit`, `runtime_mappings`, `knn`) is not accepted.
+- `size` ≤ 10,000. `from + size` ≤ 10,000 — to page past 10,000 hits use `search_after` (see *Deep pagination* below), not `from`.
+- `search_after` must be a non-empty array of ≤ 10 scalar sort values, requires an explicit `sort`, and `from` must be 0 or omitted.
 - **Accepted query types** include `term`/`terms`/`match`/`bool`/`nested`/`range`/`exists`/`match_phrase`. `query_string`, `regexp`, `wildcard`, `fuzzy`, `more_like_this`, `has_child`, `has_parent`, `parent_id` are not accepted.
 - **No scripts** — any key whose name contains `script` is not accepted.
 - **At most one aggregation total** counted recursively (top-level + sub-agg = 2 = not accepted). Run multiple calls for multi-metric work.
 
 ### ElasticSearch document structure ("articles")
 
-The `doc_type.name` field in ES objects determins between records for video uploads and for channel data.
+The `doc_type` join field distinguishes video uploads ("articles") from channel data — channel docs are parents, article docs are their children. Filter with `{"term": {"doc_type": "article"}}` or `{"term": {"doc_type": "channel"}}`. ⚠️ Term-querying `doc_type.name` matches nothing — even though article docs' `_source` shows `doc_type` as an object with a `name` key, that's join-field syntax, not a queryable subfield.
 
 #### Upload/video Fields (selected — 73 total)
 
-Distinguished by `doc_type.name="article"`.
+Filter with `{"term": {"doc_type": "article"}}`.
 
 | Field | Type | Description |
 |-------|------|-------------|
@@ -80,7 +81,7 @@ Distinguished by `doc_type.name="article"`.
 
 #### Channel Fields
 
-Distinguished by `doc_type.name="channel"`.
+Filter with `{"term": {"doc_type": "channel"}}`.
 
 Contains a denormalized subset of the PostgreSQL channel data.
 
@@ -90,10 +91,10 @@ Contains a denormalized subset of the PostgreSQL channel data.
 |-------|------|-------------|
 | `name` | text | Channel name |
 | `channel` | object | Channel metadata (nested on article docs) |
-| `reach` | long | Subscriber count |
-| `impression` | long | View count |
-| `impression_live` | long | Live view count |
-| `impression_shorts` | long | Shorts view count |
+| `reach` | long | Subscriber count. ⚠️ NOT ad-industry "reach" (unique audience exposed) — this is the channel's subscriber count. |
+| `impression` | long | Projected views per longform video — forward-looking estimate. ⚠️ NOT actual views and NOT ad-industry "impressions"; for actual views see `total_views` / the video docs. |
+| `impression_live` | long | Projected views per live stream (forward-looking estimate) |
+| `impression_shorts` | long | Projected views per short (forward-looking estimate) |
 | `is_tl_channel` | boolean | TPP partner channel |
 | `is_active` | boolean | Channel is active |
 | `media_selling_network_join_date` | date | MSN join date |
@@ -215,25 +216,30 @@ tl db es '{
 
 For more dimensions, run multiple `tl db es` calls and join client-side.
 
-### Deep pagination via `search_after`
+### Deep pagination — `search_after`
+
+`from + size` is capped at 10,000, and the stateful cursors (`scroll`, `pit`) are not accepted. To page past 10,000 hits, use the stateless `search_after` cursor: sort deterministically with a unique tiebreaker (the `id` field — not `_id`), then pass each response's `next_search_after` envelope value back as `search_after` in the next request, keeping the same `query` and `sort`:
 
 ```bash
-# First page — sort must include a tiebreaker on _id for stability
+# First page
 tl db es '{
-  "size": 500,
+  "size": 10000,
   "query": {"term": {"channel.id": 12345}},
-  "sort": [{"publication_date": "desc"}, {"_id": "asc"}]
+  "sort": [{"publication_date": "asc"}, {"id": "asc"}]
 }'
+# → envelope includes "next_search_after": ["2025-09-14", "12345:abc123"]
 
-# Subsequent pages — pass the last hit's sort values as search_after
+# Next page — identical query & sort, plus the cursor
 tl db es '{
-  "size": 500,
+  "size": 10000,
   "query": {"term": {"channel.id": 12345}},
-  "sort": [{"publication_date": "desc"}, {"_id": "asc"}],
+  "sort": [{"publication_date": "asc"}, {"id": "asc"}],
   "search_after": ["2025-09-14", "12345:abc123"]
 }'
 ```
 
+Repeat until a page comes back short (`next_search_after` is absent on an empty page). Pages are not a consistent snapshot — concurrent indexing can occasionally duplicate or skip a boundary row, which is fine for analytics sweeps. Date-range windowing (filtering by `publication_date` ranges) remains a good alternative when you want resumable, idempotent slices.
+
 ## Text analyzer behavior
 
 `text` fields on article docs (`title`, `summary`, `transcript`) appear to use the `standard` analyzer (tokenize + lowercase, no stemmer, no English-possessive filter), so inflections, plurals, and possessives are each indexed as distinct terms. For example: `bitcoin` (4,466,300) vs `bitcoins` (489,262). For stemming-style recall, expand the query side with a `bool.should` over the variants.

{thoughtleaders_cli-0.7.10 → thoughtleaders_cli-0.7.12}/skills/tl/references/firebolt-schema.md

@@ -130,7 +130,7 @@ tl db pg "SELECT al.id, al.article_id, s.channel_id
           WHERE al.publish_status = 3
             AND b.name = 'Nike'
             AND al.article_id IS NOT NULL
-          LIMIT 500 OFFSET 0" --json \
+          LIMIT 10000 OFFSET 0" --json \
   | jq -r '.results[] | "\(.channel_id):\(.article_id)"'
 
 # Or videos via Elasticsearch content search

{thoughtleaders_cli-0.7.10 → thoughtleaders_cli-0.7.12}/skills/tl/references/postgres-schema.md

@@ -315,7 +315,7 @@ FROM thoughtleaders_adlink
 WHERE publish_status = 3
   AND purchase_date >= date_trunc('month', CURRENT_DATE)
 ORDER BY purchase_date DESC
-LIMIT 500 OFFSET 0
+LIMIT 10000 OFFSET 0
 ```
 
 **MSN channel joins this month:**
@@ -324,7 +324,7 @@ SELECT id, channel_name, media_selling_network_join_date
 FROM thoughtleaders_channel
 WHERE media_selling_network_join_date >= date_trunc('month', CURRENT_DATE)
 ORDER BY media_selling_network_join_date DESC
-LIMIT 500 OFFSET 0
+LIMIT 10000 OFFSET 0
 ```
 
 **A specific sponsorship info with brand and channel name:**

{thoughtleaders_cli-0.7.10 → thoughtleaders_cli-0.7.12}/src/tl_cli/__init__.py

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

{thoughtleaders_cli-0.7.10 → thoughtleaders_cli-0.7.12}/src/tl_cli/commands/channels.py

@@ -296,7 +296,9 @@ def find_cmd(
     """Resolve a string to a single channel.
 
     Accepts:
-      - A partial channel name or slug (ILIKE match)
+      - A partial channel name or slug (substring match, falling back to
+        fuzzy similarity — spacing/typo variants like "Deco Destiny" still
+        resolve a channel named "DecoDestiny")
       - A YouTube channel URL (https://youtube.com/channel/UC...,
         https://youtube.com/@handle, /c/<name>, /user/<name>)
       - A raw YouTube channel ID (UC...) or @handle
@@ -308,8 +310,9 @@ def find_cmd(
     `{"id": ..., "name": ...}`).
 
     Ambiguous matches return an error with candidate IDs and names.
-    If the input is a YouTube URL and no channel matches, the URL is
-    queued for scraping; retry the command later.
+    If the input is a YouTube URL — or a name that YouTube resolves to
+    a channel not yet in the index — it is queued for analysis; check
+    back in about 24 hours.
 
     Examples:
         tl channels find "MrBeast"

{thoughtleaders_cli-0.7.10 → thoughtleaders_cli-0.7.12}/src/tl_cli/commands/setup.py

@@ -7,9 +7,12 @@ whenever either `gemini` or `codex` is on PATH. Behaviour follows the
 OpenCode pattern (full per-skill tree copy, .tl-version stamp).
 """
 
+import filecmp
 import json
+import os
 import shutil
 import subprocess
+import sys
 from pathlib import Path
 
 import typer
@@ -41,6 +44,19 @@ OPENCODE_SKILLS_DIR = Path.home() / ".config" / "opencode" / "skills"
 AGENTS_SKILLS_DIR = Path.home() / ".agents" / "skills"
 AGENTS_SKILLS_BINARIES = ("gemini", "codex")
 
+# Personal-command shim that keeps the short `/tl` invocation working when the
+# skills are provided (namespaced) by the installed plugin. Plugin skills and
+# commands are always invoked as `/tl-cli:<name>`; this one-file pointer in
+# ~/.claude/commands/ restores plain `/tl` without duplicating any skill
+# content, so plugin updates flow through automatically.
+TL_COMMAND_SHIM = """\
+---
+description: ThoughtLeaders data analyst — shortcut for the tl-cli plugin's tl skill
+---
+
+Invoke the `tl-cli:tl` skill with this request: $ARGUMENTS
+"""
+
 
 def _find_plugin_root() -> Path | None:
     """Locate the plugin assets directory.
@@ -60,9 +76,68 @@ def _find_plugin_root() -> Path | None:
     return None
 
 
+def _newest_desktop_claude(base: Path, exe: str) -> Path | None:
+    """Pick the highest-version claude binary bundled by the Claude desktop app.
+
+    The desktop app keeps versioned copies under `<base>/<version>/<exe>`
+    (e.g. `%APPDATA%/Claude/claude-code/2.1.170/claude.exe`).
+    """
+    if not base.is_dir():
+        return None
+
+    def _version_key(d: Path) -> tuple[int, ...]:
+        try:
+            return tuple(int(part) for part in d.name.split("."))
+        except ValueError:
+            return (0,)
+
+    for version_dir in sorted(base.iterdir(), key=_version_key, reverse=True):
+        candidate = version_dir / exe
+        if candidate.is_file():
+            return candidate
+    return None
+
+
 def _find_claude_binary() -> str | None:
-    """Find the claude binary on PATH."""
-    return shutil.which("claude")
+    """Find the claude binary on PATH, falling back to known install locations.
+
+    On Windows the Claude Code installers often don't end up on the PATH of
+    the shell running `tl` (stale PATH, PowerShell-only profile changes), so
+    after `shutil.which` we probe the documented install targets directly:
+    the native installer (`~/.local/bin`), the npm global prefix, and the
+    binaries bundled with the Claude desktop app. When `tl` itself runs
+    inside a Claude Code session, `CLAUDE_CODE_EXECPATH` points straight at
+    the running binary and wins.
+    """
+    env_exec = os.environ.get("CLAUDE_CODE_EXECPATH")
+    if env_exec and Path(env_exec).is_file():
+        return env_exec
+    found = shutil.which("claude")
+    if found:
+        return found
+    home = Path.home()
+    if sys.platform == "win32":
+        appdata = Path(os.environ.get("APPDATA", str(home / "AppData" / "Roaming")))
+        candidates = [
+            home / ".local" / "bin" / "claude.exe",
+            appdata / "npm" / "claude.cmd",
+            _newest_desktop_claude(appdata / "Claude" / "claude-code", "claude.exe"),
+        ]
+    else:
+        desktop_base = (
+            home / "Library" / "Application Support" / "Claude" / "claude-code"
+            if sys.platform == "darwin"
+            else home / ".config" / "Claude" / "claude-code"
+        )
+        candidates = [
+            home / ".local" / "bin" / "claude",
+            home / ".claude" / "local" / "claude",
+            _newest_desktop_claude(desktop_base, "claude"),
+        ]
+    for candidate in candidates:
+        if candidate is not None and candidate.is_file():
+            return str(candidate)
+    return None
 
 
 def _run_claude(args: list[str], claude_bin: str) -> tuple[bool, str]:
@@ -156,6 +231,62 @@ def _install_standalone_skills(plugin_root: Path) -> int:
     return count
 
 
+def _install_command_shim() -> Path:
+    """Write the `/tl` shim command to ~/.claude/commands/tl.md."""
+    CLAUDE_COMMANDS_DIR.mkdir(parents=True, exist_ok=True)
+    dst = CLAUDE_COMMANDS_DIR / "tl.md"
+    dst.write_text(TL_COMMAND_SHIM, encoding="utf-8")
+    return dst
+
+
+def _trees_identical(a: Path, b: Path) -> bool:
+    """True if two directory trees contain the same files with the same contents.
+
+    Python runtime artifacts (`__pycache__/`, `*.pyc`) are ignored — skills
+    that ship scripts grow them when the scripts run, and they shouldn't make
+    an otherwise-pristine copy look user-modified.
+    """
+
+    def _files(root: Path) -> list[Path]:
+        return sorted(
+            p.relative_to(root)
+            for p in root.rglob("*")
+            if p.is_file() and p.suffix != ".pyc" and "__pycache__" not in p.parts
+        )
+
+    a_files = _files(a)
+    if a_files != _files(b):
+        return False
+    return all(filecmp.cmp(a / rel, b / rel, shallow=False) for rel in a_files)
+
+
+def _remove_matching_standalone_skills(plugin_root: Path) -> tuple[int, int]:
+    """Remove standalone copies in ~/.claude/skills/ that match the plugin's skills.
+
+    Earlier versions of `tl setup claude` copied every bundled skill into
+    ~/.claude/skills/. Now that the plugin provides them, those copies are
+    redundant — but a copy is only deleted when its tree is byte-identical
+    to the bundled skill, so user-modified copies are never touched.
+    Returns (removed, kept_modified).
+    """
+    removed = kept = 0
+    skills_src = plugin_root / "skills"
+    if not skills_src.is_dir():
+        return removed, kept
+    for skill_dir in skills_src.iterdir():
+        if not (skill_dir.is_dir() and (skill_dir / "SKILL.md").is_file()):
+            continue
+        standalone = CLAUDE_SKILLS_DIR / skill_dir.name
+        if not standalone.is_dir():
+            continue
+        if _trees_identical(skill_dir, standalone):
+            shutil.rmtree(standalone)
+            removed += 1
+        else:
+            kept += 1
+    return removed, kept
+
+
 def _bundled_skill_blurbs(plugin_root: Path) -> list[tuple[str, str]]:
     """Read (name, tl-blurb) for each bundled skill, for the setup summary.
 
@@ -192,18 +323,19 @@ def _bundled_skill_blurbs(plugin_root: Path) -> list[tuple[str, str]]:
 
 
 def _print_manual_instructions() -> None:
-    """Print manual install instructions when claude binary is not found."""
+    """Print manual install instructions when the plugin couldn't be installed."""
     console.print()
-    console.print("[yellow]Claude Code binary not found on PATH.[/yellow]")
+    console.print("[yellow]The Claude Code plugin could not be installed automatically.[/yellow]")
     console.print()
-    console.print("Install Claude Code first, then run these commands inside Claude Code:")
+    console.print(f"The skills were installed to {CLAUDE_SKILLS_DIR} instead — restart")
+    console.print("Claude Code and they will be available (e.g. [cyan]/tl[/cyan]).")
+    console.print()
+    console.print("To install the full plugin, run these commands inside Claude Code:")
     console.print()
     console.print(f"  [cyan]/plugin marketplace add {MARKETPLACE_SOURCE}[/cyan]")
     console.print(f"  [cyan]/plugin install {PLUGIN_KEY}[/cyan]")
     console.print()
-    console.print("Or start Claude Code with the plugin loaded directly:")
-    console.print()
-    console.print(f"  [cyan]claude --plugin-dir /path/to/tl-cli[/cyan]")
+    console.print("then re-run [cyan]tl setup claude[/cyan] to clean up the standalone copies.")
 
 
 @app.command("claude")
@@ -214,8 +346,10 @@ def setup_claude(
     """Install the TL CLI plugin for Claude Code.
 
     Registers the ThoughtLeaders marketplace, installs the tl-cli plugin,
-    and copies skills/commands to ~/.claude/ for short /tl invocation.
-    If the claude binary is not on PATH, prints manual instructions.
+    and adds a /tl shim command so the plugin's tl skill can be invoked
+    without the plugin namespace. Standalone skill copies in ~/.claude/skills
+    are only installed as a fallback when the plugin can't be installed;
+    unmodified copies left by earlier versions are removed.
 
     Examples:
         tl setup claude
@@ -249,10 +383,9 @@ def setup_claude(
     # Check claude binary
     claude_bin = _find_claude_binary()
     if not claude_bin:
-        # Still install standalone skills even without claude binary
-        console.print("  [yellow]![/yellow] claude binary not found on PATH")
+        # Fall back to standalone skill copies when the plugin can't be installed
+        console.print("  [yellow]![/yellow] claude binary not found")
         _install_standalone_skills_step(plugin_root)
-        console.print()
         _print_manual_instructions()
         raise SystemExit(1)
 
@@ -271,6 +404,7 @@ def setup_claude(
             _run_claude(["plugin", "marketplace", "update", MARKETPLACE_NAME], claude_bin)
         else:
             console.print(f"  [red]✗[/red] Marketplace registration failed: {output}")
+            _install_standalone_skills_step(plugin_root)
             _print_manual_instructions()
             raise SystemExit(1)
 
@@ -284,12 +418,20 @@ def setup_claude(
             console.print(f"  [green]✓[/green] Plugin already installed: {PLUGIN_KEY}")
         else:
             console.print(f"  [red]✗[/red] Plugin installation failed: {output}")
-            console.print("    Try running inside Claude Code:")
-            console.print(f"    [cyan]/plugin install {PLUGIN_KEY}[/cyan]")
+            _install_standalone_skills_step(plugin_root)
+            _print_manual_instructions()
             raise SystemExit(1)
 
-    # Step 3: Install standalone skills for short /tl invocation
-    _install_standalone_skills_step(plugin_root)
+    # Step 3: /tl shim command + cleanup of standalone copies from older versions
+    console.print("[bold]Installing /tl shortcut...[/bold]")
+    shim = _install_command_shim()
+    console.print(f"  [green]✓[/green] /tl command installed: {shim}")
+    removed, kept = _remove_matching_standalone_skills(plugin_root)
+    if removed:
+        console.print(f"  [green]✓[/green] Removed {removed} standalone skill(s) now provided by the plugin")
+    if kept:
+        console.print(f"  [yellow]![/yellow] Kept {kept} modified standalone skill(s) in {CLAUDE_SKILLS_DIR}")
+        console.print("    These differ from the plugin's versions and shadow nothing — remove manually if unwanted.")
 
     # Write version stamp
     version_dir = CLAUDE_PLUGINS_DIR / "tl-cli"
@@ -303,20 +445,20 @@ def setup_claude(
     blurbs = _bundled_skill_blurbs(plugin_root)
     width = max((len(name) for name, _ in blurbs), default=0)
     for name, blurb in blurbs:
-        console.print(f"  [cyan]/{name}[/cyan]{' ' * (width - len(name))}  — {blurb}")
+        console.print(f"  [cyan]/{PLUGIN_NAME}:{name}[/cyan]{' ' * (width - len(name))}  — {blurb}")
     console.print()
-    console.print("Try it:")
+    console.print("Try it (restart Claude Code first):")
     console.print("  [cyan]/tl Which channels did we sponsor in Q1?[/cyan]")
     console.print()
     console.print("[dim]To update, run: tl setup claude[/dim]")
 
 
 def _install_standalone_skills_step(plugin_root: Path) -> None:
-    """Install standalone skills and print status."""
-    console.print("[bold]Installing skills for /tl shortcut...[/bold]")
+    """Install standalone skills (plugin-less fallback) and print status."""
+    console.print("[bold]Installing standalone skills (plugin fallback)...[/bold]")
     count = _install_standalone_skills(plugin_root)
     if count > 0:
-        console.print(f"  [green]✓[/green] Installed {count} skills/commands to ~/.claude/")
+        console.print(f"  [green]✓[/green] Installed {count} skills/commands to {CLAUDE_HOME}")
     else:
         console.print("  [yellow]![/yellow] No skills found to install")
 
@@ -362,9 +504,19 @@ def _setup_noninteractive(fmt: str = "json") -> None:
         result["marketplace_registered"] = False
         result["plugin_installed"] = False
 
-    # Always install standalone skills
-    count = _install_standalone_skills(plugin_root)
-    result["standalone_skills_installed"] = count
+    if result["plugin_installed"]:
+        # Plugin provides the skills; install the /tl shim and clean up
+        # unmodified standalone copies left by earlier versions.
+        _install_command_shim()
+        removed, kept = _remove_matching_standalone_skills(plugin_root)
+        result["command_shim_installed"] = True
+        result["standalone_skills_installed"] = 0
+        result["standalone_skills_removed"] = removed
+        result["standalone_skills_kept_modified"] = kept
+    else:
+        # Fallback: standalone skill copies so Claude Code still gets /tl
+        result["command_shim_installed"] = False
+        result["standalone_skills_installed"] = _install_standalone_skills(plugin_root)
 
     # Write version stamp
     version_dir = CLAUDE_PLUGINS_DIR / "tl-cli"

{thoughtleaders_cli-0.7.10 → thoughtleaders_cli-0.7.12}/src/tl_cli/self_update.py

@@ -22,6 +22,7 @@ import urllib.request
 from pathlib import Path
 
 from tl_cli import __version__
+from tl_cli.commands.setup import _find_claude_binary
 
 CACHE_DIR = Path.home() / ".cache" / "tl-cli"
 CACHE_PATH = CACHE_DIR / "version-check.json"
@@ -210,8 +211,12 @@ def _spawn_detached_windows_upgrade(cmd: list[str], latest: str) -> bool:
         "set RC=%ERRORLEVEL%\r\n"
         f'echo [tl-cli upgrader] exit code %RC% >> "{log_path}"\r\n'
         "if not %RC%==0 goto end\r\n"
+        "set CLAUDE_FOUND=0\r\n"
         "where claude >NUL 2>&1\r\n"
-        "if not errorlevel 1 (\r\n"
+        "if not errorlevel 1 set CLAUDE_FOUND=1\r\n"
+        'if exist "%USERPROFILE%\\.local\\bin\\claude.exe" set CLAUDE_FOUND=1\r\n'
+        'if exist "%APPDATA%\\npm\\claude.cmd" set CLAUDE_FOUND=1\r\n'
+        "if %CLAUDE_FOUND%==1 (\r\n"
         f'    echo [tl-cli upgrader] re-syncing claude skills >> "{log_path}"\r\n'
         f'    tl setup claude --json >> "{log_path}" 2>&1\r\n'
         ")\r\n"
@@ -411,7 +416,10 @@ def _resync_integrations() -> None:
         ("gemini", "gemini"),
         ("codex", "codex"),
     ):
-        if not shutil.which(binary):
+        # claude is often installed off-PATH (native installer, npm prefix);
+        # use the same probing the setup command uses.
+        found = _find_claude_binary() if binary == "claude" else shutil.which(binary)
+        if not found:
             continue
         print(f"[tl-cli] re-syncing {tool} skills…", file=sys.stderr)
         try: