Make Workbench the consumer AI-agent front door

docs/README.md

@@ -2,7 +2,7 @@
 
 Pickleball extends Cucumber with a dynamic feature-file language while preserving normal Cucumber behavior. The pages below describe the supported authoring model and link to real executable examples in [`maven-consumer-project`](consumer-project.md).
 
-When these docs are materialized from the Maven dependency with `DiagnosticCli export-guidance`, links to `../maven-consumer-project/...` resolve to the version-matched, read-only reference snapshot exported beside the docs. Human readers can inspect those working features, configuration, calls, data, runner, and local test-site examples without checking out the Pickleball source repository. Consumer AI agents should follow `.pickleball/AGENT-GUIDE.md` first and open a specific guide only when needed.
+When these docs are materialized from the Maven dependency with Workbench `export-guidance`, links to `../maven-consumer-project/...` resolve to the version-matched, read-only reference snapshot exported beside the docs. Human readers can inspect those working features, configuration, calls, data, runner, and local test-site examples without checking out the Pickleball source repository. Consumer AI agents should follow `.pickleball/AGENT-GUIDE.md` first and open a specific guide only when needed.
 
 ## Start here
 

docs/agent/README.md

@@ -18,9 +18,9 @@ This directory supports repository-native AI coding agents. It is not a runtime
 
 Agent adapters should remain small and point back to the canonical contract rather than copying the full project description.
 
-The nested `/maven-consumer-project/AGENTS.md` is a dependency-owned guidance bootstrap plus a short discover-vs-isolate pointer. It materializes version-matched guidance, directs the consumer agent to `.pickleball/AGENT-GUIDE.md`, and states that agents discover with a diagnostic `mvn test`; MCP is optional if already connected, and agents do not self-register IDE MCP. Refresh/version/manifest semantics, authoring rules, configuration, diagnostics, and troubleshooting belong in the exported dependency guidance.
+The nested `/maven-consumer-project/AGENTS.md` is a dependency-owned Workbench bootstrap plus a short Discover/Isolate/Confirm pointer. It materializes version-matched guidance through `PickleballWorkbenchLauncher export-guidance`, directs the consumer agent to `.pickleball/AGENT-GUIDE.md`, and tells agents to use Workbench `hint` / `discover` / `isolate` / `confirm`. Do not start the GUI. Do not register IDE MCP. Refresh/version/manifest semantics, authoring rules, configuration, diagnostics, and troubleshooting belong in the exported dependency guidance.
 
-The nested `/maven-consumer-project/.github/copilot-instructions.md` is the same bootstrap-plus-pointer for IntelliJ Copilot Chat, which reads that file rather than `AGENTS.md`.
+The nested `/maven-consumer-project/.github/copilot-instructions.md` is identical to `AGENTS.md` so Copilot Chat sees the same Workbench pointer.
 
 The nested `/maven-consumer-project/README.md` is ordinary sample-project documentation. It may point humans and agents at `AGENTS.md` for guidance export, but should not duplicate the AI guidance lifecycle.
 

docs/agent/repository-index.md

@@ -237,13 +237,17 @@ This inventory helps coding agents discover relevant files. It does not replace
 - `src/main/java/tools/dscode/common/mappings/ScenarioMapping.java`
 - `src/main/java/tools/dscode/common/mappings/StepMapping.java`
 - `src/main/java/tools/dscode/common/mappings/ValueFormatting.java`
+- `src/main/java/tools/dscode/common/reporting/diagnostic/AgentBrowserLadder.java`
+- `src/main/java/tools/dscode/common/reporting/diagnostic/AgentDiscoverPlanner.java`
 - `src/main/java/tools/dscode/common/reporting/diagnostic/ConfigurationProvenance.java`
+- `src/main/java/tools/dscode/common/reporting/diagnostic/ConsumerMavenTestRunner.java`
 - `src/main/java/tools/dscode/common/reporting/diagnostic/DiagnosticCli.java`
 - `src/main/java/tools/dscode/common/reporting/diagnostic/DiagnosticIndexRebuilder.java`
 - `src/main/java/tools/dscode/common/reporting/diagnostic/DiagnosticReporter.java`
 - `src/main/java/tools/dscode/common/reporting/diagnostic/DiagnosticRunComparator.java`
 - `src/main/java/tools/dscode/common/reporting/diagnostic/DiagnosticRuntime.java`
 - `src/main/java/tools/dscode/common/reporting/diagnostic/ExplicitReportRegistry.java`
