@harness-lab/cli 0.2.1 → 0.2.3

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

@@ -0,0 +1,426 @@
+# Facilitator Commands
+
+Příkazy pro facilitátory, kteří řídí workshop instance přes AI agenta.
+
+## Auth
+
+Facilitátor se musí nejdřív přihlásit přes `harness` CLI. Skill nemá být další secret store pro raw credentials ani dlouhodobou session.
+
+### `/workshop facilitator login`
+
+Pokud není aktivní facilitátorská session, řekni facilitátorovi, aby spustil:
+
+```bash
+harness auth login
+```
+
+CLI provede browser/device auth flow, uloží session do lokálního file storage a zpřístupní ji pro další privileged příkazy.
+
+Model:
+- `harness auth login` autentizuje facilitátora vůči platformě
+- konkrétní workshop instance se vybírá až při operaci nebo přes default context
+- instance grant se vyhodnocuje při přístupu ke konkrétní akci, ne při samotném loginu
+
+Aktuální praktický path v repu:
+
+- default / browser-device auth:
+```bash
+harness auth login --dashboard-url https://harness-lab-dashboard.vercel.app
+```
+- file mode / lokální demo fallback:
+```bash
+harness auth login --auth basic --dashboard-url http://localhost:3000 --username facilitator --password secret
+```
+- neon mode / sdílený dashboard bootstrap fallback:
+```bash
+harness auth login --auth neon --dashboard-url https://harness-lab-dashboard.vercel.app --email facilitator@example.com
+```
+
+Poznámka:
+- CLI dnes defaultně používá browser/device auth a ukládá session do lokálního file storage
+- Pokud facilitátor chce OS-native storage, může použít `HARNESS_SESSION_STORAGE=keychain`, `credential-manager` nebo `secret-service`
+- `--auth basic` a `--auth neon` zůstávají jen jako explicitní fallback pro lokální dev/bootstrap
+
+### `/workshop facilitator logout`
+
+Požádej o:
+
+```bash
+harness auth logout
+```
+
+## Instance Management
+
+### `/workshop facilitator status`
+
+Preferovaný path:
+
+```bash
+harness workshop status
+```
+
+Zobraz:
+- aktivní instanci a její stav
+- aktuální fázi
+- seznam facilitátorů s rolemi
+- počet týmů
+
+### `/workshop facilitator grant <email> <role>`
+
+Použij CLI-backed privileged request path. Skill nemá řešit auth bootstrap sám.
+
+API capability zůstává:
+
+```http
+POST {DASHBOARD_URL}/api/admin/facilitators
+Content-Type: application/json
+
+{ "email": "...", "role": "operator" }
+```
+
+Vyžaduje `owner` roli. Vrací info o novém grantu.
+
+### `/workshop facilitator revoke <email>`
+
+Nejdřív zavolej `GET /api/admin/facilitators` a najdi grant podle emailu.
+Pak:
+```
+DELETE {DASHBOARD_URL}/api/admin/facilitators/{grantId}
+```
+
+Vyžaduje `owner` roli.
+
+### `/workshop facilitator create-instance`
+
+Preferovaný path je CLI příkaz nad sdíleným runtime API:
+
+```bash
+harness workshop create-instance developer-hackathon-praha-24-4-saturn \
+  --template-id blueprint-default \
+  --content-lang cs \
+  --event-title "Developer Hackathon Praha" \
+  --city Praha \
+  --date-range "24. dubna 2026" \
+  --venue-name "Seyfor Praha jednička 103" \
+  --room-name Saturn \
+  --address-line "CZ, Praha 8, Sokolovska 695/115b" \
+  --location-details "17 osob + lektor" \
+  --facilitator-label Ondrej
+```
+
+Raw API reference zůstává jen jako diagnostická nebo architektonická reference:
+
+```http
+POST {DASHBOARD_URL}/api/workshop/instances
+Content-Type: application/json
+
+{
+  "id": "developer-hackathon-praha-24-4-saturn",
+  "templateId": "blueprint-default",
+  "contentLang": "cs",
+  "eventTitle": "Developer Hackathon Praha",
+  "city": "Praha",
+  "dateRange": "24. dubna 2026",
+  "venueName": "Seyfor Praha jednička 103",
+  "roomName": "Saturn",
+  "addressLine": "CZ, Praha 8, Sokolovska 695/115b",
+  "locationDetails": "17 osob + lektor",
+  "facilitatorLabel": "Ondrej"
+}
+```
+
+Poznámky pro skill:
+- skill má preferovat CLI, ne ručně skládané `fetch` skripty
+- `id` musí být lowercase slug s písmeny, čísly a pomlčkami
+- `contentLang` určuje jazyk workshopového obsahu pro dashboard, presenter a skill delivery; není to totéž jako UI language
+- když skill volá create opakovaně se stejným `id`, route vrací `created: false` a existující instance record
+- nehádej venue metadata zkráceně, když je facilitátor zná; pošli je rovnou při create
+
+### `/workshop facilitator update-instance <instance-id>`
+
+Preferovaný path:
+
+```bash
+harness workshop update-instance developer-hackathon-praha-24-4-saturn \
+  --content-lang en \
+  --event-title "Developer Hackathon Praha" \
+  --date-range "24. dubna 2026" \
+  --venue-name "Seyfor Praha jednička 103" \
+  --room-name Saturn \
+  --address-line "CZ, Praha 8, Sokolovska 695/115b" \
+  --location-details "17 osob + lektor" \
+  --facilitator-label Ondrej
+```
+
+Raw API reference:
+
+```http
+PATCH {DASHBOARD_URL}/api/workshop/instances/{instanceId}
+Content-Type: application/json
+
+{
+  "action": "update_metadata",
+  "contentLang": "en",
+  "eventTitle": "Developer Hackathon Praha",
+  "dateRange": "24. dubna 2026",
+  "venueName": "Seyfor Praha jednička 103",
+  "roomName": "Saturn",
+  "addressLine": "CZ, Praha 8, Sokolovska 695/115b",
+  "locationDetails": "17 osob + lektor",
+  "facilitatorLabel": "Ondrej"
+}
+```
+
+Pravidla:
+- pošli jen fieldy, které chceš změnit
+- nepoužívej reset pro obyčejnou opravu názvu, venue nebo room
+- když route vrátí `400`, payload je špatně; když vrátí `404`, instance neexistuje
+
+### `/workshop facilitator prepare`
+
+Preferovaný path:
+
+```bash
+harness workshop prepare developer-hackathon-praha-24-4-saturn
+```
+
+Raw API reference:
+
+```http
+POST {DASHBOARD_URL}/api/workshop
+Content-Type: application/json
+
+{ "action": "prepare", "instanceId": "developer-hackathon-praha-24-4-saturn" }
+```
+
+Nastaví instanci do stavu `prepared`, ověří event code.
+
+### `/workshop facilitator remove-instance <instance-id>`
+
+Preferovaný path:
+
+```bash
+harness workshop remove-instance developer-hackathon-praha-24-4-saturn
+```
+
+Raw API reference:
+
+```http
+PATCH {DASHBOARD_URL}/api/workshop/instances/{instanceId}
+Content-Type: application/json
+
+{ "action": "remove" }
+```
+
+Pravidla:
+- remove zůstává owner-only operace
+- skill má facilitátora upozornit, že jde o destruktivní odebrání z aktivního seznamu, ne o běžnou editaci metadata
+
+### `/workshop facilitator agenda`
+
+Lokální editace agendy pro konkrétní instanci používá instanční route:
+
+```http
+GET {DASHBOARD_URL}/api/workshop/instances/{instanceId}/agenda
+PATCH {DASHBOARD_URL}/api/workshop/instances/{instanceId}/agenda
+POST {DASHBOARD_URL}/api/workshop/instances/{instanceId}/agenda
+DELETE {DASHBOARD_URL}/api/workshop/instances/{instanceId}/agenda
+```
+
+Příklady:
+
+```http
+PATCH {DASHBOARD_URL}/api/workshop/instances/{instanceId}/agenda
+Content-Type: application/json
+
+{
+  "action": "update",
+  "itemId": "build-1",
+  "title": "...",
+  "time": "...",
+  "goal": "...",
+  "roomSummary": "...",
+  "facilitatorPrompts": ["..."],
+  "watchFors": ["..."],
+  "checkpointQuestions": ["..."]
+}
+```
+
+```http
+PATCH {DASHBOARD_URL}/api/workshop/instances/{instanceId}/agenda
+Content-Type: application/json
+
+{ "action": "move", "itemId": "build-1", "direction": "up" }
+```
+
+```http
+POST {DASHBOARD_URL}/api/workshop/instances/{instanceId}/agenda
+Content-Type: application/json
+
+{
+  "title": "...",
+  "time": "...",
+  "goal": "...",
+  "roomSummary": "...",
+  "facilitatorPrompts": ["..."],
+  "watchFors": ["..."],
+  "checkpointQuestions": ["..."],
+  "afterItemId": "build-1"
+}
+```
+
+Pravidla:
+
+- agenda item je facilitátorský pack, ne jen `title/time/description`
+- preferované fieldy jsou `goal`, `roomSummary`, `facilitatorPrompts`, `watchFors`, `checkpointQuestions`
+- `description` zůstává compatibility field pro starší surface; pro room-facing shrnutí preferuj `roomSummary`
+- používej kanonická agenda ids jako `opening`, `talk`, `demo`, `build-1`, `intermezzo-1`, `rotation`, `build-2`, `intermezzo-2`, `reveal`
+- skill nemá vymýšlet vlastní názvy workshop momentů mimo tuto kostru
+
+### `/workshop facilitator scenes`
+
+Presenter scenes jsou agenda-linked room-facing výstupy pro facilitátora a projektor. Skill má umět:
+
+- vypsat scény pro celou instanci nebo konkrétní agenda item
+- vytvořit novou scénu
+- upravit obsah, label, scene type a CTA
+- změnit default scénu pro danou agenda položku
+- přeuspořádat scény
+- skrýt nebo znovu povolit scénu
+- smazat lokální scénu
+- číst a případně upravit `facilitatorNotes`, `sourceRefs` a `blocks`
+
+Instanční route:
+
+```http
+GET {DASHBOARD_URL}/api/workshop/instances/{instanceId}/scenes
+GET {DASHBOARD_URL}/api/workshop/instances/{instanceId}/scenes?agendaItemId=talk
+POST {DASHBOARD_URL}/api/workshop/instances/{instanceId}/scenes
+PATCH {DASHBOARD_URL}/api/workshop/instances/{instanceId}/scenes
+DELETE {DASHBOARD_URL}/api/workshop/instances/{instanceId}/scenes
+```
+
+Příklady:
+
+```http
+POST {DASHBOARD_URL}/api/workshop/instances/{instanceId}/scenes
+Content-Type: application/json
+
+{
+  "agendaItemId": "talk",
+  "label": "Prompt blob vs repo context",
+  "sceneType": "demo",
+  "intent": "walkthrough",
+  "chromePreset": "agenda",
+  "title": "Nejdřív bez kontextu, potom s mapou",
+  "facilitatorNotes": [
+    "Držte jednu story, ne přehlídku funkcí."
+  ],
+  "blocks": [
+    {
+      "id": "hero",
+      "type": "hero",
+      "title": "Nejdřív bez kontextu, potom s mapou",
+      "body": "Ukažte rozdíl mezi prompt blobem a krátkou mapou zapsanou v repu."
+    },
+    {
+      "id": "questions",
+      "type": "bullet-list",
+      "title": "Pointa",
+      "items": [
+        "Co není v repu, neexistuje.",
+        "Kontext je páka, ne kosmetika."
+      ]
+    }
+  ],
+  "ctaLabel": "Potom přepnout na participant walkthrough"
+}
+```
+
+```http
+PATCH {DASHBOARD_URL}/api/workshop/instances/{instanceId}/scenes
+Content-Type: application/json
+
+{
+  "action": "update",
+  "agendaItemId": "talk",
+  "sceneId": "scene-123",
+  "label": "Upravený demo flow",
+  "sceneType": "demo",
+  "intent": "walkthrough",
+  "chromePreset": "agenda",
+  "title": "Jedna story, ne přehlídka funkcí",
+  "blocks": [
+    {
+      "id": "hero",
+      "type": "hero",
+      "title": "Jedna story, ne přehlídka funkcí",
+      "body": "Neukazujte pět režimů práce. Ukažte jeden čitelný workflow."
+    }
+  ]
+}
+```
+
+```http
+PATCH {DASHBOARD_URL}/api/workshop/instances/{instanceId}/scenes
+Content-Type: application/json
+
+{ "action": "set_default", "agendaItemId": "talk", "sceneId": "talk-participant-view" }
+```
+
+```http
+PATCH {DASHBOARD_URL}/api/workshop/instances/{instanceId}/scenes
+Content-Type: application/json
+
+{ "action": "move", "agendaItemId": "talk", "sceneId": "scene-123", "direction": "up" }
+```
+
+```http
+PATCH {DASHBOARD_URL}/api/workshop/instances/{instanceId}/scenes
+Content-Type: application/json
+
+{ "action": "set_enabled", "agendaItemId": "talk", "sceneId": "scene-123", "enabled": false }
+```
+
+```http
+DELETE {DASHBOARD_URL}/api/workshop/instances/{instanceId}/scenes
+Content-Type: application/json
+
+{ "agendaItemId": "talk", "sceneId": "scene-123" }
+```
+
+Když facilitátor chce změnit wording, flow nebo participant walkthrough přes coding agenta, preferuj tuto route místo ručního popisu změn v UI.
+
+Při práci přes API:
+
+- neznámé `agendaItemId` nebo `sceneId` vrací `404`
+- malformed payload pořád vrací `400`
+- skill má stale target ids hlásit explicitně, ne pokračovat jako by se změna povedla
+- room-facing obsah patří do `blocks`, facilitátorské pokyny do `facilitatorNotes`
+- `title/body` zůstávají kvůli compatibility, ale skill má preferovat strukturované `blocks`
+- když runtime agenda existuje, skill má číst a citovat její `goal`, `roomSummary`, `facilitatorPrompts`, `watchFors`, `checkpointQuestions`, `facilitatorNotes` a `blocks`
+- když runtime data nejsou dostupná, fallbackni na blueprint a facilitační docs z repa a explicitně to řekni
+
+### `/workshop facilitator archive`
+
+Zavolej:
+```
+POST {DASHBOARD_URL}/api/workshop/archive
+Content-Type: application/json
+
+{ "reason": "manual", "notes": "..." }
+```
+
+## Environment
+
+Agent potřebuje vědět URL dashboardu:
+- `HARNESS_DASHBOARD_URL` — URL produkčního nebo preview dashboardu
+- Pokud není nastaveno, použij `https://harness-lab-dashboard.vercel.app`
+
+## Poznámky
+
+- Facilitátorské příkazy jsou oddělené od participant příkazů
+- `/workshop facilitator login` má facilitátora navést do `harness auth login`
+- Všechny ostatní privileged příkazy používají CLI-backed uloženou session
+- Pokud session expiruje, agent řekne facilitátorovi, aby se znovu přihlásil
+- Tyto příkazy nikdy nezobrazuj participant účastníkům

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

