thoughtleaders-cli 0.9.2__tar.gz → 0.9.3__tar.gz

{thoughtleaders_cli-0.9.2 → thoughtleaders_cli-0.9.3}/PKG-INFO

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

{thoughtleaders_cli-0.9.2 → thoughtleaders_cli-0.9.3}/pyproject.toml

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

{thoughtleaders_cli-0.9.2 → thoughtleaders_cli-0.9.3}/skills/tl/SKILL.md

@@ -242,7 +242,6 @@ tl channels update 12345 '{"demographic_male_share": 62}'
 tl channels update 12345 '{"demographic_geo": {"US": 60, "UK": 12, "CA": 8}}'
 tl channels update 12345 '{"demographic_male_share": 55, "demographic_usa_share": 70}'
 tl channels update 12345 '{"outreach_email": "press@creator.com"}'
-tl channels update 12345 '{"media_selling_network_join_date": "2026-01-15"}'
 ```
 
 **Channel contact emails.** Besides demographics, `tl channels update` accepts one
@@ -256,11 +255,6 @@ sending it returns a 400. It is append-only: new addresses are added with the
 internal CLI's `tl-internal channels add-email` command (superuser-only), which never
 modifies or removes existing entries.
 
-**MSN membership.** `tl channels update` also accepts **`media_selling_network_join_date`** —
-the date the channel joined the Media Selling Network, as a `YYYY-MM-DD` string. This date is
-itself the membership flag: set it to add the channel to MSN (it then reads as `is_msn` and
-appears in MSN-filtered queries), or send `null` to remove the channel from the network.
-
 **Profile notes.** `tl profiles update` (superuser only) edits a brand/publisher profile's
 **`superuser_notes`** — the internal free-text notes field on the customer record
 (`thoughtleaders_profile.superuser_notes`, max 2500 chars). Send a string to set, `null` to

thoughtleaders_cli-0.9.3/skills/tl-create-workflow/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: tl-create-workflow
+tl-blurb: design & stand up a sponsorship pipeline (workflow) from a goal
+description: >
+  Turn a sponsorship / sourcing goal into a structured, data-populated
+  **Workflow** — an ordered funnel of report-stages that channels (or brands)
+  move through, e.g. Sourced → Qualified → Get face on screen → Reach out →
+  Contacted → Sold. Invoke when the user wants to build or set up a workflow or
+  pipeline, design an outreach / acquisition funnel for a brand or campaign,
+  turn an existing report into a workflow, or organise channel sourcing into
+  stages. Triggers: "create a workflow", "build a pipeline / funnel", "set up
+  outreach for <brand>", "turn this report into a workflow", "organise my
+  sourcing into stages", "workflow for finding channels to sponsor <brand>",
+  "build an acquisition funnel". It designs the funnel from the goal + the TL
+  methodology, sources the entry stage with real data (delegating to
+  tl-keyword-research / tl channels / tl recommender / guide-brand research),
+  defines each stage as a query-or-list report, and creates it with
+  "tl workflow create" (or, until the backend endpoint is deployed, hands back the
+  create-ready blueprint + in-app assembly steps). Also answers
+  HELP asks about how workflows work ("how do workflows work", "what's a
+  query vs a list stage", "explain workflow stages") for free.
+---
+
+# tl-create-workflow — a sponsorship goal → a populated pipeline
+
+Turn a fuzzy goal ("I need channels to sponsor **Magic Spoon**", "set up our
+outreach funnel", "organise my sourcing") into a **Workflow**: an ordered chain
+of report-**stages** that entities move through, with the **entry stage already
+populated with the right channels** and every stage typed correctly. The value
+is not drawing boxes — it's (a) designing the funnel from the **ThoughtLeaders
+methodology** rather than a generic CRM template, (b) **sourcing the entry
+stage with real data** so the pipeline starts full, not empty, and (c) getting
+the **query-vs-list mechanics right** so the workflow doesn't break the way
+hand-built ones do.
+
+A workflow is **not a new kind of object** — every stage IS a saved Report
+(campaign), chained in order. Understanding that is the whole game; read
+`references/workflow-model.md` before you design anything.
+
+> `<SKILL_DIR>` below is this skill's directory (the one holding `SKILL.md`).
+
+## Hard rules
+
+- **A stage is a Report.** A workflow = ordered Reports linked by
+  `workflow_step_number`. There is no separate "stage" object. Design in terms
+  of reports.
+- **The entry stage is a QUERY; every later stage is a LIST.** This is the
+  single most important rule and the #1 cause of broken hand-built workflows —
+  see `references/workflow-model.md` (query vs list) and
+  `references/pitfalls.md`. Never make stage 2+ a query.
+- **Creating the workflow.** `tl workflow create --file <blueprint.json>` builds
+  it in one call — it POSTs `{name, report_type, steps}` to the Bearer endpoint
+  `/api/cli/v1/workflows/build` (the twin of the web builder). The command ships
+  in this repo; the endpoint ships with backend **PR #4192** — **until that is
+  deployed the command errors**, and the user stands the workflow up in the web
+  app from the blueprint (Convert → Add stage). Both paths are in
+  `references/creating-in-app.md`. **Never claim a workflow was created unless a
+  `tl workflow create` call actually returned one** — otherwise you prepared a
+  blueprint.
+- **Source with real data, never placeholder channels.** The entry stage must
+  be filled from the index (delegate to `tl-keyword-research` /
+  `tl channels find` / `tl recommender` / guide-brand research), never a made-up
+  list. An empty pipeline is a failed deliverable.
+- Do all data processing with the `utf-8` encoding explicitly in any script you
+  write.
+
+## Setup check
+
+```bash
+tl whoami        # confirms the CLI is authed and shows plan/limits
+```
+If this errors, tell the user to run `tl auth login` (or set `TL_API_KEY`).
+Sourcing stages needs intelligence access on the org's plan; if `tl whoami`
+shows no intelligence flag, say so — you can still design the funnel, but you
+can't populate it from the index.
+
+## When to invoke / skip
+
+**Invoke** when the user wants to **stand up a pipeline**: build/set up a
+workflow, design an outreach or acquisition funnel for a brand/campaign, turn a
+report into a workflow, or organise sourcing into stages.
+
+**Skip when:**
+- They just want to *find* channels/brands/videos → `tl channels find`,
+  `tl-keyword-research`, `tl recommender`. (You'll *use* these, but a lookup
+  alone isn't a workflow.)
+- They want to persist one flat list/report they already have →
+  `tl-save-report`.
+- They're asking about an **existing** workflow's data (counts, who's in which
+  stage) → query it with `tl` directly.
+
+## Help mode — explain workflows on request, for free
+
+When the user asks what a workflow is, how stages work, query vs list, or "how
+do I build one" as a *question* (not a request to build): **run nothing**. Read
+`references/workflow-model.md` (+ `references/pitfalls.md` for the gotchas) and
+explain, sized to the ask. Close by offering to design one. Mid-run questions
+get the same treatment — answer, then resume.
+
+## The build (you orchestrate; the tl CLI + sibling skills do the data work)
+
+| Stage | What happens | Tooling |
+|---|---|---|
+| 0 Frame | goal, entity type, funnel shape, stage list — interview, don't assume | you + `references/methodology.md` |
+| 1 Source the entry stage | fill stage 1 with the right channels/brands (a QUERY) | `tl-keyword-research` · `tl channels find` · `tl recommender` · guide-brand research |
+| 2 Define the stages | each stage as a report config (query for stage 1, lists after) | you + `references/workflow-model.md` |
+| 3 Blueprint | emit the create-ready plan: stage names, types, the entry filter, links | you |
+| 4 Assemble | the exact in-app steps to build it (Convert → Add stage → link) | `references/creating-in-app.md` |
+| 5 Deliver | blueprint + entry-stage report link + how to work the funnel | `tl-save-report` (for the entry report) |
+
+**Narrate the run** — one line per stage transition, and surface every
+assumption so the user can correct it. Sourcing spends credits (it's real ES
+work); say roughly how much as you go, exactly like `tl-keyword-research`.
+
+### Stage 0 — Frame the funnel (interview; never assume)
+
+Two things decide everything, and both are the user's:
+
+1. **The goal & entity.** What is this pipeline *for*, and does it move
+   **channels** (usual), **brands**, or **sponsorships**? "Find channels to
+   sponsor Magic Spoon" → a channel-acquisition funnel. "Work our brand
+   prospects" → a brand funnel. The entity type fixes the workflow's
+   `report_type` and can't be mixed later.
+2. **The funnel shape.** How many stages and what they mean. Don't invent a
+   generic "Lead → MQL → SQL" — derive it from the **ThoughtLeaders
+   methodology** (`references/methodology.md`): the real sourcing funnel is
+   *find the pool → qualify on value-vs-price → enrich (face-on-screen,
+   contacts) → outreach → pipeline (proposed/pending/sold)*. Offer the canonical
+   funnel below and let them cut/rename stages — the huddle's real stages are
+   good defaults:
+
+   > **Sourced** (query) → **Qualify** (list) → **Get face on screen** (list) →
+   > **Reach out** (list) → **Contacted** (list) → **Proposed** (list)
+
+   Stage names are just report titles — pick names the team will recognise
+   (they persist on the campaign). Fewer, meaningful stages beat many empty
+   ones.
+
+State the goal, entity, and stage list back to the user before sourcing
+anything.
+
+### Stage 1 — Source the entry stage (the QUERY)
+
+Stage 1 is the **pool**: the channels the funnel starts from, selected by a
+*filter* (a query), not an explicit list. Pick the sourcing path from the goal —
+this is where the methodology becomes data:
+
+- **Sponsor a specific brand / product** → find the brand's category and its
+  **guide brands** (proven sponsors / competitors), then their **winner
+  channels** (TRUE renewals — the real signal), then **look-alikes**. Use
+  `tl brands` research + `tl channels similar` / `tl recommender`.
+- **A topic / niche** ("cooking channels for a kitchenware brand") →
+  **`tl-keyword-research`** to turn the topic into a validated content filter +
+  the channels it selects. Take its `report_link` / filter set as stage 1.
+- **A known shortlist** → then stage 1 is really a *list*, and a workflow may be
+  overkill — say so; `tl-save-report` might be all they need.
+
+Deliver stage 1 as a **query report** (a filter set), and — because it's the
+entry — it's fine and correct for it to be a query. Populate it, eyeball the
+count and a sample, and confirm the breadth with the user (too broad → narrow
+the filter; too thin → widen), exactly like keyword-research's breadth check.
+
+### Stage 2 — Define the stages (query first, lists after)
+
+For each downstream stage, the report is a **list**: it starts empty and fills
+as the user bulk-selects entities in the previous stage and **Moves** them
+forward. You don't pre-populate lists — you just create the (empty) list
+reports with the right names and types.
+
+- **Types must alternate correctly:** stage 1 = query; stages 2..N = lists.
+  Re-check `references/workflow-model.md` if unsure how the platform infers
+  query-vs-list from the FilterSet.
+- **Columns per stage:** if a stage needs a specific column the team acts on
+  (e.g. *Face On Screen* on the "Get face on screen" stage, *Outreach email* on
+  "Reach out"), note it — columns are set per report.
+- **Linked reports (include/exclude), sparingly:** a stage can pull in another
+  report's entities (e.g. exclude "no email / captcha"). Keep this to **≤1–2
+  layers of nesting** — deep chains are the documented performance + confusion
+  trap (`references/pitfalls.md`). Prefer a flat stage over a clever nest.
+
+### Stage 3 — Emit the blueprint
+
+Hand the user a compact, create-ready plan:
+
+```
+Workflow: "Magic Spoon — channel sourcing"   (report_type: channels)
+  1. Sourced            [QUERY]  ← <entry filter summary> · ~<N> channels · <report_link>
+  2. Qualify            [list]   empty; move channels that pass value-vs-price
+  3. Get face on screen [list]   empty; column: Face On Screen
+  4. Reach out          [list]   empty; column: Outreach email; exclude → "No email / captcha"
+  5. Contacted          [list]   empty
+```
+
+Include the **entry report link** (from keyword-research / `tl reports create`)
+so stage 1 exists as a real, openable report before assembly.
+
+### Stage 4 — Assemble in the web app
+
+Workflows are built in-app (no CLI endpoint). Walk the user through
+`references/creating-in-app.md`:
+
+1. Open the **entry (Sourced) report** → **Convert to workflow** → name it. That
+   report becomes **stage 1**.
+2. **Add stage** for each downstream stage, in order, with the names from the
+   blueprint (they save on the campaign — renames persist).
+3. For any stage with a **linked report** (e.g. exclude "no email"), add it on
+   that stage — keep nesting shallow.
+4. Set per-stage **columns** where noted.
+5. Work the funnel: on a stage, **filter** (e.g. by *Face On Screen*),
+   **bulk-select**, **Move** to the next stage. Moving is non-destructive.
+
+### Stage 5 — Deliver
+
+Show: the funnel (stages, types, per-stage columns/links), the **entry-stage
+report link** (populated), and the one-paragraph "how to work this funnel"
+(filter → select → move). Offer to **save the entry report** via
+`tl-save-report` if it isn't already saved. Never save or create anything the
+user didn't ask for.
+
+## Cost
+
+Framing and blueprinting are free (no queries). **Sourcing stage 1 spends
+credits** — that's real ES work delegated to `tl-keyword-research` /
+`tl channels` / `tl recommender`; their own costs apply (keyword-research: ~10–20
+credits quick, ~60–120 deep). Run `tl describe show db` for live rates. The
+in-app assembly costs nothing (it's the user clicking in the platform).
+
+## Self-check before you finish
+
+1. You established the **goal**, the **entity type** (channels / brands /
+   sponsorships → the workflow's `report_type`), and the **stage list** with the
+   user — derived from the methodology, not a generic CRM funnel — and stated
+   them back before sourcing.
+2. **Stage 1 is a QUERY and it's populated** from real index data (not a
+   placeholder list), with its breadth confirmed against the goal (narrowed /
+   widened as needed). **Every stage after 1 is a LIST.** No stage 2+ is a query.
+3. Any **linked reports** are ≤1–2 nesting layers; you preferred a flat stage
+   over a deep nest, and flagged per-stage **columns** the team acts on.
+4. The blueprint is **create-ready**: named stages, correct types, the entry
+   filter summary + a working **report link**, and the in-app assembly steps.
+5. You were explicit that the **Workflow is assembled in the web app** (the CLI
+   can't create it) — you prepared it, you didn't claim to have created it.
+6. You narrated the run and its credit spend, and saved / created **nothing**
+   without the user's say-so.
+7. If the user requests a diagram of the funnel, create it as an SVG graphic.

thoughtleaders_cli-0.9.3/skills/tl-create-workflow/references/creating-in-app.md

@@ -0,0 +1,95 @@
+# Creating the workflow
+
+**`tl workflow create` builds the workflow from a blueprint in one call** — it
+POSTs `{name, report_type, steps}` to the Bearer endpoint
+`/api/cli/v1/workflows/build` (the twin of the web "New Workflow" builder). The
+result is the same `Workflow` / stage-`Campaign` / `FilterSet` objects the rest of
+the platform uses, so it shows up in the web app's workflow list/detail
+immediately, where the team moves / edits / duplicates it.
+
+> **Availability.** The `tl workflow` command ships in this repo; the endpoint it
+> calls ships with backend **thoughtleaders PR #4192** (`create_full_workflow`).
+> Until that backend change is deployed, `tl workflow create` returns an error —
+> use the **manual in-app assembly** at the bottom of this file. The blueprint is
+> the exact same input either way, so nothing is wasted.
+
+## Create it directly (preferred)
+
+1. **Build + save the entry (Sourced) report first**, so it exists with an **id**.
+   It's a *query* report populated by this skill (`tl-keyword-research`,
+   `tl channels`, `tl recommender`, or `tl reports create`) and saved
+   (`tl-save-report` / `tl reports create`). This is the only stage that starts
+   with data, and it must be a saved **query** so the stage stays live.
+2. **Write the blueprint to a file** and run `tl workflow create`:
+
+   ```bash
+   tl workflow create --file blueprint.json        # add --yes to skip the confirm
+   ```
+
+   `blueprint.json`:
+
+   ```json
+   {
+     "name": "Q3 Creator Outreach",
+     "report_type": 3,
+     "steps": [
+       { "title": "Sourced",            "include_report_ids": [<entryReportId>], "exclude_report_ids": [] },
+       { "title": "Qualify",            "include_report_ids": [], "exclude_report_ids": [] },
+       { "title": "Get face on screen", "include_report_ids": [], "exclude_report_ids": [] },
+       { "title": "Reach out",          "include_report_ids": [], "exclude_report_ids": [] }
+     ]
+   }
+   ```
+
+   - `report_type`: **1** content · **2** brands · **3** channels · **8** sponsorships.
+   - Stages are created **in order**; the first is the entry stage (link the saved
+     query report via `include_report_ids`), the rest are empty **lists** channels
+     move into. Keep any linked-report nesting shallow (≤1–2).
+   - Only reports you may edit are linked (others are dropped); the workflow is
+     owned by you. One atomic call creates the workflow + stage campaigns +
+     include/exclude report links + the exclude-earlier-stages chaining.
+   - Use `--config '<json>'` for inline JSON, or `--name` / `--report-type` to
+     supply/override those fields. `--json` / `--toon` for machine output.
+3. The command prints the new workflow **id** and an **"Open in app"** link
+   (`/#/workflows/<report_type>/<id>`). Hand that to the user to work the funnel:
+   on a stage, filter → bulk-select → **Move** to the next stage (Move / Remove
+   are non-destructive; moved channels leave the source stage).
+
+## The endpoints (reference)
+
+| Action | Request | Auth |
+|--------|---------|------|
+| **Build a full workflow** (`tl workflow create`) | `POST /api/cli/v1/workflows/build` · `{ name, report_type, steps[] }` | **Bearer (CLI)** |
+| Convert one report → 1-stage workflow | `POST /api/workflows` · `{ campaignId, workflowName }` | session |
+| Add a stage | `POST /api/workflows/add-step` · `{ campaignTitle, workflowId }` | session |
+| Delete a stage (any same-org collaborator) | `DELETE /api/workflows/delete-step?stepId=` | session |
+| Rename / delete the workflow (delete is owner-only) | `PATCH` / `DELETE /api/workflows/:id` | session |
+| Fetch a workflow + stages | `GET /api/workflows/:id` | session |
+| Link a report / move entities on a stage | `PATCH` the stage filterset's `add_relation` action | session |
+
+Only the **build** endpoint is on the CLI's Bearer surface; the rest are the web
+app's session-authenticated management routes (used from the web UI).
+
+## Assemble it in the web app (fallback until the endpoint is live)
+
+If the build endpoint isn't deployed yet, the user stands the workflow up from
+the blueprint by hand — same design, more clicks:
+
+1. Open the saved entry report → **Convert to workflow** → name it. It becomes
+   **stage 1**.
+2. **Add stage** for each downstream stage, in blueprint order (each is an empty
+   **list**; names persist across reloads).
+3. **Link** supporting include/exclude reports where the blueprint calls for it
+   (nesting ≤1–2 layers).
+4. Set per-stage **columns** the team acts on (Face On Screen, Outreach email).
+5. **Work the funnel:** on a stage, filter → select → **Move** to the next stage.
+
+## What to hand the user
+
+- The **entry report link** (populated, openable).
+- Either the **"Open in app" workflow link** (from `tl workflow create`) or the
+  **blueprint + in-app assembly steps** (fallback).
+- The one-line "how to work the funnel": *filter a stage → select → Move to next.*
+
+Never claim a workflow was created unless a `tl workflow create` call actually
+returned one — otherwise you prepared a blueprint.

