@harness-lab/cli 0.2.0 → 0.2.2

package/README.md

@@ -1,6 +1,6 @@
 # Harness CLI
 
-Small Harness Lab CLI for facilitator auth, workshop operations, and repo-local skill installation.
+Small Harness Lab CLI for facilitator auth, workshop operations, and portable workshop skill installation.
 
 Current shipped scope:
 
@@ -63,14 +63,23 @@ harness version
 harness --help
 ```
 
-Install the repo-local workshop skill bundle for Codex/pi discovery:
+Install the portable workshop skill bundle into your current repo for Codex/pi discovery:
 
 ```bash
 harness skill install
 ```
 
-This creates `.agents/skills/harness-lab-workshop` in the current Harness Lab repo checkout.
-After install, the CLI prints the first recommended agent commands, starting with `Codex: $workshop reference` and `pi: /skill:workshop`.
+Optional explicit target:
+
+```bash
+harness skill install --target /path/to/team-repo
+```
+
+This creates `.agents/skills/harness-lab-workshop` in the target repo. The install does not require a local clone of the Harness Lab source repo.
+Rerunning `harness skill install` refreshes the installed bundle when the packaged workshop content changed and reports clearly when the target is already current. Use `--force` only when you want a full reinstall.
+After install, the CLI prints the first recommended agent commands, starting with `Codex: $workshop commands` and `pi: /skill:workshop`.
+
+Treat `.agents/skills/harness-lab-workshop` as generated workshop bundle content. The canonical authored source remains in this repository under `workshop-skill/`, `workshop-blueprint/`, selected `docs/`, and selected `materials/`.
 
 Default device/browser login:
 
@@ -135,5 +144,5 @@ Environment variables:
 ## Release Gate
 
 Public npm publication is controlled by the release gate in
-[docs/harness-cli-publication-gate.md](/Users/ondrejsvec/projects/Bobo/harness-lab/docs/harness-cli-publication-gate.md).
+[docs/harness-cli-publication-gate.md](../docs/harness-cli-publication-gate.md).
 Normal development should still happen from this repository; npm is the participant-facing distribution path, not a substitute for repo-local development.

package/assets/workshop-bundle/SKILL.md

@@ -0,0 +1,295 @@
+---
+name: workshop
+description: >
+  Participant-facing skill for the Harness Lab workshop. Supports the
+  `workshop` skill interface for setup, briefs, challenges, reference
+  materials, recap, and facilitator actions using live dashboard data when
+  available and local fallback content otherwise.
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Agent
+  - AskUserQuestion
+  - Write
+  - Edit
+  - Bash
+---
+
+# Workshop
+
+Participant-facing skill for the Harness Lab workshop. All participant-facing copy is Czech. Technical terms stay in English.
+
+## Purpose
+
+This skill is the primary workshop interface for participants in Codex or pi. It should prefer live dashboard API data when available and fall back to the local bundled content when the API is unavailable.
+
+The portable install path should make this skill usable from the participant's real working repo without requiring a clone of the Harness Lab source repo.
+
+Core mental model:
+- dashboard participant surface = orientace během dne
+- dashboard facilitator surface = řízení workshop instance
+- workshop skill = AI interface ke stejnému workshop systému
+- workshop blueprint = veřejná kanonická definice workshop method
+
+## Sources Of Truth
+
+Use runtime dashboard data for anything that changes during the workshop day:
+- current agenda phase
+- continuation reveal state
+- live team registry
+- checkpoints and sprint updates
+- facilitator-only status when the command explicitly requires facilitator access
+
+Use repo-native content for stable public guidance:
+- `content/` workshop materials
+- `workshop-skill/` reference docs
+- `workshop-blueprint/` for the reusable workshop method
+- challenge cards, project briefs, and public-safe framing
+
+Rule:
+- runtime APIs first for live workshop state
+- repo docs first for durable workshop guidance
+- if runtime is unavailable, fall back to repo material and say explicitly that the answer is fallback rather than live state
+- runtime edits do not imply blueprint edits; reusable changes belong back in the repo deliberately
+
+## Commands
+
+Syntax:
+- in Codex, invoke this skill as `$workshop ...`
+- in pi, load it with `/skill:workshop` or let pi auto-load it, then ask for the relevant workshop action in natural language
+- the command names below are runtime-neutral descriptions of the same interface
+
+### `workshop`
+
+Show:
+- current agenda phase
+- what the team should be doing right now
+- next hard milestone before the next facilitation checkpoint
+- if the dashboard is unavailable, infer the likely phase from local workshop materials and say clearly that this is fallback mode
+- if private event access is not active, clearly say which answers are fallback/public-only versus live event context
+
+### `workshop login`
+
+Ask for the shared event code and redeem it into a short-lived participant session.
+After success:
+- confirm live mode is active
+- say when the participant may need to log in again
+- keep facilitator-only data unavailable
+
+### `workshop logout`
+
+Clear the current participant session and return to fallback/public-only mode.
+
+### `workshop setup`
+
+Guide the participant through Codex or pi setup in Czech. Prefer the fastest viable path:
+- pi in terminal when the participant wants a hackable multi-model interface
+- Codex CLI on macOS/Linux
+- Codex App on Windows or macOS
+- web fallback if local install is blocked
+Use the content from `workshop-skill/setup.md`.
+
+### `workshop brief`
+
+Show the assigned project brief. Include:
+- problem statement
+- user stories
+- architecture considerations
+- first recommended prompt for the AI agent
+
+### `workshop challenges`
+
+Show available challenge cards, clearly marking:
+- semi-mandatory before lunch
+- semi-mandatory after the continuation shift
+- optional stretch cards
+
+### `workshop team`
+
+Show:
+- team name
+- members
+- repo URL
+- current sprint checkpoint
+
+### `workshop help`
+
+Give phase-aware coaching. Examples:
+- during Build Phase 1: remind the team to get a short `AGENTS.md`, a plan, commands, one executable check, and a reviewed output in place
+- during the continuation shift: tell the team to read before editing and to preserve evidence of what they changed
+- when the team is letting the agent work with more autonomy: push them toward tests, tracer bullets, or another executable check
+- for UI work: recommend `agent exploration -> Playwright regression -> human review` as the safe default workflow
+- when teams keep repeating the same rule out loud: push them to encode it in the repo instead of relying on chat memory
+- when the user asks generally what the skill can do, prefer returning a short menu based on `workshop-skill/commands.md` plus the best next step
+
+### `workshop template`
+
+Generate a starter `AGENTS.md` for the participant's current project using the 4-element structure:
+- goal
+- context
+- constraints
+- done when
+Use `workshop-skill/template-agents.md` as the default scaffold.
+Keep it short and map-like. Prefer links to deeper docs over long prose dumps.
+
+### `workshop recap`
+
+Return a short post-workshop reinforcement prompt in Czech.
+Use the content from `workshop-skill/recap.md`.
+
+### `workshop commands`
+
+Return a short participant-facing menu of the skill surface:
+- what the main commands are
+- when to use them
+- the shortest recommended path for a new participant
+Use `workshop-skill/commands.md`.
+
+### `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.
+
+### `workshop reference`
+
+Return the workshop reference card from `workshop-skill/reference.md`.
+
+### `workshop resources`
+
+Return the participant-facing resource bundle after or during the workshop.
+Use these sources together:
+- `materials/participant-resource-kit.md`
+- `docs/learner-resource-kit.md`
+
+The response should:
+- summarize what is in the kit
+- explain what to use during the workshop versus after it
+- point the participant to the most useful next artifact rather than dumping links only
+
+### `workshop gallery`
+
+Return the curated external reference gallery from `docs/learner-reference-gallery.md`.
+Use this when the participant asks for further reading, public examples, optional skill packs, or recommended external resources after the workshop.
+
+### `workshop follow-up`
+
+Return the follow-up package from `workshop-skill/follow-up-package.md`.
+Use this when the participant asks what to do after the workshop, what to revisit tomorrow, or what materials to keep using next week.
+
+### `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.
+
+### `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`
+- `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.
+
+### `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`.
+
+### `workshop facilitator prepare`
+
+Set the current instance to `prepared` state. Verify event code is ready.
+Prefer invoking `harness workshop prepare`.
+
+### `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.
+
+### `workshop facilitator archive`
+
+Archive the current workshop instance with optional notes.
+
+### `workshop analyze`
+
+Review the team's repo against the handoff criteria in `workshop-skill/analyze-checklist.md`.
+Return:
+- what helps continuation
+- what is missing
+- one concrete next improvement
+- whether the repo makes the next safe move obvious for a new team
+
+## Fallback Content
+
+If the API is not reachable, use the local content in this folder and the markdown files under `content/`.
+
+When falling back:
+- say explicitly that live workshop data is unavailable
+- avoid inventing team state, checkpoint state, or facilitator-only information
+- prefer reference guidance, setup help, templates, and local briefs over pretending to know the current live state
+
+Relevant local files:
+- `workshop-skill/setup.md`
+- `workshop-skill/commands.md`
+- `workshop-skill/reference.md`
+- `workshop-skill/recap.md`
+- `workshop-skill/template-agents.md`
+- `workshop-skill/analyze-checklist.md`
+- `workshop-skill/closing-skill.md`
+- `workshop-skill/follow-up-package.md`
+- `workshop-skill/facilitator.md`
+- `materials/participant-resource-kit.md`
+- `docs/learner-resource-kit.md`
+- `docs/learner-reference-gallery.md`
+- `content/project-briefs/*.md`
+- `content/challenge-cards/deck.md`
+- `workshop-blueprint/*`
+- `docs/workshop-event-context-contract.md`
+- `docs/harness-cli-foundation.md`
+
+## Style
+
+- Be concise and directive.
+- Use Czech for explanations.
+- Keep command names, file names, and code terms in English.
+- Prefer actionable next steps over theory during build phases.
+- Treat tests and executable checks as the default trust boundary once the agent is doing meaningful implementation work.
+- Prefer repo-native guidance over advice that would stay only in chat.
+- Treat `AGENTS.md` as a map that points to sources of truth, not as a giant instruction dump.
+- Do not present unrestricted browser autonomy in a normal authenticated browser as the default recommendation.

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

