@harness-lab/cli 0.3.2 → 0.4.1

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/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ší bezpečný krok 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/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í
 

package/package.json

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

package/src/run-cli.js

@@ -219,6 +219,7 @@ function printUsage(io, ui) {
   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");
@@ -878,11 +879,19 @@ async function handleWorkshopShowInstance(io, ui, env, positionals, flags, deps)
 
   try {
     const client = createHarnessClient({ fetchFn: deps.fetchFn, session });
-    const result = await client.getWorkshopInstance(instanceId);
+    const [result, agenda] = await Promise.all([
+      client.getWorkshopInstance(instanceId),
+      client.getWorkshopAgenda(instanceId).catch(() => null),
+    ]);
     ui.json("Workshop Instance", {
       ok: true,
       ...summarizeWorkshopInstance(result.instance),
       instance: result.instance,
+      contentSummary: agenda ? {
+        phases: Array.isArray(agenda.items) ? agenda.items.length : 0,
+        scenes: Array.isArray(agenda.items) ? agenda.items.reduce((sum, item) => sum + (item.presenterScenes?.length ?? 0), 0) : 0,
+        currentPhase: agenda.phase ?? null,
+      } : null,
     });
     return 0;
   } catch (error) {
@@ -1117,6 +1126,10 @@ async function handleWorkshopResetInstance(io, ui, env, positionals, flags, deps
       readStringFlag(flags, "template-id", "template"),
     );
     ui.json("Workshop Reset Instance", result);
+    if (result.contentSummary) {
+      const s = result.contentSummary;
+      ui.status("ok", `Reset ${instanceId}: ${s.phases} phases, ${s.scenes} scenes, ${s.briefs} briefs, ${s.challenges} challenges`);
+    }
     return 0;
   } catch (error) {
     if (error instanceof HarnessApiError) {
@@ -1335,6 +1348,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);
   }