@ironbee-ai/cli 0.15.0 → 0.16.0

package/dist/clients/codex/platforms/command-verify.browser.md

@@ -0,0 +1,108 @@
+<!-- Browser cycle verification is ENABLED for this project. The Stop hook
+     enforces a browser cycle whenever an edited file matches
+     `browser.verifyPatterns`. The `/ironbee-verify` slash command's mode
+     arguments (default / full / visual / functional) tune the depth of the
+     browser-cycle pass. -->
+
+## Mode arguments (browser cycle)
+
+- `/ironbee-verify` — **default** — focus on what changed, visual + functional checks on affected areas
+- `/ironbee-verify full` — **full scope** — entire application, all checklists, edge cases, responsive, accessibility deep dive
+- `/ironbee-verify visual` — **visual only** — contrast, layout, spacing, fonts, images, theming
+- `/ironbee-verify functional` — **functional only** — clicks, forms, navigation, data flow, error handling
+
+If no argument is given, use **default** mode. `default` and `full` apply to every active cycle (browser, node, backend) — each cycle interprets them in its own terms (see each platform section). `visual` and `functional` apply ONLY to the browser cycle; other active cycles run in `default` mode when these are passed.
+
+## Browser steps (all modes)
+
+1. **Start verification**: Run `echo '{"session_id":"<your-session-id>"}' | ironbee hook verification-start` via Bash (substitute the actual session ID printed by the SessionStart hook).
+2. **Build and start** the application if not already running
+3. **For EVERY page you visit**, repeat this cycle:
+   a. **Navigate** using `mcp__browser-devtools__bdt_navigation_go-to`
+   b. **Take a FULL PAGE screenshot** using `mcp__browser-devtools__bdt_content_take-screenshot` with `fullPage: true`
+   c. **Take an ARIA snapshot** using `mcp__browser-devtools__bdt_a11y_take-aria-snapshot`
+   d. **STOP and visually analyze the screenshot** — switch your focus entirely to finding visual problems. Look at this screenshot as if your ONLY job is to find visual defects:
+      **WARNING: ARIA reports DOM content, not what the user actually sees.** Do NOT assume the page looks correct just because ARIA shows the right content. Only the screenshot tells you what the user actually sees.
+      - Text readability — is it readable against its background? Look for text that blends in or poor contrast
+      - Layout — overlapping elements, unexpected gaps, overflow, content cut off
+      - Spacing — consistent padding/margin? Too cramped or too far apart?
+      - Colors — intentional and consistent? Any jarring mismatches?
+      - Typography — right sizes? Clipped or truncated text?
+      - Images/icons — loaded? Right size and aspect ratio?
+      - States — empty, loading, disabled, error states rendered properly?
+      Report your visual findings before continuing.
+   e. **Read the ARIA snapshot** — verify headings, labels, landmarks, and structure
+   f. If anything looks wrong → note it as an issue
+4. **Functionally test** — run the checklist for your mode (see below). After each significant interaction, take another screenshot and repeat the visual analysis.
+5. **Check console** for errors using `mcp__browser-devtools__bdt_o11y_get-console-messages`
+6. **Stop** the dev server when verification is complete
+7. **If recording was started, stop it now** — `mcp__browser-devtools__bdt_content_stop-recording`. submit-verdict rejects with `"recording is still active"` when this step is skipped. (Recording is a server-side opt-in via `recording.enable` — when on, the gate forces `mcp__browser-devtools__bdt_content_start-recording` BEFORE the steps above and demands the matching stop here.)
+8. **Submit your verdict** via Bash:
+    - Pass: `echo '{"session_id":"...","status":"pass","checks":["..."]}' | ironbee hook submit-verdict`
+    - Fail: `echo '{"session_id":"...","status":"fail","checks":["..."],"issues":["describe what failed"]}' | ironbee hook submit-verdict`
+9. **If failed** → collect ALL issues first (finish testing all affected pages), submit one fail verdict with all issues, then fix everything, rebuild, and re-verify. Do not fix one issue at a time — batch fixes to avoid repeated build/restart cycles.
+10. If pass after a previous fail, include `"fixes"` in the verdict describing what was fixed
+
+---
+
+## Default Mode
+
+Focus on the code you changed — not the entire application.
+
+### 1. Study the changes
+1. Run `git diff --name-only` and `git diff --name-only HEAD~1`
+2. **Ignore `.ironbee/`, `.claude/`, `.cursor/`** — tool config, not application code
+3. **Read the full diff** (`git diff` and/or `git diff HEAD~1`) — understand every change: what was added, removed, modified. Note specific values (colors, sizes, conditions, logic, API endpoints, component props).
+4. Before opening the browser, you should be able to answer: what exactly changed, what should look or behave differently, and what could go wrong?
+
+### 2. Verify in the browser
+- **Cross-reference the diff against what you see.** For each change in the diff, verify it is correctly reflected in the browser. If the diff changes a color → check that color. If it changes a calculation → verify the result. If it adds a component → confirm it renders.
+- **Test the flow end-to-end** — navigate, click, fill forms, submit, verify the outcome
+- **Check one edge case** — empty input, invalid data, or double-click
+- **Console** — any new errors or warnings?
+
+---
+
+## Full Mode (`/ironbee-verify full`)
+
+Comprehensive verification of the **entire application**. Do NOT run `git diff` or scope to recent changes. Test every page, every flow, every visual detail. Any issue is a failure, regardless of when it was introduced.
+
+### Visual Checklist
+In addition to the per-page visual analysis in step 3d:
+- **Responsiveness** — does the layout adapt if viewport changes? No horizontal scrolling on standard widths
+- **Borders & separators** — visible and consistent? Not too faint or missing
+- **Scroll behavior** — does the page scroll smoothly? No content hidden behind sticky headers/footers?
+
+### Functional Checklist
+- **Navigation** — do links and buttons navigate to the correct pages?
+- **Forms** — fill inputs with real data, select options, submit. Do validation messages appear correctly?
+- **Buttons & interactions** — do click handlers fire? Do toggles, dropdowns, and modals work?
+- **Data flow** — does submitted data appear where expected?
+- **Error handling** — what happens with invalid input? Does the UI handle errors gracefully?
+- **Authentication** — if applicable, do protected routes redirect correctly?
+- **API calls** — do network requests succeed? Check for failed requests in console/network
+- **State persistence** — does state survive page refresh where expected?
+- **Edge cases** — empty inputs, very long text, special characters, rapid clicks
+
+### Accessibility (deep dive)
+- Are headings hierarchical? Do form inputs have labels? Are landmarks present?
+- Check for missing alt text on images
+
+---
+
+## Visual Mode (`/ironbee-verify visual`)
+
+Focus exclusively on visual quality. Run the per-page visual analysis from step 3d on every page, plus:
+- **Responsiveness** — viewport changes, no horizontal scrolling
+- **Borders & separators** — visible and consistent?
+- **Scroll behavior** — smooth scrolling, no hidden content
+
+Take screenshots of **multiple states** if applicable (hover, active, disabled, empty, populated).
+
+---
+
+## Functional Mode (`/ironbee-verify functional`)
+
+Focus exclusively on behavior. Use the same functional checklist as Full Mode above.
+
+Test the **complete user flow**, not just the single step you changed.