+- `src/main/java/tools/dscode/common/reporting/diagnostic/LastDiscoverSnapshot.java`
 - `src/main/java/tools/dscode/common/reporting/diagnostic/ReportRetentionPolicy.java`
 - `src/main/java/tools/dscode/common/reporting/diagnostic/ScenarioIdentity.java`
 - `src/main/java/tools/dscode/common/reporting/diagnostic/SourceProvenance.java`
@@ -365,6 +369,8 @@ This inventory helps coding agents discover relevant files. It does not replace
 - `src/main/java/tools/dscode/coredefinitions/UtilitySteps.java`
 - `src/main/java/tools/dscode/cucumberextended/utilities/StringUtilities.java`
 - `src/main/java/tools/dscode/launcher/PickleballWorkbenchLauncher.java`
+- `src/main/java/tools/dscode/launcher/WorkbenchAgentCommands.java`
+- `src/main/java/tools/dscode/launcher/WorkbenchCommandLine.java`
 - `src/main/java/tools/dscode/misc/DummySteps.java`
 - `src/main/java/tools/dscode/parallelutilities/ParallelCountEstimator.java`
 - `src/main/java/tools/dscode/parallelutilities/Stagger.java`
@@ -389,8 +395,11 @@ This inventory helps coding agents discover relevant files. It does not replace
 
 ## Framework tests
 
+- `src/test/java/tools/dscode/common/reporting/diagnostic/AgentBrowserLadderTest.java`
+- `src/test/java/tools/dscode/common/reporting/diagnostic/AgentDiscoverPlannerTest.java`
 - `src/test/java/tools/dscode/control/override/StepOverrideCompilerTest.java`
 - `src/test/java/tools/dscode/launcher/PickleballWorkbenchLauncherTest.java`
+- `src/test/java/tools/dscode/launcher/WorkbenchAgentCommandsTest.java`
 - `src/test/java/tools/dscode/parallelutilities/ParallelCountEstimatorTest.java`
 - `src/test/java/tools/dscode/testengine/DynamicSuiteBootstrapWorkbenchRootTest.java`
 
@@ -484,6 +493,7 @@ This inventory helps coding agents discover relevant files. It does not replace
 - `pickleball-workbench/src/main/java/tools/dscode/workbench/catalog/ConsumerFeatureCatalog.java`
 - `pickleball-workbench/src/main/java/tools/dscode/workbench/catalog/ScenarioFilter.java`
 - `pickleball-workbench/src/main/java/tools/dscode/workbench/diagnostics/DiagnosticEvidenceNavigator.java`
+- `pickleball-workbench/src/main/java/tools/dscode/workbench/discover/LastDiscoverSnapshot.java`
 - `pickleball-workbench/src/main/java/tools/dscode/workbench/lease/WorkbenchCallContext.java`
 - `pickleball-workbench/src/main/java/tools/dscode/workbench/lease/WorkbenchControlLease.java`
 - `pickleball-workbench/src/main/java/tools/dscode/workbench/lease/WorkbenchControlLeaseSnapshot.java`
@@ -547,6 +557,7 @@ This inventory helps coding agents discover relevant files. It does not replace
 - `pickleball-workbench/src/test/java/tools/dscode/workbench/catalog/ScenarioFilterTest.java`
 - `pickleball-workbench/src/test/java/tools/dscode/workbench/diagnostics/DiagnosticEvidenceNavigatorTest.java`
 - `pickleball-workbench/src/test/java/tools/dscode/workbench/diagnostics/InvestigationHandoffTest.java`