thoughtleaders_cli-0.9.3/skills/tl-create-workflow/references/methodology.md

@@ -0,0 +1,70 @@
+# Funnel design — the ThoughtLeaders methodology, not a generic CRM
+
+Don't design a workflow like a generic sales CRM ("Lead → MQL → SQL → Won").
+Design it from how ThoughtLeaders actually sources and closes sponsorships. The
+funnel stages fall out of the methodology.
+
+## The sourcing methodology (how the pool is found)
+
+The core play for finding the right channels for a brand:
+
+1. **Identify the brands** — through competitor research and **Guide Brands**
+   (brands that are *proven* sponsors in the category). A guide brand is a
+   working example of "who already pays to sponsor this kind of content".
+2. **Find the winner channels** — the channels those guide brands *renewed*
+   with. A **TRUE renewal** (the brand came back and paid again) is the real
+   signal that the channel converts, not a vanity metric.
+3. **Find look-alike channels** — channels similar to the winners (same
+   audience/niche/shape) that haven't been booked yet. This is the addressable
+   pool.
+4. **Analyse value vs price** — for each candidate, is the projected value
+   (views, audience fit) worth the price? This is the qualification gate.
+
+The entry stage of a workflow is the output of steps 1–3 (the look-alike pool),
+expressed as a **query**. Qualification (step 4) is the first downstream list
+stage.
+
+## Terminology to keep straight (TL uses its own words)
+
+- **Brands** = the sponsors (usually companies, sometimes a single product).
+- **Channels** = the creators being sponsored (YouTube channels, sometimes
+  podcasts).
+- **Sponsorship** is the umbrella; it narrows through a funnel of its own:
+  *Sponsorships ⊃ Matches ⊃ Proposals ⊃ Deals (sold)*.
+- Pricing words: **PV** = Projected Views (a pricing estimate); **VG** = View
+  Guarantee (the contractual floor). Don't invent CPM/"margin" language — TL
+  says **Net revenue** / **TL profit**, and avoid "flight" / "hero channel".
+- **Send date** = the expected publication date of a sponsored video.
+- Two channel networks exist: **MSN** (the large ~11K opted-in Media Selling
+  Network) and **TPP** (the small ~169 directly-managed VIP channels). Sourcing
+  usually works over MSN; enrichment tasks ("get face on screen") are often
+  assigned to MSN managers.
+
+## The canonical acquisition funnel
+
+A good default channel-acquisition workflow, with each stage's type and the
+column the team acts on. Offer this, then let the user cut / rename / reorder.
+
+| # | Stage | Type | What it means | Acted-on column |
+|---|-------|------|---------------|-----------------|
+| 1 | **Sourced** | query | The pool: look-alike channels for the brand's guide-brand winners (or a topic filter). | — |
+| 2 | **Qualify** | list | Passed value-vs-price (and, if relevant, an authenticity check). | Projected views / price |
+| 3 | **Get face on screen** | list | Assigned to MSN managers to fill in face-on-screen + enrich. | Face On Screen |
+| 4 | **Reach out** | list | Has an outreach email; ready to contact. | Outreach email |
+| 5 | **Contacted** | list | Outreach sent. | — |
+| 6 | **Proposed** | list | A proposal is out. | — |
+
+Notes:
+- Stages 5–6 mirror the sponsorship sub-funnel (Match → Proposal → Deal); stop
+  wherever the team's process stops. Don't add stages the team won't work.
+- For a **brand-prospecting** workflow (report_type = brands) the shape rebases:
+  *Prospects (query: brands in a category / competitors of a guide brand) →
+  Qualified → Pitching → Won*.
+
+## Sizing the pool (breadth)
+
+There is no universal right number. A niche brand with a few dozen good
+look-alikes is a complete answer; a broad consumer brand returning a few dozen
+is probably too narrow. State your breadth judgement and offer to narrow/widen —
+exactly the calibration `tl-keyword-research` does. The pool is the query stage;
+everything downstream is a subset of it.