@@ -0,0 +1,35 @@
+# Follow-up Package
+
+## 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. Výzvu týdne:
+   - „Přidejte `AGENTS.md` do jednoho reálného projektu.“
+   - „Přesuňte jedno trvalé pravidlo z promptu do repa.“
+5. 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)
+6. Připomeňte, že stejné materiály lze vyžádat i přes skill:
+   - `workshop resources`
+   - `workshop gallery`
+   - `workshop follow-up`
+
+## 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`?
+- 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.

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

@@ -0,0 +1,58 @@
+# Workshop Skill Install
+
+## Doporučená distribuce
+
+Výchozí doporučení pro Harness Lab je instalace přes `@harness-lab/cli` do vašeho aktuálního pracovního repa.
+
+Proč:
+- skill je pořád obsah opřený o repo, ale nemá záviset na tom, že máte zrovna klon tohoto veřejného repa
+- stejné soubory slouží jako fallback i jako dokumentace
+- účastník má mít funkční workshop companion přímo v týmovém repu
+
+## Doporučený postup pro účastníka
+
+1. otevřít svůj týmový nebo workshopový repo
+2. nainstalovat Harness CLI:
+
+```bash
+npm install -g @harness-lab/cli
+```
+
+3. nainstalovat workshop skill do aktuálního repa:
+
+```bash
+harness skill install
+```
+
+Volitelně můžete cílit jinam:
+
+```bash
+harness skill install --target /cesta/k/repu
+```
+
+4. otevřít agent nástroj nad tímto repem
+5. ověřit, že fungují minimálně:
+   - Codex: `$workshop commands`, `$workshop reference`, `$workshop brief`
+   - pi: `/skill:workshop`, potom si říct o `commands`, `reference` nebo `brief`
+
+Po úspěšné instalaci `harness skill install` rovnou vypíše doporučené první kroky, aby účastník věděl, že může začít buď v Codexu přes `$workshop ...`, nebo v pi přes `/skill:workshop`.
+Když příkaz pustíte znovu později, CLI zkontroluje, jestli je bundle v cílovém repu aktuální. Pokud je zastaralý, rovnou ho obnoví. `--force` používejte jen tehdy, když chcete vynutit plný reinstall.
+
+## Co čekat dál
+
+`harness skill install` instaluje garantovaný workshop bundle. Neinstaluje za vás další workflow skills ani externí toolkity.
+
+Doporučený další postup:
+
+1. rozběhnout `workshop` skill
+2. otevřít `commands`, `reference` a `brief`
+3. doplnit `AGENTS.md`
+4. podle potřeby použít `brainstorm`, `plan`, `work`, `review` nebo `compound`, pokud je ve svém agent setupu máte k dispozici
+5. když chcete materiály pro účastníky bez hledání v GitHubu, použijte `workshop resources`, `workshop gallery` a `workshop follow-up`
+
+## Poznámka
+
+`harness skill install` vytvoří projektový bundle v `.agents/skills/harness-lab-workshop`, aby skill šel objevit v repu bez další distribuční vrstvy.
+Tuto složku berte jako generovaný workshop bundle, ne jako hlavní autorský zdroj.
+
+Přihlášení účastníka není potřeba pro samotnou existenci skillu. `workshop login` je až krok pro odemčení live event contextu.

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