+- `pickleball-workbench/src/test/java/tools/dscode/workbench/discover/LastDiscoverSnapshotTest.java`
 - `pickleball-workbench/src/test/java/tools/dscode/workbench/lease/WorkbenchControlLeaseTest.java`
 - `pickleball-workbench/src/test/java/tools/dscode/workbench/mapping/MappingValueCodecTest.java`
 - `pickleball-workbench/src/test/java/tools/dscode/workbench/mcp/WorkbenchAttachServerTest.java`
@@ -595,6 +606,7 @@ This inventory helps coding agents discover relevant files. It does not replace
 - `maven-consumer-project/src/test/java/tools/dscode/common/driver/ChromeHeadlessConfigChecks.java`
 - `maven-consumer-project/src/test/java/tools/dscode/common/mappings/MappingDataRefactorChecks.java`
 - `maven-consumer-project/src/test/java/tools/dscode/common/mappings/QuoteParserChecks.java`
+- `maven-consumer-project/src/test/java/tools/dscode/common/reporting/diagnostic/AgentBrowserLadderChecks.java`
 - `maven-consumer-project/src/test/java/tools/dscode/common/reporting/diagnostic/Diagnostic213CompletionChecks.java`
 - `maven-consumer-project/src/test/java/tools/dscode/common/reporting/diagnostic/DiagnosticReportingChecks.java`
 - `maven-consumer-project/src/test/java/tools/dscode/common/reporting/diagnostic/InvestigationHandoffChecks.java`
@@ -603,6 +615,7 @@ This inventory helps coding agents discover relevant files. It does not replace
 - `maven-consumer-project/src/test/java/tools/dscode/common/util/datetime/BusinessTimePostModifierChecks.java`
 - `maven-consumer-project/src/test/java/tools/dscode/coredefinitions/DataTableConversionChecks.java`
 - `maven-consumer-project/src/test/java/tools/dscode/coredefinitions/ModularScenariosChecks.java`
+- `maven-consumer-project/src/test/java/tools/dscode/launcher/WorkbenchAgentCommandChecks.java`
 - `maven-consumer-project/src/test/java/tools/dscode/parallelutilities/ParallelCountEstimatorChecks.java`
 - `maven-consumer-project/src/test/java/tools/dscode/testengine/PkbPropertyValueNormalizerChecks.java`
 - `maven-consumer-project/src/test/java/tools/dscode/testengine/ProfileConfigurationChecks.java`

docs/ai-diagnostic-reporting-plan.md

@@ -132,13 +132,13 @@ For a source-only fix, reuse the retained RunVars unchanged and omit `pkb_change
 ```text
 DiagnosticCli guidance
 DiagnosticCli export-guidance [output-directory]
-DiagnosticCli discover-hint
+DiagnosticCli discover-hint [project]
 DiagnosticCli emit-investigation <investigation-json-or--> <consumer-project-root>
 DiagnosticCli compare-runs <left-run-index> <right-run-index> [output-json]
 DiagnosticCli compare-fingerprints <left.pkbf> <right.pkbf> [output-json]
 DiagnosticCli rebuild <diagnostic-runs-root-or-run-root>
 ```
 
-`DiagnosticCli help`, `--help`, and `-h` print this same command list.
+`DiagnosticCli help`, `--help`, and `-h` print this list. The agent-facing entry is Pickleball Workbench.
 
 See `docs/diagnostic-reporting.md` for evidence use, `docs/ai-run-configuration.md` for controlled execution, and `docs/diagnostic-lineage-metadata.md` for investigation metadata.

docs/ai-run-configuration.md

@@ -323,18 +323,18 @@ When operating in a consumer project:
 
 ## AI agents
 
-Set a **complete** Discover `pkb_runvars` rather than a partial overlay:
+The agent-facing entry is Pickleball Workbench (`hint`, `discover`, `isolate`, `confirm`). Set a **complete** Discover `pkb_runvars` rather than a partial overlay. Workbench `hint` prints the browser-ladder result and estimated integer parallel count. The browser ladder keeps a remote project `pkb_browser` (`SAUCE_*` / `GRID_*` / `REMOTE_*`); otherwise it prefers `CHROME_HEADLESS`. Unused Sauce/Grid yaml files are not auto-selected.
 
 ```text
