thoughtleaders-cli 0.9.2__py3-none-any.whl → 0.9.4__py3-none-any.whl

{thoughtleaders_cli-0.9.2.dist-info → thoughtleaders_cli-0.9.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thoughtleaders-cli
-Version: 0.9.2
+Version: 0.9.4
 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
@@ -284,6 +284,21 @@ The plugin ships several focused skills (installed by all the `tl setup *` comma
 - **`tl-views-guarantee`** — sizes a multi-video sponsorship buy for a channel, returning the video bundle size, views guarantee, and likelihood to hit.
 - **`tl-top-partnerships`** — brand-user performance report. Ranks a brand's sold sponsorships by live eCPM vs the sold-date projection, aggregates per channel, and delivers a two-tab Google Sheet ("By Deal" / "By Channel") via `gws`. Uses only public CLI commands (`tl whoami`, `tl sponsorships list`).
 
+## Distributed skills
+
+Beyond the bundled set above, an organization can be granted additional skills that aren't part of a CLI release — `tl skill` fetches and installs them on demand into the same directories `tl setup` uses (Claude Code's standalone skills directory, OpenCode's skills directory, and the directory shared by Gemini and Codex), so every supported agent picks them up automatically.
+
+```bash
+tl skill list                 # skills available to your organization, with installed/latest versions
+tl skill list --all           # full catalog (full-access accounts only)
+tl skill download my-skill    # fetch and install into every AI-agent skill directory
+tl skill download my-skill --force   # overwrite a directory tl doesn't already manage
+tl skill update                # refresh every downloaded skill to its latest version
+tl skill remove my-skill        # uninstall a downloaded skill
+```
+
+A directory `tl skill download` doesn't already manage (no prior `tl`-managed install there) is left alone unless `--force` is passed — it never overwrites a skill you installed some other way. `tl` warns once a day, on any command, when a downloaded skill has a newer version available. `tl setup` and self-update re-syncs also respect these directories: a downloaded skill is never rmtree'd or overwritten, even if its name collides with a bundled skill.
+
 ## Output Formats
 
 By default, output is a styled table in the terminal and JSON when piped.

{thoughtleaders_cli-0.9.2.dist-info → thoughtleaders_cli-0.9.4.dist-info}/RECORD

@@ -1,12 +1,13 @@
-tl_cli/__init__.py,sha256=SS6LM2unjLV5RGfYCqFk1Gy1oudZaGmAocUwDxSiB4A,112
+tl_cli/__init__.py,sha256=vSA_gOKoNEuGKTTDXEGFTK9NgDyrC9oLOwpvRELGmLg,112
 tl_cli/_completions.py,sha256=kOyEUqC26vbYvyXWi513WX8fF73qQLR5WWuRSe_wqyk,164
 tl_cli/_typer_utils.py,sha256=ZiZsCVmEznPvBw-dYbr3tu3zWZ0iN6kjoQmK3gMqD28,860
 tl_cli/config.py,sha256=UV_OYTXuQnAIqbi_oVCXx0hhIdZWR678RRapVv51UwQ,1859
 tl_cli/filters.py,sha256=Yjj04lONGGmtCAIYN5i6KD12mAnUKEZ7i9heeWtdj7o,2952
 tl_cli/hints.py,sha256=cT8kuDtkAZqwXkc2RV0Yg_abofK-g9UiXwTTBunX78U,1557
-tl_cli/main.py,sha256=1f0Hs43fzIVeOtIbb5oGIyyPFDSJ6NdVQYjumt0CIx0,5908
+tl_cli/main.py,sha256=ZCzbgemmKlcIVlk_6TVznXooSsTBAjQ01k1olwQLhJQ,6435
 tl_cli/query_history.py,sha256=vA5avDU1DBZDWSb-w2ZxEZxV2MD21cqwzfYjXawOWZI,5540
 tl_cli/self_update.py,sha256=zLPCSzPQTHRAcTZTBBopRxAs5Bg-B7Ag_7PxfN94QOI,18800
+tl_cli/skill_registry.py,sha256=slB3K0tI_-mrPT7Eswzq2Sjlo8Wcwk5nDy0w9yQh6mM,11957
 tl_cli/auth/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tl_cli/auth/commands.py,sha256=CkCaKFb-xUwhCeIL92EC4-odiaSpLI1bmgg5tDCrclM,7387
 tl_cli/auth/login.py,sha256=AxdQ8LOZd1uZhFXPyaiGB_Hk0RiVuX7t37gkjgoEOCM,11568
@@ -14,16 +15,16 @@ tl_cli/auth/pkce.py,sha256=4Q6Ip-TeZFNG9c3swXNi4gH7mdMkltKa62gZZNybt8U,658
 tl_cli/auth/token_store.py,sha256=TcZnUol4-8r0jMEJhOPmABCX12_5RkAln2xfWPNdmHk,3275
 tl_cli/client/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tl_cli/client/errors.py,sha256=HEAEeFIgw_n_ZE9bkRRw6OPyqmwGhixzNN2bAxYj7wg,3246
-tl_cli/client/http.py,sha256=pUJYYuT0q92_SwqCuMj3ozBthvchKuKL9v9U_eCQv20,4164
+tl_cli/client/http.py,sha256=vcrNMJ5Z91-DXYq-vBH55Miii3QRnq2X1kIllMQ8yw8,4565
 tl_cli/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tl_cli/commands/_comments_common.py,sha256=x91WPSpDdV8AwE8Mwx4VtZQKWXBufsnBnC1lFD0Tzys,4522
-tl_cli/commands/balance.py,sha256=JHSmKdAUNtd-9zlKZhit9_BmhHXrEk0kQ-oSlQ0Eo6Y,2732
+tl_cli/commands/balance.py,sha256=OubiqknmLKREUzk2V0FZFtqgb4_dqQMR4V5-ifz-wfk,3150
 tl_cli/commands/brands.py,sha256=uogOfAdEbpjqiGlv4L2T1UC-Iz10G6fkRhVsDBOjRIY,15340
 tl_cli/commands/bulk_import.py,sha256=d4y1k_lD52LPJcCqXxEmyHIqcIwomZgbjqs1_QxPjeQ,4536
 tl_cli/commands/changelog.py,sha256=D1PtDdHpawTlWqUHjKzVmv9yXLSU915UVmI3dZzEwyA,4241
 tl_cli/commands/channels.py,sha256=gs6jHaxi6WjB3D8jnJETFVvkTXpqzlWR-W4JkBeG3oY,20406
 tl_cli/commands/credits.py,sha256=2xCht2e420LmaFBKNdKoMz8GlTh31qSWSlJAnVzoZic,7308
-tl_cli/commands/db.py,sha256=fPqqw5m561Tx-JkRR-RE_b_otSIMtTwPMUI0neqiyZ8,8997
+tl_cli/commands/db.py,sha256=RcuGYzmTs5KMk6RgYao3oV-j883dG7IonTQclZg7UZs,9148
 tl_cli/commands/deals.py,sha256=ZK9yneInsC6DXoCPS65oyLoVR0eRW1xdRlEN7oRp1pc,2174
 tl_cli/commands/describe.py,sha256=3lURv4NllM5qPeMEBbejrIxiMzsyTwpJIz211-wuGCU,12362
 tl_cli/commands/doctor.py,sha256=KUKglwhMc7B26XXy_3M0LkHu7wqfFO5T0YPHO1SH1VY,9024
@@ -33,15 +34,17 @@ tl_cli/commands/proposals.py,sha256=IXx9DsR7lPWRM4QvKB65t7xKNAK3H6ax9LIlIj8ydEs,
 tl_cli/commands/recommender.py,sha256=BZfviKAPhpZah0zaSyH5RDa23fG8QAkUnG5FDhOdi4I,21324
 tl_cli/commands/reports.py,sha256=7CL2atr0Y4XSE8U8kbuZ5-M-m3E9PKNZ0N_0Fbd_OkQ,26388
 tl_cli/commands/schema.py,sha256=rmfg5pvKHa5kQi59YBIHCMzBNawmYPi2tBMcZP7Vrxw,6432
-tl_cli/commands/setup.py,sha256=ypimHsp45yYSWwTLywfYtPC2P_45X4arW0K3SFuwEXk,28398
+tl_cli/commands/setup.py,sha256=p71pfwbIlMJoq2TaOfy35_absD9VMSX792FlapmQv2Y,29933
+tl_cli/commands/skills.py,sha256=4Vg5ph6T7T3WcIqIZc83EJPhtB79FE7fMej9uVhElqc,15884
 tl_cli/commands/snapshots.py,sha256=exlxFwMcM1BCiDTcE9dZfaSdRO-sxaTxtWzJmEoUVWI,3434
 tl_cli/commands/sponsorships.py,sha256=PdWCm9E4mrs_qlHtckMp99JmuRP94hthlqoWMi0k4tc,10471
 tl_cli/commands/uploads.py,sha256=Tf9tqAEm9FGe3A7sr_EDX9OzdNInCmrWNr10wWGuMUo,1526
 tl_cli/commands/whoami.py,sha256=aUXwBRwh1vAGrvz8CKGfHYtEOKJCIDfwrGesKAwYZMk,7866
+tl_cli/commands/workflows.py,sha256=ctduYa--Md6zbs8kQwO6mSyR9o1KB1UpNOaANuupDfU,6862
 tl_cli/output/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tl_cli/output/formatter.py,sha256=2FOsZb9aGcjKAGvumtEyS63cjIk47JcQGNM0K7Gpdp8,23413
 tl_cli/_plugin/.claude-plugin/marketplace.json,sha256=l56PMmyjfGXNGlV30wRyOAe74B6gJNCVNCxgsBbSNxc,446
-tl_cli/_plugin/.claude-plugin/plugin.json,sha256=MlM05A2LBDupXFroa0AsFQ5Yf1ouQa79wgfhXMt6yeA,466
+tl_cli/_plugin/.claude-plugin/plugin.json,sha256=lu-QQlhwxsIG1s6N8GFNEBGMfYek73Al0_1uTolvsC4,466
 tl_cli/_plugin/agents/keyword-context-classifier.md,sha256=8Pk6WqJKuF-ERkBh54Aa-9t60CvjdOIH0RurFlG-T7I,4325
 tl_cli/_plugin/agents/keyword-entity-resolver.md,sha256=fOAeTZa2-h7te8dEXLFcmiL2tj6IXwnQ0ChUrym3yFc,5619
 tl_cli/_plugin/agents/keyword-relevance-validator.md,sha256=uPUqobAVT7xq-brRHtNaFSTns-lYyCu3MwTuU5tn538,3127
@@ -51,7 +54,7 @@ tl_cli/_plugin/hooks/hooks.json,sha256=FSWibw1xAjA-suFV3fR8btIb2kQ82LQ08otTr-Npm
 tl_cli/_plugin/hooks/scripts/load-tl-skill.mjs,sha256=EBsyZ-caei-CBJsRtqzJXJs_20O3H22MuVmDpu96umo,805
 tl_cli/_plugin/hooks/scripts/post-usage.sh,sha256=WVvZLkZik6lbeZ20Kh-wgm4JkRFHFN0Uwl4C8S3Y0sY,759
 tl_cli/_plugin/hooks/scripts/pre-check.sh,sha256=inHopPXQ9h-KRcHuebEIQ-1EZmsTaHhAAMCFQ0MyiEQ,820
-tl_cli/_plugin/skills/tl/SKILL.md,sha256=A-hdUWXeJKd8fDlhe3qOVd1s1a64E77wldTAQKa-TTs,66805
+tl_cli/_plugin/skills/tl/SKILL.md,sha256=mFgTCMcYkEvXCO0f3uqFaQcHOJ2rJh6iZ46AdkziuVc,67959
 tl_cli/_plugin/skills/tl/references/business-glossary.md,sha256=YZ_UWygtAZB8Mfh9NPG2ld0OnmgknSBzBOpVZwN-wzs,19287
 tl_cli/_plugin/skills/tl/references/elasticsearch-schema.md,sha256=x7ZUYGbR6FJG02BSA9BjveoiC4X-7VsYxhLPBK4IH_c,23195
 tl_cli/_plugin/skills/tl/references/firebolt-schema.md,sha256=tysPKBxqQFRzfKi2vmEhHXn8PGaznep7yaKwSWZY3Jo,11110
@@ -75,6 +78,11 @@ tl_cli/_plugin/skills/tl-channel-authenticity/scripts/score.py,sha256=LwhTMf9eyO
 tl_cli/_plugin/skills/tl-channel-authenticity/scripts/tl_cli.py,sha256=Mu__ZzcELuQBPJ8Ia6GiLbW1ZtqI1aQklBeRPAw9JNk,9045
 tl_cli/_plugin/skills/tl-channel-authenticity/scripts/video_integrity.py,sha256=Pj9cZkFHX-fwfmkSjicy_B04fQ3TW3gLrGliHwCwX5g,11120
 tl_cli/_plugin/skills/tl-channel-authenticity/scripts/view_curves.py,sha256=wx4cgi_HSOBDEy9bI_8RGnAFpY8q8xHOlF7DYojmi0c,4447
+tl_cli/_plugin/skills/tl-create-workflow/SKILL.md,sha256=TSUY6vxBqTeLdeAJ1uUK8-EKPHiwRILe80Jv6dlDGAw,13347
+tl_cli/_plugin/skills/tl-create-workflow/references/creating-in-app.md,sha256=mJkmMgndNyJoTxIb9eiTLPw-jecKvIACLuvDHqvP558,5071
+tl_cli/_plugin/skills/tl-create-workflow/references/methodology.md,sha256=oXth-akS6QD7GmSDQRMaenAViTC5tlRgXIq_5uXVQQg,3847
+tl_cli/_plugin/skills/tl-create-workflow/references/pitfalls.md,sha256=6XBbe7T3o9PQcEs5FGNZ3n6xqVz0ZoNoFttJ9nNDjBU,3289
+tl_cli/_plugin/skills/tl-create-workflow/references/workflow-model.md,sha256=39cNg6AaSjb5K54neBkkn_RVJa7g9UnfZ_pVSzUsjDI,4591
 tl_cli/_plugin/skills/tl-keyword-research/SKILL.md,sha256=wvLvlumbR5fDxL-PZAqRDu7azYl4MXe1A5vOBn8YghE,38264
 tl_cli/_plugin/skills/tl-keyword-research/references/elasticsearch-content-search.md,sha256=fsXbpI3DPtkOnPEquB11Efur665o963RDN4-WIJCRJs,24263
 tl_cli/_plugin/skills/tl-keyword-research/references/help.md,sha256=yTmoU-Z6rPDjprbDa09nePoON0jnRSh_FVc7lqu1XGs,6802
@@ -101,8 +109,8 @@ tl_cli/_plugin/skills/tl-top-partnerships/SKILL.md,sha256=jOMMr40XRnAZv-oRLeyKJT
 tl_cli/_plugin/skills/tl-top-partnerships/scripts/top_partnerships.py,sha256=OqhoyvFe1zrtrStChcam7oPYgFnSbGHC3WAgLhLIC3w,13738
 tl_cli/_plugin/skills/tl-views-guarantee/SKILL.md,sha256=IH7q1WJDWri9TWJMiga1FMGJO_GKSbWwaDS6CVNZ9c0,9270
 tl_cli/_plugin/skills/tl-views-guarantee/scripts/vg.py,sha256=Qp5poinHEqh9374anq0bLtlxj2YL6ipBicaT960-Cws,15825
-thoughtleaders_cli-0.9.2.dist-info/METADATA,sha256=peW38EK69xvAHI_7RdN-jNT_K79f2bCbV4k7DjyT8Z0,19083
-thoughtleaders_cli-0.9.2.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
-thoughtleaders_cli-0.9.2.dist-info/entry_points.txt,sha256=umZp-1BkGkHDG0bNZXpTXrjwW0HGf9IDFN40eAWuuvg,39
-thoughtleaders_cli-0.9.2.dist-info/licenses/LICENSE,sha256=RUfdfLsn6jygiyrnnVUHt6r4IPwr2rbDm9Kixgtu8fo,1071
-thoughtleaders_cli-0.9.2.dist-info/RECORD,,
+thoughtleaders_cli-0.9.4.dist-info/METADATA,sha256=-BYaTIApwQ4wVdRWEc99Dr-7BhfIpCHK7d858ufwoFg,20457
+thoughtleaders_cli-0.9.4.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+thoughtleaders_cli-0.9.4.dist-info/entry_points.txt,sha256=umZp-1BkGkHDG0bNZXpTXrjwW0HGf9IDFN40eAWuuvg,39
+thoughtleaders_cli-0.9.4.dist-info/licenses/LICENSE,sha256=RUfdfLsn6jygiyrnnVUHt6r4IPwr2rbDm9Kixgtu8fo,1071
+thoughtleaders_cli-0.9.4.dist-info/RECORD,,

tl_cli/__init__.py

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

tl_cli/_plugin/.claude-plugin/plugin.json

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

tl_cli/_plugin/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
@@ -252,14 +251,8 @@ contact field:
 
 The channel's full email archive (`all_emails` — a JSON object keyed by email address,
 each value recording when and where the address was found) is **not editable here**;
-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.
+sending it returns a 400. It is append-only and managed through an internal-only
+process that never modifies or removes existing entries — not available via this CLI.
 
 **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
@@ -509,6 +502,21 @@ tl changelog since v0.4.10             # Notes from v0.4.10 to latest
 tl changelog --md > CHANGELOG.md       # Capture for a doc
 ```
 
+#### Distributed skills — beyond the bundled set
+
+An organization can be granted additional skills that aren't part of a CLI release. `tl skill` fetches and installs them on demand into the same directories `tl setup` uses (Claude Code's standalone skills directory, OpenCode's skills directory, and the directory shared by Gemini and Codex), so every supported agent picks them up automatically — no restart or reconfiguration needed beyond re-reading the skill listing.
+
+```bash
+tl skill list                          # Skills available to your org, with installed/latest versions (free)
+tl skill list --all                    # Full catalog (full-access accounts only)
+tl skill download <name>                # Fetch and install into every AI-agent skill directory on this machine
+tl skill download <name> --force        # Overwrite a directory tl doesn't already manage
+tl skill update                         # Refresh every downloaded skill to its latest version
+tl skill remove <name>                  # Uninstall a downloaded skill
+```
+
+If a user asks to find, add, or refresh a skill by capability ("is there a skill for X", "get me the latest Y skill"), check `tl skill list` before saying no — the bundled set isn't the whole catalog. `tl skill download` never overwrites a directory it doesn't already manage unless `--force` is passed, so it's safe to run without clobbering a manually-installed skill of the same name. `tl` warns once a day, on any command, when a downloaded skill has a newer version available — surface that nag to the user rather than silently ignoring it, and offer to run `tl skill update`.
+
 #### Channel & video discovery — pick the path for the question shape
 
 Four first-class paths, each with a different signal. **Pick by the SHAPE of the user's question, not by habit.** "Recommender first" is the right default only for path 2 — for paths 1, 3, and 4 the recommender is the wrong tool.

tl_cli/_plugin/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.

tl_cli/_plugin/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.

tl_cli/_plugin/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.