@ironbee-ai/cli 0.8.2 → 0.9.0

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

@@ -0,0 +1,31 @@
+<!-- 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:bdt_content_start-recording`, and `submit-verdict` rejects with `"recording is still active"` unless you call `MCP: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: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:bdt_content_take-screenshot` — capture the final visual state
+4. **Accessibility**: `MCP:bdt_a11y_take-aria-snapshot` — verify page structure
+5. **Console**: `MCP: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.
+
+### Browser verdict fields
+```json
+{
+  "session_id": "<sid>",
+  "status": "pass",
+  "pages_tested": ["http://localhost:3000/page"],
+  "checks": ["form submits successfully", "new item appears in list", "no console errors"],
+  "console_errors": 0,
+  "network_failures": 0
+}
+```
+
+For `status: "pass"` (browser cycle): `console_errors === 0` AND `network_failures === 0`.
+
+On fail, include `issues`. On pass after a previous fail, include `fixes`.

package/dist/clients/cursor/{fragments → platforms}/skill.node.md

@@ -1,6 +1,6 @@
 <!-- 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 `backend.node.verifyPatterns`. -->
+     edited file matches `node.verifyPatterns`. -->
 
 ## ⚠️ CRITICAL: when NOT to use node-devtools
 
@@ -15,7 +15,7 @@
 
 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 `MCP: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 `MCP: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 disable-backend node` to unblock the gate. Continue with browser-cycle verification only in the meantime.
+**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 `MCP: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
 

package/dist/clients/cursor/rules/ironbee-verification.mdc

@@ -1,15 +1,13 @@
 ---
-description: "MANDATORY verification after code changes — IronBee enforcement (browser + runtime cycles)"
+description: "MANDATORY verification after code changes — IronBee enforcement (per-cycle verification gate)"
 alwaysApply: true
 ---
 
 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:
+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.
 
-- **Browser cycle** — frontend file changes (default: most code extensions). Tools come from the **browser-devtools** MCP server (prefix `MCP:bdt_*`). Verification means navigating to the affected page and FUNCTIONALLY exercising the change in the browser — clicking, typing, submitting — not just looking at it.
-
-A backend-runtime cycle (e.g. `node` after `ironbee enable-backend node`) may also be active for this project — **see the runtime section near the bottom of this file** for whether it applies and which tools to call.
+**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
 
@@ -24,11 +22,9 @@ Skip start if already running. Fix build errors before proceeding. **Don't guess
 
 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 **Browser cycle** flow: navigate (`MCP:bdt_navigation_go-to`) → functionally test → screenshot (`MCP:bdt_content_take-screenshot`) → accessibility (`MCP:bdt_a11y_take-aria-snapshot`) → console (`MCP:bdt_o11y_get-console-messages`). All four are MANDATORY.
