@osfactory/har 0.1.1

package/dist/prompts/system-authoring.md

@@ -0,0 +1,104 @@
+# Harness Authoring Agent
+
+You are a harness authoring agent. Your job is to adapt a copied `.har/` boilerplate to match a specific software repository, so AI coding agents can run the project in isolated development environments.
+
+## Your Mission
+
+Explore the target repository, then edit files in `.har/` directly to make the harness runnable for this project. When done, call `finishAuthoring` with a summary.
+
+**Do NOT** create a YAML config or JSON mapping file for runtime behavior. Put behavior directly in the harness scripts and templates.
+
+## Discovery for coding agents
+
+Coding agents discover the harness through two files:
+
+1. **`AGENT.md`** (repo root) — short pointer, always read first. Propose via `proposeAgentMd` — never write it directly.
+2. **`.har/README.md`** — full index of what's in the harness. **You must maintain this** on every init/maintain run.
+
+## Tools Available
+
+**Repository exploration:**
+- `readRepoFile(path)` — read files from the target repo
+- `listRepoDir(path)` — list repo directories
+
+**Harness editing (.har/):**
+- `readHarnessFile(path)` — read files in .har/
+- `listHarnessDir(path)` — list .har/ contents
+- `writeHarnessFile(path, content)` — full file rewrite
+- `editHarnessFile(path, old_string, new_string)` — targeted edit
+- `deleteHarnessFile(path)` — remove unnecessary files
+
+**Root agent guide:**
+- `proposeAgentMd(content, rationale)` — propose AGENT.md changes for user approval
+
+**Other:**
+- `ask(question, options?)` — ask user when genuinely ambiguous
+- `finishAuthoring(summary, language?, packageManager?, database?)` — submit when done
+
+## Primary application & shared services (decide FIRST)
+
+Identify the **primary application** — the ONE app coding agents modify and run per-slot. Everything else runs once, shared by all slots:
+
+- **Primary app** → `HARNESS_PRIMARY_APP` in `harness.env`; only its dev processes go in `ecosystem.agent.template.cjs`.
+- **External dependencies** (database, cache, mail, ...) → services in `docker-compose.agent.yml`, listed in `HARNESS_INFRA_SERVICES` (e.g. `"db redis"`), started once by `setup-infra.sh` on fixed ports. Delete unused menu services.
+- **Internal supporting services** of a monolith/monorepo (needed but not modified) → shared as compose services, or PM2 processes in optional `.har/ecosystem.shared.config.cjs` (`har-shared-<name>`, auto-started by `setup-infra.sh`). Never per-slot.
+
+## Files to adapt
+
+### `.har/README.md` (required — maintain every run)
+Clear index of the harness: what each file does, quick start, architecture, how to maintain.
+Update when anything in the harness changes.
+
+### `.har/harness.env`
+Primary app, ports, `HARNESS_INFRA_SERVICES`, migrate/seed commands, health check path.
+
+### `.har/ecosystem.agent.template.cjs`
+PM2 processes for the primary application only, matching how it runs in dev.
+
+### `.har/verify.sh`
+Real typecheck, lint, test, and health check commands — replace all TODOs.
+
+### `.har/CLAUDE.agent.md`
+Detailed agent instructions: commands, credentials, architecture, definition of done.
+
+### `.har/env.template`, `setup-infra.sh`, `docker-compose.agent.yml`
+As needed for the project's infra.
+
+### `AGENT.md` (repo root — via proposeAgentMd only)
+Short pointer document. Structure:
+- Link to `.har/README.md` and `.har/CLAUDE.agent.md`
+- State plainly: **the harness is how you run this project** — to see the app live (manual testing, browser, screenshots), `launch` a slot; never hand-roll docker/dev-server startup; fix or report a failing harness command instead of working around it
+- Preferred: HAR MCP tools or `har env launch/verify/teardown`
+- Fallback: `./.har/launch.sh`, `./.har/verify.sh`, etc. (when CLI is not installed)
+- Rules (no hardcoded ports, use agent-cli.sh)
+- Project-specific notes section
+
+If AGENT.md already exists, read it first and propose minimal updates — don't replace unrelated content.
+
+### Monorepos / multiple harnesses
+If the repository contains more than one project or `.har` harness (check for `.har/` directories above or below the one you are adapting):
+- Propose a **"Harnesses in this repo"** table for the ROOT `AGENT.md` — one row per harness: path, profile, what it runs, launch/verify commands, link to its `.har/README.md`. Lead with "pick the harness that owns the files you are changing."
+- Keep a small `AGENT.md` / `CLAUDE.md` pointer inside each project directory (local discovery), back-linking to the root index.
+- One Cursor rule at repo root listing all harnesses — never one rule per project.
+
+## Port allocation
+
+Agents run in parallel on configurable slot ids. Ports: `BASE + (AGENT_ID × 10)`.
+
+Set slot limits in `.har/stages.json` (`agentSlots`) and `.har/harness.env` (`HARNESS_AGENT_SLOT_MIN` / `HARNESS_AGENT_SLOT_MAX`) based on machine capacity.
+
+## Rules
+
+1. **Edit .har/ files directly** — no YAML runtime config
+2. **Always update README.md** in .har/ to reflect current harness state
+3. **Always call proposeAgentMd** with AGENT.md content (create or update proposal)
+4. **Reuse existing project commands** from package.json, Makefile, etc.
+5. **Replace all TODO placeholders**
+6. **Do not edit manifest.json** — managed by har CLI
+7. **Run the cleanup checklist before finishing** — keep strictly what this repository needs:
+   - compose file has only used services; `HARNESS_INFRA_SERVICES` matches exactly
+   - `env.template` has no blocks for removed services; no dead branches left in scripts
+   - unused harness files deleted (`deleteHarnessFile`), e.g. `attach.sh` when unused
+   - `.har/README.md` file table matches the files that actually exist
+   - `CLAUDE.agent.md` shows only real URLs/ports and commands that run
+8. **Call finishAuthoring** when complete

package/dist/templates/AGENT.md.template

@@ -0,0 +1,40 @@
+# Agent Environment
+
+This repository uses a **`.har/` harness** for isolated agent development.
+
+The harness is not just a verification gate — it is **how you run this project**.
+To see the app live (manual testing, browser sessions, screenshots, driving the UI),
+use `har env launch <id>` or `./.har/launch.sh <id>`. It already encodes database
+setup, ports, env vars, and process management — never hand-roll `docker` / dev-server
+startup, and never claim a task "can't be verified live" without launching a slot first.
+
+If a harness command fails, fix the harness (or report the failure) — do not quietly
+fall back to ad-hoc commands.
+
+## Cursor IDE
+
+If `.cursor/rules/har-workflow.mdc` exists, the harness workflow (read-before-change, verify-before-done)
+is injected into every Cursor agent session automatically.
+Run `har env init` or `har env maintain` to create or refresh it.
+
+## Start here (all IDEs / first time)
+
+1. [`.har/README.md`](.har/README.md) — stages, verification, how to run
+2. [`stages.json`](.har/stages.json) — machine-readable stage registry
+3. [`.har/CLAUDE.agent.md`](.har/CLAUDE.agent.md) — definition of done (after `launch`)
+
+## Harness workflow
+
+Prefer **HAR MCP tools** (Cursor) or **`har env launch/verify/teardown`** — they persist run history under `.har/runs/`.
+Use `./.har/*.sh` only when the CLI is not installed.
+
+## Commit gate
+
+Full verify records the exact code state it validated (git tree hash in `.har/validations/`).
+If the commit gate is installed (`har hooks install`), commits of unverified changes are blocked:
+run `har env verify <id> --full` after your last edit, then `git add -A` and commit — any edit
+after verify invalidates the batch and requires a re-run. Do not bypass with `--no-verify`.
+
+## Project-specific notes
+
+<!-- Adapt when customizing the harness (see .har/ADAPT-PROMPT.md) -->

package/dist/templates/CLAUDE.md.template

@@ -0,0 +1,5 @@
+# __PROJECT_DISPLAY_NAME__
+
+Read [AGENT.md](./AGENT.md) and [.har/README.md](./.har/README.md) before changing this project.
+Harness workflow is enforced automatically in Cursor via `.cursor/rules/har-workflow.mdc`
+(created by `har env init`).

package/dist/templates/adaptation-prompt-init.md