@@ -0,0 +1,172 @@
+{
+  "manifestVersion": 1,
+  "bundleName": "harness-lab-workshop",
+  "bundleVersion": "0.2.2",
+  "contentHash": "6d6ce5d3aa65d63167694b96c4db70bdd77c6084b529fdf78711c0a24c4e704d",
+  "files": [
+    {
+      "path": "content/challenge-cards/.gitkeep",
+      "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+    },
+    {
+      "path": "content/challenge-cards/deck.md",
+      "sha256": "de269aabe1a598294dbd1a2c2fb5dc858fd381811446fc649ff29555a67eda07"
+    },
+    {
+      "path": "content/challenge-cards/print-spec.md",
+      "sha256": "be7ecfdae9ada4145272f12e2d6018ccde7cfaeb9f48feb58aca7da7236815c0"
+    },
+    {
+      "path": "content/facilitation/.gitkeep",
+      "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+    },
+    {
+      "path": "content/facilitation/codex-setup-verification.md",
+      "sha256": "0d7e36a8f2b8c68939997b117f1b5cf1538a5b9e27f2d18948a1ac407543de8e"
+    },
+    {
+      "path": "content/facilitation/master-guide.md",
+      "sha256": "3199e25208552384efc5bafd9be512dd8e9cb428a39ea443af9eb4569f32d37a"
+    },
+    {
+      "path": "content/project-briefs/.gitkeep",
+      "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+    },
+    {
+      "path": "content/project-briefs/code-review-helper.md",
+      "sha256": "0d70c455d000ec8bc01337db5feee2174be8359730b5c278cccee9c3e6b0f2f7"
+    },
+    {
+      "path": "content/project-briefs/devtoolbox-cli.md",
+      "sha256": "867ba1b28413fcf43a95cc247ec07656f31b2fdc7bf4512fd5b4316a31f0e27b"
+    },
+    {
+      "path": "content/project-briefs/doc-generator.md",
+      "sha256": "3f3bea866c68a927916d90fa3e387ceccdd174290944bc83db7b89d43f3ba7a0"
+    },
+    {
+      "path": "content/project-briefs/metrics-dashboard.md",
+      "sha256": "a678058b6515fec4acba5d288bb71a725dfe9e75320efa11a475d63492db14f6"
+    },
+    {
+      "path": "content/project-briefs/standup-bot.md",
+      "sha256": "bf3af5bd1c72b5d4f3f5639c82d8e28dfbd4b470b0181833a2fff6e12eb99221"
+    },
+    {
+      "path": "content/style-examples.md",
+      "sha256": "21bc5f03aeff64cc6441e521ab006f8fcf1ec0c2f55630f218a08108fe6a32f2"
+    },
+    {
+      "path": "content/style-guide.md",
+      "sha256": "0f4661a267bdec133d3eeddb36a4c86ad15c3f09a4975d6d1ed0afa7c918ae1c"
+    },
+    {
+      "path": "content/talks/.gitkeep",
+      "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+    },
+    {
+      "path": "content/talks/codex-demo-script.md",
+      "sha256": "560eec6e45a45e0cf02a85a47f5c34ea30cf741ab592c411eab96fd90ca4c1f8"
+    },
+    {
+      "path": "content/talks/context-is-king.md",
+      "sha256": "338a357e1a61cdc5b2956f0191d699d13cee8ba1ea5047af4656985cd2ff4713"
+    },
+    {
+      "path": "docs/harness-cli-foundation.md",
+      "sha256": "94d5004a795e3e3669433be9f5b480bbe71b0aaf8ba32b060f930896fb1ee2ac"
+    },
+    {
+      "path": "docs/learner-reference-gallery.md",
+      "sha256": "fe00f671111eba6092cf28941277c6e4b45dff3c01396cffd351799daee292e5"
+    },
+    {
+      "path": "docs/learner-resource-kit.md",
+      "sha256": "47819b6134e5184ec229a5f0cc61d9be0718434d59ad1cc49c263b8fb8388a48"
+    },
+    {
+      "path": "docs/workshop-event-context-contract.md",
+      "sha256": "a7706a398ea5250537fb34323c4371ea2a7db15e477aec3a7893e6089fcd281f"
+    },
+    {
+      "path": "materials/participant-resource-kit.md",
+      "sha256": "73cf30345820fec8547af96a360997562dbd4c18c8f1cfb8758e20d727c449bf"
+    },
+    {
+      "path": "SKILL.md",
+      "sha256": "8a390c373bde15558f3a552803cad2240cf926578f2b54b33baf56f4d472374f"
+    },
+    {
+      "path": "workshop-blueprint/agenda.json",
+      "sha256": "6b8e1925e20fabccfd3cd9e9d79839855f51b2b7fd449efbb336bf3edd4eadce"
+    },
+    {
+      "path": "workshop-blueprint/control-surfaces.md",
+      "sha256": "623930d85b50a35270a721c79b6af05e31facfd85636c4388a0d8361f59b7785"
+    },
+    {
+      "path": "workshop-blueprint/day-structure.md",
+      "sha256": "2d2c7a43e959059fe5d3dbb2aae20e6828fee40c700729080677c2c7b6feb0dc"
+    },
+    {
+      "path": "workshop-blueprint/edit-boundaries.md",
+      "sha256": "d5a2b6039ff9d3acc5b3a58698289817a29d52af4058034f00bc188db6f5d84d"
+    },
+    {
+      "path": "workshop-blueprint/operator-guide.md",
+      "sha256": "c1cc4d64bfeed153e6b37d9e9fe8b270d052cd98fca17793891e04b37008149d"
+    },
+    {
+      "path": "workshop-blueprint/README.md",
+      "sha256": "f82176f7476fd2ce3673f42dbdbe6a1ea250e833b177be0a7a5dc8318a6b3e41"
+    },
+    {
+      "path": "workshop-blueprint/teaching-spine.md",
+      "sha256": "3fd140be90cabb651907e71380c292a5b76746f97367adb23571a4fead1df6b4"
+    },
+    {
+      "path": "workshop-skill/.gitkeep",
+      "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+    },
+    {
+      "path": "workshop-skill/analyze-checklist.md",
+      "sha256": "46c96ddda53e9b6086187c519e7126cce9b63d6d71f9462e306c741445756077"
+    },
+    {
+      "path": "workshop-skill/closing-skill.md",
+      "sha256": "e83e381216fad93356b94da89ca2525e01978d13005f2b0f11cf5ed32382971a"
+    },
+    {
+      "path": "workshop-skill/commands.md",
+      "sha256": "c6e432e770df361c03cf81910ffef9724f50a2c8e99faec54263c27921cbfc59"
+    },
+    {
+      "path": "workshop-skill/facilitator.md",
+      "sha256": "3ba33e10a9820b8f46beb0cdfae362a7bd35e093aa3ee250647a45000667c681"
+    },
+    {
+      "path": "workshop-skill/follow-up-package.md",
+      "sha256": "01bbd1f9bf7458a1e8ceb55eee5aab749448c613cc70a91bb7b2bf14240ce593"
+    },
+    {
+      "path": "workshop-skill/install.md",
+      "sha256": "196226385ac1bf38dfa7df3845692505db62f9e08a4c0027e2722c423bf4fa24"
+    },
+    {
+      "path": "workshop-skill/recap.md",
+      "sha256": "9310f61f5adcace4c97b249d0f27e3a423b5b3a278ec6f2440bf7a66d04a3058"
+    },
+    {
+      "path": "workshop-skill/reference.md",
+      "sha256": "45364102e4e57af38e150671eb42602a572d9588ad45e7604a6e5327a311f14c"
+    },
+    {
+      "path": "workshop-skill/setup.md",
+      "sha256": "ed5af717dadf8aeac256a393bd6edc103362cc91674a0c36a0a3580aa37c18ae"
+    },
+    {
+      "path": "workshop-skill/template-agents.md",
+      "sha256": "14141706f104f16373642a08a43e66ac9fd8231da46615c898587fad2fa503ee"
+    }
+  ]
+}

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

@@ -0,0 +1,38 @@
+# Challenge Cards
+
+Karty nejsou body navíc. Jsou to malé zásahy, které zlepšují způsob práce s agentem i kvalitu handoffu.
+
+## Context Engineering
+
+- `Vytvořte AGENTS.md jako mapu` — sepište cíl, build/test příkazy, trvalá pravidla a kam má další tým sáhnout jako první.
+- `Přidejte build/test příkazy` — agent musí umět ověřit výsledek bez ručního dovysvětlování.
+- `Napište skill pro code review` — formalizujte jednu review rutinu, kterou by uměl použít i cizí tým.
+- `Přesuňte pravidlo z hovoru do repa` — vše, co už tým řekl dvakrát nahlas, převeďte do `AGENTS.md`, README, runbooku nebo testu.
+
+## Workflow
+
+- `Použijte /plan před kódováním` — ukažte, z jakého planu tým vycházel, co z něj opravdu plní a jaký je další safe move.
+- `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í` — vytvořte RED test, tracer bullet nebo jednoduchý browser check dřív, než agent dostane víc autonomie.
+
+## Advanced
+
+- `Spusťte 2 paralelní Codex sessions` — rozdělte problém na dvě nezávislé části a porovnejte výstupy.
+- `Vytvořte runbook pro deployment` — i kdyby deploy zůstal jen simulovaný.
+- `Napište AGENTS.md pro podsložku` — ukažte, že kontext může být globální i lokální.
+- `Zaveďte garbage collection` — najděte jednu opakující se formu chaosu a proměňte ji v check, template nebo pravidlo.
+
+## Meta
+
+- `Přesuňte trvalé pravidlo z promptu do AGENTS.md`.
+- `Přidejte sekci Done When ke každému tasku`.
+- `Napište README pro tým po rotaci, ne pro sebe`.
+- `Zapište, co je skutečně ověřené` — odlište hotové, rozpracované a jen předpokládané.
+
+## Jak s kartami pracovat
+
+- Před obědem má každý tým splnit aspoň jednu kartu z `Context Engineering`.
+- Před rotací má být v repu dohledatelné, co bylo opravdu ověřeno a jaký je další safe move.
+- Po rotaci má každý tým splnit aspoň jednu kartu z `Workflow`.
+- Ostatní karty jsou dobrovolné. Berte je jako stretch cíle nebo inspiraci, když nevíte, co zlepšit dál.

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

@@ -0,0 +1,28 @@
+# Challenge Cards Print Spec
+
+## Formát
+
+- velikost: A6 nebo čtvrtina A4
+- oboustranný tisk není potřeba
+- velký nadpis, 1 krátký popis, 1 ikonický štítek kategorie
+
+## Barevné rozlišení
+
+- Context Engineering: písková / žlutá
+- Workflow: modrozelená
+- Advanced: cihlová
+- Meta: šedá
+
+## Layout
+
+1. nahoře název karty
+2. pod ním kategorie
+3. 2-3 věty zadání
+4. dole malý štítek:
+   - `Před obědem`
+   - `Po rotaci`
+   - `Kdykoliv`
+
+## Tisková poznámka
+
+Pokud se tisk nestihne, primární kanál je dashboard a `/workshop challenges`. Tisk je bonus, ne závislost workshopu.

package/assets/workshop-bundle/content/facilitation/codex-setup-verification.md

@@ -0,0 +1,54 @@
+# Codex Setup Verification
+
+## Cíl
+
+Do 10:30 musí mít každý účastník jednu funkční cestu:
+
+- `pi`
+- `Codex CLI`
+- `Codex App`
+- nebo web fallback
+
+Cíl není perfektní instalace. Cíl je dostat každého co nejdřív do práce s agentem.
+
+## Rychlý start
+
+### macOS / Linux
+
+1. Otevřete terminál.
+2. Přihlaste se do Codex prostředí podle firemního flow.
+3. Otevřete repozitář.
+4. Pošlete první prompt.
+
+### pi
+
+1. Nainstalujte `pi`:
+   `npm install -g @mariozechner/pi-coding-agent`
+2. Přihlaste provider nebo účet, který chcete používat.
+3. Otevřete repozitář.
+4. Spusťte `pi`.
+5. Načtěte workshop skill přes `/skill:workshop` a řekněte si o další krok.
+
+### Windows / macOS
+
+1. Otevřete `Codex App`.
+2. Přihlaste se.
+3. Otevřete workshop repo nebo týmový projekt.
+4. Pošlete první prompt.
+
+### Web fallback
+
+Použijte ho ve chvíli, kdy vás blokuje instalace, firemní politika nebo autentizace. Nečekejte na ideální setup, když už můžete pracovat.
+
+## Troubleshooting checklist
+
+- Nejde login → přejděte na `App` nebo web fallback a pokračujte.
+- Nejde CLI instalace → nenechte se blokovat déle než 7 minut.
+- Nejde otevřít repo → spárujte se s někým od stolu a vraťte se k tomu později.
+- Nevíte, co je další krok → v Codexu použijte `$workshop setup`. V pi načtěte `/skill:workshop` a řekněte si o setup pomoc.
+
+## Facilitátorské rozhodnutí
+
+- 7 minut blokace → fallback nebo pairing.
+- 10 minut chaosu → facilitátor dává jeden konkrétní další krok.
+- Jakmile má člověk jednu funkční cestu, setup je pro tuto chvíli dost dobrý.