package/dist/clients/codex/platforms/command-verify.node.md

@@ -0,0 +1,61 @@
+<!-- Node backend verification is ENABLED for this project. -->
+
+## Backend Node Mode (when `node.verifyPatterns` matches an edited file)
+
+> **Precondition: the backend must actually be Node.js.** If you see `pom.xml`, `build.gradle`, `requirements.txt`, `pyproject.toml`, `go.mod`, `Cargo.toml`, etc., this section does NOT apply — `ndt_*` tools won't connect to non-Node processes. Just do browser verification.
+
+If the project has node backend verification enabled (`ironbee node enable` once at setup, by an operator who confirmed the backend is Node.js) and your edits touch matching paths (e.g. `server/**`, `pages/api/**`), the Stop hook also enforces a Node cycle. The same `verification-start` covers both cycles; one platform-agnostic verdict covers both.
+
+### Mode behavior (node cycle)
+- **default** (no arg or `default`): probe / log only the code paths your diff touched. Map each changed file → the handler(s) it affects → place probes there.
+- **full**: probe / log every Node code path reachable from files matching `node.verifyPatterns`, not just the changed files. Expect a much larger probe set and longer runtime.
+- `visual` / `functional`: browser-only modes; this cycle behaves as `default` when they are passed.
+
+### Steps (additive to the browser flow above)
+1. **Identify the running Node process** — note its PID, container name (`docker compose ps`), or inspector port.
+2. **Connect**: `mcp__node-devtools__ndt_debug_connect` with one of `pid` / `processName` / `containerId` / `containerName` / `inspectorPort` / `wsUrl`. Inspector is auto-activated via SIGUSR1 if needed.
+3. **Pick an evidence path** for each changed code path:
+   - **Probe path** (proves the code path executed): `mcp__node-devtools__ndt_debug_put-tracepoint` (or `put-logpoint` / `put-exceptionpoint`) at the changed code, exercise the path (e.g. trigger the API call from the browser), then `mcp__node-devtools__ndt_debug_get-probe-snapshots`. At least one probe must come back with `triggered: true`.
+   - **Log path** (proves no errors): exercise the path, then `mcp__node-devtools__ndt_debug_get-logs` with the error level filter.
+4. **Disconnect** (optional): `mcp__node-devtools__ndt_debug_disconnect`.
+5. **Submit verdict** — platform-agnostic, just status + checks (+ issues/fixes).
+
+### Verdict (platform-agnostic)
+```json
+{
+  "session_id": "...",
+  "status": "pass",
+  "checks": ["POST /api/orders returned 201", "tracepoint at handler.ts:42 fired once"]
+}
+```
+
+For a multi-cycle pass, both browser and node pass criteria must hold.
+
+---
+
+## Default Mode (node cycle)
+
+Focus on the code you changed — not the entire Node service.
+
+### 1. Study the changes
+1. Run `git diff --name-only` and `git diff --name-only HEAD~1`
+2. **Ignore `.ironbee/`, `.claude/`, `.cursor/`** — tool config, not application code
+3. **Read the full diff** for every Node file in scope (handler / route / service / middleware) — note new branches, new validations, new error paths, new external calls, changed return values
+4. Before connecting, you should be able to answer: which function(s) execute on the changed path? Where does a tracepoint prove the new code fired? What error logs would prove a regression?
+
+### 2. Verify against the running process
+- **Place a probe at each changed code site** — `mcp__node-devtools__ndt_debug_put-tracepoint` for "did it run", `put-logpoint` for variable capture, `put-exceptionpoint` for new throw branches
+- **Exercise the path end-to-end** (trigger from browser, curl, or the backend cycle if active)
+- **Each touched probe must report `triggered: true`** in `mcp__node-devtools__ndt_debug_get-probe-snapshots`
+- **Check one edge case per new branch** — invalid input, missing field, auth failure, …
+- **Logs** — `mcp__node-devtools__ndt_debug_get-logs` at error level; no ERROR-level entries are expected for `pass`
+
+---
+
+## Full Mode (`/ironbee-verify full`, node cycle)
+
+Probe every Node code path reachable from files matching `node.verifyPatterns`, not just the changed files. Do NOT run `git diff` or scope to recent changes.
+
+- Place probes at every handler / route / service entry point in scope, plus key internal branch points (early returns, error catches, conditional middleware)
+- Exercise each path with at least one happy-path call AND one failure-path call
+- No ERROR-level log entries are expected after the full run — any unexpected log error is a fail, regardless of when it was introduced

