@osfactory/har 0.64.1 → 1.0.0-rc.1

package/dist/templates/plugins/semgrep/.har/stages/sast.sh

@@ -15,22 +15,17 @@
 # See: ./.har/stages/SEMGREP.md for the full adaptation guide.
 set -euo pipefail
 
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-HARNESS_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+# 1.0 stage surface: the runner exports WORK_DIR, ENV_FILE, AGENT_ID and
+# HAR_HARNESS_DIR, with harness.env and the slot env file already sourced —
+# agent-slot.sh is retired (1.0 migration).
+HARNESS_DIR="${HAR_HARNESS_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
 REPO_ROOT="$(cd "$HARNESS_DIR/.." && pwd)"
-# agent-slot.sh expects SCRIPT_DIR to be .har/ (slot registry lives there)
-SCRIPT_DIR="$HARNESS_DIR"
 
-# shellcheck source=/dev/null
-source "$HARNESS_DIR/harness.env"
-# shellcheck source=/dev/null
-source "$HARNESS_DIR/agent-slot.sh"
-
-AGENT_ID="${1:?Usage: sast.sh <agent-id> [paths...]}"
-shift
+AGENT_ID="${1:-${AGENT_ID:?Usage: sast.sh <agent-id> [paths...]}}"
+[ "$#" -gt 0 ] && shift
 SCAN_PATHS=("$@")
 
-validate_agent_id "$AGENT_ID"
+now_ms() { node -e 'process.stdout.write(String(Date.now()))' 2>/dev/null || echo 0; }
 
 log() { echo "==> [semgrep agent-$AGENT_ID] $*" >&2; }
 
@@ -46,22 +41,11 @@ if ! command -v semgrep >/dev/null 2>&1; then
 fi
 
 # ── Resolve agent env ─────────────────────────────────────────────────────────
-ENV_FILE="$(resolve_agent_env_file "$AGENT_ID" "$REPO_ROOT")" || {
-  echo "No .env.agent.${AGENT_ID} found." >&2
-  har_suggest_launch "$AGENT_ID" >&2
-  exit 1
-}
-
-# .env.agent.<id> exports REPO_ROOT pointing at the worktree — keep the main
-# checkout path so artifacts land in the main repo root, not the worktree.
+# Artifacts land in the main repo root (where .har/ lives), not the worktree.
 MAIN_REPO_ROOT="$REPO_ROOT"
 
-set -a
-# shellcheck source=/dev/null
-source "$ENV_FILE"
-set +a
-
-WORK_DIR="$(resolve_agent_work_dir "$ENV_FILE")"
+ENV_FILE="${ENV_FILE:?No slot env for agent ${AGENT_ID} — run ./.har/launch.sh ${AGENT_ID} first}"
+WORK_DIR="${WORK_DIR:?No slot work dir for agent ${AGENT_ID} — run ./.har/launch.sh ${AGENT_ID} first}"
 
 # ── Artifact directory (main repo root, not the worktree) ─────────────────────
 ARTIFACT_DIR="$MAIN_REPO_ROOT/.har/artifacts/sast"

package/dist/templates/plugins/semgrep/README.md

@@ -13,7 +13,7 @@ har env add-plugin semgrep
 |------|---------|
 | `.har/stages/sast.sh` | Stage runner — scans the session worktree with Semgrep |
 | `.har/stages/SEMGREP.md` | Adaptation guide: rulesets, noise tuning, CI/Vanta story |
-| `.github/workflows/semgrep.yml` | Optional CI workflow (`--skip-ci` to omit) — official `semgrep ci` recipe |
+| `.github/workflows/semgrep.yml` | Optional CI workflow (opt in with `--with-ci`) — official `semgrep ci` recipe |
 
 ## Workflow
 

package/dist/templates/plugins/semgrep/template.manifest.json

@@ -2,9 +2,6 @@
   "id": "semgrep",
   "stageId": "sast",
   "verificationStages": [
-    "typecheck",
-    "unit-tests",
-    "lint",
     "sast"
   ],
   "stage": {
@@ -23,14 +20,26 @@
         "path": ".har/artifacts/sast/semgrep.json",
         "kind": "report"
       }
-    ]
+    ],
+    "tier": "full"
   },
   "files": [
-    { "src": ".har/stages/sast.sh", "dest": ".har/stages/sast.sh", "executable": true },
-    { "src": ".har/stages/SEMGREP.md", "dest": ".har/stages/SEMGREP.md" }
+    {
+      "src": ".har/stages/sast.sh",
+      "dest": ".har/stages/sast.sh",
+      "executable": true
+    },
+    {
+      "src": ".har/stages/SEMGREP.md",
+      "dest": ".har/stages/SEMGREP.md"
+    }
   ],
   "optionalFiles": [
-    { "src": ".github/workflows/semgrep.yml", "dest": ".github/workflows/semgrep.yml", "skipFlag": "skipCi" }
+    {
+      "src": ".github/workflows/semgrep.yml",
+      "dest": ".github/workflows/semgrep.yml",
+      "skipFlag": "skipCi"
+    }
   ],
   "nextSteps": [
     "pipx install semgrep   # or: pip install semgrep / brew install semgrep",

package/dist/templates/plugins/trivy/.har/stages/vuln-scan.sh

@@ -16,20 +16,15 @@
 # See: ./.har/stages/TRIVY.md for the full adaptation guide.
 set -euo pipefail
 
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-HARNESS_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+# 1.0 stage surface: the runner exports WORK_DIR, ENV_FILE, AGENT_ID and
+# HAR_HARNESS_DIR, with harness.env and the slot env file already sourced —
+# agent-slot.sh is retired (1.0 migration).
+HARNESS_DIR="${HAR_HARNESS_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
 REPO_ROOT="$(cd "$HARNESS_DIR/.." && pwd)"
-# agent-slot.sh expects SCRIPT_DIR to be .har/ (slot registry lives there)
-SCRIPT_DIR="$HARNESS_DIR"
 
-# shellcheck source=/dev/null
-source "$HARNESS_DIR/harness.env"
-# shellcheck source=/dev/null
-source "$HARNESS_DIR/agent-slot.sh"
+AGENT_ID="${1:-${AGENT_ID:?Usage: vuln-scan.sh <agent-id>}}"
 
-AGENT_ID="${1:?Usage: vuln-scan.sh <agent-id>}"
-
-validate_agent_id "$AGENT_ID"
+now_ms() { node -e 'process.stdout.write(String(Date.now()))' 2>/dev/null || echo 0; }
 
 log() { echo "==> [vuln-scan agent-$AGENT_ID] $*" >&2; }
 
@@ -44,18 +39,8 @@ if ! command -v trivy >/dev/null 2>&1; then
 fi
 
 # ── Resolve agent env ─────────────────────────────────────────────────────────
-ENV_FILE="$(resolve_agent_env_file "$AGENT_ID" "$REPO_ROOT")" || {
-  echo "No .env.agent.${AGENT_ID} found." >&2
-  har_suggest_launch "$AGENT_ID" >&2
-  exit 1
-}
-
-set -a
-# shellcheck source=/dev/null
-source "$ENV_FILE"
-set +a
-
-WORK_DIR="$(resolve_agent_work_dir "$ENV_FILE")"
+ENV_FILE="${ENV_FILE:?No slot env for agent ${AGENT_ID} — run ./.har/launch.sh ${AGENT_ID} first}"
+WORK_DIR="${WORK_DIR:?No slot work dir for agent ${AGENT_ID} — run ./.har/launch.sh ${AGENT_ID} first}"
 
 # ── Configuration ─────────────────────────────────────────────────────────────
 SEVERITY="${HARNESS_TRIVY_SEVERITY:-HIGH,CRITICAL}"

package/dist/templates/plugins/trivy/README.md

@@ -9,7 +9,7 @@ agent's worktree:
   CloudFormation (Trivy absorbed tfsec, so this covers the Terraform use case)
 
 ```bash
-har env add-plugin trivy            # --skip-ci to omit the GitHub workflow
+har env add-plugin trivy            # --with-ci to include the GitHub workflow
 ```
 
 What it adds:

package/dist/templates/plugins/trivy/template.manifest.json

@@ -2,9 +2,6 @@
   "id": "trivy",
   "stageId": "vuln-scan",
   "verificationStages": [
-    "typecheck",
-    "unit-tests",
-    "lint",
     "vuln-scan"
   ],
   "stage": {
@@ -23,15 +20,30 @@
         "path": ".har/artifacts/vuln-scan/report.json",
         "kind": "report"
       }
-    ]
+    ],
+    "tier": "full"
   },
   "files": [
-    { "src": ".har/stages/vuln-scan.sh", "dest": ".har/stages/vuln-scan.sh", "executable": true },
-    { "src": ".har/stages/TRIVY.md",     "dest": ".har/stages/TRIVY.md" },
-    { "src": ".trivyignore",             "dest": ".trivyignore" }
+    {
+      "src": ".har/stages/vuln-scan.sh",
+      "dest": ".har/stages/vuln-scan.sh",
+      "executable": true
+    },
+    {
+      "src": ".har/stages/TRIVY.md",
+      "dest": ".har/stages/TRIVY.md"
+    },
+    {
+      "src": ".trivyignore",
+      "dest": ".trivyignore"
+    }
   ],
   "optionalFiles": [
-    { "src": ".github/workflows/trivy.yml", "dest": ".github/workflows/trivy.yml", "skipFlag": "skipCi" }
+    {
+      "src": ".github/workflows/trivy.yml",
+      "dest": ".github/workflows/trivy.yml",
+      "skipFlag": "skipCi"
+    }
   ],
   "nextSteps": [
     "Install trivy: brew install trivy (or https://trivy.dev/latest/getting-started/installation/)",

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

@@ -1,27 +1,3 @@
-# Agent ${AGENT_ID} — Development Environment
-
-> [`AGENTS.md`](../AGENTS.md) · [`.har/README.md`](./README.md) · [`stages.json`](./stages.json)
-
-## Environment
-
-| | |
-|--|--|
-| **Agent ID** | ${AGENT_ID} |
-| **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. 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
-```
-
-## Readiness
-
-Adapt this section for the repository. For pure CLI/library repos, full verify
-may be enough. If the project needs services, auth, seeded data, or a sample
-workflow, document the required credentials/default data and wire a smoke into
-`HARNESS_READINESS_CMD` or full verify.
-
 ## 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`)
@@ -45,21 +21,3 @@ 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}`
 
 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`.
-
-## Project commands
-
-```bash
-# TODO: adapt for this repository. Examples:
-# npm test
-# pytest -q
-# go test ./...
-# cargo test
-# make test
-```
-
-## 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
-- 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/do-not.md

@@ -0,0 +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
+- 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/environment.md

@@ -0,0 +1,12 @@
+## Environment
+
+| | |
+|--|--|
+| **Agent ID** | ${AGENT_ID} |
+| **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. 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
+```

package/dist/templates/profiles/cli/docs/claude-agent/project-commands.md

@@ -0,0 +1,10 @@
+## Project commands
+
+```bash
+# TODO: adapt for this repository. Examples:
+# npm test
+# pytest -q
+# go test ./...
+# cargo test
+# make test
+```

package/dist/templates/profiles/cli/docs/claude-agent/readiness.md

@@ -0,0 +1,6 @@
+## Readiness
+
+Adapt this section for the repository. For pure CLI/library repos, full verify
+may be enough. If the project needs services, auth, seeded data, or a sample
+workflow, document the required credentials/default data and wire a smoke into
+`HARNESS_READINESS_CMD` or full verify.

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

@@ -0,0 +1,9 @@
+## 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.

package/dist/templates/profiles/cli/docs/readme/intro.md

@@ -0,0 +1,7 @@
+# .har — Agent Harness (CLI / library profile)
+
+This directory is the **agent harness** for this repository. It lets AI coding agents run the project in isolated git worktrees with optional Docker-backed shared infra.
+
+Generated and maintained by [`har`](https://github.com/os-factory/har). Run `har env maintain` when the repo stack changes.
+
+**The harness is how you run this project.** Launch a slot to exercise the code in isolation; don't hand-roll setup. If a harness command fails, fix the harness or report it — don't silently fall back to ad-hoc commands.

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

@@ -0,0 +1,25 @@
+## Port & shared services (CLI profile)
+
+This profile has **no PM2 app ports** — agents run project commands directly in their worktree. Port variables in `harness.env` exist for optional test servers and for shared Docker infra.
+
+### Port allocation
+
+| Layer | Scope | Rule | On conflict |
+|-------|-------|------|-------------|
+| 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.
+
+### 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` |
+| 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`

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

@@ -0,0 +1,24 @@
+## Quick start
+
+**har CLI or MCP:**
+
+```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 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
+```
+
+Read **`stages.json`** and **`verificationStages`**. Optional: `har env add-plugin playwright`.

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

@@ -0,0 +1,22 @@
+## Verification contract
+
+Steps in `verify.sh` 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.
+
+| Mode | Command | Typical steps |
+|------|---------|---------------|
+| Quick | `har env verify <id>` or `verify.sh <id>` | Stock ecosystem smoke: compile / import / build conventions |
+| Full | `har env verify <id> --full` or `verify.sh <id> --full` | Stock conventional tests/lint + optional readiness smoke, **browser-e2e** when `stages/browser-e2e.sh` exists |
+
+The stock commands are deliberately generic conventions keyed by
+`HARNESS_ECOSYSTEM`. Replace them with the repository's real commands during
+adaptation; do not leave Node/npm, Python, Go, Rust, Java, or Ruby defaults in
+place when they do not match the project.
+
+For repos that need runtime services, distinguish health from usability. If the
+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.

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

@@ -0,0 +1,27 @@
+## What's in here
+
+**Yours — the configuration surface** (edit freely; drift tracking records adaptations):
+
+| File | Purpose |
+|------|---------|
+| `README.md` | This file — index of the harness |
+| `harness.env` | Schema-validated config: worktree default, `HARNESS_INFRA_SERVICES`, toolchain provisioning (`HARNESS_ECOSYSTEM`, `HARNESS_INSTALL_CMD`), migrate/seed commands |
+| `stages.json` | Registered stages, verification tiers, artifacts, slot limits, gate policy |
+| `stages/` | Project-owned stage scripts registered from `stages.json` |
+| `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 |
+| `STAGES.md` | Stage registry and script-contract guide |
+| `justfile` | Optional shortcuts (requires `just`) |
+
+**Generated shims and state** (don't edit — `har env eject` for full ownership):
+
+| 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 |
+| `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 |
+
+No PM2 or `ecosystem.agent.template.cjs` in this profile — agents run project commands directly in their worktree.

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

@@ -4,5 +4,60 @@
   "bundles": [
     { "id": "shared-kernel", "path": "runtime-bundles/shared-kernel" },
     { "id": "runtime-cli", "path": "har-boilerplate-cli" }
-  ]
+  ],
+  "capabilities": {
+    "processManager": "none",
+    "appPortLanes": false,
+    "infra": {
+      "defaultServices": [],
+      "portLanes": "db=15432:15432-15499"
+    },
+    "defaultStages": [
+      "setup-infra",
+      "launch",
+      "verify",
+      "status",
+      "teardown",
+      "typecheck",
+      "unit-tests",
+      "lint",
+      "readiness"
+    ],
+    "defaultEnvKeys": [
+      "HARNESS_PROJECT_NAME",
+      "HARNESS_USE_WORKTREE",
+      "HARNESS_FE_BASE_PORT",
+      "HARNESS_API_BASE_PORT",
+      "HARNESS_PORT_STEP",
+      "HARNESS_HEALTH_CHECK_PATH",
+      "HARNESS_INFRA_PORT_LANES",
+      "HARNESS_AGENT_SLOT_MIN",
+      "HARNESS_AGENT_SLOT_MAX",
+      "HARNESS_ECOSYSTEM",
+      "HARNESS_INFRA_SERVICES",
+      "HARNESS_DB_MIGRATE_CMD",
+      "HARNESS_DB_SEED_CMD"
+    ]
+  },
+  "docs": {
+    "README.md": [
+      "intro",
+      "what-s-in-here",
+      "quick-start",
+      "verification-contract",
+      "run-history",
+      "for-coding-agents",
+      "port-shared-services-cli-profile",
+      "maintaining-this-harness",
+      "session-lifecycle"
+    ],
+    "CLAUDE.agent.md": [
+      "intro",
+      "environment",
+      "readiness",
+      "definition-of-done",
+      "project-commands",
+      "do-not"
+    ]
+  }
 }

package/dist/templates/profiles/default/docs/claude-agent/definition-of-done.md

@@ -0,0 +1,24 @@
+## 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`)
+- [ ] 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
+
+### Session handoff
+
+After full verify and commit, stop and propose next steps. Never autonomously run
+`complete`, `teardown`, `git push`, or open a PR. **Default recommendation:** when
+`gh` or GitHub MCP is available, complete the slot **and** open a PR (push → PR →
+`har env complete` / `har_complete_environment`). Offer complete-only or something
+else as alternatives. If PR tooling is unavailable, recommend complete and report
+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).
+
+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/do-not.md

@@ -0,0 +1,10 @@
+## 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/profiles/default/docs/claude-agent/environment.md

@@ -0,0 +1,19 @@
+## 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. An occupied slot always blocks a new launch — run `./.har/teardown.sh ${AGENT_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 — `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
+```

package/dist/templates/profiles/default/docs/claude-agent/project-commands.md

@@ -0,0 +1,10 @@
+## Project commands
+
+```bash
+# TODO: adapt for this repository (see package.json, Makefile, pyproject.toml, CI, etc.)
+# npm run typecheck
+# pytest -q
+# go test ./...
+# cargo test
+# make test
+```

package/dist/templates/profiles/default/docs/claude-agent/readiness.md

@@ -0,0 +1,12 @@
+## Readiness
+
+Adapt this section for the repository. A passing health check means the process
+is alive; it does not automatically mean an agent can use the app.
+
+- **Health**: `./.har/agent-cli.sh ${AGENT_ID} health`
+- **Agent-usable smoke**: document the login/API/UI workflow agents should try,
+  or wire it into `HARNESS_READINESS_CMD` / full verify.
+- **Credentials/default data**: document any test users, tenants, projects, or
+  settings created by the harness.
+- **Skipped full-dev setup**: document anything intentionally omitted from the
+  upstream developer setup and the minimal substitute in `.har/`.

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

@@ -0,0 +1,11 @@
+## 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`.
+
+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`.
+
+| Service | Agent 1 (default) | Agent 2 (default) |
+|---------|-------------------|-------------------|
+| Frontend | 3010 | 3020 |
+| API | 8010 | 8020 |
+| Node debug | 9210 | 9220 |

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

@@ -0,0 +1,9 @@
+## 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.

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

@@ -0,0 +1,7 @@
+# .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/os-factory/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.