@harness-lab/cli 0.2.1 → 0.2.3

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

@@ -0,0 +1,80 @@
+# Workshop Reference
+
+## 4 working defaults for today
+
+- `Map before motion` - first make the repo a place people can navigate
+- `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
+
+## 4 elements of a good task
+
+- `Goal` - what exactly the agent should create or change
+- `Context` - which files, decisions, and surrounding facts matter for the task
+- `Constraints` - the rules, standards, and solution boundaries
+- `Done When` - how you will know the work is actually finished
+
+## Fast handoff checklist
+
+- Does `AGENTS.md` exist?
+- Is `AGENTS.md` a short map rather than an overgrown dump?
+- Are there build and test commands in the repo that another team can run?
+- Is it clear what already works, what is in progress, and what is still only an idea?
+- Is there a plan, runbook, or another document that helps the next team understand the intent?
+- Can you find what was actually verified?
+- Can a new team find the first safe move within a few minutes?
+
+## Recommended commands
+
+- Workshop skill in Codex: `$workshop ...`
+- Workshop skill in pi: `/skill:workshop`, then ask for `reference`, `setup`, `brief`, or another workshop action
+- If you do not know what the skill can do: `Codex: $workshop commands`
+- The workshop skill is the guaranteed default. Workflow skills and external toolkits are recommended accelerators, not mandatory bootstrap.
+- Workflow skills like `$brainstorm`, `$plan`, `$work`, `$test-writer`, `$review`, and `$compound` are described Codex-first in this workshop. In pi, treat them as optional parts of your own setup rather than the guaranteed default.
+- `Codex: $workshop reference` at the start of the day or after you lose orientation
+- `Codex: $workshop brief` when you need to re-anchor the task
+- `Codex: $workshop resources` when you want the participant kit and learner kit without searching the repo
+- `Codex: $workshop gallery` when you want more public docs, repos, and optional toolkits
+- `Codex: $workshop follow-up` when you are deciding what to keep after the workshop
+- `Codex: $brainstorm` when the scope is still unclear
+- `Codex: $plan` before larger implementation
+- `Codex: $work` once you have a plan and want to keep implementation in one line
+- `Codex: $test-writer` or your own RED test before implementation when you need to keep the agent inside real boundaries
+- `Codex: $review` after a larger slice of work
+- `Codex: $compound` when a learning, fix, or workflow rule is worth preserving as a durable repo-native artifact
+- `Codex: $workshop` for orientation during the day
+- `Codex: $workshop template` when the repo is missing baseline context
+- `Codex: $workshop analyze` before handoff or after rotation when you want to expose blind spots in the repo quickly
+
+## Recommended participant loop
+
+- `workshop` for orientation and the next safe move
+- `brainstorm` or directly `plan` when the scope is already clear
+- `work` against one verifiable goal
+- `review` before you trust a change
+- `compound` or a short runbook when something is worth preserving
+- ongoing cleanup work: move build and test commands, constraints, and handoff notes from chat into the repo
+
+## Tests as the trust boundary
+
+- The more work the agent does independently, the less “I skimmed it quickly” is enough.
+- If you let the agent write without tests, you often just accelerate unverified complexity.
+- A RED test, tracer bullet, or simple end-to-end check is often the fastest way to tell the agent what must actually be true.
+
+## Safe UI workflow
+
+- The default pattern is: `agent exploration -> Playwright regression -> human review`.
+- Let the agent inspect the UI, screenshots, and console quickly in an isolated local environment.
+- Once you find an important flow, turn it into a repeatable browser test.
+- Then have a human review the change. Tests protect against regression, but they do not decide meaning or trade-offs for you.
+- “Let the model drive my normal signed-in browser” is not the default recommendation. That belongs only in a sandboxed, intentionally constrained environment.
+
+## Quick reminder
+
+A good prompt is not enough. If the work should survive handoff, the context must live in the repo and verification must stay traceable.
+
+## Where to go after the workshop
+
+- Official docs, the OpenAI Harness Engineering article, and verified public skill repos are collected in [`docs/learner-reference-gallery.md`](../../../docs/learner-reference-gallery.md).
+- If you already use another workflow pack or toolkit, treat it as an extension on top of this foundation, not as a replacement for `AGENTS.md`, verification, and repo-native handoff.
+- If you do not want to search the repo, use `workshop resources`, `workshop gallery`, or `workshop follow-up` directly.

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

@@ -0,0 +1,84 @@
+# Workshop Setup
+
+## Goal
+
+By 10:30, you need one working path into Codex or pi. Not a perfect setup. A working path.
+
+The first goal after setup is not a feature. It is orientation:
+
+- open the repo
+- load the workshop guidance
+- create a short `AGENTS.md`
+- name the first verifiable step
+
+The guaranteed default for today is the `workshop` skill. Additional workflow skills or external toolkits are optional accelerators, not a requirement for participation.
+
+## Fastest choice
+
+- terminal-first, hackable multi-model setup: `pi`
+- macOS / Linux: `Codex CLI`
+- Windows or macOS: `Codex App`
+- if you get blocked: web fallback or pair with someone whose setup already works
+
+## pi
+
+1. Install `pi`:
+
+```bash
+npm install -g @mariozechner/pi-coding-agent
+```
+
+2. Sign in to the provider or account you want to use.
+3. Open the repository.
+4. Run `pi`.
+5. Load the workshop skill with `/skill:workshop` and ask for `setup`, `reference`, or `brief`.
+
+## Codex CLI
+
+1. Confirm that you have access to your Codex account.
+2. Install the CLI using your organization's setup flow.
+3. Sign in.
+4. Open the repository.
+5. Send the first meaningful prompt and confirm that you get a response.
+
+## Codex App
+
+1. Install the app.
+2. Sign in with the same account.
+3. Open the workshop repo or your team project.
+4. Send the first prompt.
+5. Confirm that you can continue without another blocker.
+
+## If something does not work
+
+- Do not spend 20 minutes debugging setup alone.
+- After 7 minutes of being blocked, switch to App, web fallback, or pairing.
+- If authentication fails, continue with someone at your table and come back to your own setup later.
+- If you are unsure about the next step, use `$workshop setup` in Codex. In pi, load `/skill:workshop` and ask for setup help. Or call a facilitator.
+
+## First 15 minutes after setup
+
+1. Open workshop reference:
+   - Codex: `$workshop reference`
+   - pi: `/skill:workshop`, then ask for `reference`
+   - if you want a fast overview of the skill surface: `Codex: $workshop commands`
+2. Open the brief:
+   - Codex: `$workshop brief`
+   - pi: `/skill:workshop`, then ask for `brief`
+3. Add a short `AGENTS.md`:
+   - Codex: `$workshop template`
+4. Name the first safe move:
+   - ideally through `plan`, or `brainstorm` if the scope is still unclear
+5. Add one executable check:
+   - a RED test, tracer bullet, or at least a clear review or checklist step
+6. If you want materials for later too:
+   - `Codex: $workshop resources`
+   - `Codex: $workshop gallery`
+   - `Codex: $workshop follow-up`
+
+## Done when
+
+- You can open the repo.
+- You can send a prompt.
+- You have one working path for using an agent during the workshop.
+- You know the first safe move in the repo after setup.

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

@@ -0,0 +1,22 @@
+# Workshop Recap
+
+## Co si odnést
+
+- Kontext není kosmetika. Je to pracovní systém.
+- `AGENTS.md`, skills a runbooky nejsou doplněk navíc. Jsou to nástroje, díky kterým tým drží směr.
+- Dobrý handoff poznáte podle toho, že nový tým začne pracovat bez ústního dovysvětlování.
+
+## Zkuste tento týden
+
+- Přidejte `AGENTS.md` do jednoho reálného projektu.
+- Doplňte build/test příkazy a sekci `Done When`.
+- Jedno trvalé pravidlo přesuňte z promptu do repa.
+- Po větší změně zkuste udělat krátký runbook pro dalšího člověka.
+
+## Váš závazek
+
+Vraťte se ke sticky note z části `A teď?` a převeďte ji na první konkrétní commit, pull request nebo task v repu.
+
+## Až si nebudete jistí
+
+Začněte jednoduše: napište, co chcete udělat, kde je kontext, jaká jsou omezení a podle čeho poznáte hotovo.

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

@@ -0,0 +1,80 @@
+# Workshop Reference
+
+## 4 pracovní výchozí body pro dnešek
+
+- `Mapa před pohybem` — nejdřív udělejte z repa místo, kde se dá orientovat
+- `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
+
+## 4 prvky dobrého zadání
+
+- `Cíl` — co má agent konkrétně vytvořit nebo změnit
+- `Kontext` — které soubory, rozhodnutí a souvislosti jsou pro úkol důležité
+- `Omezení` — pravidla, standardy a hranice řešení
+- `Hotovo když` — podle čeho poznáte, že je práce opravdu dokončená
+
+## Rychlý checklist pro handoff
+
+- Existuje `AGENTS.md`?
+- Je `AGENTS.md` krátká mapa, ne přerostlý dump?
+- Jsou v repu build/test příkazy, které umí spustit i další tým?
+- Je jasné, co už funguje, co je rozpracované a co je jen nápad?
+- Je v repu plan, runbook nebo jiný dokument, ze kterého další tým pochopí záměr?
+- Je dohledatelné, co bylo skutečně ověřeno?
+- Najde nový tým během pár minut první bezpečný krok?
+
+## Doporučené příkazy
+
+- Workshop skill v Codexu: `$workshop ...`
+- Workshop skill v pi: `/skill:workshop`, potom si řekněte o `reference`, `setup`, `brief` nebo jinou workshop akci
+- Když nevíte, co skill umí: `Codex: $workshop commands`
+- Workshop skill je garantovaný výchozí nástroj. Workflow skills a externí toolkity jsou doporučené akcelerátory, ne povinný bootstrap.
+- Workflow skills jako `$brainstorm`, `$plan`, `$work`, `$test-writer`, `$review` a `$compound` jsou v tomto workshopu popsané hlavně pro Codex. V pi je berte jako volitelnou součást vlastního setupu, ne jako garantovaný výchozí stav.
+- `Codex: $workshop reference` na začátku dne nebo po ztrátě orientace
+- `Codex: $workshop brief` když potřebujete znovu ukotvit zadání
+- `Codex: $workshop resources` když chcete účastnický kit a learner kit bez hledání v repu
+- `Codex: $workshop gallery` když chcete další veřejné docs, repozitáře a volitelné toolkity
+- `Codex: $workshop follow-up` když řešíte, co si odnést po workshopu
+- `Codex: $brainstorm` když ještě není jasné, co je nejrozumnější scope nebo slice
+- `Codex: $plan` před větší implementací
+- `Codex: $work` když už máte plan a chcete držet implementaci v jedné linii
+- `Codex: $test-writer` nebo vlastní RED test před implementací, když potřebujete držet agenta v mezích
+- `Codex: $review` po větším kusu práce
+- `Codex: $compound` když chcete převést nové zjištění, fix nebo workflow pravidlo do trvalého artefaktu v repu
+- `Codex: $workshop` pro orientaci během dne
+- `Codex: $workshop template` když repu chybí základní kontext
+- `Codex: $workshop analyze` před handoffem nebo po rotaci, když chcete rychle odhalit slepá místa v repu
+
+## Doporučený pracovní rytmus
+
+- `workshop` pro orientaci a další bezpečný krok
+- `brainstorm` nebo rovnou `plan`, když už je scope zřejmý
+- `work` proti jednomu ověřitelnému cíli
+- `review` před tím, než změně uvěříte
+- `compound` nebo krátký runbook, když něco stojí za zachování
+- průběžný úklid: build/test příkazy, omezení a handoff poznámky přesouvejte z chatu do repa
+
+## Testy jako hranice důvěry
+
+- Čím víc práce dělá agent samostatně, tím méně stačí „já jsem to rychle projel očima“.
+- Když necháte agenta psát bez testů, často jen urychlíte vznik neověřené složitosti.
+- RED test, tracer bullet nebo jednoduché e2e ověření je často nejrychlejší způsob, jak agentovi říct, co přesně má být pravda.
+
+## Bezpečný UI workflow
+
+- Výchozí pattern je: `agent exploration -> Playwright regression -> human review`.
+- Nechte agenta rychle projít UI, screenshoty a konzoli v izolovaném lokálním prostředí.
+- Jakmile najdete důležitý flow, převeďte ho do opakovatelného browser testu.
+- Nakonec změnu projděte člověkem. Testy chrání proti regresi, ale neřeší automaticky smysl a trade-offy.
+- „Nech model řídit můj běžný přihlášený browser“ není výchozí doporučení. To patří jen do sandboxovaného a záměrně omezeného prostředí.
+
+## Rychlá připomínka
+
+Dobrý prompt nestačí. Když má práce přežít handoff, musí být kontext uložený v repu a ověření musí být dohledatelné.
+
+## Kam dál po workshopu
+
+- Oficiální docs, OpenAI článek o Harness Engineering a ověřené veřejné skill repozitáře najdete v [`docs/learner-reference-gallery.md`](../docs/learner-reference-gallery.md).
+- Když už používáte další workflow pack nebo toolkit, berte ho jako rozšíření nad tímto základem, ne jako náhradu za `AGENTS.md`, ověřování a handoff opřený o repo.
+- Když nechcete hledat v repu, použijte přímo `workshop resources`, `workshop gallery` nebo `workshop follow-up`.

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