@@ -0,0 +1,44 @@
+# Workshop Commands
+
+## How to use the skill
+
+- In Codex, use `$workshop ...`
+- In pi, load `/skill:workshop` and then ask for the relevant action naturally or by command name
+- The skill should be installed directly in your working repo via `harness skill install`. You do not need to clone the Harness Lab source repo for that.
+- If you are not sure where to start, begin with `workshop commands` or `workshop reference`
+
+## Shortest participant flow
+
+1. `workshop reference`
+2. `workshop brief`
+3. `workshop template`
+4. `workshop help`
+5. `workshop resources`
+
+## What each command does
+
+- `workshop` - where you are in the workshop right now and what the next safe move is
+- `workshop setup` - the fastest viable path into Codex or pi
+- `workshop brief` - your team brief and the first scope anchor
+- `workshop challenges` - challenge cards for the next step forward
+- `workshop team` - team, repo, and checkpoint
+- `workshop reference` - the short working-defaults card for today
+- `workshop help` - coaching based on the phase of the day or the problem you are stuck on
+- `workshop template` - starter `AGENTS.md`
+- `workshop analyze` - a fast handoff check of the repo
+- `workshop resources` - participant resource kit, learner kit, and follow-on materials
+- `workshop follow-up` - what to keep and what to do 48 hours to 1 week after the workshop
+- `workshop gallery` - verified external docs and public repos for continued learning
+- `workshop recap` - a short close or reminder after the workshop
+
+## When to use what
+
+- If you do not know where to start: `workshop reference`
+- If the brief feels blurry: `workshop brief`, then `brainstorm` or `plan`
+- If the repo lacks context: `workshop template`
+- If you are unsure about workflow: `workshop commands`
+- If you want materials after the workshop too: `workshop resources`, `workshop follow-up`, `workshop gallery`
+
+## 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

@@ -0,0 +1,35 @@
+# Follow-up Package
+
+## 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. A challenge for the week:
+   - "Add `AGENTS.md` to one real project."
+   - "Move one durable rule from a prompt into the repo."
+5. 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)
+6. A reminder that the same materials are available through the skill too:
+   - `workshop resources`
+   - `workshop gallery`
+   - `workshop follow-up`
+
+## 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?
+- 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.

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

@@ -0,0 +1,22 @@
+# Workshop Recap
+
+## What to keep
+
+- Context is not cosmetics. It is a working system.
+- `AGENTS.md`, skills, and runbooks are not extra garnish. They are tools that help a team keep direction.
+- A good handoff is visible when the next team can start work without verbal backfilling.
+
+## Try this this week
+
+- Add `AGENTS.md` to one real project.
+- Add build and test commands plus a `Done When` section.
+- Move one durable rule from a prompt into the repo.
+- After a larger change, try writing a short runbook for the next person.
+
+## Your commitment
+
+Return to the sticky note from the `And now?` segment and turn it into the first concrete commit, pull request, or task in the repo.
+
+## When you are not sure
+
+Start simply: write down what you want to do, where the context is, what the constraints are, and how you will know it is done.