@osfactory/har 0.1.1

package/dist/templates/har-boilerplate-ios/teardown.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# Tear down an agent slot for iOS mobile app repos.
+# The session's git branch is KEPT by default so you can push it / open a PR —
+# pass --delete-branch to remove it too.
+#
+# Usage: ./.har/teardown.sh <agent-id> [--delete-branch]
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# shellcheck source=/dev/null
+source "$SCRIPT_DIR/harness.env"
+# shellcheck source=/dev/null
+source "$SCRIPT_DIR/agent-slot.sh"
+
+AGENT_ID="${1:?Usage: teardown.sh <agent-id> [--delete-branch]}"
+DELETE_BRANCH=false
+
+for arg in "${@:2}"; do
+  case "$arg" in
+    --delete-branch) DELETE_BRANCH=true ;;
+  esac
+done
+
+validate_agent_id "$AGENT_ID"
+
+echo "==> Tearing down agent ${AGENT_ID}..."
+
+REGISTRY_FILE="$(slot_registry_file "$AGENT_ID")"
+WORKTREE_PATH=""
+WORK_DIR=""
+BRANCH=""
+if [ -f "$REGISTRY_FILE" ]; then
+  WORKTREE_PATH="$(read_slot_field "$REGISTRY_FILE" worktreePath || true)"
+  WORK_DIR="$(read_slot_field "$REGISTRY_FILE" workDir || true)"
+  BRANCH="$(read_slot_field "$REGISTRY_FILE" branch || true)"
+fi
+[ -n "$WORKTREE_PATH" ] || WORKTREE_PATH="$HOME/worktrees/${HARNESS_PROJECT_NAME}-agent-${AGENT_ID}"
+
+rm -f "$REPO_ROOT/.env.agent.${AGENT_ID}"
+if [ -n "$WORK_DIR" ] && [ -d "$WORK_DIR" ]; then
+  rm -f "$WORK_DIR/.env.agent.${AGENT_ID}"
+fi
+
+if [ -d "$WORKTREE_PATH" ]; then
+  rm -f "$WORKTREE_PATH/.env.agent.${AGENT_ID}"
+  git -C "$REPO_ROOT" worktree remove "$WORKTREE_PATH" --force 2>/dev/null || rm -rf "$WORKTREE_PATH"
+  echo "✓ Removed worktree: $WORKTREE_PATH"
+fi
+git -C "$REPO_ROOT" worktree prune 2>/dev/null || true
+
+if [ -n "$BRANCH" ]; then
+  if [ "$DELETE_BRANCH" = true ]; then
+    git -C "$REPO_ROOT" branch -D "$BRANCH" 2>/dev/null || true
+    echo "✓ Deleted branch: $BRANCH"
+  else
+    echo "✓ Kept branch: $BRANCH (push it or delete with: git branch -D $BRANCH)"
+  fi
+fi
+
+remove_slot_registry "$AGENT_ID"
+
+echo "✓ Agent ${AGENT_ID} torn down"

package/dist/templates/har-boilerplate-ios/verify.sh