thoughtleaders_cli-0.9.3/skills/tl-create-workflow/references/pitfalls.md

@@ -0,0 +1,68 @@
+# Pitfalls — the failure modes hand-built workflows hit
+
+These come from real workflows the team built (and abandoned). Design around
+them from the start; most of a good workflow is just not stepping on these.
+
+## 1. A query where a list belongs (the big one)
+
+Making stage 2+ a **query** instead of a **list** is the #1 breakage. A query
+recomputes its members from the index every time — it has nothing to *hold* the
+entities you move into it, so "moved" channels vanish on the next load. **Only
+the entry stage is a query; everything after it is a list.** If the user wants
+to "filter" a mid-funnel stage, that's a transient **view filter** on the
+list's rows (narrow what's shown so you can bulk-select), not a query stage.
+
+## 2. Empty pipeline
+
+Delivering a funnel whose entry stage is empty (or filled with placeholder
+channels) is a non-deliverable. The entry stage must be **sourced from real
+index data** — `tl-keyword-research`, `tl channels`, `tl recommender`,
+guide-brand look-alikes — with its breadth sense-checked against the goal.
+
+## 3. Over-nesting linked reports
+
+A stage can include/exclude other reports, which can themselves include others.
+There's **no depth limit in the platform**, and deep/wide nests resolve
+exponentially (slow) and become impossible to reason about ("this report
+excludes that one, which includes this other one…"). **Cap it at 1–2 layers.**
+Prefer a flat stage with its own filters over a clever nest. Historically people
+added manual exclude-hacks to make a nested workflow usable — that's a smell,
+not a pattern to copy.
+
+## 4. Meaningless / churning stage names
+
+Stages are reports; their names are the report titles and they **persist** on
+the campaign (a real historical bug reverted them, now fixed). Pick names the
+team already uses for its process ("Get face on screen", "Reach out",
+"Contacted") — not generic CRM labels. Fewer meaningful stages beat many empty
+ones nobody works.
+
+## 5. Designing for one person on a shared object
+
+A workflow is **shared** across the team by default. Don't design it around one
+AM's private view; design the stages so several people can work them. (The
+platform's own per-user view feature is what lets each person hide the reports
+that aren't theirs — not something you configure here, but keep the shared
+reality in mind when naming/structuring stages.)
+
+## 6. Claiming you created it
+
+The CLI can't create the Workflow object — you **design, source, and
+blueprint**, and the user assembles it in the app (Convert → Add stage → …).
+Never say "I created your workflow." Say "here's your populated blueprint and
+the steps to stand it up."
+
+## 7. Too many stages
+
+A funnel with eight stages the team won't actually move channels through is
+worse than four they will. Map stages to the team's *real* process steps and
+stop where the process stops. Every stage is a report someone has to maintain.
+
+## Quick checklist
+
+- [ ] Entry stage is a **query**, populated from real data, breadth confirmed.
+- [ ] Every later stage is a **list**.
+- [ ] Nesting ≤ 1–2 layers; flat preferred.
+- [ ] Stage names are the team's real process words.
+- [ ] Per-stage columns the team acts on are noted.
+- [ ] You blueprinted + handed off assembly — you didn't claim to have created it.

