Add consumer-side Pickleball guidance pointers

docs/agent/README.md

@@ -20,7 +20,9 @@ Agent adapters should remain small and point back to the canonical contract rath
 
 The nested `/maven-consumer-project/AGENTS.md` is intentionally only a dependency-owned guidance bootstrap. It materializes version-matched guidance and directs the consumer agent to `.pickleball/AGENT-GUIDE.md`. Refresh/version/manifest semantics, authoring rules, configuration, diagnostics, and troubleshooting belong in the exported dependency guidance.
 
-The nested `/maven-consumer-project/README.md` is ordinary sample-project documentation and should not duplicate the AI guidance lifecycle.
+The nested `/maven-consumer-project/.github/copilot-instructions.md` is the same one-line bootstrap for IntelliJ Copilot Chat, which reads that file rather than `AGENTS.md`.
+
+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.
 
 `export-guidance .pickleball` is deliberately unconditional before Pickleball work. A successful export writes `.pickleball/GUIDANCE-MANIFEST.json` last, removes obsolete previously managed files, and refreshes current dependency guidance. Git-ignore handling is best effort. If export fails, existing `.pickleball` content is potentially stale.
 

docs/agent/feature-map.md

@@ -19,7 +19,7 @@ This file maps consumer-visible capabilities to implementation anchors, executab
 | Custom element definitions/catalog context | `ExecutionDictionary.java`; `ElementMatch.java`; consumer `PickleballTests.java`; search `category(`, `inheritsFrom` | `catalog-context.feature`; `forms-dynamic-steps.feature`; `site/catalog.html` | `docs/custom-element-definitions.md`; `docs/config-files-and-resource-mapping.md` |
 | Mapping, ParsingMap/NodeMap, templates/directives | `MappingSteps.java`; `FileAndDataParsing.java`; `MappingProcessor.java`; `NodeMap.java`; `ParsingMap.java`; `ValueFormatting.java`; `common/dataelements` | `mapping-and-resources.feature`; `mapping-value-type-preservation.feature`; `scenario-data-references.feature`; Data Element features; internal Java checks | `docs/mapping-and-templating.md`; `docs/data-values-and-elements.md`; `docs/data-element-query-runtime.md`; `docs/config-files-and-resource-mapping.md` |
 | Configuration/profiles/RunVars | `PKB_props.java`; `PickleballProfiles.java`; `PkbPropertyValueNormalizer.java`; runner/config classes; search `pkb_profile`, `pkb_runvars`, `pkb_run_profile`, `pkb_configpath` | `configuration-system-properties.feature`; `ProfileConfigurationChecks.java`; consumer properties/profile examples | `docs/configuration.md`; `docs/getting-started.md`; `docs/ai-run-configuration.md`; `docs/consumer-project.md` |
-| Consumer guidance export/reference snapshot | `DiagnosticCli.java`; `gradle/consumer-guidance.gradle`; `scripts/sync_consumer_guidance.py`; search `export-guidance`, `GUIDANCE-MANIFEST.json` | `PickleballGuidanceChecks.java`; consumer guidance contract checks | `docs/consumer-agent-guide.md`; `docs/consumer-project.md` |
+| Consumer guidance export/reference snapshot | `DiagnosticCli.java`; `gradle/consumer-guidance.gradle`; `scripts/sync_consumer_guidance.py`; `maven-consumer-project/AGENTS.md`; `maven-consumer-project/.github/copilot-instructions.md`; search `export-guidance`, `GUIDANCE-MANIFEST.json` | `PickleballGuidanceChecks.java`; consumer guidance contract checks | `docs/consumer-agent-guide.md`; `docs/consumer-project.md` |
 | Diagnostic reporting and controlled reruns | `src/main/java/tools/dscode/common/reporting/diagnostic`; diagnostic aspects; `DiagnosticCli.java`; `VisualFingerprintComparator.java`; `DiagnosticRunComparator.java` | `DiagnosticReportingChecks.java`; `Diagnostic213CompletionChecks.java`; diagnostic features | `docs/diagnostic-reporting.md`; `docs/ai-diagnostic-reporting-plan.md`; `docs/ai-run-configuration.md`; root `AGENTS.md` |
 | Nested steps/block conditionals | search `Nested`, `Conditional`, `Block`, `Condition` in core implementation | `nested-and-block-conditionals.feature` | `docs/nested-steps.md`; `docs/block-conditionals.md` |
 | Component scenarios/reusable RUN/selectors/markers | `ModularScenarios.java`; `ScenarioStep.java`; `ScenarioStepData.java`; `StepBase.java`; `StepExtension.java`; `CurrentScenarioState.java`; `CucumberScanUtil.java`; search `finalizerSteps`, `RunSelection` | `component-scenarios.feature`; `reusable-scenario-selection.feature`; `run-step-parameter-variations.feature`; marker features | `docs/component-scenarios.md`; `docs/service-call-scenarios.md`; `docs/data-values-and-elements.md` |

docs/agent/repository-index.md

@@ -9,6 +9,7 @@ This inventory helps coding agents discover relevant files. It does not replace
 - `build.gradle`
 - `gradlew`
 - `gradlew.bat`
+- `maven-consumer-project/.github/copilot-instructions.md`
 - `maven-consumer-project/.mvn/wrapper/maven-wrapper.properties`
 - `maven-consumer-project/AGENTS.md`
 - `maven-consumer-project/mvnw`

docs/consumer-project.md

@@ -42,7 +42,7 @@ The snapshot includes:
 - static local test-site resources; and
 - the committed shared/local `profiles*.yaml` and `pickleball*.properties` examples.
 
-It intentionally excludes Maven wrappers, Git/IDE/generated artifacts, the consumer `AGENTS.md` bridge, internal Java verification classes, and maintainer-only `_local2` files. It is reference material, not another consumer project to edit or run. Make changes in the real consumer project; a future guidance export may replace every managed file in this snapshot.
+It intentionally excludes Maven wrappers, Git/IDE/generated artifacts, the consumer `AGENTS.md` and `.github/copilot-instructions.md` bridges, internal Java verification classes, and maintainer-only `_local2` files. It is reference material, not another consumer project to edit or run. Make changes in the real consumer project; a future guidance export may replace every managed file in this snapshot.
 
 ## Purpose
 

maven-consumer-project/.github/copilot-instructions.md

@@ -0,0 +1 @@
+Before any Pickleball work, run `mvn -q org.codehaus.mojo:exec-maven-plugin:3.5.0:java "-Dexec.mainClass=tools.dscode.common.reporting.diagnostic.DiagnosticCli" "-Dexec.classpathScope=test" "-Dexec.args=export-guidance .pickleball"` and, after a successful export, follow `.pickleball/AGENT-GUIDE.md`.

maven-consumer-project/README.md

@@ -2,6 +2,8 @@
 
 This is a standalone Maven example project that consumes Pickleball as a test-scoped dependency and exercises browser and service behavior against its local test site.
 