-   - If `recording.enable` is on, the gate forces `MCP:bdt_content_start-recording` BEFORE the steps above and rejects the verdict if you don't call `MCP:bdt_content_stop-recording` AFTER them. Always pair start/stop around steps above.
-   - **See the runtime section near the bottom of this file** — if a backend-runtime cycle is active for this project, run its flow within the same verification cycle as well.
+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.
-5. **If recording was started, stop it NOW** — `MCP:bdt_content_stop-recording` BEFORE submit-verdict. submit-verdict rejects with "recording is still active" if you skip this.
+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`.
    - Pass verdict carries fields for every active cycle. Fail verdict adds `issues`. Pass after fail adds `fixes`.
    - Status `pass` is overridden to fail by the gate when evidence doesn't back it.
@@ -46,8 +42,13 @@ Every file edit automatically clears your verdict, requiring re-verification.
 - 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 `MCP:bdt_*` tools without first opening a verification cycle (`ironbee hook verification-start`).
-- **Submitting a verdict while a browser recording is still active** — always call `MCP:bdt_content_stop-recording` BEFORE `ironbee hook submit-verdict`. The recording start/stop pair brackets the verification flow.
+- 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:RUNTIME:node-->
-<!--/IRONBEE:RUNTIME:node-->
+<!--IRONBEE:PLATFORM:backend-->
+<!--/IRONBEE:PLATFORM:backend-->

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

@@ -3,31 +3,30 @@ 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. Frontend changes require browser verification via the
-  browser-devtools MCP server. Backend changes ALSO require runtime-specific verification
-  via the matching MCP server when the operator has enabled that runtime (see
-  `ironbee enable-backend <runtime>`). 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.
+  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** (browser interaction or, when enabled, a backend-runtime debugger), 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.
+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.
 
-- **Browser cycle** — always available. Triggered when a changed file matches `browser.verifyPatterns` (default: most code extensions — `.ts`, `.tsx`, `.css`, `.html`, `.py`, `.go`, `.java`, etc.). Tools come from the **browser-devtools** MCP server (prefix `MCP:bdt_*`). Verification means navigating to the affected page and FUNCTIONALLY exercising the change in the browser.
-- **Backend-runtime cycle(s)** — opt-in per project via `ironbee enable-backend <runtime>` (e.g. `node`). Triggered when a changed file matches `backend.<runtime>.verifyPatterns`. Tools come from a runtime-specific MCP server. **See the runtime section near the bottom of this file** for whether a backend cycle is active for this project and which tools to call.
+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.
 
-You don't choose which cycle runs — the file pattern decides. A single file can match multiple cycles' patterns and activate them all. Cycles always run in parallel within a single stop run.
+**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 both cycles you manage the running application:
+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
@@ -39,15 +38,15 @@ If already running, skip start. If the build fails, fix it before proceeding.
 ## Universal flow
 
 1. Implement your changes (write/edit code).
-2. **Start verification** (one cycle covers every active mode — browser plus any enabled backend-runtime cycles):
+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 **Browser flow** below. **See the runtime section near the bottom of this file** — if a backend-runtime cycle is active for this project, run its flow within the same verification cycle as well.
+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, mandatory tools, and verdict fields. All active cycles must be exercised within this one verification cycle.
 5. Stop the dev server when verification is complete.
-6. **If recording was started, stop it now** — `MCP:bdt_content_stop-recording`. submit-verdict rejects when recording is still active.
+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
@@ -57,43 +56,14 @@ If already running, skip start. If the build fails, fix it before proceeding.
    - **The stop hook overrides `status: pass` to fail when evidence doesn't back it.**
 8. If failed → fix → rebuild → go back to step 2 → repeat until pass.
 
-## Browser flow (when browser cycle is active)
+<!--IRONBEE:PLATFORM:browser-->
+<!--/IRONBEE:PLATFORM:browser-->
 
-> **Recording (only when `recording.enable` is on in config):** the gate blocks every other browser tool until you first call `MCP:bdt_content_start-recording`, and `submit-verdict` rejects with `"recording is still active"` unless you call `MCP:bdt_content_stop-recording` after the steps below. **Treat start/stop as bookends around steps 1-5.** This is also enforced as step 6 of the Universal flow above.
+<!--IRONBEE:PLATFORM:node-->
+<!--/IRONBEE:PLATFORM:node-->
 
-1. **Navigate**: `MCP: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:bdt_content_take-screenshot` — capture the final visual state
-4. **Accessibility**: `MCP:bdt_a11y_take-aria-snapshot` — verify page structure
-5. **Console**: `MCP: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.
-
-### Browser verdict fields
-```json
-{
-  "session_id": "<sid>",
-  "status": "pass",
-  "pages_tested": ["http://localhost:3000/page"],
-  "checks": ["form submits successfully", "new item appears in list", "no console errors"],
-  "console_errors": 0,
-  "network_failures": 0
-}
-```
-
-For `status: "pass"` (browser cycle): `console_errors === 0` AND `network_failures === 0`.
-
-On fail, include `issues`. On pass after a previous fail, include `fixes`.
-
-<!--IRONBEE:RUNTIME:node-->
-<!--/IRONBEE:RUNTIME:node-->
-
-## What good verification looks like
-
-- Changed a form handler? → Start the app, fill the form, submit it, verify the response (browser flow).
-- Added an API endpoint in a backend file (when a runtime cycle is enabled)? → Run that runtime's flow per the runtime section: attach to the running process, set a probe at the handler, exercise the path from the browser, confirm the probe triggered (or inspect runtime logs).
-- Fixed a bug that surfaced as both a UI glitch AND a server error? → Multi-cycle: visual confirmation in the browser AND probe/log proof on the server.
-- Changed styling only? → Browser flow with extra attention on screenshot review.
+<!--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.