@@ -0,0 +1,84 @@
+# Workshop Setup
+
+## Cíl
+
+Do 10:30 potřebujete jednu funkční cestu do Codexu nebo pi. Ne perfektní setup. Funkční cestu.
+
+První cíl po setupu není feature. Je to orientace:
+
+- otevřít repo
+- načíst workshopové pokyny
+- vytvořit krátké `AGENTS.md`
+- pojmenovat první ověřitelný krok
+
+Garantovaný výchozí nástroj pro dnešek je `workshop` skill. Další workflow skills nebo externí toolkity jsou volitelné zrychlení, ne podmínka účasti.
+
+## Nejrychlejší volba
+
+- terminálový, hackovatelný multi-model setup: `pi`
+- macOS / Linux: `Codex CLI`
+- Windows nebo macOS: `Codex App`
+- Když se zaseknete: web fallback nebo pairing s někým, komu už setup běží
+
+## pi
+
+1. Nainstalujte `pi`:
+
+```bash
+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 `setup`, `reference` nebo `brief`.
+
+## Codex CLI
+
+1. Ověřte, že máte přístup ke svému Codex účtu.
+2. Nainstalujte CLI podle interního setup flow vaší organizace.
+3. Přihlaste se.
+4. Otevřete repozitář.
+5. Pošlete první smysluplný prompt a ověřte, že dostáváte odpověď.
+
+## Codex App
+
+1. Nainstalujte aplikaci.
+2. Přihlaste se stejným účtem.
+3. Otevřete workshop repo nebo týmový projekt.
+4. Pošlete první prompt.
+5. Ověřte, že můžete pokračovat bez další blokace.
+
+## Když něco nefunguje
+
+- Neztrácejte 20 minut sólo debugováním setupu.
+- Po 7 minutách blokace přepněte na App, web fallback nebo pairing.
+- Když nefunguje autentizace, pokračujte s někým od stolu a vraťte se k vlastnímu setupu později.
+- Když si nejste jistí dalším krokem, použijte v Codexu `$workshop setup`. V pi načtěte `/skill:workshop` a řekněte si o setup pomoc. Nebo si zavolejte facilitátora.
+
+## Prvních 15 minut po setupu
+
+1. Spusťte `workshop` reference:
+   - Codex: `$workshop reference`
+   - pi: `/skill:workshop`, potom si řekněte o `reference`
+   - když chcete rychlý přehled toho, co skill umí: `Codex: $workshop commands`
+2. Otevřete brief:
+   - Codex: `$workshop brief`
+   - pi: `/skill:workshop`, potom si řekněte o `brief`
+3. Doplňte krátké `AGENTS.md`:
+   - Codex: `$workshop template`
+4. Pojmenujte první bezpečný krok:
+   - ideálně přes `plan`, případně `brainstorm`, když scope ještě není jasný
+5. Přidejte jeden executable check:
+   - RED test, tracer bullet nebo aspoň jasný review/checklist krok
+6. Když chcete materiály i po workshopu:
+   - `Codex: $workshop resources`
+   - `Codex: $workshop gallery`
+   - `Codex: $workshop follow-up`
+
+## Hotovo když
+
+- Umíte otevřít repo.
+- Umíte poslat prompt.
+- Máte jednu funkční cestu, jak během workshopu pracovat s agentem.
+- Víte, jaký je první bezpečný krok v repu po setupu.

package/assets/workshop-bundle/workshop-skill/template-agents.md

@@ -0,0 +1,35 @@
+# AGENTS.md Starter
+
+Použijte to jako krátkou mapu repa. Ne jako encyklopedii. Když detail patří jinam, odkažte na konkrétní soubor místo kopírování dlouhého textu.
+
+Nejdůležitější pravidlo:
+- napište, kam má agent sáhnout jako první
+- napište, co je zdroj pravdy
+- napište, jak se práce ověří
+- když se text nafukuje, přidejte navazující dokument a odkažte na něj
+
+## Goal
+
+Popiš, co má agent v tomto repozitáři vytvořit nebo udržovat.
+
+## Context
+
+- Klíčové soubory a složky
+- Rozhodnutí, která už padla
+- Systémy nebo integrace, na které se navazuje
+- Kam má agent sáhnout jako první
+- Které docs nebo runbooky jsou zdroj pravdy
+
+## Constraints
+
+- Build/test/lint příkazy
+- Jazykové, architektonické a bezpečnostní standardy
+- Co agent nesmí dělat bez explicitního souhlasu
+- Public/private nebo auth boundary, pokud existuje
+
+## Done When
+
+- Jak poznáme, že je práce hotová
+- Jaké ověření musí proběhnout
+- Jak má vypadat handoff pro dalšího člověka nebo agenta
+- Jaký bude další bezpečný krok, pokud práce zůstane rozdělaná

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harness-lab/cli",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Participant-facing Harness Lab CLI for facilitator auth and workshop operations",
   "license": "UNLICENSED",
   "type": "module",
@@ -20,12 +20,13 @@
     "ai-agents"
   ],
   "engines": {
-    "node": ">=24"
+    "node": "22.x"
   },
   "publishConfig": {
     "access": "public"
   },
   "files": [
+    "assets",
     "bin",
     "src",
     "README.md"
@@ -37,6 +38,10 @@
     "chalk": "^5.6.2"
   },
   "scripts": {
-    "test": "node --test"
+    "preverify:workshop-bundle": "node ./scripts/sync-workshop-bundle.mjs --with-repo-bundle",
+    "prepack": "node ./scripts/sync-workshop-bundle.mjs",
+    "sync:workshop-bundle": "node ./scripts/sync-workshop-bundle.mjs --with-repo-bundle",
+    "verify:workshop-bundle": "node ./scripts/verify-workshop-bundle.mjs",
+    "test": "npm run verify:workshop-bundle && node --test"
   }
 }

package/src/run-cli.js

@@ -173,7 +173,7 @@ function printUsage(io, ui) {
     "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 [--force]",
+    "harness skill install [--target PATH] [--force]",
     "harness workshop status",
     "harness workshop archive [--notes TEXT]",
     "harness workshop create-instance [<instance-id>] [--template-id ID] [--event-title TEXT] [--city CITY]",
@@ -190,23 +190,30 @@ function printVersion(io) {
 
 async function handleSkillInstall(io, ui, deps, flags) {
   try {
-    const result = await installWorkshopSkill(deps.cwd ?? process.cwd(), { force: flags.force === true });
+    const result = await installWorkshopSkill(deps.cwd ?? process.cwd(), {
+      force: flags.force === true,
+      target: readStringFlag(flags, "target"),
+    });
     ui.heading("Workshop Skill");
-    if (result.mode === "already_bundled") {
-      ui.status("ok", "Harness Lab workshop skill is already bundled in this repo.");
+    if (result.mode === "already_current") {
+      ui.status("ok", "Harness Lab workshop skill is already current at the target path.");
+    } else if (result.mode === "refreshed") {
+      ui.status("ok", "Refreshed the installed Harness Lab workshop skill bundle.");
     } else {
       ui.status("ok", "Installed the Harness Lab workshop skill bundle.");
     }
+    ui.keyValue("Target", result.targetRoot);
     ui.keyValue("Location", result.installPath);
     ui.keyValue("Discovery", ".agents/skills");
+    ui.keyValue("Bundle source", result.sourceMode === "packaged_bundle" ? "packaged portable bundle" : "source checkout fallback");
     ui.blank();
     ui.section("Next steps");
     ui.numberedList([
-      "Open Codex or pi in this repo.",
-      "Start with the workshop reference card.",
-      "Codex: `$workshop reference`.",
-      "pi: `/skill:workshop`, then ask for the workshop reference card.",
-      "Need setup help? Codex: `$workshop setup`. pi: `/skill:workshop`, then ask for setup help.",
+      "Open Codex or pi in the target repo.",
+      "Start with the workshop command menu.",
+      "Codex: `$workshop commands`.",
+      "pi: `/skill:workshop`, then ask for the workshop commands.",
+      "Next: `$workshop reference`, `$workshop brief`, and `$workshop resources`.",
     ]);
     return 0;
   } catch (error) {

package/src/skill-install.js

@@ -1,5 +1,16 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import {
+  createWorkshopBundleManifestFromDirectory,
+  createWorkshopBundleManifestFromSource,
+  createWorkshopBundleFromSource,
+  getInstalledSkillPath,
+  getPackagedWorkshopBundlePath,
+  getRepoWorkshopSourceRoot,
+  pathExists,
+  readWorkshopBundleManifest,
+  WORKSHOP_SKILL_NAME,
+} from "./workshop-bundle.js";
 
 export class SkillInstallError extends Error {
   constructor(message, options = {}) {
@@ -9,94 +20,124 @@ export class SkillInstallError extends Error {
   }
 }
 
-const SKILL_NAME = "harness-lab-workshop";
+async function resolveBundleSource() {
+  const packagedBundlePath = getPackagedWorkshopBundlePath();
+  if (await pathExists(path.join(packagedBundlePath, "SKILL.md"))) {
+    return {
+      mode: "packaged_bundle",
+      sourcePath: packagedBundlePath,
+      sourceRoot: packagedBundlePath,
+    };
+  }
 
-async function pathExists(targetPath) {
-  try {
-    await fs.access(targetPath);
-    return true;
-  } catch {
-    return false;
+  const repoSourceRoot = getRepoWorkshopSourceRoot();
+  if (await pathExists(path.join(repoSourceRoot, "workshop-skill", "SKILL.md"))) {
+    return {
+      mode: "repo_source",
+      sourcePath: repoSourceRoot,
+      sourceRoot: repoSourceRoot,
+    };
   }
+
+  return null;
 }
 
-export async function findHarnessLabRepoRoot(startDir) {
-  let currentDir = path.resolve(startDir);
+async function ensureDirectory(targetPath) {
+  await fs.mkdir(targetPath, { recursive: true });
+  const stat = await fs.stat(targetPath);
+  if (!stat.isDirectory()) {
+    throw new SkillInstallError(`Install target is not a directory: ${targetPath}`, {
+      code: "invalid_target",
+    });
+  }
+}
 
-  while (true) {
-    if (await pathExists(path.join(currentDir, "workshop-skill", "SKILL.md"))) {
-      return currentDir;
-    }
+async function hasInstalledSkill(targetRoot) {
+  return pathExists(path.join(getInstalledSkillPath(targetRoot), "SKILL.md"));
+}
 
-    const parentDir = path.dirname(currentDir);
-    if (parentDir === currentDir) {
-      return null;
+async function getSourceBundleManifest(resolvedBundle) {
+  if (resolvedBundle.mode === "packaged_bundle") {
+    const manifest = await readWorkshopBundleManifest(resolvedBundle.sourcePath);
+    if (manifest) {
+      return manifest;
     }
 
-    currentDir = parentDir;
+    return createWorkshopBundleManifestFromDirectory(resolvedBundle.sourcePath);
   }
-}
 
-export function getInstalledSkillPath(repoRoot) {
-  return path.join(repoRoot, ".agents", "skills", SKILL_NAME);
+  return createWorkshopBundleManifestFromSource(resolvedBundle.sourceRoot);
 }
 
-async function hasBundledRepoSkill(repoRoot) {
-  return pathExists(path.join(getInstalledSkillPath(repoRoot), "SKILL.md"));
+async function installFromResolvedBundle(resolvedBundle, installPath) {
+  if (resolvedBundle.mode === "packaged_bundle") {
+    await fs.cp(resolvedBundle.sourcePath, installPath, { recursive: true });
+    return;
+  }
+
+  await createWorkshopBundleFromSource(resolvedBundle.sourceRoot, installPath);
 }
 
 export async function installWorkshopSkill(startDir, options = {}) {
-  const repoRoot = await findHarnessLabRepoRoot(startDir);
-  if (!repoRoot) {
+  const resolvedBundle = await resolveBundleSource();
+  if (!resolvedBundle) {
     throw new SkillInstallError(
-      "Harness CLI could not find `workshop-skill/SKILL.md`. Run this command inside a Harness Lab repo checkout.",
-      { code: "repo_not_found" },
+      "Harness CLI could not find a portable workshop bundle. Reinstall `@harness-lab/cli` or run from a Harness Lab source checkout.",
+      { code: "bundle_not_found" },
     );
   }
 
-  const installPath = getInstalledSkillPath(repoRoot);
-  const bundledRepoSkill = await hasBundledRepoSkill(repoRoot);
+  const targetRoot = path.resolve(startDir, options.target ?? ".");
+  await ensureDirectory(targetRoot);
+
+  const installPath = getInstalledSkillPath(targetRoot);
+  const existingInstall = await hasInstalledSkill(targetRoot);
+  const sourceManifest = await getSourceBundleManifest(resolvedBundle);
+
+  if (existingInstall && options.force !== true) {
+    const installedManifest = await createWorkshopBundleManifestFromDirectory(installPath);
+    if (installedManifest.contentHash === sourceManifest.contentHash) {
+      return {
+        installPath,
+        skillName: WORKSHOP_SKILL_NAME,
+        mode: "already_current",
+        sourceMode: resolvedBundle.mode,
+        targetRoot,
+      };
+    }
+
+    await fs.rm(installPath, { recursive: true, force: true });
 
-  if (bundledRepoSkill) {
     return {
-      repoRoot,
-      installPath,
-      skillName: SKILL_NAME,
-      mode: "already_bundled",
+      ...(await installFreshBundle(resolvedBundle, installPath, targetRoot)),
+      mode: "refreshed",
     };
   }
 
-  if ((await pathExists(installPath)) && options.force !== true) {
-    throw new SkillInstallError(
-      `Skill already installed at ${installPath}. Re-run with --force to replace it.`,
-      { code: "already_installed" },
-    );
+  if (existingInstall && options.force === true) {
+    await fs.rm(installPath, { recursive: true, force: true });
   }
 
-  if (options.force === true) {
-    await fs.rm(installPath, { recursive: true, force: true });
+  const result = await installFreshBundle(resolvedBundle, installPath, targetRoot);
+  if (existingInstall && options.force === true) {
+    return {
+      ...result,
+      mode: "refreshed",
+    };
   }
 
-  await fs.mkdir(installPath, { recursive: true });
-  await fs.cp(path.join(repoRoot, "workshop-skill"), path.join(installPath, "workshop-skill"), { recursive: true });
-  await fs.cp(path.join(repoRoot, "content"), path.join(installPath, "content"), { recursive: true });
-  await fs.cp(path.join(repoRoot, "workshop-blueprint"), path.join(installPath, "workshop-blueprint"), { recursive: true });
-  await fs.rm(path.join(installPath, "workshop-skill", "SKILL.md"), { force: true });
-  await fs.mkdir(path.join(installPath, "docs"), { recursive: true });
-  await fs.copyFile(path.join(repoRoot, "workshop-skill", "SKILL.md"), path.join(installPath, "SKILL.md"));
-  await fs.copyFile(
-    path.join(repoRoot, "docs", "workshop-event-context-contract.md"),
-    path.join(installPath, "docs", "workshop-event-context-contract.md"),
-  );
-  await fs.copyFile(
-    path.join(repoRoot, "docs", "harness-cli-foundation.md"),
-    path.join(installPath, "docs", "harness-cli-foundation.md"),
-  );
+  return result;
+}
+
+async function installFreshBundle(resolvedBundle, installPath, targetRoot) {
+  await fs.mkdir(path.dirname(installPath), { recursive: true });
+  await installFromResolvedBundle(resolvedBundle, installPath);
 
   return {
-    repoRoot,
     installPath,
-    skillName: SKILL_NAME,
+    skillName: WORKSHOP_SKILL_NAME,
     mode: "installed",
+    sourceMode: resolvedBundle.mode,
+    targetRoot,
   };
 }