@harness-lab/cli 0.3.0 → 0.3.2

package/assets/workshop-bundle/SKILL.md

@@ -326,6 +326,14 @@ Rules for rich scenes:
 
 Archive the current workshop instance with optional notes.
 
+### `workshop facilitator learnings`
+
+Query the cross-cohort learnings log to review rotation signals from past and current workshops.
+Prefer invoking `harness --json workshop learnings` for machine-readable output.
+Supports flags: `--tag TAG`, `--instance ID`, `--cohort NAME`, `--limit N` (default 20).
+When the facilitator asks for rotation signals, captured observations, or what happened during past handoffs, use this command.
+If the learnings log is empty, say so and suggest capturing the first signal using the rotation capture panel in the facilitator dashboard.
+
 ### `workshop analyze`
 
 Review the team's repo against the handoff criteria in `workshop-skill/analyze-checklist.md`.

package/assets/workshop-bundle/bundle-manifest.json

@@ -1,8 +1,8 @@
 {
   "manifestVersion": 1,
   "bundleName": "harness-lab-workshop",
-  "bundleVersion": "0.3.0",
-  "contentHash": "b0fd5ae303c75a44d04b923e25f7a28584c8fc63940b142fdfbba4f2f8ff255c",
+  "bundleVersion": "0.3.2",
+  "contentHash": "579eac8240790ff7974b9cfdfba7f4c2ae0c901fbf3bf312e1017ad258069174",
   "files": [
     {
       "path": "content/challenge-cards/.gitkeep",
@@ -10,7 +10,7 @@
     },
     {
       "path": "content/challenge-cards/deck.md",
-      "sha256": "1c8b4e3a6ab987dc2e9e5418a32a84b8dd3485b8ee0d7d5dc9dc01394f57e3cc"
+      "sha256": "d2523b1fbedd84faef5327affe5a698f44b8634c9eb0da8320dc8339bc5158fc"
     },
     {
       "path": "content/challenge-cards/locales/en/deck.md",
@@ -18,7 +18,7 @@
     },
     {
       "path": "content/challenge-cards/print-spec.md",
-      "sha256": "be7ecfdae9ada4145272f12e2d6018ccde7cfaeb9f48feb58aca7da7236815c0"
+      "sha256": "0c6bc2953d6296b8901705d938a29c1ef859490e53cc265fe401bb9585611e16"
     },
     {
       "path": "content/codex-craft.md",
@@ -34,7 +34,7 @@
     },
     {
       "path": "content/facilitation/master-guide.md",
-      "sha256": "2c8033a43459dad42a88c1c842e5e915e6bb7d6dbdea38412d4a9c06b93544d7"
+      "sha256": "c5f3df56380b3df498a92dc6de55e922b2c7722e53e4f6f2efbef9b76de1d163"
     },
     {
       "path": "content/project-briefs/.gitkeep",
@@ -42,7 +42,7 @@
     },
     {
       "path": "content/project-briefs/code-review-helper.md",
-      "sha256": "96bbbef60ab0ff93ad4aa3858852886329139a25ce9f375bc4cc57ad706b7c98"
+      "sha256": "faf51210e1305683432f3e96eec1e18f91cdb2f1fd086ff73aeb70b6d17895a0"
     },
     {
       "path": "content/project-briefs/devtoolbox-cli.md",
@@ -50,7 +50,7 @@
     },
     {
       "path": "content/project-briefs/doc-generator.md",
-      "sha256": "48b8298be1e14e962055ac6d157be2728aa96fc71109e7ee833a6c56dab64731"
+      "sha256": "b4a3da683eba039f6009be61fe546ed1585341c82c3492f94add8363ad9496e3"
     },
     {
       "path": "content/project-briefs/locales/en/code-review-helper.md",
@@ -74,11 +74,11 @@
     },
     {
       "path": "content/project-briefs/metrics-dashboard.md",
-      "sha256": "40c0d09c02fb20c97c0f99088641de20fa966b17089f6f7701a7808814b31c55"
+      "sha256": "926dd8ccedab65a30b862bf4dc481f2c8054778e5668d97f5c8cf46665c60860"
     },
     {
       "path": "content/project-briefs/standup-bot.md",
-      "sha256": "df9abc9d7bc8283d30d1c09fb412f9e072a980782c0b622747b13744b2a81c84"
+      "sha256": "c2f56513bf69dd92c95f3dbd68c5b0925d19faf17d9d42eb2ed40c7cc8e8839b"
     },
     {
       "path": "content/talks/.gitkeep",
@@ -90,7 +90,7 @@
     },
     {
       "path": "content/talks/context-is-king.md",
-      "sha256": "33583f7982dd8f2d4d1bcbb637c0408562d6e0e20825eea06f897b34fe5efe16"
+      "sha256": "2f666585220c50901fe91443904a127e3357aa71a92e93b10eafa17100eb105c"
     },
     {
       "path": "docs/harness-cli-foundation.md",
@@ -126,11 +126,11 @@
     },
     {
       "path": "materials/participant-resource-kit.md",
-      "sha256": "d7cd7db05429faf7af570e33401cb5788d663e06c984f193596c14d2d8a12a5b"
+      "sha256": "c9c58ebf3e66a6f6823a06b5d938bc930eb3a768d3d23a2b4f18fe99b4b85a47"
     },
     {
       "path": "SKILL.md",
-      "sha256": "a8b8f76f8eeef2a7e7cd0d2906f33a7ab7a146a14383f5f679fddc6b3bdf8242"
+      "sha256": "0188da9de8f517a09dc4d0e2eb14f395aa465048253bf0c719995e8a232a33e2"
     },
     {
       "path": "workshop-blueprint/agenda.json",
@@ -166,11 +166,11 @@
     },
     {
       "path": "workshop-skill/closing-skill.md",
-      "sha256": "7019aa2afe4ac68869f0ec0c4bf9509f35695d171b66292d874e41355da178e0"
+      "sha256": "f0ce3f0f4a515dff14dab77fd31317a73a489ee24ba536eb7dd20f0b13cff4ec"
     },
     {
       "path": "workshop-skill/commands.md",
-      "sha256": "837c795baf133f220d3badf329c2484028f87209fb4e39cc729df54754b9a0a3"
+      "sha256": "d0af2bcc53c9752be3b013da002c22d4a8c7a09dea1995075b82550947141736"
     },
     {
       "path": "workshop-skill/facilitator.md",
@@ -178,7 +178,7 @@
     },
     {
       "path": "workshop-skill/follow-up-package.md",
-      "sha256": "74b8232f54b663d8ba9a97485c898ef0e8cffd5b5423831627ee7fe94d1cca44"
+      "sha256": "3299b0cf49e90f87ec3090ed934234d8c06e502fd3305c4e69c8aadfe1b42e7e"
     },
     {
       "path": "workshop-skill/install.md",
@@ -186,7 +186,7 @@
     },
     {
       "path": "workshop-skill/locales/en/commands.md",
-      "sha256": "17856fa19a44c3336709186cba171505db4b503d11bc16ad2fbc49f67d6c78a0"
+      "sha256": "596af69cff67b770c284b4485c94bc39b511a60f3ff1b2b34f91f2c58a9f8b03"
     },
     {
       "path": "workshop-skill/locales/en/follow-up-package.md",
@@ -198,7 +198,7 @@
     },
     {
       "path": "workshop-skill/locales/en/reference.md",
-      "sha256": "f5931048a100e7da07b2b0cbfcf40d3f7744014cb0658df51e34930d23692903"
+      "sha256": "2e941f974ae86c79131770d40302eec0e7968e217f36d8ff166065c7819c47b3"
     },
     {
       "path": "workshop-skill/locales/en/setup.md",
@@ -206,11 +206,11 @@
     },
     {
       "path": "workshop-skill/recap.md",
-      "sha256": "fa242bbb17d5305fda2b3c08a8da14744f60f6895985bbbbb1604c4c1ad4c8b4"
+      "sha256": "c479b255b4ebd35dde9a1afbf7a174e3aa8b348ebed8e07187f641f5dcb1b143"
     },
     {
       "path": "workshop-skill/reference.md",
-      "sha256": "89ef69ce4380468557a2f43576286937baf891bb0dc19035f0f06da69a3d0e38"
+      "sha256": "438cfc517d5ff707ce737e81a7ec3f8098c08f8fd2589ac105aea968da39f9a6"
     },
     {
       "path": "workshop-skill/setup.md",

package/assets/workshop-bundle/content/challenge-cards/deck.md

@@ -15,7 +15,7 @@ Karty nejsou body navíc. Jsou to malé zásahy, které zlepšují způsob prác
 - `Rozdělte práci do více vláken` — zkuste dvě nezávislé linie práce a jednoho člověka na integraci.
 - `Delegujte úkol a vraťte se ke kontrole za 10 minut` — neskákejte agentovi do každého kroku, kontrolujte až výsledek.
 - `Přidejte nejmenší užitečné ověření` — zapište done criteria jako spustitelný check (unit test, tracer bullet nebo jednoduchý browser check) dřív, než agent dostane víc autonomie.
-- `Napište diagnózu po handoffu` — pojmenujte, co pomohlo, co chybělo a jaký je další safe move.
+- `Napište diagnózu po handoffu` — pojmenujte, co pomohlo, co chybělo a jaký je další bezpečný krok.
 - `Opravte jeden slabý signál v repu` — README, AGENTS.md, plán, runbook nebo check.
 
 ## Advanced

package/assets/workshop-bundle/content/challenge-cards/print-spec.md

@@ -17,7 +17,7 @@
 
 1. nahoře název karty
 2. pod ním kategorie
-3. 2-3 věty zadání
+3. 2–3 věty zadání
 4. dole malý štítek:
    - `Před obědem`
    - `Po rotaci`

package/assets/workshop-bundle/content/facilitation/master-guide.md

@@ -24,7 +24,7 @@ Spustit den jako společný start pro celý workshop, ne jako provozní brief k
 2. proč na tom záleží právě teď
 3. analogie typu Lego duck: stejné ingredience, různé použitelné výsledky
 4. krátká pohybová aktivace podle zkušenosti s AI agenty
-5. první pracovní kontrakt pro Build fázi 1
+5. první pracovní kontrakt pro build fázi 1
 
 ### Lego-duck analogie
 
@@ -78,7 +78,7 @@ Do oběda má být vidět:
 
 ### Cíl
 
-Proměnit energii z openingu v přesnou tezi a čistý most do Build fáze 1.
+Proměnit energii z openingu v přesnou tezi a čistý most do build fáze 1.
 
 ### Klíčová message
 
@@ -108,7 +108,7 @@ Pointa:
 - přenos mantinelů
 - přenos done criteria
 
-### Most do Build fáze 1
+### Co si odnesete do build fáze
 
 Na konci talku má být jasné:
 
@@ -232,7 +232,6 @@ Vést ho jako krátký checkpoint, ze kterého si týmy odnesou jednu věc, kter
 
 - Začněte `README`, `AGENTS.md` a planem.
 - Needitujte hned první soubor, který otevřete.
-- Nejprve si udělejte mapu: co funguje, co chybí, co je rizikové.
 - Nejdřív napište vlastní diagnózu: co pomáhá, co chybí, co je rizikové a jaký je další bezpečný krok.
 - Když tým neví, po čem sáhnout, vraťte ho k learner kitu: `template-agents`, `reference`, `analyze-checklist` a challenge cards.
 

package/assets/workshop-bundle/content/project-briefs/code-review-helper.md

@@ -24,7 +24,7 @@ Vaším úkolem je navrhnout nástroj, který z diffu nebo změny vytvoří pou
 - Nástroj vytvoří review checklist ze seed diffu.
 - Výstup odlišuje jistá zjištění od doporučení, hypotéz a bodů pro lidský úsudek.
 - Je jasné, jak přidat nové pravidlo nebo heuristiku bez dlouhého onboardingu.
-- Další tým může během několika minut pokračovat v rozvoji bez chaosu.
+- Další tým může během 10 minut pokračovat v rozvoji bez chaosu.
 
 ## První krok pro agenta
 

package/assets/workshop-bundle/content/project-briefs/doc-generator.md

@@ -9,7 +9,7 @@ Vaším úkolem je navrhnout nástroj, který z projektu vygeneruje základní
 ## User stories
 
 - Jako vývojář chci z projektu rychle získat základní technickou dokumentaci bez ručního sepisování všeho od nuly.
-- Jako reviewer chci během pár minut pochopit strukturu modulů a hlavní vstupní body.
+- Jako reviewer chci během 5 minut pochopit strukturu modulů a hlavní vstupní body.
 - Jako tým po rotaci chci objevit architekturu projektu bez dlouhého pátrání po souvislostech.
 
 ## Architektonické poznámky
@@ -26,7 +26,7 @@ Vaším úkolem je navrhnout nástroj, který z projektu vygeneruje základní
 - Je jasné, jak se nástroj spouští lokálně a nad jakým vstupem.
 - Výstup odděluje fakta od odhadů nebo heuristik.
 - Další tým umí přidat nový typ výstupu bez chaosu v repu.
-- Reviewer během pár minut pozná, odkud které tvrzení pochází.
+- Reviewer během 10 minut pozná, odkud které tvrzení pochází.
 
 ## První krok pro agenta
 

package/assets/workshop-bundle/content/project-briefs/metrics-dashboard.md

@@ -10,7 +10,7 @@ Vaším úkolem je navrhnout jednoduchý dashboard, který z několika metrik v
 
 - Jako tým chci zobrazit několik metrik na jedné obrazovce tak, aby z nich šlo rychle vyčíst stav.
 - Jako facilitátor chci snadno měnit seed data bez zásahu do UI logiky.
-- Jako tým po rotaci chci během několika minut pochopit strukturu dat, komponent i obrazovek.
+- Jako tým po rotaci chci během 10 minut pochopit strukturu dat, komponent i obrazovek.
 
 ## Architektonické poznámky
 

package/assets/workshop-bundle/content/project-briefs/standup-bot.md

@@ -25,7 +25,7 @@ Vaším úkolem je navrhnout nástroj, který ze standup vstupů vytvoří přeh
 - Nástroj umí ingestovat seed data a vytvořit čitelný souhrn.
 - Výstup zvýrazní blokery nebo položky, které potřebují pozornost.
 - Repo obsahuje instrukce, jak řešení napojit na reálný chat nebo jiný vstupní kanál.
-- Po rotaci lze navázat bez dalšího vysvětlování.
+- Po rotaci může nový tým pokračovat v práci z README a `AGENTS.md` bez ústního handoffu.
 - Je jasné, co je jisté shrnutí a co je jen heuristika nebo návrh.
 
 ## První krok pro agenta

package/assets/workshop-bundle/content/talks/context-is-king.md

@@ -43,15 +43,23 @@ Vezmeme stejný malý task ve dvou podmínkách. Jedna varianta bude prompt blob
 
 ## Hlavní teze
 
+### Kontext je páka
+
 - Kontext je páka, ne kosmetika.
 - `AGENTS.md`, skills a runbooky jsou týmová infrastruktura.
 - `AGENTS.md` nemá být encyklopedie. Má to být mapa, která ukáže, kam sáhnout dál.
-- Co není v repu, neexistuje. Slack, ústní dovysvětlení a "to si pamatujeme" se při návaznosti rozpadají.
+- Co není v repu, neexistuje. Slack, ústní dovysvětlení a „to si pamatujeme" se rozpadne, jakmile práci někdo převezme.
+
+### Ověření je hranice důvěry
+
 - Testy jsou hranice důvěry. Když agent pracuje samostatněji, musíte mnohem líp ověřovat, že udělal právě to, co jste chtěli.
 - Jednoduché mantinely zrychlují práci. Agentovi pomáhá jasný build/test flow, viditelné hranice a předvídatelná struktura.
 - U UI práce je výchozí pattern: agent exploration, potom repeatable browser test, potom lidské review.
 - „Nech model jezdit v mém běžném přihlášeném browseru“ není výchozí doporučení. Bezpečnější je izolované lokální prostředí a jasné mantinely.
-- Ověření napsané dřív, než pustíte agenta do většího kusu práce, není test-first dogma. Je to zápis done criteria do formy, kterou agent i další tým umí zkontrolovat. Iteraci to zrychluje, protože agent dostane přesné mantinely, ne další prompt.
+- Ověření napsané dřív, než pustíte agenta do většího kusu práce, není test-first dogma. Znamená to zapsat done criteria v takové formě, aby je agent i další tým uměl zkontrolovat. Iteraci to zrychluje, protože agent dostane přesné mantinely, ne další prompt.
+
+### Repo se udržuje, ne jen plní
+
 - Úklid není bonus po workshopu. Když narazíte na opakující se chaos, je čas ho proměnit v lepší template, ověření nebo runbook.
 - Odpolední návaznost prověří, jestli váš kontext funguje i bez vás.
 
@@ -62,14 +70,14 @@ Vezmeme stejný malý task ve dvou podmínkách. Jedna varianta bude prompt blob
 - Když agent dělá víc, já musím lépe ověřovat.
 - Handoff není závěr dne. Je to průběžná podmínka celé práce.
 
-## Most do Build fáze 1
+## Co si odnesete do build fáze
 
 Po tomhle talku se tým nemá vracet k repu s pocitem, že potřebuje jen chytřejší prompt. Má se vracet s jedním jasným očekáváním:
 
 - pokud ještě nemá workshop skill, teď je chvíle na `harness skill install`, pak `Codex: $workshop setup` nebo `pi: /skill:workshop`
 - nejdřív krátká mapa v repu
 - potom krátký plán kroků
-- potom první explicitní ověření
+- potom první explicitní ověření, že agent dělá, co jste čekali
 - teprve potom další feature motion
 
 ## Závěr

package/assets/workshop-bundle/materials/participant-resource-kit.md

@@ -77,7 +77,7 @@ Poznámka:
 Codex a další kódovací agenti se mění měsíčně. Tenhle kit není zmrazená reference — je to startovní harness pro vaši vlastní čtecí praxi.
 
 - **Codex CLI release notes** — čtěte při každém vydání. Změny v approval módech a sandboxingu jsou ty nejdůležitější.
-- **Simon Willison's blog** ([simonwillison.net](https://simonwillison.net/)) — jeden z nejhustších praktických zdrojů o Codexu, Claude Code a dalších agentech. Denně pracuje s těmito nástroji a zapisuje si to.
+- **Simon Willison's blog** ([simonwillison.net](https://simonwillison.net/)) — praktický zdroj o Codexu, Claude Code a dalších agentech. Píše z vlastní každodenní praxe.
 - **OpenAI Harness Engineering articles** — viz `docs/learner-reference-gallery.md` pro odkazy.
 - **Anthropic engineering blog** — když pracujete s Claude Code, sledujte oficiální posts.
 - **Vlastní `AGENTS.md` jako živý dokument** — každé čtvrtletí si je znovu přečtěte skeptickým okem. Smažte, co už není nosné. Jednoduchost je součást harnessu.

package/assets/workshop-bundle/workshop-skill/closing-skill.md

@@ -2,7 +2,7 @@
 
 ## Úkol
 
-Na konci dne vytvoř krátké shrnutí workshopu, které je:
+Po posledním bloku vytvoř krátké shrnutí workshopu, které je:
 
 - konkrétní
 - systémové, ne osobní
@@ -19,7 +19,7 @@ Na konci dne vytvoř krátké shrnutí workshopu, které je:
 
 1. Co pomohlo týmům pokračovat po handoffu
 2. Co opakovaně chybělo
-3. Jaké 2-3 principy si má místnost odnést do příštího týdne
+3. Jaké 2–3 principy si má místnost odnést do příštího týdne
 4. Jedna závěrečná věta, která propojí workshop s reálnou prací v týmu
 
 ## Styl

package/assets/workshop-bundle/workshop-skill/commands.md

@@ -39,6 +39,10 @@
 - Když si nejste jistí workflow: `workshop commands`
 - Když chcete materiály i po workshopu: `workshop resources`, `workshop follow-up`, `workshop gallery`
 
+## Facilitátorské příkazy
+
+- `workshop facilitator learnings` — dotaz do learnings logu: záznamy z rotace z minulých i aktuálních workshopů. Podporuje filtrování podle tagu, instance a cohortu.
+
 ## Důležitá poznámka
 
 `workshop` skill je garantovaný výchozí nástroj workshopu. Další workflow skills a veřejné toolkity jsou doporučené rozšíření, ne podmínka účasti.

package/assets/workshop-bundle/workshop-skill/follow-up-package.md

@@ -32,7 +32,7 @@ Krátký navazující dotaz:
 
 - Vytvořili jste `AGENTS.md` v reálném projektu?
 - Přidali jste build/test příkazy nebo sekci `Done When`?
-- Přidali jste další safe move nebo krátký handoff runbook?
+- Přidali jste další bezpečný krok nebo krátký handoff runbook?
 - Co vám pomohlo a co vás zablokovalo?
 
 ## W³ připomínka

package/assets/workshop-bundle/workshop-skill/locales/en/commands.md

@@ -39,6 +39,10 @@
 - If you are unsure about workflow: `workshop commands`
 - If you want materials after the workshop too: `workshop resources`, `workshop follow-up`, `workshop gallery`
 
+## Facilitator commands
+
+- `workshop facilitator learnings` — query the cross-cohort learnings log: rotation signals from past and current workshops. Supports filtering by tag, instance, and cohort.
+
 ## Important note
 
 The `workshop` skill is the guaranteed workshop default. Additional workflow skills and public toolkits are recommended accelerators, not a requirement for participation.

package/assets/workshop-bundle/workshop-skill/locales/en/reference.md

@@ -59,6 +59,7 @@
 - `Codex: $workshop` for orientation during the day
 - `Codex: $workshop template` when the repo is missing baseline context
 - `Codex: $workshop analyze` before handoff or after rotation when you want to expose blind spots in the repo quickly
+- `Codex: $workshop facilitator learnings` or `harness workshop learnings` to query the cross-cohort learnings log (rotation signals from past workshops). Prefers the CLI path for machine-readable output with filtering by tag, instance, or cohort.
 
 ## Recommended participant loop
 

package/assets/workshop-bundle/workshop-skill/recap.md

@@ -26,4 +26,4 @@ Vraťte se ke sticky note z části `A teď?` a převeďte ji na první konkr
 
 ## Až si nebudete jistí
 
-Začněte jednoduše: napište, co chcete udělat, kde je kontext, jaká jsou omezení, podle čeho poznáte hotovo a jaký je další safe move, když práce zůstane rozdělaná.
+Začněte jednoduše: napište, co chcete udělat, kde je kontext, jaká jsou omezení, podle čeho poznáte hotovo a jaký je další bezpečný krok, když práce zůstane rozdělaná.

package/assets/workshop-bundle/workshop-skill/reference.md

@@ -36,7 +36,7 @@
 - V prvním buildu: `template-agents`, brief, plán a první ověření
 - Před obědem: dopsat další bezpečný krok a použít `workshop analyze`, když si nejste jistí handoffem
 - Po rotaci: `workshop analyze`, learner kit a challenge cards místo ústního rescue
-- Na konci dne: `workshop recap` a `workshop follow-up`
+- Po posledním bloku: `workshop recap` a `workshop follow-up`
 
 ## Doporučené příkazy
 
@@ -87,6 +87,14 @@
 
 Dobrý prompt nestačí. Když má práce přežít handoff, musí být kontext uložený v repu, další bezpečný krok musí být dohledatelný a ověření musí zůstat čitelné i pro cizí tým.
 
+## Learnings log — pro facilitátory
+
+- Po rotaci můžete procházet zachycené signály přímo v CLI: `harness workshop learnings`
+- Filtrujte podle tagu: `harness --json workshop learnings --tag missing_runbook`
+- Filtrujte podle kohorty nebo instance: `--cohort 2026-Q2`, `--instance <id>`
+- V dashboardu: rotační panel v detailu instance obsahuje capture formulář i přehled posledních záznamů
+- Learnings log přežije smazání instance a postupně buduje evidenci pro vylepšení blueprintu
+
 ## Kam dál po workshopu
 
 - Oficiální docs, OpenAI článek o Harness Engineering a ověřené veřejné skill repozitáře najdete v [`docs/learner-reference-gallery.md`](../docs/learner-reference-gallery.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harness-lab/cli",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Participant-facing Harness Lab CLI for facilitator auth and workshop operations",
   "license": "MIT",
   "type": "module",

package/src/run-cli.js

@@ -1,3 +1,5 @@
+import fs from "node:fs/promises";
+import path from "node:path";
 import { getDefaultDashboardUrl } from "./config.js";
 import { createHarnessClient, HarnessApiError } from "./client.js";
 import { createCliUi, prompt, writeLine } from "./io.js";
@@ -200,38 +202,87 @@ function resolveCurrentInstanceTarget(session, env) {
   };
 }
 
+function helpLine(command, description) {
+  return description ? `${command.padEnd(48)} ${description}` : `    ${command}`;
+}
+
 function printUsage(io, ui) {
   ui.heading("Harness CLI");
-  ui.paragraph(`Version ${version}`);
+  ui.paragraph(`Workshop toolkit for teams working with AI coding agents. Version ${version}.`);
   ui.blank();
+
   ui.section("Usage");
+  ui.commandList(["harness <command> [flags]"]);
+  ui.blank();
+
+  ui.section("Participant");
+  ui.commandList([
+    helpLine("skill install [--target PATH] [--force]", "Install the workshop skill into your repo"),
+  ]);
+  ui.blank();
+
+  ui.section("Authentication");
   ui.commandList([
-    "harness [--json] <command>",
-    "harness --help",
-    "harness --version",
-    "harness version",
+    helpLine("auth login [--auth device|basic|neon]", "Authenticate as a facilitator"),
+    helpLine("auth logout", "End the current session"),
+    helpLine("auth status", "Check session status"),
   ]);
   ui.blank();
-  ui.section("Commands");
+
+  ui.section("Workshop — inspect");
+  ui.commandList([
+    helpLine("workshop status", "Show current state and selected instance"),
+    helpLine("workshop current-instance", "Show the locally selected instance"),
+    helpLine("workshop select-instance <id> [--clear]", "Pin an instance for subsequent commands"),
+    helpLine("workshop list-instances", "List all facilitator-visible instances"),
+    helpLine("workshop show-instance <id>", "Inspect one instance in detail"),
+  ]);
+  ui.blank();
+
+  ui.section("Workshop — lifecycle");
+  ui.commandList([
+    helpLine("workshop create-instance [<id>]", "Create a new workshop from a template"),
+    helpLine("  [--template-id ID] [--content-lang cs|en]", ""),
+    helpLine("  [--event-title TEXT] [--city CITY]", ""),
+    helpLine("workshop update-instance <id>", "Update event metadata for an instance"),
+    helpLine("  [--content-lang cs|en] [--event-title TEXT]", ""),
+    helpLine("  [--city CITY]", ""),
+    helpLine("workshop reset-instance <id> [--template-id ID]", "Reset an instance from the blueprint"),
+    helpLine("workshop prepare <id>", "Mark an instance as ready for participants"),
+    helpLine("workshop remove-instance <id>", "Soft-remove an instance from the list"),
+    helpLine("workshop archive [--notes TEXT]", "Snapshot runtime state before reset"),
+  ]);
+  ui.blank();
+
+  ui.section("Workshop — live facilitation");
   ui.commandList([
-    "harness auth login [--auth device|basic|neon] [--dashboard-url URL] [--username USER] [--email EMAIL] [--password PASS] [--no-open]",
-    "harness auth logout",
-    "harness auth status",
-    "harness skill install [--target PATH] [--force]",
-    "harness workshop current-instance",
-    "harness workshop select-instance <instance-id> [--clear]",
-    "harness workshop status",
-    "harness workshop list-instances",
-    "harness workshop show-instance <instance-id>",
-    "harness workshop participant-access [<instance-id>] [--rotate] [--code VALUE]",
-    "harness workshop archive [--notes TEXT]",
-    "harness workshop create-instance [<instance-id>] [--template-id ID] [--content-lang cs|en] [--event-title TEXT] [--city CITY]",
-    "harness workshop update-instance <instance-id> [--content-lang cs|en] [--event-title TEXT] [--city CITY]",
-    "harness workshop reset-instance <instance-id> [--template-id ID]",
-    "harness workshop prepare <instance-id>",
-    "harness workshop remove-instance <instance-id>",
-    "harness workshop phase set <phase-id>",
+    helpLine("workshop phase set <phase-id>", "Advance the agenda to a phase"),
+    helpLine("workshop participant-access [<id>]", "Inspect or rotate the event code"),
+    helpLine("  [--rotate] [--code VALUE]", ""),
+    helpLine("workshop learnings", "Query the cross-cohort learnings log"),
+    helpLine("  [--tag TAG] [--instance ID]", ""),
+    helpLine("  [--cohort NAME] [--limit N]", ""),
   ]);
+  ui.blank();
+
+  ui.section("Global flags");
+  ui.commandList([
+    helpLine("--json", "Output machine-readable JSON"),
+    helpLine("--help", "Show this help"),
+    helpLine("--version", "Print version"),
+  ]);
+  ui.blank();
+
+  ui.section("Examples");
+  ui.commandList([
+    helpLine("harness skill install", "Install workshop skill here"),
+    helpLine("harness auth login", "Start device-code login"),
+    helpLine("harness workshop status", "Check what instance you target"),
+    helpLine("harness workshop learnings --tag missing_runbook", "Search learnings by tag"),
+  ]);
+  ui.blank();
+
+  ui.paragraph("Documentation: https://github.com/ondrej-svec/harness-lab");
 }
 
 function printVersion(io) {
@@ -1142,6 +1193,101 @@ async function handleWorkshopPhaseSet(io, ui, env, positionals, deps) {
   }
 }
 
+async function handleWorkshopLearningsQuery(io, ui, env, flags) {
+  const dataDir = env.HARNESS_DATA_DIR ?? path.join(process.cwd(), "data");
+  const logPath = env.HARNESS_LEARNINGS_LOG_PATH ?? path.join(dataDir, "learnings-log.jsonl");
+
+  let rawLines;
+  try {
+    const content = await fs.readFile(logPath, "utf8");
+    rawLines = content.split("\n").filter((line) => line.trim().length > 0);
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      ui.json("Workshop Learnings", { ok: true, signals: [], totalMatched: 0, source: logPath });
+      return 0;
+    }
+    ui.status("error", `Could not read learnings log at ${logPath}: ${error instanceof Error ? error.message : String(error)}`, { stream: "stderr" });
+    return 1;
+  }
+
+  let entries;
+  try {
+    entries = rawLines.map((line) => JSON.parse(line));
+  } catch (error) {
+    ui.status("error", `Learnings log has malformed JSON lines: ${error instanceof Error ? error.message : String(error)}`, { stream: "stderr" });
+    return 1;
+  }
+
+  const filterTag = readStringFlag(flags, "tag");
+  const filterInstance = readStringFlag(flags, "instance");
+  const filterCohort = readStringFlag(flags, "cohort");
+  const limit = Number(readStringFlag(flags, "limit") ?? "20");
+
+  let matched = entries;
+  if (filterTag) {
+    matched = matched.filter((entry) =>
+      Array.isArray(entry.signal?.tags) && entry.signal.tags.some((tag) => tag === filterTag),
+    );
+  }
+  if (filterInstance) {
+    matched = matched.filter((entry) => entry.instanceId === filterInstance);
+  }
+  if (filterCohort) {
+    matched = matched.filter((entry) => entry.cohort === filterCohort);
+  }
+
+  const totalMatched = matched.length;
+  const limited = Number.isFinite(limit) && limit > 0 ? matched.slice(-limit) : matched;
+
+  if (ui.jsonMode) {
+    ui.json("Workshop Learnings", {
+      ok: true,
+      totalMatched,
+      returned: limited.length,
+      source: logPath,
+      signals: limited.map((entry) => ({
+        cohort: entry.cohort,
+        instanceId: entry.instanceId,
+        capturedAt: entry.signal?.capturedAt ?? entry.loggedAt,
+        capturedBy: entry.signal?.capturedBy ?? "unknown",
+        teamId: entry.signal?.teamId ?? null,
+        tags: entry.signal?.tags ?? [],
+        freeText: entry.signal?.freeText ?? "",
+      })),
+    });
+    return 0;
+  }
+
+  ui.heading("Workshop Learnings");
+  if (limited.length === 0) {
+    ui.paragraph(totalMatched === 0
+      ? "No signals captured yet. Use the rotation capture panel in the facilitator dashboard during the continuation shift."
+      : `No signals matched the current filters (${totalMatched} total in log).`,
+    );
+    ui.blank();
+    ui.keyValue("Source", logPath);
+    return 0;
+  }
+
+  ui.paragraph(`${totalMatched} signal${totalMatched === 1 ? "" : "s"} matched${totalMatched > limited.length ? ` (showing last ${limited.length})` : ""}`);
+  ui.blank();
+
+  for (const entry of limited) {
+    const signal = entry.signal ?? {};
+    const capturedAt = signal.capturedAt ?? entry.loggedAt ?? "";
+    const time = capturedAt ? new Date(capturedAt).toLocaleString("en-US", { dateStyle: "short", timeStyle: "short" }) : "";
+    const team = signal.teamId ? ` [${signal.teamId}]` : "";
+    const tags = Array.isArray(signal.tags) && signal.tags.length > 0 ? `  {${signal.tags.join(", ")}}` : "";
+
+    ui.section(`${entry.cohort ?? "?"} · ${time}${team}${tags}`);
+    ui.paragraph(signal.freeText ?? "(no observation text)", { indent: "  " });
+    ui.blank();
+  }
+
+  ui.keyValue("Source", logPath);
+  return 0;
+}
+
 export async function runCli(argv, io, deps = {}) {
   const fetchFn = deps.fetchFn ?? globalThis.fetch;
   const mergedDeps = { fetchFn, sleepFn: deps.sleepFn, openUrl: deps.openUrl, cwd: deps.cwd };
@@ -1241,6 +1387,10 @@ export async function runCli(argv, io, deps = {}) {
     return handleWorkshopPhaseSet(io, ui, io.env, positionals, mergedDeps);
   }
 
+  if (scope === "workshop" && action === "learnings") {
+    return handleWorkshopLearningsQuery(io, ui, io.env, flags);
+  }
+
   printUsage(io, ui);
   return 1;
 }