thoughtleaders_cli-0.9.3/skills/tl-create-workflow/references/workflow-model.md

@@ -0,0 +1,89 @@
+# The Workflow data model — read this before designing anything
+
+A Workflow looks like a bespoke pipeline object. It isn't. It's a thin wrapper
+over the same **Report** (campaign) objects the platform already has. Get this
+model right and the rest of the skill is easy; get it wrong and you'll design
+workflows that break the way hand-built ones do.
+
+## A stage IS a Report
+
+- A **Workflow** has a `name`, a `report_type` (content / brands / channels /
+  sponsorships), an `owner`, and an ordered set of **steps**.
+- **There is no separate "step" / "stage" object.** A step *is* a `Campaign`
+  (the platform's word for a saved Report), linked to the workflow by a
+  `workflow` FK + a `workflow_step_number` that gives the order.
+- So "add a stage" = "create a report and hang it on the workflow at position
+  N". "Rename a stage" = "rename that report". Everything you know about
+  reports applies to stages.
+- A workflow is **typed**: every stage is the same `report_type`. You can't mix
+  channels and brands in one workflow.
+
+## Query vs list — the distinction that matters most
+
+Every report (stage) has a **FilterSet**. Whether a stage behaves as a **query**
+or a **list** is *not a stored flag* — it's implied by what's in that FilterSet:
+
+- **QUERY stage** — the FilterSet holds **filter criteria**: keywords, date
+  ranges, view/subscriber ranges, categories, content filters. The stage
+  *computes* its members by matching the index. It's a live search.
+- **LIST stage** — the FilterSet holds **explicit included / excluded
+  entities**: specific channels (or brands) that were put there. The stage *is*
+  that set. It doesn't search; it holds.
+
+Why it matters for building a workflow:
+
+- **The entry stage should be a QUERY.** It's the pool — the funnel needs a way
+  to *find* candidates, and a query does that (e.g. "channels matching this
+  topic / these guide-brand look-alikes").
+- **Every stage after the entry should be a LIST.** Downstream stages are where
+  you *move* entities into as they progress. Moving an entity = adding it to the
+  target stage's included list. A downstream stage that's a query has nothing to
+  hold what you move into it.
+- A query as anything but the first stage is the classic broken-workflow bug.
+  If a user asks for a mid-funnel "query" stage, what they usually want is a
+  **filter applied to a list stage's view** (narrow the visible rows) — that's a
+  transient view filter, not a query stage. Keep the stage a list.
+
+## Moving entities through the funnel
+
+- Users advance entities by **bulk-selecting** rows in a stage and clicking
+  **Move** (to the next stage) — this adds them to the target stage's included
+  list.
+- **Exclude / Remove** puts selected entities on a stage's *exclude* list
+  (removes them from that stage's results).
+- Moving and excluding are **non-destructive** to the rest of the stage — they
+  add to include/exclude lists, they don't rewrite the whole set. (This was a
+  real data-loss bug historically; it's fixed, but design as if every move is a
+  targeted add, because that's what it is.)
+
+## Linked reports (nesting) — powerful, easy to overuse
+
+- A stage can **include or exclude another report's entities** (not just
+  individual channels). E.g. a "Reach out" stage that *excludes* a "No email /
+  captcha" report so those channels never appear.
+- This nests: report A includes report B, which includes report C… There is **no
+  hard depth limit in the platform**, and deep chains are a documented
+  performance + comprehension trap (exponential resolution on wide/deep nests).
+- **Design rule: ≤1–2 layers of nesting.** Prefer a flat stage with its own
+  filters over a clever multi-level include/exclude chain. If you find yourself
+  drawing a nest more than two deep, flatten it.
+
+## Columns are per-stage
+
+- Each stage (report) has its own **columns**. A "Get face on screen" stage
+  wants a *Face On Screen* column; a "Reach out" stage wants an *Outreach email*
+  column. Note the acted-on column for each stage in the blueprint — the team
+  works off it.
+
+## Multi-user
+
+- A workflow is **shared** across the team by default — several account managers
+  work the same stages. (Per-user saved views — each person hiding the reports
+  that aren't theirs — is a platform feature area, not something you configure
+  from this skill.)
+
+## One-line summary to tell a user
+
+> A workflow is an ordered set of reports. The first one is a *search* (a query)
+> that finds your pool; each one after it is a *list* that you move channels
+> into as they move through the funnel.

{thoughtleaders_cli-0.9.2 → thoughtleaders_cli-0.9.3}/src/tl_cli/__init__.py

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