@@ -0,0 +1,165 @@
+#!/usr/bin/env bash
+# Verification pipeline for iOS mobile app repos — build and test with xcodebuild.
+# Outputs JSON to stdout, human-readable progress to stderr.
+#
+# Usage: ./.har/verify.sh <agent-id> [--full]
+#
+# Quick (default): build + unit-tests
+# Full (--full):   + lint (SwiftLint) + rocketsim-flows (if installed)
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# shellcheck source=/dev/null
+source "$SCRIPT_DIR/harness.env"
+# shellcheck source=/dev/null
+source "$SCRIPT_DIR/agent-slot.sh"
+
+AGENT_ID="${1:?Usage: verify.sh <agent-id> [--full]}"
+FULL=""
+
+for arg in "${@:2}"; do
+  [ "$arg" = "--full" ] && FULL=1
+done
+
+validate_agent_id "$AGENT_ID"
+
+ENV_FILE="$(resolve_agent_env_file "$AGENT_ID" "$REPO_ROOT")" || {
+  echo "No .env.agent.${AGENT_ID} found. Run: ./.har/launch.sh ${AGENT_ID}" >&2
+  exit 1
+}
+
+set -a
+# shellcheck source=/dev/null
+source "$ENV_FILE"
+set +a
+
+WORK_DIR="$(resolve_agent_work_dir "$ENV_FILE")"
+
+echo "==> Verifying agent ${AGENT_ID} in ${WORK_DIR}..." >&2
+
+# Build xcodebuild project/workspace flags
+xc_target_flags() {
+  if [ -n "${HARNESS_XCODE_WORKSPACE:-}" ] && [ -e "$WORK_DIR/${HARNESS_XCODE_WORKSPACE}" ]; then
+    echo "-workspace $WORK_DIR/${HARNESS_XCODE_WORKSPACE}"
+  elif [ -n "${HARNESS_XCODE_PROJECT:-}" ] && [ -e "$WORK_DIR/${HARNESS_XCODE_PROJECT}" ]; then
+    echo "-project $WORK_DIR/${HARNESS_XCODE_PROJECT}"
+  else
+    # Auto-detect: prefer workspace (CocoaPods), then project
+    local ws prj
+    ws="$(find "$WORK_DIR" -maxdepth 2 -name "*.xcworkspace" ! -path "*/\.*" 2>/dev/null | head -1 || true)"
+    prj="$(find "$WORK_DIR" -maxdepth 2 -name "*.xcodeproj" ! -path "*/\.*" 2>/dev/null | head -1 || true)"
+    if [ -n "$ws" ]; then echo "-workspace $ws"
+    elif [ -n "$prj" ]; then echo "-project $prj"
+    fi
+  fi
+}
+
+XC_FLAGS="$(xc_target_flags)"
+XC_SCHEME="${HARNESS_XCODE_SCHEME:-MyApp}"
+XC_DESTINATION="${HARNESS_IOS_DESTINATION:-platform=iOS Simulator,name=iPhone 16}"
+XC_DERIVED="${WORK_DIR}/build/DerivedData"
+
+OVERALL_PASS=true
+START_TOTAL=$(date +%s%3N 2>/dev/null || echo "0")
+RESULTS_JSON="[]"
+
+run_step() {
+  local name="$1"
+  local cmd="$2"
+  local start end elapsed exit_code output
+
+  printf "  → %-40s" "$name..." >&2
+  start=$(date +%s%3N 2>/dev/null || echo "0")
+
+  set +e
+  output=$(cd "$WORK_DIR" && eval "$cmd" 2>&1)
+  exit_code=$?
+  set -e
+
+  end=$(date +%s%3N 2>/dev/null || echo "0")
+  elapsed=$(( end - start ))
+
+  local pass_bool step_output_escaped
+  if [ "$exit_code" = "0" ]; then
+    echo "✓ (${elapsed}ms)" >&2
+    pass_bool="true"
+  else
+    echo "✗ (${elapsed}ms)" >&2
+    echo "$output" | head -40 | sed 's/^/    /' >&2
+    pass_bool="false"
+    OVERALL_PASS=false
+  fi
+
+  step_output_escaped=$(echo "$output" | head -50 | \
+    node -e "let d=''; process.stdin.on('data',c=>d+=c); process.stdin.on('end',()=>process.stdout.write(JSON.stringify(d.trim())))" \
+    2>/dev/null || echo '""')
+
+  RESULTS_JSON=$(echo "$RESULTS_JSON" | node -e "
+const fs = require('fs');
+let arr = JSON.parse(fs.readFileSync('/dev/stdin','utf8'));
+arr.push({name:'$name',pass:$pass_bool,ms:$elapsed,output:$step_output_escaped});
+process.stdout.write(JSON.stringify(arr));
+" 2>/dev/null || echo "$RESULTS_JSON")
+
+  if [ "$pass_bool" = "false" ] && [ -z "$FULL" ]; then
+    return 1
+  fi
+}
+
+# Build (compile-only — catches syntax errors and missing symbols)
+run_step "build" "xcodebuild build \
+  ${XC_FLAGS} \
+  -scheme \"${XC_SCHEME}\" \
+  -destination \"${XC_DESTINATION}\" \
+  -derivedDataPath \"${XC_DERIVED}\" \
+  CODE_SIGNING_ALLOWED=NO \
+  | xcbeautify 2>/dev/null || xcodebuild build \
+    ${XC_FLAGS} \
+    -scheme \"${XC_SCHEME}\" \
+    -destination \"${XC_DESTINATION}\" \
+    -derivedDataPath \"${XC_DERIVED}\" \
+    CODE_SIGNING_ALLOWED=NO" || { [ -z "$FULL" ] && true; }
+
+# Unit tests
+run_step "unit-tests" "xcodebuild test \
+  ${XC_FLAGS} \
+  -scheme \"${XC_SCHEME}\" \
+  -destination \"${XC_DESTINATION}\" \
+  -derivedDataPath \"${XC_DERIVED}\" \
+  CODE_SIGNING_ALLOWED=NO \
+  | xcbeautify 2>/dev/null || xcodebuild test \
+    ${XC_FLAGS} \
+    -scheme \"${XC_SCHEME}\" \
+    -destination \"${XC_DESTINATION}\" \
+    -derivedDataPath \"${XC_DERIVED}\" \
+    CODE_SIGNING_ALLOWED=NO" || { [ -z "$FULL" ] && true; }
+
+if [ -n "$FULL" ]; then
+  # SwiftLint — optional, skip gracefully when not installed
+  run_step "lint" "command -v \"${HARNESS_SWIFTLINT_CMD:-swiftlint}\" >/dev/null 2>&1 && \
+    \"${HARNESS_SWIFTLINT_CMD:-swiftlint}\" --quiet 2>&1 || echo 'swiftlint not installed — skipping'" || true
+
+  # RocketSim user-flow validation — installed via: har env add-stage rocketsim
+  run_rocketsim_flows_if_present "$SCRIPT_DIR" "$AGENT_ID" || true
+fi
+
+END_TOTAL=$(date +%s%3N 2>/dev/null || echo "0")
+TOTAL_MS=$(( END_TOTAL - START_TOTAL ))
+
+node -e "
+const results = $RESULTS_JSON;
+const overall = results.length > 0 && results.every(r => r.pass);
+const out = {
+  status: overall ? 'pass' : 'fail',
+  agent_id: $AGENT_ID,
+  total_ms: $TOTAL_MS,
+  stages: results,
+};
+process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+" 2>/dev/null || echo "{\"status\":\"fail\",\"agent_id\":${AGENT_ID},\"stages\":[]}"
+
+if [ "$OVERALL_PASS" = "false" ]; then
+  exit 1
+fi

package/dist/templates/stage-templates/playwright/.github/workflows/playwright.yml

@@ -0,0 +1,30 @@
+name: Playwright tests
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 18
+      - name: Install deps
+        run: npm ci
+      - name: Install browsers
+        run: npx playwright install --with-deps
+      - name: Run Playwright tests
+        env:
+          BASE_URL: ${{ secrets.BASE_URL }}
+          TEST_RESET_API: 'true'
+        run: npm run test:e2e:ci
+      - name: Upload Playwright HTML report
+        if: success() || failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-report
+          path: .har/artifacts/browser-e2e/playwright-report

package/dist/templates/stage-templates/playwright/.har/stages/PLAYWRIGHT.md

@@ -0,0 +1,21 @@
+# Playwright (browser-e2e)
+
+Adapt specs under `tests/` for your application. Full verification (`verify --full`) runs this stage when `stages/browser-e2e.sh` is present.
+
+| Directory | Purpose |
+|-----------|---------|
+| `tests/frontend/` | UI smoke and flows — extend when you add UI |
+| `tests/api/` | HTTP checks via Playwright `request` |
+| `tests/a11y/` | axe-core on key routes |
+
+## Run
+
+After `./.har/launch.sh <id>`:
+
+```bash
+./.har/stages/browser-e2e.sh <id>
+# included in:
+./.har/verify.sh <id> --full
+```
+
+Replace TODO selectors and paths in the scaffold specs during harness adaptation.

package/dist/templates/stage-templates/playwright/.har/stages/browser-e2e.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# Playwright browser/API/a11y tests for an agent slot.
+# Outputs JSON to stdout, human-readable progress to stderr.
+#
+# Usage: ./.har/stages/browser-e2e.sh <agent-id>
+# Prerequisite: ./.har/launch.sh <agent-id>
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HARNESS_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+REPO_ROOT="$(cd "$HARNESS_DIR/.." && pwd)"
+
+# shellcheck source=/dev/null
+source "$HARNESS_DIR/harness.env"
+# shellcheck source=/dev/null
+source "$HARNESS_DIR/agent-slot.sh"
+
+AGENT_ID="${1:?Usage: browser-e2e.sh <agent-id>}"
+validate_agent_id "$AGENT_ID"
+
+log() { echo "==> [browser-e2e agent-$AGENT_ID] $*" >&2; }
+
+ENV_FILE="$(resolve_agent_env_file "$AGENT_ID" "$REPO_ROOT")" || {
+  echo "No .env.agent.${AGENT_ID} found. Run: ./.har/launch.sh ${AGENT_ID}" >&2
+  exit 1
+}
+
+set -a
+# shellcheck source=/dev/null
+source "$ENV_FILE"
+set +a
+
+WORK_DIR="$(resolve_agent_work_dir "$ENV_FILE")"
+FE_PORT="${FE_PORT:-$(( HARNESS_FE_BASE_PORT + AGENT_ID * 10 ))}"
+API_PORT="${API_PORT:-$(( HARNESS_API_BASE_PORT + AGENT_ID * 10 ))}"
+
+export BASE_URL="${BASE_URL:-http://localhost:${FE_PORT}}"
+export API_URL="${API_URL:-http://localhost:${API_PORT}}"
+
+ARTIFACT_DIR="$REPO_ROOT/.har/artifacts/browser-e2e"
+mkdir -p "$ARTIFACT_DIR"
+
+log "Running Playwright against $BASE_URL (API: $API_URL)"
+log "Work dir: $WORK_DIR"
+
+START_TOTAL=$(date +%s%3N 2>/dev/null || echo "0")
+
+set +e
+cd "$WORK_DIR"
+PW_OUTPUT=$(npx playwright test 2>&1)
+PW_EXIT=$?
+set -e
+
+END_TOTAL=$(date +%s%3N 2>/dev/null || echo "0")
+TOTAL_MS=$(( END_TOTAL - START_TOTAL ))
+
+echo "$PW_OUTPUT" >&2
+
+REPORT_DIR="$ARTIFACT_DIR/playwright-report"
+REPORT_INDEX="$REPORT_DIR/index.html"
+
+node -e "
+const out = {
+  status: ${PW_EXIT} === 0 ? 'pass' : 'fail',
+  stageId: 'browser-e2e',
+  kind: 'test',
+  agent_id: ${AGENT_ID},
+  total_ms: ${TOTAL_MS},
+  urls: [
+    { label: 'frontend', url: process.env.BASE_URL || '${BASE_URL}' },
+    { label: 'api', url: process.env.API_URL || '${API_URL}' },
+  ],
+  artifacts: [
+    { path: '.har/artifacts/browser-e2e', kind: 'directory' },
+  ],
+};
+if (require('fs').existsSync('${REPORT_INDEX}')) {
+  out.artifacts.push({ path: '.har/artifacts/browser-e2e/playwright-report', kind: 'report' });
+}
+process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+"
+
+exit "$PW_EXIT"

package/dist/templates/stage-templates/playwright/README.md

@@ -0,0 +1,14 @@
+# Playwright HAR stage template
+
+This template was added by `har env add-stage playwright`. It registers a `browser-e2e` stage and scaffolds a minimal Playwright test suite.
+
+## Next steps
+
+```bash
+npm install
+npx playwright install
+./.har/launch.sh 1
+./.har/stages/browser-e2e.sh 1
+```
+
+See `.har/stages/PLAYWRIGHT.md` for adaptation checklist and layout.

package/dist/templates/stage-templates/playwright/package.fragment.json

@@ -0,0 +1,14 @@
+{
+  "scripts": {
+    "test:e2e": "playwright test",
+    "test:e2e:ui": "playwright test tests/frontend",
+    "test:e2e:api": "playwright test tests/api",
+    "test:e2e:a11y": "playwright test tests/a11y",
+    "test:e2e:headed": "playwright test --headed",
+    "test:e2e:ci": "playwright test --reporter=html --workers=2 --retries=2"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.40.0",
+    "axe-core": "^4.7.0"
+  }
+}

package/dist/templates/stage-templates/playwright/playwright.config.js

@@ -0,0 +1,30 @@
+// Playwright config tuned for HAR agent slots and CI.
+const { defineConfig, devices } = require('@playwright/test');
+
+module.exports = defineConfig({
+  testDir: './tests',
+  timeout: 30 * 1000,
+  expect: { timeout: 5000 },
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 2 : undefined,
+  reporter: [
+    ['list'],
+    ['html', { open: 'never', outputFolder: '.har/artifacts/browser-e2e/playwright-report' }],
+  ],
+  outputDir: '.har/artifacts/browser-e2e/test-results',
+  use: {
+    baseURL: process.env.BASE_URL || 'http://localhost:3000',
+    headless: true,
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
+    trace: 'on-first-retry',
+  },
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+  ],
+});

package/dist/templates/stage-templates/playwright/template.manifest.json

@@ -0,0 +1,44 @@
+{
+  "id": "playwright",
+  "stageId": "browser-e2e",
+  "verificationStages": [
+    "typecheck",
+    "unit-tests",
+    "api-health",
+    "lint",
+    "browser-e2e"
+  ],
+  "stage": {
+    "id": "browser-e2e",
+    "kind": "test",
+    "description": "Playwright E2E (frontend + API + a11y)",
+    "script": "stages/browser-e2e.sh",
+    "requiresAgentId": true,
+    "artifacts": [
+      {
+        "path": ".har/artifacts/browser-e2e",
+        "kind": "directory",
+        "description": "HTML report, traces, screenshots, videos"
+      },
+      {
+        "path": ".har/artifacts/browser-e2e/playwright-report",
+        "kind": "report"
+      }
+    ]
+  },
+  "files": [
+    { "src": ".har/stages/browser-e2e.sh", "dest": ".har/stages/browser-e2e.sh", "executable": true },
+    { "src": ".har/stages/PLAYWRIGHT.md", "dest": ".har/stages/PLAYWRIGHT.md" },
+    { "src": "playwright.config.js", "dest": "playwright.config.js" },
+    { "src": "tests/frontend/smoke.spec.js", "dest": "tests/frontend/smoke.spec.js" },
+    { "src": "tests/api/health.spec.js", "dest": "tests/api/health.spec.js" },
+    { "src": "tests/a11y/smoke.spec.js", "dest": "tests/a11y/smoke.spec.js" },
+    { "src": "README.md", "dest": "tests/playwright/README.md" }
+  ],
+  "optionalFiles": [
+    { "src": ".github/workflows/playwright.yml", "dest": ".github/workflows/playwright.yml", "skipFlag": "skipCi" }
+  ],
+  "merge": {
+    "package.json": "package.fragment.json"
+  }
+}

package/dist/templates/stage-templates/playwright/tests/a11y/smoke.spec.js

@@ -0,0 +1,14 @@
+const { test, expect } = require('@playwright/test');
+
+test('homepage passes axe critical/serious checks', async ({ page }) => {
+  await page.goto('/');
+  await page.addScriptTag({ path: require.resolve('axe-core/axe.min.js') });
+  const results = await page.evaluate(async () => {
+    // eslint-disable-next-line no-undef
+    return await axe.run();
+  });
+  const blocking = results.violations.filter(
+    (v) => v.impact === 'critical' || v.impact === 'serious',
+  );
+  expect(blocking).toEqual([]);
+});

package/dist/templates/stage-templates/playwright/tests/api/health.spec.js

@@ -0,0 +1,10 @@
+const { test, expect } = require('@playwright/test');
+
+// TODO: adapt path and expected body for your app's health endpoint
+test.describe('API smoke', () => {
+  test('health endpoint responds', async ({ request }) => {
+    const healthPath = process.env.HARNESS_HEALTH_PATH || '/health';
+    const res = await request.get(healthPath);
+    expect(res.ok()).toBeTruthy();
+  });
+});

package/dist/templates/stage-templates/playwright/tests/frontend/smoke.spec.js

@@ -0,0 +1,9 @@
+const { test, expect } = require('@playwright/test');
+
+// TODO: adapt heading text and routes for your app
+test.describe('Frontend smoke', () => {
+  test('homepage loads', async ({ page }) => {
+    await page.goto('/');
+    await expect(page.locator('body')).toBeVisible();
+  });
+});

package/dist/templates/stage-templates/rocketsim/.har/stages/ROCKETSIM.md

@@ -0,0 +1,126 @@
+# RocketSim User-Flow Validation
+
+The `rocketsim-flows` stage runs reusable bash scripts from `flows/` that interact with your iOS app on the simulator and validate its state. Full verify (`verify --full`) runs all flows automatically.
+
+## Flow script contract
+
+A flow is a bash script (`flows/<name>.sh`) that:
+
+1. Uses the `rocketsim` CLI to inspect the UI, interact with the app, and take screenshots
+2. Exits **0** on success (all assertions passed), **non-zero** on failure
+3. Writes human-readable progress to **stderr**
+4. Optionally saves screenshots to `$FLOW_ARTIFACT_DIR` (provided by the runner)
+
+The runner sets these environment variables for each flow:
+| Variable | Value |
+|----------|-------|
+| `FLOW_ARTIFACT_DIR` | Directory for screenshots and output of this flow |
+| `WORK_DIR` | Path to the agent's session worktree |
+| `HARNESS_BUNDLE_ID` | App bundle identifier (from `harness.env`) |
+| `HARNESS_SIMULATOR_NAME` | Target simulator name (from `harness.env`) |
+| `AGENT_ID` | Active agent slot id |
+
+## Key RocketSim CLI commands
+
+```bash
+# Health check
+rocketsim doctor
+
+# Check which simulator is focused
+rocketsim simulator focused
+
+# Read visible UI elements (compact format for agents)
+rocketsim elements --agent
+
+# Wait for screen to change after an interaction
+rocketsim wait screen-changed
+
+# Wait for a specific element to appear
+rocketsim wait element --label "Continue"
+
+# Tap by element label
+rocketsim interact tap --label "Continue"
+
+# Tap by type + label (more precise)
+rocketsim interact tap --type Button --label "Submit"
+
+# Tap at coordinates
+rocketsim interact tap 210 642
+
+# Swipe
+rocketsim interact swipe --direction up
+rocketsim interact swipe --from 200,650 --to 200,150
+
+# Type text
+rocketsim interact type "hello@example.com"
+
+# Press hardware button
+rocketsim interact button home
+
+# Take a screenshot (PNG bytes to stdout)
+rocketsim screenshot > "$FLOW_ARTIFACT_DIR/screen.png"
+```
+
+## Writing a new flow
+
+```bash
+#!/usr/bin/env bash
+# flows/my-feature.sh — Validate MyFeature after changes
+set -euo pipefail
+
+log() { echo "==> [my-feature] $*" >&2; }
+
+# 1. Snapshot the current screen
+rocketsim wait screen-changed --timeout 5 2>/dev/null || true
+ELEMENTS=$(rocketsim elements --agent)
+
+# 2. Assert expected element is present
+if echo "$ELEMENTS" | grep -q "My Feature Button"; then
+  log "✓ My Feature Button visible"
+else
+  log "✗ My Feature Button not found"
+  rocketsim screenshot > "$FLOW_ARTIFACT_DIR/failure.png"
+  exit 1
+fi
+
+# 3. Interact
+rocketsim interact tap --label "My Feature Button"
+rocketsim wait screen-changed
+
+# 4. Assert outcome
+AFTER=$(rocketsim elements --agent)
+if echo "$AFTER" | grep -q "Expected Result Label"; then
+  log "✓ Expected result is visible"
+  rocketsim screenshot > "$FLOW_ARTIFACT_DIR/success.png"
+else
+  log "✗ Expected result not visible"
+  rocketsim screenshot > "$FLOW_ARTIFACT_DIR/failure.png"
+  exit 1
+fi
+```
+
+## Running flows
+
+```bash
+# All flows
+./.har/stages/rocketsim-flows.sh 1
+
+# Single flow
+./.har/stages/rocketsim-flows.sh 1 example-smoke
+
+# Included in full verify
+./.har/verify.sh 1 --full
+```
+
+Screenshots and per-flow logs are saved under `.har/artifacts/rocketsim-flows/`.
+
+## Guidelines for agents creating flows
+
+- **One flow per user journey** — keep flows focused: login, onboarding, settings, a specific feature.
+- **Validate after each action** — use `rocketsim wait screen-changed` or `wait element` before asserting.
+- **Take a screenshot on failure** — always save `$FLOW_ARTIFACT_DIR/failure.png` on assertion failures so humans can diagnose problems.
+- **Take a screenshot on success** — save `$FLOW_ARTIFACT_DIR/success.png` as visual confirmation.
+- **Use label-based selectors** — prefer `--label` over raw coordinates; coordinates break when layout changes.
+- **Reset state** — if the flow navigates away from the start screen, navigate back at the end.
+- **Name flows for their user journey** — `onboarding.sh`, `login.sh`, `settings-notification-toggle.sh`.
+- **Add a new flow for every new UI feature** — this ensures regressions are caught on future changes.