-pkb_browser=CHROME_HEADLESS
+pkb_browser=<browser ladder>
 pkb_parallel=<conservative JVM estimate or auto>
 pkb_reportingmode=diagnostic
 pkb_loglevel=warn
 pkb_reportretention=failed
 ```
 
-plus the narrowest useful `pkb_tags` / `pkb_name`. `DiagnosticCli discover-hint` prints the estimated integer parallel count for the current JVM. Multi-scenario Discover/Confirm must use headless Chrome and high parallelism. Isolate / live Workbench stays one paused scenario.
+plus the narrowest useful `pkb_tags` / `pkb_name`. Multi-scenario Discover/Confirm use that high parallelism. Isolate / live Workbench stays one paused scenario.
 
-After the run, inspect `pkb_run_profile` from `run-catalog.json`, `run-index.json`, or `summary.json`. That output is the complete resolved RunVar list after inheritance (glue/features/data/call/component/configpath) and after `pkb_parallel=auto` is stamped as an integer. Do not assume omitted `pkb_runvars` keys equal project `pickleball.properties` — optional keys such as headed Chrome, `pretty`, and `pkb_tags=@all` do not leak into a controlled run, which is why agents must set the Discover keys explicitly.
+After Discover, inspect `pkb_run_profile` from `run-catalog.json`, `run-index.json`, or `summary.json`. Isolate and confirm replay that retained profile through `pkb_runvars`. If there is no prior Discover snapshot, Workbench says so; it does not silently re-resolve from project defaults.
 
 Never supply `pkb_run_profile` as input. Workbench MCP `workbench_diagnostic_catalog`, `workbench_diagnostic_run`, and `workbench_diagnostic_summary` return the same retained `runProfile` when present. The consumer worker resolves the same snapshot internally through `PickleballRunner`; it does not accept `pkb_run_profile` as input.

docs/configuration.md

@@ -356,7 +356,7 @@ max(2, min(availableProcessors, floor(maxMemoryMB / 512), 24))
 
 Chrome workers are RAM-heavy, so a 32-core / 64GiB box does not blindly pick 32 workers; the hard cap is 24, and heap can cap lower. Tiny heaps resolve to 2. An explicit numeric `pkb_parallel` is never overwritten. Omitting `pkb_parallel` does not enable parallel execution.
 
-The resolved integer is stamped into the final RunVars and `pkb_run_profile`. `DiagnosticCli discover-hint` prints that estimated number in the recommended Discover `pkb_runvars` command.
+The resolved integer is stamped into the final RunVars and `pkb_run_profile`. Workbench `hint` prints that estimated number in the recommended Discover `pkb_runvars` command.
 
 ## Bundled `CHROME_HEADLESS`
 
@@ -367,6 +367,16 @@ The resolved integer is stamped into the final RunVars and `pkb_run_profile`. `D
 
 The bundled headless config uses `--headless=new`, a fixed `--window-size=1920,1080`, no `MAXIMIZE`, and `QUIT_LOCAL_DRIVER`. Consumer `CHROME`, `EDGE`, `GRID`, and `SAUCE` yaml files are unchanged. Agents can set `pkb_browser=CHROME_HEADLESS` without copying yaml into the project.
 
+## Agent Discover browser ladder
+
+Workbench Discover/Confirm do not blindly MUST-use `CHROME_HEADLESS` for every project:
+
+1. If `default_profile` / runner / retained `pkb_run_profile` `pkb_browser` is already a remote farm name (`SAUCE_*`, `GRID_*`, `REMOTE_*`, or clearly non-local), keep it. Those consumers run exclusively on the external farm.
+2. Otherwise prefer `CHROME_HEADLESS` (consumer yaml if present, else the JAR-bundled config above).
+3. If local headless cannot start and the project already defines and uses GRID/SAUCE/REMOTE as its `pkb_browser`, fall back to that project browser. Do not pick Sauce/Grid merely because unused yaml files exist in `configs/`.
+
+Isolate stays one scenario and does not raise `pkb_parallel`.
+
 ## Cucumber aliases
 
 Pickleball synchronizes its main selection aliases with Cucumber properties, including: