@harness-lab/cli 0.2.1 → 0.2.3

package/assets/workshop-bundle/docs/locales/en/learner-reference-gallery.md

@@ -0,0 +1,82 @@
+# Learner Reference Gallery
+
+This is a short list of resources for participants after the workshop.
+
+The rule is simple:
+- official documentation first
+- then a few strong public repos
+- and finally a small number of patterns directly relevant to Harness Lab
+
+Once this page starts to look like an “awesome list,” it has become too long.
+
+## Official documentation
+
+- [OpenAI Codex documentation](https://developers.openai.com/codex)
+  Use this as the main source for current Codex workflows, skills, `AGENTS.md`, subagents, and security guidance.
+
+- [OpenAI Codex best practices](https://developers.openai.com/codex/learn/best-practices)
+  The best fast entry point for using Codex as a long-term collaborator: context, `AGENTS.md`, review, verification, MCP, and automation.
+
+- [OpenAI Codex skills documentation](https://developers.openai.com/codex/skills)
+  Useful once you want to turn repeated prompts into reusable repo-native skills.
+
+- [OpenAI Codex plugins](https://developers.openai.com/codex/plugins)
+  Good for understanding when to use plugins and marketplace distribution in Codex instead of repo-native skills alone. In this workshop, treat plugins as an optional Codex accelerator, not as the core bootstrap.
+
+- [OpenAI Codex build plugins](https://developers.openai.com/codex/plugins/build)
+  Useful for maintainers who want to understand the marketplace model, repo-local marketplace patterns, or bundling skills, app integrations, and MCP servers into one Codex package.
+
+- [OpenAI Codex workflows](https://developers.openai.com/codex/workflows)
+  Good for turning workshop habits into real project workflows.
+
+- [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)
+  Useful for understanding why repo knowledge should be the system of record and why plans, review, and garbage collection belong to engineering discipline rather than bonus process.
+
+- [Next.js AI Coding Agents](https://nextjs.org/docs/app/guides/ai-agents)
+  Important mainly for Next.js projects: it shows why agents should read version-matched framework docs instead of relying on stale model memory.
+
+## Public repositories
+
+- [openai/codex](https://github.com/openai/codex)
+  The official CLI repo and the best anchor for how the tool itself evolves.
+
+- [openai/skills](https://github.com/openai/skills)
+  The official skills catalog and the best reference for what a Codex-native skill looks like.
+
+- [openai/codex-action](https://github.com/openai/codex-action)
+  A strong example of narrow, safe automation around Codex in CI.
+
+- [vercel-labs/skills](https://github.com/vercel-labs/skills)
+  Useful when you want skill packaging that stays portable across more than one coding agent.
+
+- [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills)
+  Good examples of practical, high-quality skills, especially for frontend and React work.
+
+## Optional workflow packs
+
+- [EveryInc/compound-engineering-plugin](https://github.com/EveryInc/compound-engineering-plugin)
+  A strong optional choice for people who want an explicit `brainstorm -> plan -> work -> review -> compound` loop. This repo supports installation for both Codex and pi, but treat it as an accelerator on top of the workshop default, not as required setup.
+
+## Practical patterns
+
+- Start with repo context before you start repeating the prompt.
+  In practice: first add `AGENTS.md`, build/test commands, and a concrete definition of done.
+
+- Use skills for repeated workflows, not as one-off chat macros.
+  If the same task returns across multiple sessions or repos, it is a good skill candidate.
+
+- Treat plugins and marketplace distribution as a Codex-specific delivery layer, not as the definition of the workshop method.
+  If something is taught as a Harness Lab default, it should still make sense outside Codex. A plugin makes sense where it genuinely adds Codex integrations or easier distribution.
+
+- Treat tests, tracer bullets, and checklists as the trust boundary.
+  The more autonomy the agent gets, the less “I skimmed the diff quickly” is enough.
+
+- Keep participant-facing examples smaller than backstage systems.
+  A good learner artifact is copyable and readable, not exhaustive.
+
+## Freshness rule
+
+Review this list:
+- before every workshop run
+- after a major change in Codex capabilities
+- when a recommended repo becomes stale, noisy, or stops being the best example

package/assets/workshop-bundle/docs/locales/en/learner-resource-kit.md

@@ -0,0 +1,126 @@
+# Learner Resource Kit
+
+This page defines the participant-facing resource kit for Harness Lab.
+
+It is the small, copyable slice of the repo that participants should take away, revisit, and reuse in their own projects.
+
+## Core rule
+
+The learner kit is not the full backstage harness.
+
+It should answer:
+- what should I copy from the workshop into my own repo?
+- what should the agent do first?
+- how do I make the work survive handoff?
+- what must I verify before I trust the output?
+
+The default participant pattern this kit should reinforce is:
+- `workshop` for orientation
+- `brainstorm` or `plan` before a larger cut
+- `work` against one verifiable goal
+- `review` before trust
+- `compound` and cleanup for things that should survive the session
+
+## Core learner kit
+
+### 1. Workshop skill
+
+Primary participant interface:
+- [`SKILL.md`](../../../SKILL.md)
+- [`workshop-skill/locales/en/setup.md`](../../../workshop-skill/locales/en/setup.md)
+- [`workshop-skill/locales/en/reference.md`](../../../workshop-skill/locales/en/reference.md)
+- [`workshop-skill/locales/en/recap.md`](../../../workshop-skill/locales/en/recap.md)
+
+Why it belongs here:
+- it shows how a participant-facing skill can guide setup, workflow, and verification in reviewed workshop language
+- it is a real repo-native interface, not a workshop slide artifact
+
+### 2. `AGENTS.md` example
+
+Default starter:
+- [`workshop-skill/template-agents.md`](../../../workshop-skill/template-agents.md)
+
+Why it belongs here:
+- it is the smallest reusable example of durable context in the repo
+- participants can adapt it directly for their own project
+
+### 3. Verification / review example
+
+Default checklist:
+- [`workshop-skill/analyze-checklist.md`](../../../workshop-skill/analyze-checklist.md)
+
+Why it belongs here:
+- it provides a concrete standard for “can another team continue from here?”
+- it turns repo quality into a checklist people can actually run
+
+### 4. Challenge cards
+
+Recommended subset:
+- [`content/challenge-cards/locales/en/deck.md`](../../../content/challenge-cards/locales/en/deck.md)
+
+Use:
+- as small interventions during the workshop
+- as prompts for what to improve later in a real repo
+
+### 5. Follow-up package
+
+Post-workshop reinforcement:
+- [`workshop-skill/locales/en/follow-up-package.md`](../../../workshop-skill/locales/en/follow-up-package.md)
+- [`materials/locales/en/participant-resource-kit.md`](../../../materials/locales/en/participant-resource-kit.md)
+
+Why it belongs here:
+- it turns the workshop from a one-day event into a repeatable prompt for behavior change
+- it provides a literal handout you can send or print without further explanation
+
+## When to use which artifact
+
+### During setup
+
+Use:
+- [`workshop-skill/locales/en/setup.md`](../../../workshop-skill/locales/en/setup.md)
+- [`workshop-skill/locales/en/reference.md`](../../../workshop-skill/locales/en/reference.md)
+
+### During Build Phase 1
+
+Use:
+- [`workshop-skill/template-agents.md`](../../../workshop-skill/template-agents.md)
+- the `Context Engineering` cards in [`content/challenge-cards/locales/en/deck.md`](../../../content/challenge-cards/locales/en/deck.md)
+
+### During the continuation shift
+
+Use:
+- [`workshop-skill/analyze-checklist.md`](../../../workshop-skill/analyze-checklist.md)
+- the `Workflow` cards in [`content/challenge-cards/locales/en/deck.md`](../../../content/challenge-cards/locales/en/deck.md)
+
+### After the workshop
+
+Use:
+- [`workshop-skill/locales/en/recap.md`](../../../workshop-skill/locales/en/recap.md)
+- [`workshop-skill/locales/en/follow-up-package.md`](../../../workshop-skill/locales/en/follow-up-package.md)
+- [`materials/locales/en/participant-resource-kit.md`](../../../materials/locales/en/participant-resource-kit.md)
+- [`learner-reference-gallery.md`](learner-reference-gallery.md)
+
+## What to carry into a real project
+
+Participants should leave with these concrete moves:
+
+1. Add `AGENTS.md` with:
+   - goal
+   - context
+   - constraints
+   - done when
+2. In `context`, write what the agent should read first and which docs are the source of truth.
+3. In `done when`, write explicit verification and the next safe move if work remains unfinished.
+4. Add build/test commands that another team or agent can run without verbal backfilling.
+5. Add one review or handoff checklist.
+6. Move one durable rule from chat into the repo.
+7. Use plan before a larger implementation and review or another check after a larger change.
+8. If you already use an external workflow skill pack, layer it on top of this foundation instead of replacing repo-native context and verification.
+
+## What does not belong here
+
+The learner kit should not include the full backstage operating detail, for example:
+- workshop-instance runbooks
+- private runtime architecture and operations
+- facilitator-only monitoring or control procedures
+- maintainer-level deployment and security procedures unless they are being taught explicitly as participant skill content

package/assets/workshop-bundle/docs/workshop-event-context-contract.md

@@ -0,0 +1,123 @@
+# Workshop Event Context Contract
+
+This document defines the day-one contract for participant event access across the dashboard and `workshop-skill/`.
+
+## Auth States
+
+### 1. Public mode
+
+Available without event login:
+- public participant dashboard surface
+- public-safe dashboard content
+- local/fallback `workshop-skill` behavior
+- setup, reference, and bundled project brief content
+
+Not available:
+- real event-private participant data
+- team repo registry
+- live checkpoint state
+
+### 2. Participant-authenticated mode
+
+Unlocked by redeeming the shared event code into a short-lived participant session.
+
+Available:
+- authenticated core bundle
+- on-demand participant team/runtime lookups
+
+### 3. Facilitator mode
+
+Separate auth path.
+
+Available:
+- admin surface
+- write operations
+- facilitator-only views and monitoring
+- facilitator skill commands via the CLI-backed auth path
+
+## Authenticated Core Bundle
+
+Day-one shape:
+
+- `event.title`
+- `event.subtitle`
+- `event.currentPhaseLabel`
+- `event.dateRange`
+- `event.city`
+- `agenda`
+- `briefs`
+- `challenges`
+- `keyLinks`
+- `announcements`
+
+Design rule:
+- small enough to fetch immediately after login
+- rich enough to make `/workshop` and the participant dashboard feel live
+
+## On-Demand Participant Lookups
+
+Fetched only when requested:
+
+- `teams[].id`
+- `teams[].name`
+- `teams[].city`
+- `teams[].repoUrl`
+- `teams[].checkpoint`
+
+These remain outside the core bundle because they are more privacy-sensitive and more volatile.
+
+## API Endpoints
+
+### Event access
+
+- `POST /api/event-access/redeem`
+- `POST /api/event-access/logout`
+
+### Participant event context
+
+- `GET /api/event-context/core`
+- `GET /api/event-context/teams`
+
+### Existing facilitator routes
+
+Current admin/facilitator write routes remain under existing admin protection and must not be unlocked by participant auth.
+
+## Skill Command Mapping
+
+| Command | Scope | Notes |
+|---------|-------|-------|
+| `/workshop` | Public first, authenticated when available | Must state clearly whether it is using fallback/public-only data or live event context |
+| `/workshop login` | Participant-auth bootstrap | Redeems the shared event code into a short-lived participant session |
+| `/workshop logout` | Participant-auth teardown | Clears the active participant session |
+| `/workshop setup` | Public | Always available |
+| `/workshop brief` | Public first, authenticated when available | Public brief content stays available; event-specific assignment can be layered later |
+| `/workshop challenges` | Public first, authenticated when available | Public deck stays available; live completion context can be layered later |
+| `/workshop team` | Participant-authenticated | Repo URLs and live checkpoint state are not public by default |
+| `/workshop help` | Public first, authenticated when available | Coaching stays useful in fallback mode |
+| `/workshop reference` | Public | Always available |
+| `/workshop analyze` | Public/local | Works against the participant repo even without live event access |
+
+## Error States
+
+- `invalid_code`
+- `expired_code`
+- `expired_session`
+- `participant event access required`
+- `fallback mode`
+
+## Session Transport Rules
+
+- dashboard participant sessions are stored in a server-issued HTTP-only cookie
+- skill-side session persistence should stay minimal and prefer renewable short-lived tokens over long-lived bearer state
+- the event code must not be reused as the live bearer credential after redemption
+- facilitator skill auth/session handling should live in the `harness` CLI, not in arbitrary skill state
+
+## Logging Expectations
+
+The private workshop-instance layer should log at least:
+
+- redemption attempts
+- successful session creation
+- session expiry or invalidation
+- failed protected lookups
+- event-code rotation events

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

@@ -0,0 +1,72 @@
+# Participant Resource Kit
+
+A short set of artifacts you can take from Harness Lab into your own project.
+
+## 1. Start with `AGENTS.md`
+
+Use this baseline:
+- `goal`
+- `context`
+- `constraints`
+- `done when`
+
+Default template:
+- [`workshop-skill/template-agents.md`](../../../workshop-skill/template-agents.md)
+
+## 2. Add one trust anchor
+
+Choose at least one:
+- build/test commands
+- a RED test
+- a tracer bullet
+- a review checklist
+
+When the agent handles a larger slice of work, “I skimmed it quickly” is not enough.
+
+Checklist for handoff:
+- [`workshop-skill/analyze-checklist.md`](../../../workshop-skill/analyze-checklist.md)
+
+## 3. Use a small workflow, not chaos
+
+Recommended baseline:
+- `workshop` for orientation and the next safe move
+- `/brainstorm` when the scope or first slice is still unclear
+- `/plan` before larger implementation
+- `/work` or another narrow implementation loop once you know what you are building
+- a test or another executable check before an important change
+- `/review` after a larger slice of work
+- `/compound` or a short repo-native note when a discovery makes future work cheaper
+- small ongoing cleanup: move build/test commands, constraints, and handoff notes from chat into the repo
+
+## 4. Move one rule from chat into the repo
+
+Typical candidates:
+- build/test commands
+- safety constraints
+- the definition of done
+- a handoff rule
+
+## 5. Keep UI work on a safe track
+
+Default pattern:
+- `agent exploration`
+- `Playwright regression`
+- `human review`
+
+Do not let the model drive your normal signed-in browser by default without sandboxing and control.
+
+## 6. What to revisit after the workshop
+
+- [`workshop-skill/locales/en/reference.md`](../../../workshop-skill/locales/en/reference.md)
+- [`workshop-skill/locales/en/recap.md`](../../../workshop-skill/locales/en/recap.md)
+- [`docs/locales/en/learner-reference-gallery.md`](../../../docs/locales/en/learner-reference-gallery.md)
+
+Note:
+- the `workshop` skill is the guaranteed workshop default
+- additional workflow skills and public toolkits are optional accelerators, not required setup
+
+## Next-week challenge
+
+1. Add `AGENTS.md` to one real project.
+2. Move one durable rule from a prompt into the repo.
+3. Add one review or handoff checklist.

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

@@ -0,0 +1,72 @@
+# Participant Resource Kit
+
+Krátká sada artefaktů, které si můžete odnést z Harness Lab do vlastního projektu.
+
+## 1. Začněte `AGENTS.md`
+
+Použijte tento základ:
+- `goal`
+- `context`
+- `constraints`
+- `done when`
+
+Výchozí šablona:
+- [`workshop-skill/template-agents.md`](../workshop-skill/template-agents.md)
+
+## 2. Přidejte jeden zdroj důvěry
+
+Vyberte si alespoň jeden:
+- build/test příkazy
+- RED test
+- tracer bullet
+- review checklist
+
+Když agent dělá větší kus práce, nestačí „rychle jsem to projel očima“.
+
+Checklist pro handoff:
+- [`workshop-skill/analyze-checklist.md`](../workshop-skill/analyze-checklist.md)
+
+## 3. Používejte malý workflow, ne chaos
+
+Doporučený základ:
+- `workshop` pro orientaci a další bezpečný krok
+- `/brainstorm`, když ještě není jasný scope nebo první slice
+- `/plan` před větší implementací
+- `/work` nebo jiný úzký implementační loop, když už víte co stavíte
+- test nebo jiný executable check před důležitou změnou
+- `/review` po větším kusu práce
+- `/compound` nebo krátká poznámka zapsaná přímo v repu, když objev udělá další práci levnější
+- průběžný úklid: build/test příkazy, omezení a handoff poznámky přesouvejte z chatu do repa
+
+## 4. Přesuňte jedno pravidlo z chatu do repa
+
+Typické kandidáty:
+- build/test příkazy
+- bezpečnostní omezení
+- definice hotovo
+- pravidlo pro handoff
+
+## 5. Pro UI práci držte bezpečný postup
+
+Výchozí pattern:
+- `agent exploration`
+- `Playwright regression`
+- `human review`
+
+Nenechávejte model jako výchozí volbu ovládat váš běžný přihlášený browser bez sandboxu a kontroly.
+
+## 6. Co si projít po workshopu
+
+- [`workshop-skill/reference.md`](../workshop-skill/reference.md)
+- [`workshop-skill/recap.md`](../workshop-skill/recap.md)
+- [`docs/learner-reference-gallery.md`](../docs/learner-reference-gallery.md)
+
+Poznámka:
+- `workshop` skill je garantovaný výchozí nástroj workshopu
+- další workflow skills a veřejné toolkity berte jako volitelné akcelerátory, ne povinný setup
+
+## Výzva na příští týden
+
+1. Přidejte `AGENTS.md` do jednoho reálného projektu.
+2. Přesuňte jedno trvalé pravidlo z promptu do repa.
+3. Přidejte jeden review nebo handoff checklist.

package/assets/workshop-bundle/workshop-blueprint/README.md

@@ -0,0 +1,55 @@
+# Workshop Blueprint
+
+This folder is the canonical public definition of how Harness Lab works.
+
+Use it for the reusable workshop method:
+
+- what the workshop is trying to teach
+- how the day is structured
+- what facilitators operate
+- what participants use
+- what is editable in the public repo versus only in the private runtime layer
+
+Do not use this folder for live event state. Real dates, rooms, rosters, checkpoint data, monitoring output, and facilitator-only operations belong in the private workshop-instance layer.
+
+## Recommended Reading Order
+
+1. [`day-structure.md`](day-structure.md)
+2. [`teaching-spine.md`](teaching-spine.md)
+3. [`operator-guide.md`](operator-guide.md)
+4. [`control-surfaces.md`](control-surfaces.md)
+5. [`edit-boundaries.md`](edit-boundaries.md)
+6. [`agenda.json`](agenda.json)
+
+## Blueprint Contents
+
+### Human-readable guidance
+
+- [`day-structure.md`](day-structure.md)
+  Explains the workshop arc, phase goals, and what should survive handoff.
+- [`teaching-spine.md`](teaching-spine.md)
+  Defines the habits, facilitator messages, and participant defaults the workshop should install.
+- [`operator-guide.md`](operator-guide.md)
+  Explains how a facilitator prepares, runs, and closes a workshop.
+- [`control-surfaces.md`](control-surfaces.md)
+  Defines participant surface, facilitator dashboard, facilitator skill, and the `harness` CLI as equal clients of one runtime model.
+- [`edit-boundaries.md`](edit-boundaries.md)
+  Explains what changes in the public repo, what changes only in runtime, and how learnings are published back deliberately.
+
+### Structured data
+
+- [`agenda.json`](agenda.json)
+  Public-readable workshop agenda summary and workshop metadata.
+
+## Related Runtime Documents
+
+- [`harness-cli-foundation.md`](../docs/harness-cli-foundation.md)
+
+The deeper runtime and maintainer docs such as blueprint import, publish-back flow, and workshop-instance runbooks remain part of the source repository and maintainer path. They are intentionally not part of the portable participant bundle.
+
+For maintainers working in the source repository, the runtime-facing structured agenda sources are:
+
+- `docs/workshop-content-language-architecture.md`
+- `dashboard/lib/workshop-blueprint-agenda.json`
+
+Treat those as maintainer/source-repo references, not as portable participant-bundle docs.

package/assets/workshop-bundle/workshop-blueprint/agenda.json

@@ -0,0 +1,70 @@
+{
+  "version": 1,
+  "blueprintId": "harness-lab-core-day",
+  "title": "Harness Lab",
+  "subtitle": "Workshop operating system pro práci s AI agenty",
+  "principles": [
+    "Mapa před pohybem",
+    "Ověření je hranice důvěry",
+    "Pište tak, aby další tým mohl pokračovat"
+  ],
+  "phases": [
+    {
+      "id": "opening",
+      "order": 1,
+      "label": "Úvod a naladění",
+      "startTime": "09:10",
+      "kind": "shared",
+      "goal": "Rámec dne: nejde o promptování, ale o repo a workflow, které přežijí handoff."
+    },
+    {
+      "id": "talk",
+      "order": 2,
+      "label": "Context is King",
+      "startTime": "09:40",
+      "kind": "shared",
+      "goal": "Krátký talk a porovnání přístupů. Krátká mapa v repu je silnější než prompt blob."
+    },
+    {
+      "id": "build-1",
+      "order": 3,
+      "label": "Build Phase 1",
+      "startTime": "10:30",
+      "kind": "team",
+      "goal": "Nejdřív udělejte z repa operating surface: krátké AGENTS.md, plán, build/test flow, první ověření a první reviewed output."
+    },
+    {
+      "id": "rotation",
+      "order": 4,
+      "label": "Rotace týmů",
+      "startTime": "13:30",
+      "kind": "team",
+      "goal": "Plný přesun lidí mezi stoly. Nejdřív čtěte a napište diagnózu, až pak měňte kód."
+    },
+    {
+      "id": "reveal",
+      "order": 5,
+      "label": "Reveal a reflexe",
+      "startTime": "15:45",
+      "kind": "shared",
+      "goal": "Co pomohlo pokračovat, co chybělo, a kterou bolest teď proměníme v lepší harness."
+    }
+  ],
+  "runtimeImport": {
+    "copiedIntoInstance": [
+      "title",
+      "subtitle",
+      "phases"
+    ],
+    "instanceLocalOnly": [
+      "currentPhaseId",
+      "continuationRevealed",
+      "realDate",
+      "venue",
+      "room",
+      "teamRegistry",
+      "checkpoints",
+      "monitoringSnapshots"
+    ]
+  }
+}