package/dist/clients/codex/platforms/rule.backend.md

@@ -0,0 +1,32 @@
+<!-- Backend protocol verification is ENABLED for this project. The Stop hook
+     enforces a backend cycle in addition to the browser cycle whenever an
+     edited file matches `backend.verifyPatterns`. -->
+
+## Backend cycle (runtime-agnostic protocol verification)
+
+When the file matches `backend.verifyPatterns`, the Stop hook ALSO requires verification through the **backend-devtools** MCP server (prefix `bedt_`). The cycle is satisfied by **any one of three** evidence paths: a real protocol call (HTTP / gRPC / GraphQL / WebSocket) against the running service, log inspection from the running service (file / docker / kubernetes) when an external driver is hitting the endpoint, OR direct database inspection for schema / data-state changes. Pick whichever fits the task — language- and framework-independent in all three cases.
+
+The backend cycle and the node cycle are **independent**. Node attaches to a Node.js V8 inspector with non-blocking probes (`ndt_*`); backend drives wire protocols and/or reads logs / DB state from outside (`bedt_*`). They can be active in the same task; both must be satisfied for `status: pass`.
+
+### Backend-cycle additions to the main flow
+
+These attach to the **Required steps** above — they don't replace any step. Numbering follows the main flow:
+
+- **Within step 3 (run flow):** also run the backend flow via ONE of three evidence paths:
+  - **Protocol-call** — identify the affected endpoint(s) → call the matching protocol tool (`bedt_request_http` / `bedt_request_grpc` / `bedt_request_graphql` / `bedt_request_websocket-open` / `bedt_request_replay`) → inspect status / body / `traceId` → chain follow-up calls when verifying side effects. **A 4xx / 5xx response is a normal result, not an error** — only transport failures populate the `error` field.
+  - **Log evidence** — `bedt_log_register-source` (file / docker / kubernetes) → `bedt_log_read` (point-in-time, supports `tail` / `since-until` / `pattern` / `level` / `parseJson` + `jsonFilter` / `contextBefore-After` / `select` / `coalesce`) OR `bedt_log_follow` + `bedt_log_get-followed` (streaming). Fit for jobs / queue workers / async handlers, or any case where an external driver is hitting the endpoint and you only need to verify what the server logged. `bedt_log_register-source` is mandatory on this path (the gate counts it as the setup step).
+  - **DB evidence** — `bedt_db_connect` (named, `connectionStringEnv` preferred, default readonly) → ONE of `bedt_db_query` / `bedt_db_describe-table` / `bedt_db_list-tables` / `bedt_db_snapshot` (+ optional `bedt_db_diff`) / `bedt_db_get-changes`. Fit for migrations, seed-data changes, query-result regressions, and any code change whose side effect lives in a relational DB. `bedt_db_connect` is mandatory on this path (same anti-fluke rule as `log-evidence` — the connection name is on the wire).
+- **Within step 6 (submit verdict):** submit one platform-agnostic verdict (`status` + `checks` + optionally `issues` / `fixes`). The gate requires that at least one evidence path (protocol-call, log-evidence, or DB-evidence) was exercised in your `bedt_*` tool calls.
+
+### Trace correlation (`o11y_*` is auxiliary, not evidence)
+
+IronBee already injects the active verification `traceId` into every backend tool call via `_metadata.traceId`. That id outranks anything `bedt_o11y_new-trace-id` / `bedt_o11y_set-trace-context` would pin for the cycle, so the orchestrator's correlation root stays authoritative. The `o11y_*` tools are still useful for log searches (`bedt_log_read { pattern: traceId }` against an explicit id), but they don't count toward the gate.
+
+### Additional BANNED for backend cycle
+
+- Calling `bedt_*` tools without first opening a verification cycle (`ironbee hook verification-start`).
+- Treating a 4xx / 5xx response as a transport failure when the test was specifically asking for that error condition (e.g. "POST should reject malformed body with 400"). Decide PASS/FAIL based on the test's intent, not the status code's HTTP-class default.
+- Claiming `status: pass` for a backend cycle without exercising at least one evidence path (no `bedt_request_*` call, no `bedt_log_register-source` + read, no `bedt_db_connect` + read). The gate will reject.
+- Inferring backend behavior by reading code without exercising any evidence path. The cycle is satisfied only by making a real protocol call, reading real logs, or inspecting real DB state on the running service.
+- Reading a pre-existing log source / DB unrelated to your task to fake the log-evidence or db-evidence path. `bedt_log_register-source` and `bedt_db_connect` are required setup steps on those paths so the registration / connection is on the wire.
+- Opening a DB connection with `allowWrites: true` to "set up" verification data without an explicit need (seed / migration). Read-only is the default for a reason — flipping it widens the blast radius if a query goes wrong.

package/dist/clients/codex/platforms/rule.browser.md

@@ -0,0 +1,17 @@
+<!-- Browser cycle verification is ENABLED for this project. The Stop hook
+     enforces a browser cycle whenever an edited file matches
+     `browser.verifyPatterns`. -->
+
+**Browser cycle** — frontend file changes (default: most code extensions). Tools come from the **browser-devtools** MCP server (prefix `bdt_`). Verification means navigating to the affected page and FUNCTIONALLY exercising the change in the browser — clicking, typing, submitting — not just looking at it.
+
+## Browser flow steps
+
+Run the **Browser cycle** flow when an edited file activates it: navigate (`bdt_navigation_go-to`) → functionally test → screenshot (`bdt_content_take-screenshot`) → accessibility (`bdt_a11y_take-aria-snapshot`) → console (`bdt_o11y_get-console-messages`). All four are MANDATORY.
+
+- If `recording.enable` is on, the gate forces `bdt_content_start-recording` BEFORE the steps above and rejects the verdict if you don't call `bdt_content_stop-recording` AFTER them. Always pair start/stop around the steps above.
+- The verdict you submit carries only semantic judgment (`status`, `checks`, optionally `issues` / `fixes`). The gate enforces that the required `bdt_*` tools were called and that `checks` is non-empty.
+
+## Browser-cycle BANNED
+
+- Calling `bdt_*` tools without first opening a verification cycle (`ironbee hook verification-start`).
+- **Submitting a verdict while a browser recording is still active** — always call `bdt_content_stop-recording` BEFORE `ironbee hook submit-verdict`. The recording start/stop pair brackets the verification flow.

package/dist/clients/codex/platforms/rule.node.md

@@ -0,0 +1,28 @@
+<!-- Node backend verification is ENABLED for this project. The Stop hook
+     enforces a node cycle in addition to the browser cycle whenever an
+     edited file matches `node.verifyPatterns`. -->
+
+## Node cycle
+
+Backend file changes IF the file matches `node.verifyPatterns` ALSO require verification through the **node-devtools** MCP server (prefix `ndt_`). Node-cycle verification means attaching to the running Node process via the V8 inspector, setting a probe (tracepoint / logpoint / exceptionpoint) at the changed code, exercising the path so the probe fires, and reading snapshots — OR inspecting runtime error logs.
+
+Both cycles can be active simultaneously (e.g. you edit both a React component and an API handler in the same task). One `verification-start` covers all active cycles; one platform-agnostic verdict covers them all; one retry counter applies globally.
+
+### ⚠️ `node-devtools` is ONLY for Node.js backends
+
+`node-devtools` is a V8 inspector wrapper. It does NOT work for Java, Python, Go, Rust, Ruby, .NET, PHP, or any other runtime. If you see `pom.xml`, `build.gradle`, `requirements.txt`, `pyproject.toml`, `go.mod`, `Cargo.toml`, etc., the backend is NOT Node.js and you must NOT call `ndt_*` tools — they will fail to connect to non-Node processes.
+
+**Misconfiguration recovery.** If you reach this state, the operator enabled the node cycle for a non-Node project by mistake. The Stop hook will keep blocking with `incomplete_tools` for the node cycle until you call `ndt_debug_connect` (which will fail) or until `maxRetries` is exhausted. Don't attempt the connection. Instead, stop and clearly report to the user: the project's backend is not Node.js, and they must run `ironbee node disable` to unblock the gate. Continue with browser-cycle verification only in the meantime.
+
+### Node-cycle additions to the main flow
+
+These attach to the **Required steps** above — they don't replace any step. Numbering follows the main flow:
+
+- **Within step 3 (run flow):** also run the node flow: connect (`ndt_debug_connect`) → set probe (`ndt_debug_put-tracepoint` / `put-logpoint` / `put-exceptionpoint`) AND exercise + read snapshots (`ndt_debug_get-probe-snapshots`), OR exercise + read logs (`ndt_debug_get-logs`). When both browser and node cycles are active, run BOTH within the same verification cycle.
+- **Within step 6 (submit verdict):** submit one platform-agnostic verdict with `status` + `checks` (+ `issues`/`fixes` as needed). Node-cycle pass criteria: process connected, probe triggered (or log path used with no ERROR entries).
+
+### Additional BANNED for node cycle
+
+- Calling `ndt_*` tools without first opening a verification cycle (`ironbee hook verification-start`).
+- **Calling `ndt_*` tools when the project's backend is NOT Node.js** (Java / Python / Go / Rust / .NET / Ruby / PHP / Elixir / etc.). Use the browser cycle only for non-Node backends.
+- Claiming `status: pass` for a node cycle when no probe triggered AND no log path was used — those criteria must hold.

package/dist/clients/codex/platforms/skill.backend.md