package/dist/commands/backend.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `ironbee backend <subcommand>` — manage the runtime-agnostic backend
+ * protocol cycle (HTTP / gRPC / GraphQL / WebSocket via the
+ * `backend-devtools` MCP, `bedt_*` tools).
+ *
+ * Subcommands today:
+ *   - `enable`  — opt in (writes a minimal `{ "backend": {} }` block;
+ *                 multi-language code defaults flow in at runtime).
+ *   - `disable` — opt out (drops the block clean when no customizations
+ *                 + no lower-layer override; otherwise hard-kills via
+ *                 `verifyPatterns: []`).
+ */
+import { Command } from "commander";
+export declare const backendEnableCommand: Command;
+export declare const backendDisableCommand: Command;
+export declare const backendCommand: Command;
+//# sourceMappingURL=backend.d.ts.map

package/dist/commands/backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../src/commands/backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAqBpC,eAAO,MAAM,oBAAoB,EAAE,OAW7B,CAAC;AAEP,eAAO,MAAM,qBAAqB,EAAE,OAW9B,CAAC;AAEP,eAAO,MAAM,cAAc,EAAE,OAGS,CAAC"}

package/dist/commands/backend.js

@@ -0,0 +1,58 @@
+"use strict";
+/**
+ * `ironbee backend <subcommand>` — manage the runtime-agnostic backend
+ * protocol cycle (HTTP / gRPC / GraphQL / WebSocket via the
+ * `backend-devtools` MCP, `bedt_*` tools).
+ *
+ * Subcommands today:
+ *   - `enable`  — opt in (writes a minimal `{ "backend": {} }` block;
+ *                 multi-language code defaults flow in at runtime).
+ *   - `disable` — opt out (drops the block clean when no customizations
+ *                 + no lower-layer override; otherwise hard-kills via
+ *                 `verifyPatterns: []`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.backendCommand = exports.backendDisableCommand = exports.backendEnableCommand = void 0;
+const commander_1 = require("commander");
+const registry_1 = require("../clients/registry");
+const config_1 = require("../lib/config");
+const output_1 = require("../lib/output");
+const cycle_toggle_1 = require("./cycle-toggle");
+function attachToggleOptions(cmd) {
+    return cmd
+        .option("-p, --project-dir <dir>", "Project directory (default: cwd).")
+        .option("-g, --global", "Write to the global config (~/.ironbee/config.json) instead of the project.")
+        .option("--local", "Write to the gitignored project-local override (<project>/.ironbee/config.local.json). Mutually exclusive with --global.")
+        .option("--client <name>", `Only update guidance md files for this client (${(0, registry_1.clientNames)()}), or "all". Default: every registered client (per-file existsSync gate skips uninstalled ones).`);
+}
+exports.backendEnableCommand = attachToggleOptions(new commander_1.Command("enable"))
+    .description("Enable the runtime-agnostic backend protocol cycle. Writes a minimal `{ \"backend\": {} }` block — multi-language code defaults (TS/JS/Py/Go/Java/Ruby/.NET/Rust/Kotlin/Scala paths) flow in at runtime.")
+    .action((opts) => {
+    try {
+        const projectDir = opts.projectDir ?? process.cwd();
+        const target = (0, config_1.resolveConfigTargetFromFlags)(opts);
+        (0, cycle_toggle_1.applyEnableCycle)("backend", projectDir, target, opts.client);
+    }
+    catch (e) {
+        console.error(`${output_1.pc.red("✗")}  ${e instanceof Error ? e.message : e}`);
+        process.exit(1);
+    }
+});
+exports.backendDisableCommand = attachToggleOptions(new commander_1.Command("disable"))
+    .description("Disable the backend protocol cycle. Drops the entire `backend` block when no customizations + no lower-layer override exist; otherwise writes `backend.verifyPatterns: []` (hard kill, preserves customizations).")
+    .action((opts) => {
+    try {
+        const projectDir = opts.projectDir ?? process.cwd();
+        const target = (0, config_1.resolveConfigTargetFromFlags)(opts);
+        (0, cycle_toggle_1.applyDisableCycle)("backend", projectDir, target, opts.client);
+    }
+    catch (e) {
+        console.error(`${output_1.pc.red("✗")}  ${e instanceof Error ? e.message : e}`);
+        process.exit(1);
+    }
+});
+exports.backendCommand = new commander_1.Command("backend")
+    .description("Manage the runtime-agnostic backend protocol cycle (HTTP / gRPC / GraphQL / WebSocket via the `backend-devtools` MCP, `bedt_*` tools).")
+    .addCommand(exports.backendEnableCommand)
+    .addCommand(exports.backendDisableCommand);
+//# sourceMappingURL=backend.js.map

package/dist/commands/backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.js","sourceRoot":"","sources":["../../src/commands/backend.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;AAEH,yCAAoC;AACpC,kDAAkD;AAClD,0CAA2E;AAC3E,0CAAmC;AACnC,iDAAqE;AASrE,SAAS,mBAAmB,CAAC,GAAY;IACrC,OAAO,GAAG;SACL,MAAM,CAAC,yBAAyB,EAAE,mCAAmC,CAAC;SACtE,MAAM,CAAC,cAAc,EAAE,6EAA6E,CAAC;SACrG,MAAM,CAAC,SAAS,EAAE,0HAA0H,CAAC;SAC7I,MAAM,CAAC,iBAAiB,EAAE,kDAAkD,IAAA,sBAAW,GAAE,kGAAkG,CAAC,CAAC;AACtM,CAAC;AAEY,QAAA,oBAAoB,GAAY,mBAAmB,CAAC,IAAI,mBAAO,CAAC,QAAQ,CAAC,CAAC;KAClF,WAAW,CAAC,0MAA0M,CAAC;KACvN,MAAM,CAAC,CAAC,IAAmB,EAAQ,EAAE;IAClC,IAAI,CAAC;QACD,MAAM,UAAU,GAAW,IAAI,CAAC,UAAU,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;QAC5D,MAAM,MAAM,GAAiB,IAAA,qCAA4B,EAAC,IAAI,CAAC,CAAC;QAChE,IAAA,+BAAgB,EAAC,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IACjE,CAAC;IAAC,OAAO,CAAU,EAAE,CAAC;QAClB,OAAO,CAAC,KAAK,CAAC,GAAG,WAAE,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACvE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;AACL,CAAC,CAAC,CAAC;AAEM,QAAA,qBAAqB,GAAY,mBAAmB,CAAC,IAAI,mBAAO,CAAC,SAAS,CAAC,CAAC;KACpF,WAAW,CAAC,mNAAmN,CAAC;KAChO,MAAM,CAAC,CAAC,IAAmB,EAAQ,EAAE;IAClC,IAAI,CAAC;QACD,MAAM,UAAU,GAAW,IAAI,CAAC,UAAU,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;QAC5D,MAAM,MAAM,GAAiB,IAAA,qCAA4B,EAAC,IAAI,CAAC,CAAC;QAChE,IAAA,gCAAiB,EAAC,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IAClE,CAAC;IAAC,OAAO,CAAU,EAAE,CAAC;QAClB,OAAO,CAAC,KAAK,CAAC,GAAG,WAAE,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACvE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;AACL,CAAC,CAAC,CAAC;AAEM,QAAA,cAAc,GAAY,IAAI,mBAAO,CAAC,SAAS,CAAC;KACxD,WAAW,CAAC,wIAAwI,CAAC;KACrJ,UAAU,CAAC,4BAAoB,CAAC;KAChC,UAAU,CAAC,6BAAqB,CAAC,CAAC"}

package/dist/commands/browser.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `ironbee browser <subcommand>` — manage the browser verification cycle.
+ *
+ * Subcommands today:
+ *   - `enable`  — turn the browser cycle on (default-on; use this to re-enable
+ *                 after `disable`, or to strip a prior `verifyPatterns: []`
+ *                 override).
+ *   - `disable` — turn the browser cycle off (writes `verifyPatterns: []` as
+ *                 a hard kill; preserves customizations).
+ *
+ * The hierarchical `browser <verb>` shape leaves room for future per-platform
+ * commands beyond enable/disable (e.g. `browser status`, `browser inspect`,
+ * `browser test`) without name-spacing them at the top level.
+ */
+import { Command } from "commander";
+export declare const browserEnableCommand: Command;
+export declare const browserDisableCommand: Command;
+export declare const browserCommand: Command;
+//# sourceMappingURL=browser.d.ts.map

package/dist/commands/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../src/commands/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAqBpC,eAAO,MAAM,oBAAoB,EAAE,OAW7B,CAAC;AAEP,eAAO,MAAM,qBAAqB,EAAE,OAW9B,CAAC;AAEP,eAAO,MAAM,cAAc,EAAE,OAGS,CAAC"}

package/dist/commands/browser.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * `ironbee browser <subcommand>` — manage the browser verification cycle.
+ *
+ * Subcommands today:
+ *   - `enable`  — turn the browser cycle on (default-on; use this to re-enable
+ *                 after `disable`, or to strip a prior `verifyPatterns: []`
+ *                 override).
+ *   - `disable` — turn the browser cycle off (writes `verifyPatterns: []` as
+ *                 a hard kill; preserves customizations).
+ *
+ * The hierarchical `browser <verb>` shape leaves room for future per-platform
+ * commands beyond enable/disable (e.g. `browser status`, `browser inspect`,
+ * `browser test`) without name-spacing them at the top level.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.browserCommand = exports.browserDisableCommand = exports.browserEnableCommand = void 0;
+const commander_1 = require("commander");
+const registry_1 = require("../clients/registry");
+const config_1 = require("../lib/config");
+const output_1 = require("../lib/output");
+const cycle_toggle_1 = require("./cycle-toggle");
+function attachToggleOptions(cmd) {
+    return cmd
+        .option("-p, --project-dir <dir>", "Project directory (default: cwd).")
+        .option("-g, --global", "Write to the global config (~/.ironbee/config.json) instead of the project.")
+        .option("--local", "Write to the gitignored project-local override (<project>/.ironbee/config.local.json). Mutually exclusive with --global.")
+        .option("--client <name>", `Only update guidance md files for this client (${(0, registry_1.clientNames)()}), or "all". Default: every registered client (per-file existsSync gate skips uninstalled ones).`);
+}
+exports.browserEnableCommand = attachToggleOptions(new commander_1.Command("enable"))
+    .description("Enable the browser cycle. Browser is default-on; this command writes a minimal `{ \"browser\": {} }` block (no pattern materialization; code defaults flow in at runtime) OR strips a prior `verifyPatterns: []` disable-override.")
+    .action((opts) => {
+    try {
+        const projectDir = opts.projectDir ?? process.cwd();
+        const target = (0, config_1.resolveConfigTargetFromFlags)(opts);
+        (0, cycle_toggle_1.applyEnableCycle)("browser", projectDir, target, opts.client);
+    }
+    catch (e) {
+        console.error(`${output_1.pc.red("✗")}  ${e instanceof Error ? e.message : e}`);
+        process.exit(1);
+    }
+});
+exports.browserDisableCommand = attachToggleOptions(new commander_1.Command("disable"))
+    .description("Disable the browser cycle (writes `browser.verifyPatterns: []` to override the default 40+ extension fallback; preserves customizations of `alwaysRequired` / `evidencePaths` / `additionalVerifyPatterns`).")
+    .action((opts) => {
+    try {
+        const projectDir = opts.projectDir ?? process.cwd();
+        const target = (0, config_1.resolveConfigTargetFromFlags)(opts);
+        (0, cycle_toggle_1.applyDisableCycle)("browser", projectDir, target, opts.client);
+    }
+    catch (e) {
+        console.error(`${output_1.pc.red("✗")}  ${e instanceof Error ? e.message : e}`);
+        process.exit(1);
+    }
+});
+exports.browserCommand = new commander_1.Command("browser")
+    .description("Manage the browser verification cycle (DOM / console / a11y / screenshots via the `browser-devtools` MCP, `bdt_*` tools).")
+    .addCommand(exports.browserEnableCommand)
+    .addCommand(exports.browserDisableCommand);
+//# sourceMappingURL=browser.js.map

package/dist/commands/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../../src/commands/browser.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AAEH,yCAAoC;AACpC,kDAAkD;AAClD,0CAA2E;AAC3E,0CAAmC;AACnC,iDAAqE;AASrE,SAAS,mBAAmB,CAAC,GAAY;IACrC,OAAO,GAAG;SACL,MAAM,CAAC,yBAAyB,EAAE,mCAAmC,CAAC;SACtE,MAAM,CAAC,cAAc,EAAE,6EAA6E,CAAC;SACrG,MAAM,CAAC,SAAS,EAAE,0HAA0H,CAAC;SAC7I,MAAM,CAAC,iBAAiB,EAAE,kDAAkD,IAAA,sBAAW,GAAE,kGAAkG,CAAC,CAAC;AACtM,CAAC;AAEY,QAAA,oBAAoB,GAAY,mBAAmB,CAAC,IAAI,mBAAO,CAAC,QAAQ,CAAC,CAAC;KAClF,WAAW,CAAC,oOAAoO,CAAC;KACjP,MAAM,CAAC,CAAC,IAAmB,EAAQ,EAAE;IAClC,IAAI,CAAC;QACD,MAAM,UAAU,GAAW,IAAI,CAAC,UAAU,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;QAC5D,MAAM,MAAM,GAAiB,IAAA,qCAA4B,EAAC,IAAI,CAAC,CAAC;QAChE,IAAA,+BAAgB,EAAC,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IACjE,CAAC;IAAC,OAAO,CAAU,EAAE,CAAC;QAClB,OAAO,CAAC,KAAK,CAAC,GAAG,WAAE,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACvE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;AACL,CAAC,CAAC,CAAC;AAEM,QAAA,qBAAqB,GAAY,mBAAmB,CAAC,IAAI,mBAAO,CAAC,SAAS,CAAC,CAAC;KACpF,WAAW,CAAC,8MAA8M,CAAC;KAC3N,MAAM,CAAC,CAAC,IAAmB,EAAQ,EAAE;IAClC,IAAI,CAAC;QACD,MAAM,UAAU,GAAW,IAAI,CAAC,UAAU,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;QAC5D,MAAM,MAAM,GAAiB,IAAA,qCAA4B,EAAC,IAAI,CAAC,CAAC;QAChE,IAAA,gCAAiB,EAAC,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IAClE,CAAC;IAAC,OAAO,CAAU,EAAE,CAAC;QAClB,OAAO,CAAC,KAAK,CAAC,GAAG,WAAE,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACvE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;AACL,CAAC,CAAC,CAAC;AAEM,QAAA,cAAc,GAAY,IAAI,mBAAO,CAAC,SAAS,CAAC;KACxD,WAAW,CAAC,2HAA2H,CAAC;KACxI,UAAU,CAAC,4BAAoB,CAAC;KAChC,UAAU,CAAC,6BAAqB,CAAC,CAAC"}

