@harness-lab/cli 0.3.1 → 0.4.0

package/assets/workshop-bundle/workshop-skill/SKILL-facilitator.md

@@ -0,0 +1,191 @@
+---
+name: workshop-facilitator
+description: >
+  Facilitator-facing skill for the Harness Lab workshop. Provides workshop
+  instance management, agenda editing, scene authoring, participant access
+  control, and cross-cohort learnings. Activates only after successful
+  facilitator login via the harness CLI.
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Agent
+  - AskUserQuestion
+  - Write
+  - Edit
+  - Bash
+---
+
+# Workshop — Facilitator
+
+Facilitator-facing skill for the Harness Lab workshop. This skill activates only after successful `workshop facilitator login` via the harness CLI.
+
+For the full operational reference with API routes, payload shapes, and rules, see `workshop-skill/facilitator.md`.
+
+## Loading Condition
+
+This skill should be loaded only when the facilitator has an active facilitator session. Participant sessions do not grant access to these commands.
+
+## Language Resolution
+
+Facilitator-control commands are operational rather than room-facing delivery:
+- prefer the user's current language unless the facilitator explicitly asks for another reviewed locale or you are quoting workshop content
+- the authored language of a supporting doc does not decide the reply language by itself
+- if the requested locale has no reviewed variant, fall back to English and say so explicitly
+- do not let a Czech-authored fallback file force a Czech answer when the resolved response locale is English
+
+## Commands
+
+### `workshop facilitator login`
+
+Authenticate as a facilitator through the `harness` CLI privileged path.
+The skill should ask the facilitator to complete CLI login/bootstrap if needed, then use the CLI-backed session for subsequent commands.
+This is a facilitator-only command — do not surface to participants.
+
+### `workshop facilitator status`
+
+Show the current instance state, agenda phase, facilitator list, and team count.
+Requires active facilitator session.
+If a local current instance is selected, prefer that target over deployment-default status.
+When an agent needs machine-readable output, prefer `harness --json workshop status`.
+
+### `workshop facilitator current-instance`
+
+Show the locally selected facilitator target, where it came from, and the resolved instance record.
+Prefer invoking `harness workshop current-instance`.
+Use this to confirm the CLI target before update, reset, prepare, remove, or phase operations.
+
+### `workshop facilitator select-instance <instance-id>`
+
+Persist a facilitator-local current target for later workshop commands.
+Prefer invoking `harness workshop select-instance <instance-id>`.
+Use `harness workshop select-instance --clear` to remove the stored selection.
+
+### `workshop facilitator list-instances`
+
+List the facilitator-visible workshop instance registry.
+Prefer invoking `harness workshop list-instances` over raw API scripts or local session-file inspection.
+Use this when the facilitator needs to discover what currently exists on a shared dashboard before choosing an explicit instance for reset, update, or agenda work.
+When an agent needs strict parsing, prefer `harness --json workshop list-instances`.
+
+### `workshop facilitator show-instance <instance-id>`
+
+Inspect one explicit workshop instance.
+Prefer invoking `harness workshop show-instance <instance-id>` over raw API scripts.
+Use this when the facilitator needs the full record for one instance rather than the deployment-default runtime status returned by `workshop facilitator status`.
+If a current instance is already selected, the CLI may omit `<instance-id>` and use the stored target.
+
+### `workshop facilitator participant-access`
+
+Inspect or rotate the shared participant event code for the current workshop instance.
+Prefer invoking `harness --json workshop participant-access` for inspection and `harness --json workshop participant-access --rotate` to issue a fresh code.
+If the current raw code is no longer recoverable from the hash-only runtime store, issue a new code instead of guessing.
+
+### `workshop facilitator grant <email> <role>`
+
+Grant a Neon Auth user access to the current workshop instance.
+Roles: owner, operator, observer. Requires `owner` role.
+
+### `workshop facilitator revoke <email>`
+
+Revoke a facilitator's access to the current instance. Requires `owner` role.
+
+### `workshop facilitator create-instance`
+
+Create a new workshop instance from a template. Requires facilitator session.
+Prefer invoking `harness workshop create-instance` over raw API scripts.
+
+The skill should support rich event metadata, not just id and city:
+- `id`
+- `templateId`
+- `contentLang`
+- `eventTitle`
+- `city`
+- `dateRange`
+- `venueName`
+- `roomName`
+- `addressLine`
+- `locationDetails`
+- `facilitatorLabel`
+
+### `workshop facilitator update-instance <instance-id>`
+
+Update event metadata for an existing workshop instance. Requires facilitator session.
+Prefer invoking `harness workshop update-instance` over raw API scripts.
+Use this when the facilitator wants to correct or refine date, venue, room, address, or event title without resetting the instance.
+Support `contentLang` changes explicitly so facilitators can choose workshop delivery language per instance without changing admin UI language.
+
+Facilitator discovery rule:
+- for routine discovery, use `harness workshop list-instances` and `harness workshop show-instance`
+- for repeated work on one live workshop, use `harness workshop select-instance <instance-id>` and `harness workshop current-instance`
+- do not read local CLI session files or improvise authenticated `node -e` fetch scripts unless you are diagnosing the CLI itself
+
+### `workshop facilitator reset-instance <instance-id>`
+
+Reset one existing workshop instance from the selected blueprint template. Requires facilitator session.
+Prefer invoking `harness workshop reset-instance` over raw API scripts.
+Use this when the facilitator wants fresh canonical agenda, runner, and presenter content for a live instance and accepts that local runtime state will be reinitialized.
+If a current instance is already selected, the CLI may omit `<instance-id>` and use the stored target.
+
+### `workshop facilitator remove-instance`
+
+Remove a workshop instance from the active list without deleting its archive history. Requires facilitator session.
+Prefer invoking `harness workshop remove-instance`.
+If a current instance is already selected, the CLI may omit `<instance-id>` and use the stored target.
+
+### `workshop facilitator prepare`
+
+Set the current instance to `prepared` state. Verify event code is ready.
+Prefer invoking `harness workshop prepare`.
+If a current instance is already selected, the CLI may omit `<instance-id>` and use the stored target.
+
+### `workshop facilitator agenda`
+
+Inspect and edit the local agenda copy for one workshop instance. Requires facilitator session.
+
+### `workshop facilitator scenes`
+
+Inspect and edit presenter scenes for one workshop instance. This includes listing scenes for an agenda item, creating a new scene, editing content, changing default scene, reordering scenes, and enabling or hiding scenes. Requires facilitator session.
+
+Rules for rich scenes:
+- keep scenes agenda-linked and room-facing rather than inventing a freeform slide deck
+- prefer one dominant voice per scene and one main idea per scene
+- use reviewed local blueprint assets for reusable visuals instead of ad hoc remote image URLs
+- treat runtime scene edits as instance-local until a maintainer deliberately publishes them back into the repo
+- when richer scene authoring or promotion is involved, follow `docs/presenter-rich-scene-authoring.md`
+
+### `workshop facilitator archive`
+
+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 closing`
+
+Prepare Ondrej's closing synthesis by using:
+- sprint checkpoints from the dashboard
+- monitoring summary
+- W³ commitments or closing notes
+Use `workshop-skill/closing-skill.md`.
+Treat this as facilitator-facing. Do not proactively surface it to participants during normal workshop help.
+
+## Fallback Content
+
+If the API is not reachable:
+- say explicitly that live workshop data is unavailable
+- avoid inventing team state, checkpoint state, or facilitator-only information
+- prefer `workshop-skill/facilitator.md` for the full operational command reference
+
+## Style
+
+- Be concise and directive.
+- Use the resolved response language.
+- English is the default bundled fallback locale when no live or user-language signal overrides it.
+- Keep command names, file names, and code terms in English.
+- Prefer actionable operational guidance over theory.

package/assets/workshop-bundle/workshop-skill/analyze-checklist.md

@@ -10,6 +10,7 @@ Když agent dělá `/workshop analyze`, měl by projít:
 - jestli repo rozlišuje hotové vs. rozpracované části
 - jestli je v repu plán nebo runbook pro další tým
 - jestli je dohledatelné, co bylo skutečně ověřeno
+- jestli existuje záznam stavu session — co bylo ověřeno, co je rozpracované, jaký je další bezpečný krok
 - kolik pravidel žije jen v promptu a ne v repu
 - jak snadné by bylo pokračovat po rotaci bez ústního handoffu
 - jestli je zřejmý další bezpečný krok

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í

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

@@ -39,10 +39,6 @@
 - 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

@@ -2,39 +2,32 @@
 
 ## 48 hodin po workshopu
 
-Pošli účastníkům:
-
-1. Krátké připomenutí hlavních principů:
-   - Kontext je pracovní systém
-   - `AGENTS.md` je týmová infrastruktura
-   - `Done When` a build/test příkazy zvyšují šanci na dobrý handoff
-2. Odkaz na `/workshop recap`
-3. Odkaz nebo výřez z `workshop-skill/template-agents.md`
-4. Jednu větu, která vrátí room contract:
-   - „Nejde o chytřejší prompt. Jde o repo, ze kterého naváže další tým.“
-5. Výzvu týdne:
-   - „Přidejte `AGENTS.md` do jednoho reálného projektu.“
-   - „Přesuňte jedno trvalé pravidlo z promptu do repa.“
-6. Odkaz na learner kit:
-   - [`docs/learner-resource-kit.md`](../docs/learner-resource-kit.md)
-   - [`docs/learner-reference-gallery.md`](../docs/learner-reference-gallery.md)
-   - [`materials/participant-resource-kit.md`](../materials/participant-resource-kit.md)
-7. Připomeňte, že stejné materiály lze vyžádat i přes skill:
-   - `workshop resources`
-   - `workshop gallery`
-   - `workshop follow-up`
-8. Přidejte malý závazek:
-   - „Pošlete si sami sobě nebo týmu jeden commit, task nebo PR, který tenhle týden opravdu vznikne.“
-
-## 1 týden po workshopu
-
-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?
-- Co vám pomohlo a co vás zablokovalo?
-
-## W³ připomínka
-
-Pokud máš fotku sticky notes z části `A teď?`, pošli každému jeho vlastní závazek jako osobní připomínku.
+### Váš závazek
+
+Pokud máš fotku sticky notes z části „A teď?", pošli každému jeho vlastní závazek jako osobní připomínku. Závazek ze sticky note je to jediné, co je specifické právě pro tebe, právě z tohoto dne. Začni tím.
+
+**Jedna věc do pátku:** Splňte svůj závazek ze sticky note. Jeden commit, jeden PR, jeden task — cokoli, co z vašeho závazku udělá realitu.
+
+### Anchor cvičení
+
+Zapište si tři momenty z vašeho běžného pracovního týdne, kdy otevíráte nový úkol nebo novou session — to jsou vaše Anchor momenty pro „Map before motion." Když se tyto momenty stanou vaším spouštěčem, návyk se udrží sám.
+
+### Zdroje
+
+- Připomínka principů: Kontext je pracovní systém. `AGENTS.md` je týmová infrastruktura. `Done When` a build/test příkazy zvyšují šanci na dobrý handoff.
+- Odkaz na `/workshop recap`
+- Odkaz nebo výřez z `workshop-skill/template-agents.md`
+- Learner kit: [`docs/learner-resource-kit.md`](../docs/learner-resource-kit.md), [`docs/learner-reference-gallery.md`](../docs/learner-reference-gallery.md), [`materials/participant-resource-kit.md`](../materials/participant-resource-kit.md)
+- Skill příkazy: `workshop resources`, `workshop gallery`, `workshop follow-up`
+
+## Týdenní generační prompty
+
+Místo checklistů — jeden prompt týdně, který vás přiměje popsat konkrétní zkušenost:
+
+**Týden 1:** Popište konkrétní moment z tohoto týdne, kdy jste potřebovali ověřit výstup agenta. Co jste použili jako kontrolu a co byste příště změnili?
+
+**Týden 2:** Popište rozhodnutí, které jste tento týden zapsali do repozitáře místo toho, abyste ho nechali v chatu. Co vás přimělo ho zapsat?
+
+**Týden 3:** Popište moment, kdy jste agentovi dali omezení předem a ušetřilo vám to opravu. Jaké to bylo omezení?
+
+**Týden 4:** Popište situaci, kdy se stejný problém opakoval. Změnili jste systém (template, check, pravidlo), nebo jen výstup?

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

@@ -39,10 +39,6 @@
 - 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/follow-up-package.md

@@ -2,39 +2,32 @@
 
 ## 48 hours after the workshop
 
-Send participants:
-
-1. A short reminder of the main principles:
-   - Context is a working system
-   - `AGENTS.md` is team infrastructure
-   - `Done When` and build/test commands improve the chances of a good handoff
-2. A pointer to `/workshop recap`
-3. A link to or excerpt from `workshop-skill/template-agents.md`
-4. One sentence that brings the room contract back:
-   - "This is not about a smarter prompt. It is about a repo another team can continue from."
-5. A challenge for the week:
-   - "Add `AGENTS.md` to one real project."
-   - "Move one durable rule from a prompt into the repo."
-6. Links to the learner kit:
-   - [`docs/locales/en/learner-resource-kit.md`](../../../docs/locales/en/learner-resource-kit.md)
-   - [`docs/locales/en/learner-reference-gallery.md`](../../../docs/locales/en/learner-reference-gallery.md)
-   - [`materials/locales/en/participant-resource-kit.md`](../../../materials/locales/en/participant-resource-kit.md)
-7. A reminder that the same materials are available through the skill too:
-   - `workshop resources`
-   - `workshop gallery`
-   - `workshop follow-up`
-8. Add one small commitment:
-   - "Send yourself or your team one commit, task, or PR that will actually happen this week."
-
-## 1 week after the workshop
-
-Short follow-up questions:
-
-- Did you create `AGENTS.md` in a real project?
-- Did you add build/test commands or a `Done When` section?
-- Did you add the next safe move or a short handoff runbook?
-- What helped you and what blocked you?
-
-## W³ reminder
-
-If you have a photo of the sticky notes from the `And now?` section, send each person their own commitment as a personal reminder.
+### Your commitment
+
+If you have a photo of the sticky notes from the "And now?" section, send each person their own commitment as a personal reminder. The sticky-note commitment is the only thing specific to you, from this day. Start there.
+
+**One thing before Friday:** Complete your sticky-note commitment. One commit, one PR, one task — anything that turns your commitment into reality.
+
+### Anchor exercise
+
+Write down three moments in your normal work week when you open a new task or a new session — these are your Anchor moments for "Map before motion." When these moments become your trigger, the habit sustains itself.
+
+### Resources
+
+- Principle reminder: Context is a working system. `AGENTS.md` is team infrastructure. `Done When` and build/test commands improve the chances of a good handoff.
+- Pointer to `/workshop recap`
+- Link to or excerpt from `workshop-skill/template-agents.md`
+- Learner kit: [`docs/learner-resource-kit.md`](../../../docs/learner-resource-kit.md), [`docs/learner-reference-gallery.md`](../../../docs/learner-reference-gallery.md), [`materials/participant-resource-kit.md`](../../../materials/participant-resource-kit.md)
+- Skill commands: `workshop resources`, `workshop gallery`, `workshop follow-up`
+
+## Weekly generation prompts
+
+Instead of checklists — one prompt per week that asks you to describe a concrete experience:
+
+**Week 1:** Describe a specific moment this week when you needed to verify agent output. What did you use as the check, and what would you change next time?
+
+**Week 2:** Describe a decision you wrote into the repository this week instead of leaving it in chat. What made you decide to write it down?
+
+**Week 3:** Describe a moment when you gave the agent a constraint upfront and it saved you a correction. What was the constraint?
+
+**Week 4:** Describe a situation where the same problem repeated. Did you change the system (template, check, rule), or just the output?

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

@@ -6,6 +6,7 @@
 - `If it is not in the repo, it does not exist` - important agreements, rules, and next steps belong in files
 - `Verification is the trust boundary` - more autonomy requires stronger evidence
 - `Handoff is a continuous constraint` - the next team should find the first safe move without your explanation
+- `Fix the system, not just the symptom` - when the same thing repeats, do not fix the output — fix the system
 
 ## 4 elements of a good task
 

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

@@ -6,6 +6,7 @@
 - `Co není v repu, neexistuje` — důležité dohody, pravidla a další kroky patří do souborů
 - `Ověření je hranice důvěry` — s větší autonomií musí růst i kvalita evidence
 - `Handoff je průběžná podmínka práce` — další tým má najít první bezpečný krok bez vašeho výkladu
+- `Opravte systém, ne jen symptom` — když se stejná věc opakuje, neopravujte výstup — opravte systém
 
 ## 4 prvky dobrého zadání
 
@@ -36,7 +37,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
 

package/package.json

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

package/src/run-cli.js

@@ -202,39 +202,88 @@ 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.paragraph("Most participants only need this. After install, use $workshop in your agent.");
+  ui.blank();
+
+  ui.section("Authentication");
+  ui.commandList([
+    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("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 [--json] <command>",
-    "harness --help",
-    "harness --version",
-    "harness version",
+    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("Commands");
+
+  ui.section("Global flags");
   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>",
-    "harness workshop learnings [--tag TAG] [--instance ID] [--cohort NAME] [--limit N]",
+    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) {
@@ -1287,6 +1336,28 @@ export async function runCli(argv, io, deps = {}) {
     return handleSkillInstall(io, ui, mergedDeps, flags);
   }
 
+  if (scope === "skill") {
+    ui.heading("Harness CLI — Skill");
+    ui.paragraph("Install the workshop skill into your project repo.");
+    ui.blank();
+    ui.section("Commands");
+    ui.commandList([
+      helpLine("harness skill install [--target PATH] [--force]", "Install the workshop skill"),
+    ]);
+    ui.blank();
+    ui.section("After install");
+    ui.commandList([
+      "Open Codex or pi in the same repo",
+      "Run: $workshop commands",
+      "Run: $workshop reference",
+      "Run: $workshop brief",
+      "Run: $workshop help",
+    ]);
+    ui.blank();
+    ui.paragraph("The skill is the participant's primary workshop interface.");
+    return 0;
+  }
+
   if (scope === "workshop" && action === "current-instance") {
     return handleWorkshopCurrentInstance(io, ui, io.env, mergedDeps);
   }