+Before Pickleball work, export guidance and see `AGENTS.md`.
+
 ## Run
 
 ```bash

maven-consumer-project/src/test/java/tools/dscode/common/reporting/diagnostic/PickleballGuidanceChecks.java

@@ -112,6 +112,7 @@ void dependencyExportsVersionMatchedGuidanceAndManifest() throws Exception {
             ));
             assertTrue(managedFiles.stream().noneMatch(path -> path.contains("_local2")));
             assertFalse(managedFiles.contains("maven-consumer-project/AGENTS.md"));
+            assertFalse(managedFiles.contains("maven-consumer-project/.github/copilot-instructions.md"));
             assertFalse(managedFiles.contains("maven-consumer-project/mvnw"));
             assertFalse(managedFiles.contains(
                     "maven-consumer-project/src/test/java/tools/dscode/common/reporting/diagnostic/PickleballGuidanceChecks.java"

scripts/refresh_agent_index.py

@@ -31,6 +31,7 @@
         "gradlew",
         "gradlew.bat",
         "maven-consumer-project/AGENTS.md",
+        "maven-consumer-project/.github/copilot-instructions.md",
         "maven-consumer-project/pom.xml",
         "maven-consumer-project/README.md",
         "maven-consumer-project/mvnw",

scripts/verify_agent_contract.py

@@ -47,6 +47,7 @@
     "scripts/agent_validate.sh",
     "scripts/agent_validate.ps1",
     "maven-consumer-project/AGENTS.md",
+    "maven-consumer-project/.github/copilot-instructions.md",
     "maven-consumer-project/README.md",
     "maven-consumer-project/.gitignore",
     "maven-consumer-project/mvnw",
@@ -79,7 +80,6 @@
     "maven-consumer-project/GEMINI.md",
     "maven-consumer-project/REVIEW.md",
     "maven-consumer-project/.clinerules",
-    "maven-consumer-project/.github/copilot-instructions.md",
 }
 ADAPTER_FILES = (
     "CLAUDE.md",
@@ -136,6 +136,7 @@
     "pickleball-workbench/AGENTS.md",
     "maven-consumer-project/README.md",
     "maven-consumer-project/AGENTS.md",
+    "maven-consumer-project/.github/copilot-instructions.md",
 }
 
 WORKBENCH_CONTRACT_FILES = (
@@ -278,50 +279,69 @@ def starts_with_any(path: str, prefixes: tuple[str, ...]) -> bool:
     return any(path.startswith(prefix) for prefix in prefixes)
 
 
-def validate_consumer_bridge(errors: list[str]) -> None:
-    bridge = ROOT / "maven-consumer-project" / "AGENTS.md"
-    if not bridge.is_file():
-        return
+CONSUMER_BRIDGE_FILES = (
+    "maven-consumer-project/AGENTS.md",
+    "maven-consumer-project/.github/copilot-instructions.md",
+)
 
-    text = bridge.read_text(encoding="utf-8").strip()
-    nonblank_lines = [line for line in text.splitlines() if line.strip()]
-    if len(nonblank_lines) != 1:
-        errors.append(
-            "Consumer AGENTS bridge must stay a single nonblank bootstrap line: "
-            "maven-consumer-project/AGENTS.md"
-        )
 
-    for required in (
-        "DiagnosticCli",
-        "export-guidance",
-        ".pickleball/AGENT-GUIDE.md",
-    ):
-        if required not in text:
-            errors.append(
-                f"Consumer AGENTS bridge must reference {required}: "
-                "maven-consumer-project/AGENTS.md"
-            )
+def validate_consumer_bridge(errors: list[str]) -> None:
+    texts: list[str] = []
+    for relative in CONSUMER_BRIDGE_FILES:
+        path = ROOT / relative
+        if not path.is_file():
+            continue
 
-    for forbidden in (
-        "GUIDANCE-MANIFEST.json",
-        ".git/info/exclude",
-        "pkb_changed_variables",
-        "runProfileFingerprint",
-        "Diagnostic investigation protocol",
-    ):
-        if forbidden in text:
+        text = path.read_text(encoding="utf-8").strip()
+        texts.append(text)
+        nonblank_lines = [line for line in text.splitlines() if line.strip()]
+        if len(nonblank_lines) != 1:
             errors.append(
-                f"Consumer AGENTS bridge contains dependency-owned guidance ({forbidden}); "
-                "keep only the bootstrap command and generated-guide pointer."
+                "Consumer guidance bridge must stay a single nonblank bootstrap line: "
+                + relative
             )
 
+        for required in (
+            "DiagnosticCli",
+            "export-guidance",
+            ".pickleball/AGENT-GUIDE.md",
+        ):
+            if required not in text:
+                errors.append(
+                    f"Consumer guidance bridge must reference {required}: {relative}"
+                )
+
+        for forbidden in (
+            "GUIDANCE-MANIFEST.json",
+            ".git/info/exclude",
+            "pkb_changed_variables",
+            "runProfileFingerprint",
+            "Diagnostic investigation protocol",
+        ):
+            if forbidden in text:
+                errors.append(
+                    f"Consumer guidance bridge contains dependency-owned guidance ({forbidden}); "
+                    "keep only the bootstrap command and generated-guide pointer: "
+                    + relative
+                )
+
+    if len(texts) == len(CONSUMER_BRIDGE_FILES) and len(set(texts)) != 1:
+        errors.append(
+            "Consumer AGENTS.md and .github/copilot-instructions.md bridges must be identical."
+        )
+
 
 def validate_consumer_readme(errors: list[str]) -> None:
     readme = ROOT / "maven-consumer-project" / "README.md"
     if not readme.is_file():
         return
 
     text = readme.read_text(encoding="utf-8")
+    if "AGENTS.md" not in text:
+        errors.append(
+            "Consumer README must point to AGENTS.md for guidance export: "
+            "maven-consumer-project/README.md"
+        )
     for forbidden in (
         "export-guidance",
         ".pickleball/",

src/main/resources/META-INF/pickleball/guidance/docs/agent/README.md

@@ -20,7 +20,9 @@ Agent adapters should remain small and point back to the canonical contract rath
 
 The nested `/maven-consumer-project/AGENTS.md` is intentionally only a dependency-owned guidance bootstrap. It materializes version-matched guidance and directs the consumer agent to `.pickleball/AGENT-GUIDE.md`. Refresh/version/manifest semantics, authoring rules, configuration, diagnostics, and troubleshooting belong in the exported dependency guidance.
 
-The nested `/maven-consumer-project/README.md` is ordinary sample-project documentation and should not duplicate the AI guidance lifecycle.
+The nested `/maven-consumer-project/.github/copilot-instructions.md` is the same one-line bootstrap for IntelliJ Copilot Chat, which reads that file rather than `AGENTS.md`.
+
+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.
 
 `export-guidance .pickleball` is deliberately unconditional before Pickleball work. A successful export writes `.pickleball/GUIDANCE-MANIFEST.json` last, removes obsolete previously managed files, and refreshes current dependency guidance. Git-ignore handling is best effort. If export fails, existing `.pickleball` content is potentially stale.
 

src/main/resources/META-INF/pickleball/guidance/docs/agent/feature-map.md

@@ -19,7 +19,7 @@ This file maps consumer-visible capabilities to implementation anchors, executab
 | Custom element definitions/catalog context | `ExecutionDictionary.java`; `ElementMatch.java`; consumer `PickleballTests.java`; search `category(`, `inheritsFrom` | `catalog-context.feature`; `forms-dynamic-steps.feature`; `site/catalog.html` | `docs/custom-element-definitions.md`; `docs/config-files-and-resource-mapping.md` |
 | Mapping, ParsingMap/NodeMap, templates/directives | `MappingSteps.java`; `FileAndDataParsing.java`; `MappingProcessor.java`; `NodeMap.java`; `ParsingMap.java`; `ValueFormatting.java`; `common/dataelements` | `mapping-and-resources.feature`; `mapping-value-type-preservation.feature`; `scenario-data-references.feature`; Data Element features; internal Java checks | `docs/mapping-and-templating.md`; `docs/data-values-and-elements.md`; `docs/data-element-query-runtime.md`; `docs/config-files-and-resource-mapping.md` |
 | Configuration/profiles/RunVars | `PKB_props.java`; `PickleballProfiles.java`; `PkbPropertyValueNormalizer.java`; runner/config classes; search `pkb_profile`, `pkb_runvars`, `pkb_run_profile`, `pkb_configpath` | `configuration-system-properties.feature`; `ProfileConfigurationChecks.java`; consumer properties/profile examples | `docs/configuration.md`; `docs/getting-started.md`; `docs/ai-run-configuration.md`; `docs/consumer-project.md` |
-| Consumer guidance export/reference snapshot | `DiagnosticCli.java`; `gradle/consumer-guidance.gradle`; `scripts/sync_consumer_guidance.py`; search `export-guidance`, `GUIDANCE-MANIFEST.json` | `PickleballGuidanceChecks.java`; consumer guidance contract checks | `docs/consumer-agent-guide.md`; `docs/consumer-project.md` |
+| Consumer guidance export/reference snapshot | `DiagnosticCli.java`; `gradle/consumer-guidance.gradle`; `scripts/sync_consumer_guidance.py`; `maven-consumer-project/AGENTS.md`; `maven-consumer-project/.github/copilot-instructions.md`; search `export-guidance`, `GUIDANCE-MANIFEST.json` | `PickleballGuidanceChecks.java`; consumer guidance contract checks | `docs/consumer-agent-guide.md`; `docs/consumer-project.md` |
 | Diagnostic reporting and controlled reruns | `src/main/java/tools/dscode/common/reporting/diagnostic`; diagnostic aspects; `DiagnosticCli.java`; `VisualFingerprintComparator.java`; `DiagnosticRunComparator.java` | `DiagnosticReportingChecks.java`; `Diagnostic213CompletionChecks.java`; diagnostic features | `docs/diagnostic-reporting.md`; `docs/ai-diagnostic-reporting-plan.md`; `docs/ai-run-configuration.md`; root `AGENTS.md` |
 | Nested steps/block conditionals | search `Nested`, `Conditional`, `Block`, `Condition` in core implementation | `nested-and-block-conditionals.feature` | `docs/nested-steps.md`; `docs/block-conditionals.md` |
 | Component scenarios/reusable RUN/selectors/markers | `ModularScenarios.java`; `ScenarioStep.java`; `ScenarioStepData.java`; `StepBase.java`; `StepExtension.java`; `CurrentScenarioState.java`; `CucumberScanUtil.java`; search `finalizerSteps`, `RunSelection` | `component-scenarios.feature`; `reusable-scenario-selection.feature`; `run-step-parameter-variations.feature`; marker features | `docs/component-scenarios.md`; `docs/service-call-scenarios.md`; `docs/data-values-and-elements.md` |

src/main/resources/META-INF/pickleball/guidance/docs/agent/repository-index.md

@@ -9,6 +9,7 @@ This inventory helps coding agents discover relevant files. It does not replace
 - `build.gradle`
 - `gradlew`
 - `gradlew.bat`
+- `maven-consumer-project/.github/copilot-instructions.md`
 - `maven-consumer-project/.mvn/wrapper/maven-wrapper.properties`
 - `maven-consumer-project/AGENTS.md`
 - `maven-consumer-project/mvnw`

src/main/resources/META-INF/pickleball/guidance/docs/consumer-project.md

@@ -42,7 +42,7 @@ The snapshot includes:
 - static local test-site resources; and
 - the committed shared/local `profiles*.yaml` and `pickleball*.properties` examples.
 
-It intentionally excludes Maven wrappers, Git/IDE/generated artifacts, the consumer `AGENTS.md` bridge, internal Java verification classes, and maintainer-only `_local2` files. It is reference material, not another consumer project to edit or run. Make changes in the real consumer project; a future guidance export may replace every managed file in this snapshot.
+It intentionally excludes Maven wrappers, Git/IDE/generated artifacts, the consumer `AGENTS.md` and `.github/copilot-instructions.md` bridges, internal Java verification classes, and maintainer-only `_local2` files. It is reference material, not another consumer project to edit or run. Make changes in the real consumer project; a future guidance export may replace every managed file in this snapshot.
 
 ## Purpose