package/dist/commands/config.d.ts

@@ -1,11 +1,23 @@
 /**
- * `ironbee config` — generic config reader / writer for project & global
- * `<root>/.ironbee/config.json` files.
+ * `ironbee config` — generic config reader / writer for the three config
+ * layers IronBee resolves at runtime:
+ *
+ *   1. Global         — `~/.ironbee/config.json`                       (`--global` / `-g`)
+ *   2. Project        — `<projectDir>/.ironbee/config.json`            (default; committed)
+ *   3. Project-local  — `<projectDir>/.ironbee/config.local.json`      (`--local`; gitignored)
+ *
+ * `loadConfig` merges them in that order — each later layer overrides the
+ * earlier ones (see `lib/config.ts` for deep-merge semantics on `browser` /
+ * `backend.<runtime>` blocks). The local layer is for per-machine /
+ * per-developer overrides (debug toggles, machine-specific paths, alternate
+ * collector endpoints) and must not be committed; `ironbee install`
+ * gitignores `.ironbee/config.local.json` automatically.
  *
  * Subcommands:
  *   - `config get <key>`   — print the value at a dotted path. Default reads
- *                            the merged effective value (global + project);
- *                            `--global` / `--project` narrow to one source.
+ *                            the merged effective value (global + project +
+ *                            local); `--global` / `--project` / `--local`
+ *                            narrow to one source.
  *   - `config set <key> <value>` — write a value. Smart re-render: when the
  *                            top-level key affects installed client artifacts
  *                            (hooks, MCP servers, skill/rule md, permissions),
@@ -15,9 +27,13 @@
  *                            state (artifacts-before-config ordering, same as
  *                            `applyVerificationToggle`).
  *   - `config unset <key>` — remove a key. Same rerender rules as `set`.
- *   - `config list`        — print the whole config (merged / global / project).
+ *   - `config list`        — print the whole config (merged / global / project / local).
  *   - `config path`        — print the on-disk path of the targeted config file.
  *
+ * `--global`, `--project`, and `--local` are mutually exclusive on read
+ * paths; on write paths only one of `--global` / `--local` may be set
+ * (project is the implicit default when neither is given).
+ *
  * Type coercion for `set`: tries `JSON.parse(value)` first (so `true`,
  * `false`, `42`, `null`, `[…]`, `{…}` come through as their JSON types).
  * Falls back to the raw string when JSON parse fails, which lets URLs,
@@ -27,16 +43,24 @@
  * misinterpreted (e.g. a string that happens to look like a number).
  *
  * Artifact-affecting top-level keys (the `ARTIFACT_AFFECTING_TOP_KEYS`
- * registry below) are: `verification`, `collector`, `browser`, `backend`,
- * `browserDevTools`, `nodeDevTools`. Changing anything else (e.g.
- * `maxRetries`, `import.concurrency`, `recording`, `jobQueue`, `analytics`)
- * is a pure config flip — runtime hooks read it on next session, no
- * artifact regeneration needed.
+ * registry below) are: `verification`, `collector`, `browser`, `node`,
+ * `backend`, `browserDevTools`, `nodeDevTools`, `backendDevTools`. Changing
+ * anything else (e.g. `maxRetries`, `import.concurrency`, `recording`,
+ * `jobQueue`, `analytics`) is a pure config flip — runtime hooks read it on
+ * next session, no artifact regeneration needed.
  */
 import { Command } from "commander";
 export interface SetOpts {
     projectDir?: string;
+    /** Write to `~/.ironbee/config.json`. Mutually exclusive with `local`. */
     global?: boolean;
+    /**
+     * Write to `<projectDir>/.ironbee/config.local.json` (gitignored
+     * personal override layer). Mutually exclusive with `global`. When
+     * neither flag is set, writes go to the committed project config
+     * (`<projectDir>/.ironbee/config.json`).
+     */
+    local?: boolean;
     client?: string;
     rerender?: boolean;
     json?: boolean;
@@ -46,13 +70,19 @@ export interface SetOpts {
      *   - `true`  → apply everywhere, no prompt (CLI: `--apply-all`)
      *   - `false` → skip everywhere, no prompt (CLI: `--no-apply-all`)
      *   - `undefined` → prompt on TTY; skip with hint on non-TTY
+     *
+     * Only consulted on `--global` writes — local and project writes never
+     * propagate to other projects.
      */
     applyAll?: boolean;
 }
 export declare function runSet(key: string, rawValue: string, opts: SetOpts): Promise<void>;
 export interface UnsetOpts {
     projectDir?: string;
+    /** Write to `~/.ironbee/config.json`. Mutually exclusive with `local`. */
     global?: boolean;
+    /** Write to the gitignored project-local layer. Mutually exclusive with `global`. */
+    local?: boolean;
     client?: string;
     rerender?: boolean;
     /** See `SetOpts.applyAll`. */
@@ -61,14 +91,19 @@ export interface UnsetOpts {
 export declare function runUnset(key: string, opts: UnsetOpts): Promise<void>;
 export interface GetOpts {
     projectDir?: string;
+    /** Read only the global layer (`~/.ironbee/config.json`). */
     global?: boolean;
+    /** Read only the committed project layer (`<projectDir>/.ironbee/config.json`). */
     project?: boolean;
+    /** Read only the gitignored local layer (`<projectDir>/.ironbee/config.local.json`). */
+    local?: boolean;
 }
 export declare function runGet(key: string, opts: GetOpts): void;
 export declare function runList(opts: GetOpts): void;
 export declare function runPath(opts: {
     projectDir?: string;
     global?: boolean;
+    local?: boolean;
 }): void;
 /**
  * `ironbee config` parent command. Subcommands attached below; each one

package/dist/commands/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/commands/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA6XpC,MAAM,WAAW,OAAO;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,wBAAsB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAiCxF;AAED,MAAM,WAAW,SAAS;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,wBAAsB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAgC1E;AAED,MAAM,WAAW,OAAO;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAevD;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAI3C;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAG7E;AAED;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,OACoI,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/commands/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA6ZpC,MAAM,WAAW,OAAO;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,wBAAsB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAiCxF;AAED,MAAM,WAAW,SAAS;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,qFAAqF;IACrF,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,wBAAsB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAgC1E;AAED,MAAM,WAAW,OAAO;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,mFAAmF;IACnF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,wFAAwF;IACxF,KAAK,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAevD;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAI3C;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAG9F;AAED;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,OACoI,CAAC"}