@@ -0,0 +1,124 @@
+Adapt the `.har/` harness in this repository so AI coding agents can run the project in isolated development environments.
+
+## Your mission
+
+Explore this repository, then edit files in `.har/` directly to make the harness runnable for this project.
+
+**Do NOT** create a YAML config or JSON mapping file for runtime behavior. Put behavior directly in the harness scripts and templates.
+
+## Profile: {{PROFILE}}
+
+{{PROFILE_HINT}}
+
+## Step 1 — Explore the repository
+
+Read key files to understand the stack and how developers run the project today:
+
+- Root manifests (`package.json`, `go.mod`, `pyproject.toml`, `Cargo.toml`, `Makefile`, etc.)
+- Docker / compose files, CI config, README
+- Existing test, lint, and build commands
+
+## Step 2 — Adapt `.har/` files
+
+Replace all TODO placeholders. Key files:
+
+### Primary application & shared services (decide this FIRST)
+
+Identify the **primary application** — the ONE app coding agents will modify and run per-slot. Everything else is shared and runs once for all slots:
+
+1. **Primary app** → set `HARNESS_PRIMARY_APP` in `harness.env`; wire ONLY its dev processes into `ecosystem.agent.template.cjs` (a primary app may still need several processes, e.g. api + frontend of the same app).
+2. **External dependencies** (database, cache, queue, mail, ...) → keep/add them as services in `docker-compose.agent.yml`, delete the menu entries the project doesn't use, and list the needed ones in `HARNESS_INFRA_SERVICES` (e.g. `"db redis"`). They start once via `setup-infra.sh` on fixed ports and serve every slot.
+3. **Internal supporting services** (a monolith/monorepo's other services the agent depends on but is not changing) → do NOT start them per-slot. Run them once and shared: as compose services in `docker-compose.agent.yml`, or as PM2 processes in `.har/ecosystem.shared.config.cjs` (processes named `har-shared-<name>`, started automatically by `setup-infra.sh` when the file exists). Point the primary app at them through `env.template`.
+
+Simple single-app repos need none of the extra machinery: one primary app, usually one `db` in `HARNESS_INFRA_SERVICES`, no shared ecosystem file.
+
+### `.har/README.md` (required)
+Clear index of the harness: what each file does, quick start, architecture, how to maintain. Update when anything in the harness changes.
+
+### `.har/harness.env`
+Primary app, ports, `HARNESS_INFRA_SERVICES`, migrate/seed commands, health check path.
+
+### `.har/ecosystem.agent.template.cjs` (default profile only)
+PM2 processes for the primary application only, matching how it runs in dev. Skip entirely for the CLI profile.
+
+### `.har/verify.sh`
+Real typecheck, lint, test, and health check commands — replace all TODOs.
+
+### Optional Playwright stage
+If the user ran `har env add-stage playwright` (or `@playwright/test` is in package.json):
+
+- Adapt `tests/**` selectors and API paths for this stack
+- Ensure `HARNESS_HEALTH_CHECK_PATH` matches the app health route used in API smoke tests
+- `verify --full` runs `browser-e2e` automatically when `.har/stages/browser-e2e.sh` exists
+- Do not wire Playwright into quick `verify` unless the team wants e2e on every loop
+
+See `.har/stages/PLAYWRIGHT.md` when present.
+
+### `.har/CLAUDE.agent.md`
+Detailed agent instructions: commands, credentials, architecture, definition of done.
+
+### `.har/env.template`, `setup-infra.sh`, `docker-compose.agent.yml`
+Adapt as needed for the project's infra.
+
+### Port allocation
+Agents run in parallel on configurable slot ids. Ports: `BASE + (AGENT_ID × 10)`.
+Set slot limits in `.har/stages.json` (`agentSlots`) and `.har/harness.env` (`HARNESS_AGENT_SLOT_MIN` / `HARNESS_AGENT_SLOT_MAX`) based on machine capacity.
+
+### Git worktree
+`launch.sh` creates an isolated worktree at `~/worktrees/<project>-agent-<id>` by default (`HARNESS_USE_WORKTREE=true`). Agents should commit from that worktree, not the main checkout.
+
+## Step 3 — Update repo-root `AGENT.md`
+
+Coding agents discover the harness through two files:
+
+1. **`AGENT.md`** (repo root) — short pointer, always read first
+2. **`.har/README.md`** — full index of what's in the harness
+
+If **no `AGENT.md` exists**, create one at the repo root using this structure:
+
+- Link to `.har/README.md` and `.har/CLAUDE.agent.md`
+- State plainly: **the harness is how you run this project** — to see the app live (manual testing, browser, screenshots), `launch` a slot; never hand-roll docker/dev-server startup, and never work around a failing harness command with ad-hoc setup (fix or report it instead)
+- Preferred commands: HAR MCP tools or `har env launch/verify/teardown` (persists run history)
+- Shell fallback: `./.har/launch.sh`, `./.har/verify.sh`, `./.har/teardown.sh` (when CLI is not installed)
+- Rules (no hardcoded ports, use `./.har/agent-cli.sh`, do not touch other agents' resources)
+- Project-specific notes (stack, credentials, definition of done)
+
+If **`AGENT.md` already exists**, add or update a concise **HAR / agent environment** section — do not replace unrelated content.
+
+### Monorepos / multiple harnesses
+
+If this repository contains **more than one project or `.har` harness** (check for `.har/` directories above or below this one):
+
+- Maintain a **"Harnesses in this repo"** table in the ROOT `AGENT.md` — one row per harness: path, profile, what it runs, launch/verify commands, link to its `.har/README.md`. Lead with "pick the harness that owns the files you are changing."
+- Keep a small `AGENT.md` (and `CLAUDE.md` pointer) **inside each project directory** for local discovery, with a back-link to the root index.
+- Keep ONE Cursor rule at the repo root (`.cursor/rules/har-workflow.mdc`) listing all harnesses — not one rule per project.
+
+Include a **Run history** subsection:
+
+- `./.har/*.sh` does not write run records
+- `har env …` and MCP write to `.har/runs/YYYY-MM-DD/HH-mm-ss_<stageId>_agent-<id>.json`
+- With worktrees, code runs in the worktree but run JSON lives in the main checkout `.har/runs/`
+- Document MCP/CLI as the preferred agent interface; shell scripts as fallback
+
+## Step 4 — Cleanup checklist (required)
+
+The boilerplate ships more than any single repository needs. Strip it down to strictly what this project uses — leftover template content confuses agents and rots. Verify each item:
+
+- [ ] `docker-compose.agent.yml` contains ONLY services this project uses (menu entries and their volumes deleted); `HARNESS_INFRA_SERVICES` lists exactly those services
+- [ ] `env.template` has no env blocks for removed services (MinIO/S3, mailpit, headless browser, ...) and no vars the app never reads
+- [ ] `harness.env` has no leftover config for features not in use (e.g. `HARNESS_TEMPLATE_DB` and migrate/seed commands when there is no database)
+- [ ] Scripts (`launch.sh`, `setup-infra.sh`, `teardown.sh`, `agent-cli.sh`, `verify.sh`) contain no dead branches for services this project will never enable — prune, don't comment out
+- [ ] No `TODO` placeholders remain anywhere in `.har/`
+- [ ] Unused harness files are deleted (e.g. `attach.sh` when tmux isn't part of the workflow; CLI profile: `ecosystem.agent.template.cjs`, `env.template`)
+- [ ] `.har/README.md` file table lists exactly the files that exist — no more, no less
+- [ ] `.har/CLAUDE.agent.md` shows only real URLs/ports/credentials (e.g. drop the Frontend row for an API-only project) and project commands that actually run
+
+## Rules
+
+1. Edit `.har/` files directly — no YAML runtime config
+2. Always update `.har/README.md` to reflect current harness state
+3. Reuse existing project commands from package.json, Makefile, CI, etc.
+4. Replace all TODO placeholders
+5. Do not edit `.har/manifest.json` — managed by the har CLI
+
+When finished, summarize what you changed, confirm verification commands (`har env verify 1 --full` or `./.har/verify.sh 1 --full`) are correct for this stack, and record the adaptation with `har env maintain --finalize --summary "<what changed>"`.

package/dist/templates/adaptation-prompt-maintain.md

@@ -0,0 +1,73 @@
+Update the `.har/` harness in this repository to reflect current codebase changes.
+
+## Your mission
+
+The harness already exists. Inspect what changed in the repo since the harness was last updated, then edit `.har/` files so coding agents can still run and verify the project correctly.
+
+**Do NOT** create a YAML config or JSON mapping file for runtime behavior. Put behavior directly in the harness scripts and templates.
+
+## Step 1 — Inspect the repository
+
+Compare the current repo against the existing harness:
+
+- Root manifests, CI, Docker, README
+- New or changed test, lint, build, migrate, or seed commands
+- New services, ports, or environment variables
+- Run `har env maintain` drift report (generator version, template checksum mismatches)
+
+## Step 2 — Update `.har/` files
+
+Prefer targeted edits over full rewrites. Key files to review:
+
+### `.har/README.md` (required)
+Keep this accurate — it is the harness index. Update whenever scripts, stages, or workflow change.
+
+### `.har/harness.env`, `verify.sh`, `ecosystem.agent.template.cjs`, `CLAUDE.agent.md`
+Align commands and instructions with the current stack.
+
+### `.har/env.template`, `setup-infra.sh`, `docker-compose.agent.yml`
+Update only if infra changed.
+
+### HAR platform upgrades checklist
+
+When upgrading `@osfactory/har` or adopting new harness standards:
+
+**Generator 0.4.0 — primary app & shared infra services:**
+
+- Migrate `harness.env` from boolean `HARNESS_INFRA_*` flags to the `HARNESS_INFRA_SERVICES` list (space-separated compose service names, e.g. `"db mailpit"`) and add the `har_infra_enabled()` helper — copy both from the bundled template. Update every script that still tests `HARNESS_INFRA_POSTGRES`-style flags (`setup-infra.sh`, `launch.sh`, `teardown.sh`, `agent-cli.sh`) to use `har_infra_enabled <service>`.
+- Set `HARNESS_PRIMARY_APP` in `harness.env` to the ONE app agents modify. Ensure `ecosystem.agent.template.cjs` starts only that app's processes. Move any other in-repo services agents depend on but don't change to shared infra: compose services in `docker-compose.agent.yml` or an optional `.har/ecosystem.shared.config.cjs` (processes `har-shared-<name>`; `setup-infra.sh` starts it when present — resync `setup-infra.sh` from the template to get this hook).
+- Prune `docker-compose.agent.yml` to only the services this project uses; delete unused menu services and volumes.
+- Run the **cleanup checklist**: no TODO placeholders, no env blocks for removed services in `env.template`, no dead script branches, `.har/README.md` file table matches the actual files, `CLAUDE.agent.md` shows only real URLs/ports and commands, unused files deleted.
+
+**Earlier standards:**
+
+- Add **Run history** section to repo-root `AGENT.md` if missing (shell vs `har env`, worktree vs runs location)
+- Ensure `AGENT.md` / `CLAUDE.agent.md` frame the harness as **how you run the project** (launch for manual testing/browser/screenshots; fix — don't work around — failing harness commands)
+- Ensure `launch.sh` installs dependencies in fresh worktrees and resolves the project subdirectory inside the worktree (`git rev-parse --show-prefix`) for monorepos
+- If the repo has multiple projects/harnesses, maintain the **"Harnesses in this repo"** table in root `AGENT.md`, per-project pointer docs, and a single root Cursor rule
+- Remove dead boilerplate files (CLI profile: `ecosystem.agent.template.cjs`, `env.template`, `attach.sh`)
+- Align `launch.sh` / `harness.env` with worktree-default standard (`HARNESS_USE_WORKTREE=true`)
+- Do **not** blindly overwrite customized `verify.sh`
+
+## Step 3 — Refresh repo-root `AGENT.md`
+
+If harness commands, rules, or workflow changed, update the **HAR / agent environment** section in repo-root `AGENT.md`:
+
+- Links to `.har/README.md` and `.har/CLAUDE.agent.md`
+- Preferred: HAR MCP tools or `har env …` (persists run history)
+- Fallback: `./.har/*` shell scripts (when CLI is not installed)
+- Run history rules (shell vs CLI/MCP, worktree vs `.har/runs/` location)
+- Agent rules (ports, agent-cli.sh, isolation)
+- Project-specific notes
+
+If `AGENT.md` does not mention HAR yet, add a concise section. If it already has a HAR section, update it minimally — do not replace unrelated content.
+
+## Rules
+
+1. Prefer targeted edits — keep working harness behavior where still valid
+2. Always update `.har/README.md` when anything in the harness changes
+3. Reuse existing project commands from package.json, Makefile, CI, etc.
+4. Replace any remaining TODO placeholders
+5. Do not edit `.har/manifest.json` — managed by the har CLI
+
+When finished, summarize what you changed, confirm verification commands still match the repo, and record the adaptation with `har env maintain --finalize --summary "<what changed>"` (updates the manifest's generator version and checksums).

package/dist/templates/cursor-rule.mdc.template

@@ -0,0 +1,101 @@
+---
+description: HAR harness workflow — read before change, verify before done
+alwaysApply: true
+---
+
+# HAR Harness Workflow
+
+This repository uses a `.har/` agent harness. Follow this workflow on every change.
+
+The harness is **how you run the project**, not only how you verify it. To see the app
+live (manual testing, browser sessions, screenshots), launch a slot — never hand-roll
+docker/dev-server startup; the harness already encodes DB setup, ports, and env.
+If a harness command fails, fix the harness or surface the failure — do not quietly
+work around it with ad-hoc commands.
+
+## Before making changes
+
+1. **Launch your slot FIRST — before editing any file.** Use `har_launch_environment` with `agentId: 1` (MCP), `har env launch 1`, or `./.har/launch.sh 1`. Launch always creates a **fresh session worktree** from the current HEAD and returns its **work dir**.
+2. **Make ALL file edits under the returned work dir — never in the main checkout.** The work dir looks like `~/worktrees/<base-branch>-<sha4>-har-agent-<id>-<rand4>` (recorded in `.har/slots/agent-<id>.json`). Edits there hot-reload in the running slot; use `./.har/agent-cli.sh <id> restart` if a change doesn't take.
+3. Read [AGENT.md](./AGENT.md) at the repo root
+4. Read [.har/README.md](./.har/README.md) and [.har/stages.json](./.har/stages.json)
+5. After launch, read [.har/CLAUDE.agent.md](./.har/CLAUDE.agent.md) for slot URLs and definition of done
+
+Relaunching a slot **replaces** its previous session (the old branch is kept). Replacement requires explicit confirmation (`--replace`, `confirmReplace=true`, or an interactive prompt). If the previous session has uncommitted changes, you must also pass `force`/`--force` after **explicit user approval** — never autonomously.
+
+### Slot safety (read before launch)
+
+- **One slot ≈ one task** — do not share slot 1 across unrelated chats; use slot 2+ for parallel work.
+- **Call `har_get_status` / `./.har/agent-cli.sh <id> status`** before launch when a slot may be occupied.
+- **Never** set `force`/`confirmReplace` without the user explicitly approving replacement.
+- **Commit early and often** in the session worktree — teardown keeps the branch, not uncommitted work.
+- **Gitignored paths are ephemeral** (`state/`, `runs/`, local clones) — they are lost when the worktree is removed.
+- Optional: set `HAR_SESSION_PURPOSE=label` or `--purpose=label` on launch so occupied-slot warnings show what you were doing.
+
+<!-- Monorepo: if this repository contains multiple .har harnesses, list them here
+     and pick by the files you are changing. Example:
+
+## Harnesses in this repo
+
+| Path | Runs | Use when changing |
+|------|------|-------------------|
+| `.har/` | backend + frontend | `src/`, `packages/` |
+| `apps/admin/.har/` | admin dashboard | `apps/admin/` |
+
+Run harness commands from the directory that owns the harness (e.g. `cd apps/admin`).
+-->
+
+
+## After making changes
+
+Validate through the harness — do not skip verification or substitute ad-hoc npm/test commands.
+
+### 1. HAR MCP (preferred in Cursor when `.cursor/mcp.json` has the har server)
+
+- `har_run_verification` with `agentId: 1` — fast loop (typecheck + unit tests)
+- `har_run_verification` with `agentId: 1, full: true` — required before declaring work done
+- `har_complete_environment` with `agentId: 1` — when the work is done: full verify + validation record + teardown, **keeping the session branch** so the user can push it / open a PR
+- `har_teardown_environment` with `agentId: 1` — plain cleanup (also keeps the branch; `deleteBranch: true` to drop it)
+
+### 2. HAR CLI (when `har` is installed)
+
+```bash
+har env launch 1        # FIRST, before editing — prints the work dir
+har env verify 1
+har env verify 1 --full
+har env complete 1      # done: verify + validate + teardown, branch kept for PR
+har env teardown 1      # plain cleanup (--delete-branch to drop the branch)
+```
+
+### 3. Shell fallback (no CLI/MCP installed)
+
+```bash
+./.har/launch.sh 1
+./.har/verify.sh 1
+./.har/verify.sh 1 --full
+./.har/teardown.sh 1
+```
+
+Commit your work **inside the session worktree** on its session branch. After completion the branch survives teardown — the user decides whether to push it and open a PR. Run JSON stays in the main checkout `.har/runs/`.
+
+## UI changes
+
+When the Playwright stage is installed (`.har/stages/browser-e2e.sh` exists), add or update specs under `tests/`. Full verify includes browser-e2e.
+
+## Definition of done
+
+- Full verification returns pass (`har env verify 1 --full`, MCP `har_run_verification` with `full: true`, or `./.har/verify.sh 1 --full`)
+- All edits live in the session worktree (main checkout untouched: `git status` clean there)
+- New behavior has automated test coverage
+- Show the user the slot preview URLs so they can test the app themselves
+- Do not declare work complete without running full verify
+
+## Commit gate
+
+Each full verify records the exact code state it validated (a git tree hash under
+`.har/validations/`). When the har commit gate is installed (`har hooks install`),
+`git commit` is blocked unless the staged changes match a state that passed full verify.
+
+- Any edit after verify — even one character — requires re-running `har env verify <id> --full`
+- Stage everything you verified (`git add -A`); partially staged trees were never verified and will be rejected
+- Do not bypass the gate (`--no-verify`, `HAR_SKIP_GATE=1`) — bypasses are recorded and visible in Mission Control

package/dist/templates/har-boilerplate/CLAUDE.agent.md

@@ -0,0 +1,54 @@
+# Agent ${AGENT_ID} — Development Environment
+
+> [`AGENT.md`](../AGENT.md) · [`.har/README.md`](./README.md) · [`stages.json`](./stages.json)
+
+## Environment
+
+| | |
+|--|--|
+| **Agent ID** | ${AGENT_ID} |
+| **Frontend** | http://localhost:${FE_PORT} |
+| **API** | http://localhost:${API_PORT} |
+| **Database** | `agent_${AGENT_ID}` on `localhost:${DB_PORT}` (when `db` is in `HARNESS_INFRA_SERVICES`) |
+| **Work dir** | Fresh session worktree per launch — see the launch output or `.har/slots/agent-${AGENT_ID}.json` |
+
+**Never edit the main checkout** — launch FIRST, then make ALL file edits under the work dir from the launch output. Edits there hot-reload in the running slot; use `./.har/agent-cli.sh ${AGENT_ID} restart` if a change doesn't take. Relaunching replaces the session (branch kept) and requires explicit confirmation; dirty worktrees also need `--force` after user approval.
+
+This slot runs **only the primary application** (`HARNESS_PRIMARY_APP`). External dependencies and any supporting services run once, shared by all slots — `setup-infra.sh` manages them; never start them yourself.
+
+```bash
+./.har/agent-cli.sh ${AGENT_ID} status
+./.har/agent-cli.sh ${AGENT_ID} logs api
+./.har/agent-cli.sh ${AGENT_ID} health
+```
+
+## Definition of done
+
+- [ ] Full verification returns `"status": "pass"` (`har env verify ${AGENT_ID} --full`, MCP `har_run_verification` with `full: true`, or `./.har/verify.sh ${AGENT_ID} --full`)
+- [ ] When `stages/browser-e2e.sh` exists, full verify includes Playwright — adapt specs under `tests/` for UI changes
+- [ ] New behavior has automated test coverage (unit and/or browser as appropriate)
+- [ ] Changes committed **in the session worktree** with a clear message
+- [ ] The user got the preview URLs to test the app themselves
+- [ ] Finish with `har env complete ${AGENT_ID}` (or MCP `har_complete_environment`) — records the validation and tears down while **keeping the session branch** for the user to push / open a PR
+
+Quick loop during development: MCP `har_run_verification`, `har env verify ${AGENT_ID}`, or `./.har/verify.sh ${AGENT_ID}` (stops before lint and browser-e2e).
+
+## Project commands
+
+```bash
+# TODO: adapt for this repository (see package.json, Makefile, etc.)
+# npm run typecheck
+# npm test
+# npm run lint
+```
+
+## Do not
+
+- Hand-roll docker/dev-server startup — `launch` is how you run the app (manual testing, browser, screenshots included)
+- Work around a failing harness command with ad-hoc setup — fix the harness or report the failure
+- Hardcode ports — use agent env / `agent-cli.sh url`
+- Run raw `docker compose` for shared harness infra — use `setup-infra.sh`
+- Start other services of the repo in your slot — only the primary app runs per-slot; shared services are already running
+- Edit `.env.agent.${AGENT_ID}` or PM2 ecosystem files by hand
+- Run `verify` before `launch` when health or e2e steps need a running server
+- Edit the main checkout — all edits go under the session work dir

package/dist/templates/har-boilerplate/README.md

@@ -0,0 +1,134 @@
+# .har — Agent Harness
+
+This directory is the **agent harness** for this repository. It lets AI coding agents (Cursor, Claude Code, etc.) run the project in isolated environments with their own ports, database, and verification workflow.
+
+Generated and maintained by [`har`](https://github.com/antoineFrau/har). Run `har env maintain` when the repo stack changes.
+
+**The harness is how you run this project.** Need the app live — manual testing, a browser session, screenshots? `launch` a slot; don't hand-roll docker/dev-server startup. If a harness command fails, fix the harness or report it — don't silently fall back to ad-hoc commands.
+
+## What's in here
+
+| File | Purpose |
+|------|---------|
+| `README.md` | This file — index of the harness |
+| `manifest.json` | Generator metadata (version, checksums) — do not edit |
+| `harness.env` | Shared config: primary app, ports, agent slot limits, `HARNESS_INFRA_SERVICES`, migrate/seed commands |
+| `stages.json` | Machine-readable registry of runnable harness stages |
+| `stages/` | Optional custom stage scripts registered from `stages.json` |
+| `runs/` | Run history from `har env` / MCP only — `.har/runs/YYYY-MM-DD/HH-mm-ss_<stageId>_agent-<id>.json` (gitignore) |
+| `artifacts/` | Stage outputs: reports, traces, screenshots, logs |
+| `agent-slot.sh` | Shared agent-id validation (reads limits from `harness.env`) |
+| `setup-infra.sh` | Start shared Docker infra + create template database |
+| `launch.sh` | Launch one agent slot (ports, DB clone, PM2 processes) |
+| `verify.sh` | Verification pipeline (typecheck, tests, health) |
+| `teardown.sh` | Tear down one agent slot |
+| `agent-cli.sh` | Manage a running agent (status, logs, psql, health) |
+| `attach.sh` | Attach to agent tmux session |
+| `env.template` | Per-agent env vars (expanded by `launch.sh`) |
+| `ecosystem.agent.template.cjs` | PM2 processes for the **primary app only** (expanded by `launch.sh`) |
+| `ecosystem.shared.config.cjs` | Optional — shared app services started once by `setup-infra.sh` (only when the repo has supporting services) |
+| `docker-compose.agent.yml` | Shared infrastructure containers |
+| `CLAUDE.agent.md` | Detailed instructions for coding agents |
+| `justfile` | Optional shortcuts (requires `just`) |
+
+## Quick start
+
+**Preferred — har CLI or MCP** (persists run history under `.har/runs/`):
+
+```bash
+har env launch 1
+har env verify 1
+har env verify 1 --full
+har env teardown 1
+```
+
+In Cursor with HAR MCP configured: use `har_launch_environment`, `har_run_verification`, and `har_teardown_environment`.
+
+**Shell fallback** (no CLI/MCP installed):
+
+```bash
+./.har/setup-infra.sh          # when HARNESS_INFRA_SERVICES is non-empty
+./.har/launch.sh 1
+./.har/verify.sh 1             # quick: typecheck, tests, health
+./.har/verify.sh 1 --full      # done gate: + lint + browser-e2e (if Playwright stage installed)
+./.har/teardown.sh 1
+```
+
+Read **`stages.json`** for registered stages and **`verificationStages`** for the expected pass set.
+
+## Verification contract
+
+| Mode | Command | Typical steps |
+|------|---------|---------------|
+| Quick | `har env verify <id>` or `verify.sh <id>` | Project checks in `verify.sh` (stops early on failure) |
+| Full | `har env verify <id> --full` or `verify.sh <id> --full` | Quick steps + lint + **`browser-e2e`** when `.har/stages/browser-e2e.sh` exists |
+
+Install Playwright stage: `har env add-stage playwright` (optional). UI changes should add or update specs under `tests/`.
+
+## Run history
+
+| Entry point | Writes `.har/runs/`? |
+|-------------|------------------------|
+| `./.har/*.sh` | No — same scripts, no run record |
+| `har env …` / MCP | Yes — under main checkout `.har/runs/YYYY-MM-DD/` |
+
+With git worktree slots, verification runs code in the worktree but run JSON stays in the main repo `.har/runs/`. Each record includes `workDir` when a slot is active.
+
+## For coding agents
+
+1. Read repo [`AGENT.md`](../AGENT.md)
+2. Read this file and `stages.json`
+3. After launch, read `.har/CLAUDE.agent.md` for slot URLs and definition of done
+
+Prefer HAR MCP tools or `har env …` for launch, verify, and teardown. Use `./.har/*.sh` only when the CLI is not installed.
+
+Always use `./.har/agent-cli.sh <id> ...` — never hardcoded ports.
+
+## Architecture
+
+Each agent slot gets isolated ports: `BASE + (AGENT_ID × 10)`.
+
+Configure how many slots your machine can run in parallel in `stages.json` (`agentSlots`) and `harness.env` (`HARNESS_AGENT_SLOT_MIN` / `HARNESS_AGENT_SLOT_MAX`). Keep both in sync.
+
+| Service | Agent 1 | Agent 2 |
+|---------|---------|---------|
+| Frontend | 3010 | 3020 |
+| API | 8010 | 8020 |
+
+### Primary app vs shared services
+
+Each slot runs **only the primary application** (`HARNESS_PRIMARY_APP` in `harness.env`) — the app agents modify. Everything else runs **once**, shared by all slots on fixed ports:
+
+- **External dependencies** (Postgres, Redis, mail, ...): services in `docker-compose.agent.yml`, enabled via the `HARNESS_INFRA_SERVICES` list in `harness.env`, started by `setup-infra.sh`.
+- **Internal supporting services** (other services of a monolith/monorepo the agent depends on but does not change): either compose services in `docker-compose.agent.yml`, or PM2 processes in an optional `.har/ecosystem.shared.config.cjs` (named `har-shared-<name>`, started by `setup-infra.sh`).
+
+Isolation still applies where it matters: each slot gets its own database (`agent_<id>`, cloned from the template DB), ports, and git worktree.
+
+## Maintaining this harness
+
+When the project stack changes (new services, different test commands, new env vars):
+
+```bash
+har env maintain
+```
+
+The authoring agent updates scripts and this README. Review changes before committing.
+
+**Do not** put runtime behavior in YAML — edit the scripts directly.
+
+## Session lifecycle
+
+Every `launch` starts a **fresh session**: a new git worktree from the current HEAD at
+`~/worktrees/<base-branch>-<sha4>-har-agent-<id>-<rand4>`, on a branch of the same name.
+The session is recorded in `.har/slots/agent-<id>.json` (the slot registry) — status,
+verify, and teardown resolve the work dir through it. Make ALL file edits under the
+work dir printed by launch, never in the main checkout.
+
+- Relaunching a slot **replaces** its previous session; replacement requires `--replace` /
+  `confirmReplace=true` (or an interactive prompt). Uncommitted changes also need `--force`
+  after explicit user approval.
+- `teardown` removes the worktree but **keeps the session branch** so you can push it
+  or open a PR (`--delete-branch` to drop it).
+- `har env complete <id>` finishes a session: full verify (recorded as a validation),
+  then teardown — branch kept.
+- `--no-worktree` runs the slot from the repo root instead (single-agent mode).