@osfactory/har 1.0.0-rc.2 → 1.0.0

package/dist/templates/AGENTS.md.template

@@ -5,72 +5,25 @@ This repository uses a **`.har/` harness** for isolated agent development.
 <!-- har:agent-environment:start -->
 ## HAR / agent environment
 
-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.
-
-### Before making changes
-
-1. On the **main checkout**, switch to the intended base (usually `main`) — launch
-   creates a worktree from that HEAD.
-2. **Launch first** — MCP `har_launch_environment` / `har env launch 1`. Use the
-   returned **work dir** for ALL edits (never the main checkout).
-   **Bind tracker work** when the task names a durable issue or ticket (GitHub,
-   Linear, etc.): pass a short repo-scoped `--work-id` / `workUnitId` (e.g.
-   `widget-123`), `--work-source` / `source`, `--work-url` / `sourceUrl`, and
-   `--work-title` / `title` when known. Skip binding for ad-hoc work with no
-   tracker identity.
-3. Read [`.har/README.md`](.har/README.md), [`.har/stages.json`](.har/stages.json), then
-   [`.har/CLAUDE.agent.md`](.har/CLAUDE.agent.md) (slot URLs / definition of done).
-4. Hot-reload usually applies; if not, `./.har/agent-cli.sh <id> restart` (no-op on
-   cli/ios profiles without managed processes).
-
-**Occupied slots always block.** Run `complete` / `teardown`, then `launch`. Resume
-failed/starting launches with `--resume` / `recover`. Prefer a free slot (2+) over
-sharing slot 1 across unrelated chats. Check `har_get_status` / `har env status` first.
-Commit early — teardown keeps the branch, not uncommitted work.
-
-### After making changes
-
-Prefer MCP → CLI → shell. Quick verify for the loop; **full verify before done**.
-
-- MCP: `har_run_verification` / `full: true`; finish with `har_complete_environment`
-  (propose; wait for approval) or `har_teardown_environment`
-- CLI: `har env verify 1`, `har env verify 1 --full`, `complete 1`, `teardown 1`
-- Shell: `./.har/verify.sh 1`, `./.har/verify.sh 1 --full`, `./.har/teardown.sh 1`
-
-Commit in the session worktree. Run JSON stays in the main checkout `.har/runs/`.
-
-### Definition of done
-
-- Full verify passes; edits only in the session worktree; tests cover new behavior;
-  changes committed; show preview URLs; then **session handoff** (below).
-
-### Session handoff (required)
-
-After full verify and commit, stop. Include summary, session branch
-(`.har/slots/agent-<id>.json`), and preview URLs. Wait — never autonomously
-complete, teardown, push, or open a PR. **Default:** when `gh`/GitHub MCP is available,
-recommend **Complete + open a PR** (still needs approval). Alternatives: **Complete only**,
-or **Something else**. Without PR tooling, recommend **Complete only** and give the
-session branch for a manual push.
-
-### Commit gate
-
-Full verify records a tree hash under `.har/validations/`. With `har hooks install`,
-commits must match a passing full verify. Re-verify after any edit; `git add -A`.
-Do not bypass (`--no-verify`, `HAR_SKIP_GATE=1`).
-
-### Cursor IDE
-
-If `.cursor/rules/har-workflow.mdc` exists, the same harness workflow is injected into
-every Cursor agent session automatically. Run `har env init` or `har env maintain` to
-create or refresh it.
+This repository uses a `.har/` harness. It is **how you run and verify this
+project** — launch a slot for live apps, browsers and screenshots; never
+hand-roll docker or dev-server startup. If a harness command fails, fix the
+harness or report it; do not fall back to ad-hoc commands.
+
+1. **Launch first** — `har_launch_environment` / `har env launch <id>`. Make ALL
+   edits under the returned **work dir**, never the main checkout. Bind tracker
+   work with `--work-id` / `--work-url` when the task names an issue.
+2. **Verify before done** — `har_run_verification` (`full: true`) /
+   `har env verify <id> --full`. Commit in the session worktree.
+3. **Stop at handoff** — report summary, session branch and preview URLs, then
+   wait. Never autonomously `complete`, `teardown`, push, or open a PR.
+
+Occupied slots always block: `complete` / `teardown`, then launch. Customize the
+harness only through `harness.env`, `stages.json` + `.har/stages/`, `.har/hooks/`
+and `.har/plugins/` — the generated `.har/*.sh` shims are not an editing surface.
+
+Full detail — slot environment, readiness, definition of done, project commands,
+commit gate: [`.har/README.md`](.har/README.md) and [`.har/stages.json`](.har/stages.json).
 <!-- har:agent-environment:end -->
 
 ## Project-specific notes