@@ -0,0 +1,95 @@
+<!-- Backend protocol verification is ENABLED for this project. The Stop hook
+     enforces a backend cycle in addition to the browser cycle whenever an
+     edited file matches `backend.verifyPatterns`. The cycle is runtime- and
+     language-agnostic — it binds to wire protocols, not frameworks. -->
+
+## Backend cycle — runtime- and language-agnostic
+
+The **backend protocol cycle** verifies backend changes by driving real protocol calls (HTTP / gRPC / GraphQL / WebSocket) against the running service and reading the responses, OR by inspecting the logs of the running service (file / docker / kubernetes) when an external driver is hitting the endpoint. It works for ANY backend runtime: Node, Java, Python, Go, Rust, Ruby, .NET, PHP, Elixir, Kotlin, Scala — the agent never attaches to a process.
+
+**This is different from the node cycle.** Node-cycle (`ndt_*`) attaches to a V8 inspector and sets non-blocking probes inside a running Node.js process — it's Node-only. Backend-cycle (`bedt_*`) makes outside-in protocol calls and/or reads logs of any service. They can be active at the same time when both are enabled.
+
+## Backend flow (three evidence paths — at least one is required)
+
+You can satisfy the cycle via **protocol-call evidence** (you drive the request yourself), **log evidence** (something else drives the request, you read the resulting logs), **DB evidence** (you inspect database state directly), or any combination. Pick whichever fits the task; one is enough.
+
+### Path A — Protocol-call evidence
+
+1. **Confirm a backend service is running** (the user's dev server, Docker compose, k8s port-forward, …). The agent itself does not start the service — ask the user if uncertain.
+2. **Identify the affected endpoint(s)** for your code change. Look at routes / handlers / controllers in the changed files. Map them to wire-level addresses (URL, gRPC service+method, GraphQL operation name, WebSocket path).
+3. **Make a real protocol call** with one of:
+   - **HTTP/1.1 + HTTP/2**: `mcp__backend-devtools__bedt_request_http` — full method/headers/body/query/follow-redirects support; ALPN auto-negotiates H2 on TLS, falls back to H1.1.
+   - **gRPC**: `mcp__backend-devtools__bedt_request_grpc` — unary + 3 streaming modes; pass `.proto` text or descriptor.
+   - **GraphQL**: `mcp__backend-devtools__bedt_request_graphql` — query/mutation, variables, persisted query support.
+   - **WebSocket** (stateful — open/send/receive/close cycle):
+     - `mcp__backend-devtools__bedt_request_websocket-open` — establish session.
+     - `mcp__backend-devtools__bedt_request_websocket-send` / `bedt_request_websocket-receive` — exchange frames.
+     - `mcp__backend-devtools__bedt_request_websocket-close` — clean teardown (and `bedt_request_websocket-list` for running sessions).
+   - **Replay**: `mcp__backend-devtools__bedt_request_replay` — re-issue a captured curl command or HAR entry.
+4. **Inspect the response** — `status` (HTTP / gRPC code), body, headers, returned `traceId` (always W3C `traceparent`).
+   **`4xx/5xx and gRPC non-OK are normal results, not errors.** A test for "404 Not Found" SHOULD return 404. Only transport-level failures (DNS, TLS, timeout, abort) populate the response's `error` field. Decide PASS/FAIL based on what your task actually requires.
+5. **Chain follow-up calls** if you need to verify side effects (e.g. POST then GET to confirm the new resource is readable). Use `bedt_request_set-default-headers` to pin auth tokens once per host, `bedt_request_set-cookies` for session cookies — both stay scoped to that target across calls.
+
+### Path B — Log evidence (when an external driver hits the endpoint)
+
+Useful when an integration test, the user, or a deploy script is already driving the protocol — your job is to verify "side B" by reading what the server logged. Also a fit for jobs / queue workers / cron handlers where there is no synchronous request to make.
+
+1. **Register the log source** with `mcp__backend-devtools__bedt_log_register-source` — pick `type: "file"` for any process whose stdout is redirected to a file, `type: "docker"` for a container (`container: "<name|id>"`), `type: "kubernetes"` for a pod (`pod`, optionally `kubernetesContainer` / `namespace`). Source names are session-unique; re-register to overwrite. Listing/check helpers: `bedt_log_list-sources`, `bedt_log_check-source`.
+2. **Read or follow the source**:
+   - `mcp__backend-devtools__bedt_log_read` / `bedt_log_read-multi` — point-in-time read across one or many sources. Filters: `tail` (last N lines), `since` / `until` (ISO-8601 — natively docker; file sources require `parseJson: true` so timestamp is extracted from a JSON field), `pattern` (substring; use for trace-id correlation), `level` (ERROR/WARN/INFO/DEBUG/TRACE/FATAL), `limit`, `parseJson`, `jsonFilter` (dot-path equality predicates against parsed JSON), `contextBefore` / `contextAfter`, `select` (dot-path projection to trim verbose JSONL), `coalesce` (fold multi-line stack traces into one line).
+   - `mcp__backend-devtools__bedt_log_follow` — open a streaming subscription that pushes lines into a ring buffer; `bedt_log_get-followed` drains it on demand; `bedt_log_stop-follow` tears it down. Use this when you need to capture logs that emit AFTER your trigger.
+3. **Verify the lines you got match the expectation** — error gone, expected log line present, trace-id chained through. Plain-text and JSON sources are both supported; JSON sources accept structural predicates (`jsonFilter: { 'level': 'error', 'route': '/api/orders' }`).
+4. **Unregister when done** — `bedt_log_unregister-source` cleans up. Optional; the session tears them down at end too.
+
+### Path C — DB evidence (when the change touches database state)
+
+Best fit for schema migrations, seed-data changes, query-result regressions, and any backend change whose side effect is visible in a relational DB. The agent opens a named, read-only-by-default connection and inspects the state — no need to drive a protocol call when the verification IS reading the DB.
+
+1. **Open a named connection** with `mcp__backend-devtools__bedt_db_connect` — `type: "postgres" | "mysql" | "sqlite"`, `connectionString` or (preferred) `connectionStringEnv`. Default is `allowWrites: false` (server-side READ ONLY mode); only set `allowWrites: true` if you need to seed test data. The session can hold multiple named connections side-by-side (`bedt_db_list-connections` to inspect).
+2. **Inspect state** — pick the tool that fits:
+   - `mcp__backend-devtools__bedt_db_list-tables` — discover tables.
+   - `mcp__backend-devtools__bedt_db_describe-table` — verify schema (columns / types / indexes / FKs) after a migration.
+   - `mcp__backend-devtools__bedt_db_query` — run an arbitrary read query (`SELECT count(*) FROM orders WHERE …`, etc.). Always parameterized — the gate honors readonly mode.
+   - `mcp__backend-devtools__bedt_db_snapshot` + `bedt_db_diff` — pre/post state diff for verifying that a code path changed exactly the rows it should.
+   - `mcp__backend-devtools__bedt_db_watch-changes` + `bedt_db_get-changes` — streaming change capture when a protocol call (or external driver) triggers writes you want to verify after the fact.
+3. **(Optional) Seed / migrate** — `bedt_db_seed` (structured) and `bedt_db_run-script` (raw SQL) write data; both require `allowWrites: true` at connect time. Use sparingly and prefer per-test transactions (`bedt_db_transaction-begin` / `-commit` / `-rollback`) so the seed doesn't leak across tests.
+4. **Disconnect when done** — `bedt_db_disconnect` releases the connection cleanly. Optional; the session tears them down at end too.
+
+### Trace correlation across paths (`o11y_*` primitives)
+
+The IronBee verification cycle already pins a W3C trace id on every backend tool call via `_metadata.traceId` (see `require-verification`). It outranks any trace pin the agent sets, so you usually don't need the `o11y_*` tools. They are still available when you want to grep logs by trace id, or anchor a multi-tool flow under an explicit id:
+
+- `mcp__backend-devtools__bedt_o11y_new-trace-id` — generate a fresh 32-hex id and pin it on the session (shadowed by IronBee's verification traceId for the cycle).
+- `mcp__backend-devtools__bedt_o11y_set-trace-context` — set / clear specific trace-context values.
+- `mcp__backend-devtools__bedt_o11y_get-trace-context` — inspect the current pin (useful for `bedt_log_read { pattern: "<traceId>" }`).
+
+### Submit verdict
+
+The verdict is platform-agnostic — `status`, `checks`, and (when applicable) `issues` / `fixes`. The gate enforces that AT LEAST one backend evidence path was exercised in your `bedt_*` tool calls (protocol-call OR log-evidence OR DB-evidence) and that `checks` is non-empty.
+
+```json
+{
+  "session_id": "<sid>",
+  "status": "pass",
+  "checks": ["POST /api/orders returned 201 with order id", "GET /api/orders/:id reflects new order"]
+}
+```
+
+## Multi-cycle (browser + backend, or browser + node + backend)
+
+Common case: a feature edit touches a `.tsx` page (browser-cycle) and a `routes/orders.ts` (node-cycle if Node.js, plus backend-cycle for protocol verification when `backend` is enabled). All active cycles must be satisfied for `status: pass`. **Single** `verification-start`, **single** verdict, **single** retry counter cover all of them. The verdict shape doesn't change with the number of active cycles — same minimal verdict regardless:
+
+```json
+{
+  "session_id": "<sid>",
+  "status": "pass",
+  "checks": [
+    "checkout page renders",
+    "POST /api/orders returned 201",
+    "tracepoint at handler.ts:42 fired once",
+    "orders table reflects the new row"
+  ]
+}
+```
+
+For a multi-cycle pass, EVERY active cycle's pass criteria must hold.

package/dist/clients/codex/platforms/skill.browser.md

@@ -0,0 +1,28 @@
+<!-- Browser cycle verification is ENABLED for this project. The Stop hook
+     enforces a browser cycle whenever an edited file matches
+     `browser.verifyPatterns` (default: most code extensions). -->
+
+## Browser flow
+
+> **Recording (only when `recording.enable` is on in config):** the gate blocks every other browser tool until you first call `mcp__browser-devtools__bdt_content_start-recording`, and `submit-verdict` rejects with `"recording is still active"` unless you call `mcp__browser-devtools__bdt_content_stop-recording` after the steps below. **Treat start/stop as bookends around steps 1-5.** The same is enforced as step 6 of the Universal flow.
+
+1. **Navigate**: `mcp__browser-devtools__bdt_navigation_go-to` — go to the affected page(s)
+2. **Interact**: actually exercise what changed — click buttons, fill forms, submit data, trigger workflows. Don't just look at the page.
+3. **Screenshot**: `mcp__browser-devtools__bdt_content_take-screenshot` — capture the final visual state
+4. **Accessibility**: `mcp__browser-devtools__bdt_a11y_take-aria-snapshot` — verify page structure
+5. **Console**: `mcp__browser-devtools__bdt_o11y_get-console-messages` — check for errors
+
+All four tools are MANDATORY (the Stop hook checks each). Functional interaction is expected for every verification.
+
+### Verdict fields
+The verdict is platform-agnostic — you submit only semantic judgment:
+
+```json
+{
+  "session_id": "<sid>",
+  "status": "pass",
+  "checks": ["form submits successfully", "new item appears in list", "no console errors"]
+}
+```
+
+On fail, include `issues`. On pass after a previous fail, include `fixes`.

package/dist/clients/codex/platforms/skill.node.md

@@ -0,0 +1,62 @@
+<!-- Node backend verification is ENABLED for this project. The Stop hook
+     enforces a node cycle in addition to the browser cycle whenever an
+     edited file matches `node.verifyPatterns`. -->
+
+## ⚠️ CRITICAL: when NOT to use node-devtools
+
+**`node-devtools` is ONLY for Node.js backends.** It is a V8 inspector wrapper (`node --inspect` attach via PID / inspector port / Docker container). It does **NOT** work with any other runtime. Do **NOT** call `ndt_*` tools for projects whose backend is:
+- Java (Spring, Quarkus, Micronaut, …) — use the JVM debugger, not supported by IronBee yet
+- Python (FastAPI, Django, Flask, …) — not supported yet
+- Go, Rust, Ruby, .NET, PHP, Elixir, Kotlin/JVM, Swift — not supported yet
+
+**How to tell whether the backend is Node.js:**
+- `package.json` is the main project manifest, with `"type": "module"` or `"engines": { "node": ... }`, or scripts that run `node`/`tsx`/`ts-node`.
+- The dev server command is `npm run dev`, `next dev`, `nest start`, `nodemon`, etc.
+
+If you see `pom.xml`, `build.gradle`, `requirements.txt`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `Gemfile`, `composer.json`, `*.csproj` — the backend is NOT Node.js. Do NOT call any `ndt_*` tools.
+
+**Misconfiguration recovery.** If you read this section it means the operator enabled the node cycle for this project. If the backend isn't actually Node.js, this was a mistake — the Stop hook will keep blocking the gate (with `incomplete_tools` for the node cycle) until you call `ndt_debug_connect` (which will fail) or `maxRetries` is exhausted. Don't attempt the connection. Stop and tell the user clearly: the project's backend is not Node.js; ask them to run `ironbee node disable` to unblock the gate. Continue with browser-cycle verification only in the meantime.
+
+## Node flow
+
+1. **Identify the running Node process** — note its PID, container name (`docker compose ps`), or inspector port.
+2. **Connect**: `mcp__node-devtools__ndt_debug_connect` with one of `pid` / `processName` / `containerId` / `containerName` / `inspectorPort` / `wsUrl`. SIGUSR1 is auto-sent if the inspector isn't on; for Docker, it goes through `docker exec`.
+3. **Pick an evidence path** per changed code path:
+   - **Probe path** (proves the code path executed):
+     - Set a probe at the changed location: `ndt_debug_put-tracepoint` (checkpoint), `ndt_debug_put-logpoint` (logged expression), or `ndt_debug_put-exceptionpoint` (caught/uncaught exception).
+     - **Exercise the path** (e.g. send a request from the browser, run a CLI command, post to a queue) — without this the probe never fires.
+     - Read collected snapshots: `ndt_debug_get-probe-snapshots`. At least one probe must come back with `triggered: true`.
+   - **Log path** (proves no errors during execution):
+     - Exercise the path.
+     - Read errors: `ndt_debug_get-logs` with the error-level filter.
+4. **Disconnect** (optional): `ndt_debug_disconnect`.
+
+### Verdict fields
+The verdict is platform-agnostic — you submit only semantic judgment:
+
+```json
+{
+  "session_id": "<sid>",
+  "status": "pass",
+  "checks": ["POST /api/orders returned 201", "tracepoint at handler.ts:42 fired once"]
+}
+```
+
+Node-cycle pass criteria:
+- If probes were set, at least one must have triggered (proves the code path executed).
+- If only logs were used, no ERROR-level entries.
+- If both forms were used, both conditions must hold.
+
+## Multi-cycle (browser + node simultaneously)
+
+Common case: in the same task you edit a `.tsx` component (browser-cycle) and a `server/api/*.ts` handler (node-cycle). Both cycles activate. **Single** `verification-start`, **single** `verdict.json`, **single** retry counter cover both. The verdict shape doesn't change — one verdict regardless of how many cycles ran:
+
+```json
+{
+  "session_id": "<sid>",
+  "status": "pass",
+  "checks": ["checkout submits", "POST /api/orders returned 201", "no console errors"]
+}
+```
+
+For a multi-cycle `pass`, BOTH cycles' pass criteria must hold.

package/dist/clients/codex/rules/ironbee-verification.md

@@ -0,0 +1,48 @@
+You MUST verify all code changes through real tools before completing any task. After every verification attempt, you MUST submit a verdict (pass or fail) via `ironbee hook submit-verdict` before doing anything else. If verification fails, submit the fail verdict first, then fix.
+
+Verification runs in **cycles** decided by file-pattern match — you don't choose, the gate detects. Multiple cycles can run in parallel within a single Stop hook; each one has its own activation patterns, tools, and verdict fields.
+
+**See the platform sections near the bottom of this file** for which cycles are active for this project, the tools they expose, and the per-cycle verdict fields you must include.
+
+## Application lifecycle
+
+You manage the running application during verification:
+- **Build** if needed (e.g. `npm run build`, `docker compose build`).
+- **Start** before navigating/connecting (e.g. `npm run dev`, `docker compose up -d`).
+- **Stop** the dev server after verification is complete.
+
+Skip start if already running. Fix build errors before proceeding. **Don't guess ports** — check actual via `docker compose ps`, process output, or config.
+
+## Required steps
+
+1. Build and start the application if not already running.
+2. **Start verification**: `echo '{"session_id":"<your-session-id>"}' | ironbee hook verification-start` — required before any devtools tool call.
+3. **Run the per-cycle flow for every active cycle** — see the platform sections near the bottom of this file. Multiple cycles can be active in the same Stop run; every one of them must be exercised within this single verification cycle.
+4. Stop the dev server when done — every cycle, including the final one.
+5. **Honor any cycle-specific teardown** noted in the platform sections BEFORE submit-verdict.
+6. **IMMEDIATELY submit your verdict** — do NOT edit any code before submitting: `echo '<verdict-json>' | ironbee hook submit-verdict`.
+   - Platform-agnostic shape: `status`, `checks` (always required); add `issues` on fail; add `fixes` on pass-after-fail. One verdict regardless of how many cycles ran.
+
+The Stop hook checks tool usage for every active cycle and that the verdict carries non-empty `checks`. After EVERY verification attempt, you MUST submit a verdict before doing anything else — even if it failed. Do not skip to fixing code.
+
+If verification fails: submit fail verdict → fix the code → re-verify → submit again.
+
+Every code edit (Write/Edit) automatically clears your verdict, requiring re-verification.
+
+## BANNED
+
+- Writing `verdict.json` directly — always use `ironbee hook submit-verdict`.
+- Skipping the fail verdict — always submit fail before fixing, so issues are tracked.
+- Submitting a verdict without actually performing verification through real tools.
+- Submitting a verdict based on assumptions, code reading, or prior knowledge.
+- Copying example verdicts from hook messages without doing real verification first.
+- Calling devtools tools for any cycle without first opening a verification cycle (`ironbee hook verification-start`).
+
+<!--IRONBEE:PLATFORM:browser-->
+<!--/IRONBEE:PLATFORM:browser-->
+
+<!--IRONBEE:PLATFORM:node-->
+<!--/IRONBEE:PLATFORM:node-->
+
+<!--IRONBEE:PLATFORM:backend-->
+<!--/IRONBEE:PLATFORM:backend-->

package/dist/clients/codex/skills/ironbee-verification.md

@@ -0,0 +1,80 @@
+---
+name: ironbee-verification
+description: >
+  MANDATORY verification after code changes. Activates when implementing features, fixing
+  bugs, modifying UI components, API endpoints, styles, refactoring, or any task that
+  changes application behavior. Verification runs in cycles activated by file-pattern
+  match — which cycles are wired up for this project is shown in the platform sections
+  near the bottom of this file. After every code edit you MUST verify the affected
+  cycle(s) through real tools and submit a single verdict (pass or fail) before
+  reporting task completion. If verification fails, submit the fail verdict first,
+  then fix.
+---
+
+# IronBee Verification
+
+## Rule
+No task is complete until changes are verified — through **real tools**, not by reading code or inferring behavior. After verification, you MUST submit a verdict (pass or fail) before doing anything else. If verification fails, submit the fail verdict first, then fix.
+
+## Cycles
+
+IronBee runs verification in **cycles**. A single Stop hook can drive multiple cycles in parallel — every active cycle must pass for your task to complete.
+
+You don't choose which cycle runs — the file pattern decides. A single edited file can match multiple cycles' patterns and activate them all. Cycles always run in parallel within a single Stop run. Each cycle has its own tools, flow steps, and verdict fields.
+
+**See the platform sections near the bottom of this file** for which cycles are active for this project, the tools they expose, and the per-cycle verdict fields you must include.
+
+## Application lifecycle (your responsibility)
+
+For every active cycle you manage the running application:
+- **Build** if needed (`npm run build`, `docker compose build`, …)
+- **Start** before navigating/connecting (`npm run dev`, `docker compose up -d`, …)
+- **Stop** when verification is complete
+
+If already running, skip start. If the build fails, fix it before proceeding.
+
+**Don't guess ports.** After starting, check the actual port via `docker compose ps`, process output, or config files.
+
+## Universal flow
+
+1. Implement your changes (write/edit code).
+2. **Start verification** (one cycle covers every active mode — every active cycle's flow runs within the same verification cycle):
+   ```
+   echo '{"session_id":"<your-session-id>"}' | ironbee hook verification-start
+   ```
+   Devtools tools are blocked without this.
+3. Build and start the application if not already running.
+4. **Run the per-cycle flows for every active cycle.** See the platform sections near the bottom of this file — each enabled cycle's section has its own flow steps and mandatory tools. All active cycles must be exercised within this one verification cycle.
+5. Stop the dev server when verification is complete (every cycle — including the final one).
+6. **Honor any cycle-specific teardown** noted in the platform sections (e.g. recording stop) BEFORE submitting your verdict.
+7. **Submit your verdict immediately** — do NOT edit any code first:
+   ```
+   echo '<verdict-json>' | ironbee hook submit-verdict
+   ```
+   - Verdict shape is platform-agnostic: `status`, `checks`, optionally `issues` / `fixes`. One verdict regardless of how many cycles ran.
+   - Pass → `{ "session_id": "...", "status": "pass", "checks": [...] }`
+   - Fail → add `"issues": [...]` describing what failed.
+   - Pass after a previous fail → add `"fixes": [...]` describing what was repaired.
+   - **The Stop hook enforces that you called the required tools for every active cycle and that the verdict carries non-empty `checks`.**
+8. If failed → fix → rebuild → go back to step 2 → repeat until pass.
+
+<!--IRONBEE:PLATFORM:browser-->
+<!--/IRONBEE:PLATFORM:browser-->
+
+<!--IRONBEE:PLATFORM:node-->
+<!--/IRONBEE:PLATFORM:node-->
+
+<!--IRONBEE:PLATFORM:backend-->
+<!--/IRONBEE:PLATFORM:backend-->
+
+## Important
+- **Always submit a verdict after every verification attempt** — both pass AND fail. Fail verdicts are tracked for analytics.
+- The Stop hook checks that the required tools were used for every active cycle and that the verdict carries non-empty `checks`.
+- Submit verdicts via `ironbee hook submit-verdict`, never write `verdict.json` directly.
+- Every code edit (Write/Edit) automatically clears your session's verdict.
+- After 3 failed verification attempts, you may complete but must report unresolved issues.
+
+## Subagent teams
+- Subagents focus on implementation only — do NOT verify.
+- The main orchestrator agent verifies ALL changes after subagents complete.
+- Each session's verification is isolated via session-specific verdict files.