package/dist/templates/CLAUDE.md.template

@@ -1,5 +1 @@
-# __PROJECT_DISPLAY_NAME__
-
-Read [AGENTS.md](./AGENTS.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`).
+@AGENTS.md

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

@@ -161,8 +161,9 @@ are user-owned: never drift-checked; `har env doctor` only validates names and
 executability. Use registered stages for verification steps; use hooks for
 lifecycle side effects.
 
-### `.har/CLAUDE.agent.md`
-Detailed agent instructions: commands, credentials, architecture, definition of done.
+### `.har/README.md`
+The harness reference agents read: slot environment, readiness / what "agent
+usable" means here, definition of done, project commands, architecture.
 
 ### `.har/env.template`, `docker-compose.agent.yml`
 Adapt as needed for the project's infra (`setup-infra.sh` is a shim — the
@@ -195,7 +196,7 @@ Onboarding may set an initial `agentSlots.max` in `.har/stages.json`. After you
 - [ ] For each service in `HARNESS_INFRA_SERVICES`, a matching lane exists in `HARNESS_INFRA_PORT_LANES` in `harness.env`
 - [ ] `.har/README.md` has a **Port & shared services** section (allocation table, shared vs per-slot, do-not rules)
 - [ ] App code and tests read ports from `.env.agent.<id>` / `agent-cli.sh` / slot registry — no hardcoded `3000`, `15432`, `3847`, etc.
-- [ ] `env.template` and `CLAUDE.agent.md` show resolved ports via variables, not literals
+- [ ] `env.template` and `.har/README.md` show resolved ports via variables, not literals
 - [ ] Monorepos with `har control up`: document slot-1 conflict if the app port overlaps (e.g. Mission Control on 3847)
 
 ### Git worktree
@@ -214,7 +215,7 @@ If **`har env init` already created `AGENTS.md`**, refresh the **HAR / agent env
 
 If **no `AGENTS.md` exists**, create one at the repo root using this structure:
 
-- Link to `.har/README.md` and `.har/CLAUDE.agent.md`
+- Link to `.har/README.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)
 - Commands: HAR MCP tools or `har env launch/verify/teardown`
 - Shell shims: `./.har/launch.sh`, `./.har/verify.sh`, `./.har/teardown.sh` — same runtime and run records
@@ -223,7 +224,7 @@ If **no `AGENTS.md` exists**, create one at the repo root using this structure:
 
 If **`AGENTS.md` already exists** (project-owned), add or update a concise **HAR / agent environment** section — do not replace unrelated content.
 
-Keep **`CLAUDE.md`** as a thin pointer to `AGENTS.md` (Claude Code auto-loads `CLAUDE.md`). Do not paste the full harness workflow into `CLAUDE.md`.
+Keep **`CLAUDE.md`** as the line `@AGENTS.md` (Claude Code auto-loads `CLAUDE.md` and follows the import). Never paste the harness workflow into it — `AGENTS.md` is the single instruction file.
 
 ### Monorepos / multiple harnesses
 
@@ -249,7 +250,7 @@ not yours to trim, and wholesale deletion just manufactures drift):
 - [ ] `HARNESS_INFRA_SERVICES` lists exactly the services this project uses, each with a lane in `HARNESS_INFRA_PORT_LANES`
 - [ ] All per-slot data stores are provisioned, not just the primary database
 - [ ] If full seed/setup is skipped, `.har/` provides a minimal bootstrap or documents why none is needed
-- [ ] `.har/CLAUDE.agent.md` defines what "agent usable" means for this repo (credentials, default data, smoke workflow) and shows only real URLs/ports/commands
+- [ ] `.har/README.md` defines what "agent usable" means for this repo (credentials, default data, smoke workflow) and shows only real URLs/ports/commands
 - [ ] `.har/README.md` documents port allocation and the shared-service model
 - [ ] No hardcoded default ports (`3000`, `15432`, `3847`, …) in app code, tests, or harness docs — use agent env / slot registry
 

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

@@ -31,7 +31,7 @@ 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`, `stages.json`, `ecosystem.agent.template.cjs`, `CLAUDE.agent.md`
+### `.har/harness.env`, `stages.json`, `ecosystem.agent.template.cjs`, `README.md`
 Align commands and instructions with the current stack. Verify steps must use toolchain paths from `.env.agent.<id>` (`PYTHON_BIN`, `NPM_BIN`, `XCODEBUILD_BIN`, …) — never hardcoded venv or interpreter paths. `NPM_BIN` may be bun, pnpm, or yarn, so Node steps must use `${NPM_BIN:-npm} run <script>` and avoid npm-only flags such as `--prefix`. Replace stock ecosystem conventions that do not match the repository; do not leave npm/pytest/go/cargo/maven/gradle examples in place by accident.
 
 ### `.har/env.template`, `docker-compose.agent.yml`
@@ -62,7 +62,7 @@ Look specifically for drift introduced since the last adaptation:
 - `verificationStages` became health-only and no longer checks the key workflow
   that makes the slot usable.
 
-Update `.har/CLAUDE.agent.md` with skipped setup steps, substitutes, credentials,
+Update `.har/README.md` with skipped setup steps, substitutes, credentials,
 and the repo-specific definition of "agent usable."
 
 ### Custom lifecycle behavior — `.har/hooks/`
@@ -96,7 +96,7 @@ come back here afterwards. Two standing rules:
 
 If harness commands, rules, or workflow changed, update the **HAR / agent environment** section in repo-root `AGENTS.md`:
 
-- Links to `.har/README.md` and `.har/CLAUDE.agent.md`
+- Links to `.har/README.md`
 - Commands: HAR MCP tools or `har env …`
 - Shell shims: `./.har/*.sh` — thin delegates to `har env`, same run records
 - Run history (worktree runs record to the main checkout `.har/runs/`)
@@ -105,7 +105,7 @@ If harness commands, rules, or workflow changed, update the **HAR / agent enviro
 
 If `AGENTS.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.
 
-Do **not** create `AGENT.md` (singular). If legacy `AGENT.md` exists, merge unique notes into `AGENTS.md` and delete `AGENT.md`. Keep `CLAUDE.md` as a thin pointer to `AGENTS.md`.
+Do **not** create `AGENT.md` (singular). If legacy `AGENT.md` exists, merge unique notes into `AGENTS.md` and delete `AGENT.md`. Keep `CLAUDE.md` as the line `@AGENTS.md`.
 
 ## Rules
 

package/dist/templates/agent-skills/har-wt.md

@@ -43,7 +43,7 @@ completion to HAR.
 - The main checkout must stay clean (`git status` there shows no changes from you).
 - Edits hot-reload in the running slot; use `./.har/agent-cli.sh <id> restart` if a change doesn't take.
 - Commit early and often on the session branch — teardown keeps the branch, not uncommitted work.
-- After launch, read `.har/CLAUDE.agent.md` in the worktree for slot URLs and the definition of done.
+- After launch, read `.har/README.md` in the worktree for slot URLs and the definition of done.
 
 ## 4. Verify through the harness
 

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

@@ -1,79 +1,14 @@
 ---
-description: HAR harness workflow — read before change, verify before done
+description: HAR harness workflow — read AGENTS.md before changing anything
 alwaysApply: true
 ---
 
 # HAR Harness Workflow
 
-This repository uses a `.har/` agent harness. Follow this on every change.
+This repository uses a `.har/` agent harness. **Read [`AGENTS.md`](../../AGENTS.md)
+and follow it** — it is the single source of truth for the harness workflow
+(launch a slot first, edit only in the work dir, full verify before done, stop at
+handoff). `.har/README.md` has the harness detail.
 
-The harness is **how you run the project**, not only how you verify it. Launch a
-slot for live apps, browsers, and screenshots — never hand-roll docker/dev-server
-startup. If a harness command fails, fix the harness or surface the failure. Customize
-only via the contract (`harness.env`, `stages.json` + `.har/stages/`, `.har/hooks/`, `.har/plugins/`) — never edit the generated `./.har/*.sh` shims.
-
-## Before making changes
-
-1. On the **main checkout**, switch to the intended base (usually `main`) — launch
-   creates a worktree from that HEAD.
-2. **Launch first** — MCP `har_launch_environment` / `har env launch 1`. Use the
-   returned **work dir** for ALL edits (never the main checkout). Path looks like
-   `~/worktrees/<base>-<sha4>-har-agent-<id>-<rand4>` (see `.har/slots/agent-<id>.json`).
-   **Bind tracker work** when the task names an issue or ticket — short `--work-id`
-   (e.g. `widget-123`) plus `--work-source` / `--work-url` / `--work-title`. Skip for ad-hoc work.
-3. Read `AGENTS.md`, `.har/README.md`, `.har/stages.json`, then
-   `.har/CLAUDE.agent.md` (slot URLs / definition of done).
-4. Hot-reload usually applies; if not, `./.har/agent-cli.sh <id> restart` (no-op on
-   cli/ios profiles without managed processes).
-
-**Occupied slots always block.** Run `complete` / `teardown`, then `launch`. Resume
-failed/starting launches with `--resume` / `recover`. Prefer a free slot (2+) over
-sharing slot 1 across unrelated chats. Check `har_get_status` / `har env status`
-first. Commit early — teardown keeps the branch, not uncommitted work. Gitignored
-paths are ephemeral. With telemetry on, Mission Control derives session purpose from
-the first captured user prompt.
-
-<!-- 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
-
-Prefer MCP → CLI → shell. Quick verify for the loop; **full verify before done**.
-
-- MCP: `har_run_verification` / `full: true`; finish with `har_complete_environment`
-  (propose; wait for approval) or `har_teardown_environment`
-- CLI: `har env verify 1`, `har env verify 1 --full`, `complete 1`, `teardown 1`
-- Shell: `./.har/verify.sh 1`, `./.har/verify.sh 1 --full`, `./.har/teardown.sh 1`
-
-Commit in the session worktree. Run JSON stays in the main checkout `.har/runs/`.
-UI changes with Playwright: update specs under `tests/` (full verify includes browser-e2e).
-
-## Definition of done
-
-- Full verify passes; edits only in the session worktree; tests cover new behavior;
-  changes committed; show preview URLs; then **session handoff** (below).
-
-## Session handoff (required)
-
-After full verify and commit, stop. Include summary, session branch
-(`.har/slots/agent-<id>.json`), and preview URLs. Wait — never autonomously
-complete, teardown, push, or open a PR. **Default (1 is the default):** when
-`gh`/GitHub MCP is available, recommend **Complete + open a PR** — push → open
-PR → `har env complete` / `har_complete_environment` (branch kept). Still needs
-approval. Alternatives: **Complete only**, or **Something else**. Without PR
-tooling, recommend **Complete only** and give the session branch for a manual push.
-
-## Commit gate
-
-Full verify records a tree hash under `.har/validations/`. With `har hooks install`,
-commits must match a passing full verify. Re-verify after any edit; `git add -A`.
-Do not bypass (`--no-verify`, `HAR_SKIP_GATE=1`).
+This rule exists only to guarantee that instruction reaches every Cursor session;
+it deliberately does not restate the workflow, so there is one copy to keep current.

package/dist/templates/har-boilerplate/gitignore.template

@@ -9,12 +9,14 @@ artifacts/
 state/
 maintain/
 ADAPT-PROMPT.md
+migrate/
+MIGRATE-PROMPT.md
 AGENTS.md.proposed
 AGENTS.md.proposed.meta.json
 AGENT.md.proposed
 AGENT.md.proposed.meta.json
 slots/
 
-# Generated by launch.sh (also listed in repo-root .gitignore)
+# Generated at launch (also listed in repo-root .gitignore)
 .env.agent.*
 ecosystem.agent.*.config.cjs

package/dist/templates/har-boilerplate-cli/gitignore.template

@@ -9,12 +9,14 @@ artifacts/
 state/
 maintain/
 ADAPT-PROMPT.md
+migrate/
+MIGRATE-PROMPT.md
 AGENTS.md.proposed
 AGENTS.md.proposed.meta.json
 AGENT.md.proposed
 AGENT.md.proposed.meta.json
 slots/
 
-# Generated by launch.sh (also listed in repo-root .gitignore)
+# Generated at launch (also listed in repo-root .gitignore)
 .env.agent.*
 ecosystem.agent.*.config.cjs

package/dist/templates/har-boilerplate-ios/gitignore.template

@@ -12,6 +12,8 @@ AGENT.md.proposed
 AGENT.md.proposed.meta.json
 maintain/
 ADAPT-PROMPT.md
+migrate/
+MIGRATE-PROMPT.md
 slots/
 simulators/
 

package/dist/templates/migration-prompt.md

@@ -50,5 +50,6 @@ Record the migration and clean up the migration artifacts (`.har/migrate/`, this
 1. Never edit `.har/manifest.json` by hand — it is managed by the har CLI.
 2. Do not delete `.har/migrate/backup/` until finalize — it is the only copy of the pre-1.0 adaptations.
 3. Keep `stages.json` stage ids stable — run records and Mission Control reference them.
-4. Update `.har/README.md` and `.har/CLAUDE.agent.md` if commands or workflow notes changed.
+4. Update `.har/README.md` if commands or workflow notes changed — 1.0 does not
+   generate `.har/CLAUDE.agent.md`; its content belongs there.
 5. Commit the migrated harness (shims, `harness.env`, `stages.json`, `.har/hooks/`) once verified — `.har/migrate/` and this prompt are transient and stay untracked.

package/dist/templates/profiles/cli/docs/{claude-agent → readme}/definition-of-done.md

@@ -1,12 +1,12 @@
 ## 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`)
+- [ ] Full verification returns `"status": "pass"` (`har env verify <id> --full`, MCP `har_run_verification` with `full: true`, or `har env verify <id> --full`)
 - [ ] The slot is agent-usable for this repo's documented smoke workflow when runtime services are involved
 - [ ] Full verify runs every registered stage in `stages.json` `verificationStages` (Playwright, custom checks, …) — when `stages/browser-e2e.sh` exists, adapt specs under `tests/` for UI changes
 - [ ] New behavior has automated test coverage
 - [ ] Changes committed **in the session worktree** with a clear message
 - [ ] Present session handoff (summary, branch, preview URLs) and **wait for user** before `complete`, push, or PR
-- [ ] On user approval of the default: push + open PR (when `gh`/GitHub MCP available), then `har env complete ${AGENT_ID}` (or MCP `har_complete_environment`) — full verify + validation + teardown, branch kept
+- [ ] On user approval of the default: push + open PR (when `gh`/GitHub MCP available), then `har env complete <id>` (or MCP `har_complete_environment`) — full verify + validation + teardown, branch kept
 
 ### Session handoff
 
@@ -18,6 +18,6 @@ else as alternatives. If PR tooling is unavailable, recommend complete and repor
 the session branch for a manual push. Prefer `complete` over bare `teardown` when
 the work succeeded. See `.cursor/rules/har-workflow.mdc` for the handoff shape.
 
-Quick loop: MCP `har_run_verification`, `har env verify ${AGENT_ID}`, or `./.har/verify.sh ${AGENT_ID}`
+Quick loop: MCP `har_run_verification`, `har env verify <id>`, or `har env verify <id>`
 
 Stages are the harness's single vocabulary for checks: templates and custom stages compile to generic kinds in `.har/stages.json`, and you interact with them only through the registry (`har_run_stage`, `verify`), never stack-specific tooling. Authoring guide: `.har/STAGES.md`.

package/dist/templates/profiles/cli/docs/{claude-agent → readme}/do-not.md

@@ -1,6 +1,6 @@
 ## Do not
 
 - Work around a failing harness command with ad-hoc setup — fix the harness or report the failure
-- Edit `.env.agent.${AGENT_ID}` by hand
+- Edit `.env.agent.<id>` by hand
 - Run `verify` before `launch` when e2e needs a running server
 - Edit the main checkout — all edits go under the session work dir

package/dist/templates/profiles/cli/docs/{claude-agent → readme}/environment.md

@@ -2,11 +2,11 @@
 
 | | |
 |--|--|
-| **Agent ID** | ${AGENT_ID} |
-| **Work dir** | Fresh session worktree per launch — see the launch output or `.har/slots/agent-${AGENT_ID}.json` |
+| **Agent ID** | <id> |
+| **Work dir** | Fresh session worktree per launch — see the launch output or `.har/slots/agent-<id>.json` |
 
 **Never edit the main checkout** — launch FIRST, then make ALL file edits under the work dir from the launch output. An occupied slot always blocks a new launch — run `har env teardown <id>` (or `complete <id>`) first, then launch again.
 
 ```bash
-./.har/agent-cli.sh ${AGENT_ID} status
+har env agent <id> status
 ```

package/dist/templates/profiles/cli/docs/readme/for-coding-agents.md

@@ -1,9 +1,7 @@
 ## For coding agents
 
-**Start here:** read [`AGENTS.md`](../AGENTS.md) at the repo root for a short pointer, then [`.har/CLAUDE.agent.md`](./CLAUDE.agent.md) for full instructions.
-
-Prefer HAR MCP tools or `har env …` for launch, verify, and teardown. Use `./.har/*.sh` only when the CLI is not installed.
-
-Work in the isolated git worktree created by launch. Use `./.har/agent-cli.sh <id> exec ...` to run ad-hoc project commands in that work dir.
-
-When the project needs Postgres, Redis, or similar, add the service to `docker-compose.agent.yml` (or keep one from the menu), list it in `HARNESS_INFRA_SERVICES` in `harness.env`, and use `setup-infra.sh` — never run raw `docker compose` for shared infra. Shared services run once on fixed ports and serve every agent slot.
+1. Read repo [`AGENTS.md`](../AGENTS.md)
+2. Read this file and `stages.json` — this file is the harness reference:
+   slot environment, readiness, definition of done, project commands
+3. Drive the harness with HAR MCP tools or `har env …`; never hardcode ports —
+   ask `har env agent <id> url`

package/dist/templates/profiles/cli/docs/readme/port-shared-services-cli-profile.md

@@ -9,17 +9,17 @@ This profile has **no PM2 app ports** — agents run project commands directly i
 | Shared Postgres | Per machine | `HARNESS_DB_PORT_DEFAULT` | Scan `HARNESS_DB_PORT_SCAN_START..END` |
 | Other compose services | Per machine | `HARNESS_*_PORT_DEFAULT` for that service | Scan configured ranges in `harness.env` |
 
-When a repo adds a local HTTP server for integration tests, prefer reading ports from `.env.agent.<id>` or `./.har/agent-cli.sh <id>` rather than hardcoding values.
+When a repo adds a local HTTP server for integration tests, prefer reading ports from `.env.agent.<id>` or `har env agent <id>` rather than hardcoding values.
 
 ### Shared vs per-slot
 
 | Resource | Model | Configuration |
 |----------|-------|---------------|
 | Postgres / Redis / mail / … | One shared container on a scanned host port | `HARNESS_INFRA_SERVICES` + matching vars in `harness.env` |
-| Per-slot databases | Cloned from template DB when `db` is enabled | `launch.sh` |
+| Per-slot databases | Cloned from template DB when `db` is enabled | `har env launch` |
 | Application code | Isolated git worktree per slot | `HARNESS_USE_WORKTREE=true` |
 
 ### Do not
 
 - Hardcode `15432` or other default infra ports in tests — read `AGENT_DB_PORT` from `.env.agent.<id>` or `har_pg`
-- Run raw `docker compose` for harness infrastructure — use `setup-infra.sh`
+- Run raw `docker compose` for harness infrastructure — use `har env setup-infra`

package/dist/templates/profiles/cli/docs/readme/quick-start.md

@@ -11,14 +11,8 @@ har env teardown 1
 
 In Cursor with HAR MCP configured: use `har_launch_environment`, `har_run_verification`, and `har_teardown_environment`.
 
-**Shell shims** (same runtime — each `./.har/*.sh` forwards to `har env`, with a pinned `npx @osfactory/har` fallback):
-
-```bash
-./.har/setup-infra.sh          # when HARNESS_INFRA_SERVICES is non-empty
-./.har/launch.sh 1
-./.har/verify.sh 1             # quick: ecosystem smoke (compile/import/build)
-./.har/verify.sh 1 --full      # + conventional tests, lint, browser-e2e (if installed)
-./.har/teardown.sh 1
-```
+`./.har/*.sh` exist as compatibility shims over the same runtime — generated,
+never edited, and not the way to drive the harness. Take explicit ownership of
+them with `har env eject`.
 
 Read **`stages.json`** and **`verificationStages`**. Optional: `har env add-plugin playwright`.

package/dist/templates/profiles/cli/docs/readme/verification-contract.md

@@ -1,6 +1,6 @@
 ## Verification contract
 
-Steps in `verify.sh` are **project-specific examples** — adapt them to your stack
+Steps in `har env verify` are **project-specific examples** — adapt them to your stack
 during `har env init` / `har env maintain` / benchmark setup. The table describes
 each tier's intent, not a fixed command list.
 
@@ -19,4 +19,4 @@ harness skips slow local-dev setup, document the skipped steps and add a minimal
 bootstrap/readiness check when agents need default data, credentials, or an
 authenticated workflow.
 
-Use `har env launch 1 --no-worktree` or `./.har/launch.sh 1 --no-worktree` only when working in the repo root.
+Use `har env launch 1 --no-worktree` only when working in the repo root.

package/dist/templates/profiles/cli/docs/readme/what-s-in-here.md

@@ -11,7 +11,7 @@
 | `hooks/` | Optional lifecycle hooks (`pre-launch.sh`, `post-launch.sh`, `pre-verify.sh`, `pre-teardown.sh`, `post-teardown.sh`) |
 | `plugins/` | Optional local plugins (`har plugin create <id>`) |
 | `docker-compose.agent.yml` | Optional shared infrastructure containers (services listed in `HARNESS_INFRA_SERVICES`) |
-| `CLAUDE.agent.md` | Detailed instructions for coding agents |
+| `.har/README.md` | Detailed instructions for coding agents |
 | `STAGES.md` | Stage registry and script-contract guide |
 | `justfile` | Optional shortcuts (requires `just`) |
 
@@ -19,7 +19,7 @@
 
 | File | Purpose |
 |------|---------|
-| `launch.sh` / `verify.sh` / `teardown.sh` / `setup-infra.sh` / `preflight.sh` / `agent-cli.sh` | Thin shims forwarding to the packaged runtime (`har env …`); same run records on every surface |
+| `har env launch` / `har env verify` / `har env teardown` / `har env setup-infra` / `preflight.sh` / `agent-cli.sh` | Thin shims forwarding to the packaged runtime (`har env …`); same run records on every surface |
 | `manifest.json` | Runtime version, profile, checksums — managed by the har CLI |
 | `runs/` | Run history from every entry point — `.har/runs/YYYY-MM-DD/HH-mm-ss_<stageId>_agent-<id>.json` (gitignored) |
 | `artifacts/` | Stage outputs: reports, traces, logs |

package/dist/templates/profiles/cli/profile.manifest.json

@@ -1,9 +1,15 @@
 {
   "id": "cli",
-  "description": "CLI/library — shared kernel + CLI overlay (no PM2)",
+  "description": "CLI/library \u2014 shared kernel + CLI overlay (no PM2)",
   "bundles": [
-    { "id": "shared-kernel", "path": "runtime-bundles/shared-kernel" },
-    { "id": "runtime-cli", "path": "har-boilerplate-cli" }
+    {
+      "id": "shared-kernel",
+      "path": "runtime-bundles/shared-kernel"
+    },
+    {
+      "id": "runtime-cli",
+      "path": "har-boilerplate-cli"
+    }
   ],
   "capabilities": {
     "processManager": "none",
@@ -44,20 +50,17 @@
       "intro",
       "what-s-in-here",
       "quick-start",
+      "environment",
       "verification-contract",
+      "definition-of-done",
+      "readiness",
       "run-history",
       "for-coding-agents",
+      "project-commands",
       "port-shared-services-cli-profile",
+      "do-not",
       "maintaining-this-harness",
       "session-lifecycle"
-    ],
-    "CLAUDE.agent.md": [
-      "intro",
-      "environment",
-      "readiness",
-      "definition-of-done",
-      "project-commands",
-      "do-not"
     ]
   }
 }

package/dist/templates/profiles/default/docs/readme/architecture.md

@@ -1,6 +1,6 @@
 ## Architecture
 
-Each agent slot gets isolated app ports. Defaults follow `BASE + (AGENT_ID × HARNESS_PORT_STEP)`; when a default is busy, `launch.sh` scans the slot lane (`STEP` increments) and writes the resolved ports to `.env.agent.<id>` and `.har/slots/agent-<id>.json`.
+Each agent slot gets isolated app ports. Defaults follow `BASE + (AGENT_ID × HARNESS_PORT_STEP)`; when a default is busy, `har env launch` scans the slot lane (`STEP` increments) and writes the resolved ports to `.env.agent.<id>` and `.har/slots/agent-<id>.json`.
 
 Configure how many slots your machine can run in parallel in `.har/stages.json` (`agentSlots`). Bash scripts and the CLI read that first; `harness.env` keeps legacy `HARNESS_AGENT_SLOT_*` exports in sync via `har env maintain --finalize`.
 

package/dist/templates/profiles/default/docs/{claude-agent → readme}/definition-of-done.md

@@ -1,13 +1,13 @@
 ## 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`)
+- [ ] Full verification returns `"status": "pass"` (`har env verify <id> --full`, MCP `har_run_verification` with `full: true`, or `har env verify <id> --full`)
 - [ ] The slot is agent-usable for this repo's documented smoke workflow, not only health-check green
 - [ ] Full verify runs every registered stage in `stages.json` `verificationStages` (Playwright, custom checks, …) — when `stages/browser-e2e.sh` exists, 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
 - [ ] Present session handoff (summary, branch, preview URLs) and **wait for user** before `complete`, push, or PR
-- [ ] On user approval of the default: push + open PR (when `gh`/GitHub MCP available), then `har env complete ${AGENT_ID}` (or MCP `har_complete_environment`) — full verify + validation + teardown, branch kept
+- [ ] On user approval of the default: push + open PR (when `gh`/GitHub MCP available), then `har env complete <id>` (or MCP `har_complete_environment`) — full verify + validation + teardown, branch kept
 
 ### Session handoff
 
@@ -19,6 +19,6 @@ else as alternatives. If PR tooling is unavailable, recommend complete and repor
 the session branch for a manual push. Prefer `complete` over bare `teardown` when
 the work succeeded. See `.cursor/rules/har-workflow.mdc` for the handoff shape.
 
-Quick loop during development: MCP `har_run_verification`, `har env verify ${AGENT_ID}`, or `./.har/verify.sh ${AGENT_ID}` (smoke + health only; `--full` adds the registered verification stages).
+Quick loop during development: MCP `har_run_verification`, `har env verify <id>`, or `har env verify <id>` (smoke + health only; `--full` adds the registered verification stages).
 
 Stages are the harness's single vocabulary for checks: templates and custom stages compile to generic kinds in `.har/stages.json`, and you interact with them only through the registry (`har_run_stage`, `verify`), never stack-specific tooling. Authoring guide: `.har/STAGES.md`.

package/dist/templates/profiles/default/docs/{claude-agent → readme}/do-not.md

@@ -3,8 +3,8 @@
 - 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`
+- Run raw `docker compose` for shared harness infra — use `har env setup-infra`
 - 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
+- Edit `.env.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/profiles/default/docs/readme/environment.md

@@ -0,0 +1,19 @@
+## Environment
+
+| | |
+|--|--|
+| **Agent ID** | <id> |
+| **Frontend** | http://localhost:${FE_PORT} |
+| **API** | http://localhost:${API_PORT} |
+| **Database** | `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-<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 env agent <id> restart` if a change doesn't take. An occupied slot always blocks a new launch — run `har env teardown <id>` (or `complete`) first, then launch again.
+
+This slot runs **only the primary application** (`HARNESS_PRIMARY_APP`). External dependencies and any supporting services run once, shared by all slots — `har env setup-infra` manages them; never start them yourself.
+
+```bash
+har env agent <id> status
+har env agent <id> logs api
+har env agent <id> health
+```

package/dist/templates/profiles/default/docs/readme/for-coding-agents.md

@@ -1,9 +1,7 @@
 ## For coding agents
 
 1. Read repo [`AGENTS.md`](../AGENTS.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.
+2. Read this file and `stages.json` — this file is the harness reference:
+   slot environment, readiness, definition of done, project commands
+3. Drive the harness with HAR MCP tools or `har env …`; never hardcode ports —
+   ask `har env agent <id> url`