From 556fe3b37a5502b9a6d831654496fe6f9ce622c6 Mon Sep 17 00:00:00 2001
From: Jaroslav Bachorik <j.bachorik@btrace.io>
Date: Fri, 2 Oct 2026 23:31:49 +0200
Subject: [PATCH] docs: invoke JBang scripts directly, note jbang fallback

The Java scripts are executable with a self-launching header, so docs now
call them directly and mention `jbang <script>` for checkouts that lose
the executable bit. Docs-only; no code changed.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 plugins/jfr-analyzer/README.md                      |  2 +-
 .../skills/jfr-analyzer/subskills/eval/SKILL.md     |  4 +++-
 plugins/perf-engineer/README.md                     | 13 ++++++++-----
 plugins/perf-engineer/skills/perf-engineer/SKILL.md |  2 +-
 4 files changed, 13 insertions(+), 8 deletions(-)

diff --git a/plugins/jfr-analyzer/README.md b/plugins/jfr-analyzer/README.md
index 6d6fb42..4ffaf2c 100644
--- a/plugins/jfr-analyzer/README.md
+++ b/plugins/jfr-analyzer/README.md
@@ -54,7 +54,7 @@ plugins/jfr-analyzer/eval/scripts/regen.sh
 The script prompts before installing JBang, async-profiler, or `jq`, then records the corpus and
 updates its manifest. After the MCP server is available, run `/jfr-analyzer eval regen` to extract
 event types and optionally validate oracle results. Run `/jfr-analyzer eval run` for triage passes,
-then `/jfr-analyzer eval score` to generate the report. Scoring runs `eval/scripts/Score.java` through JBang and may require the judge API
+then `/jfr-analyzer eval score` to generate the report. Scoring runs the executable `eval/scripts/Score.java` (a JBang script; `jbang eval/scripts/Score.java` works too) and may require the judge API
 key named in that file.
 
 ## Transport strategy
diff --git a/plugins/jfr-analyzer/skills/jfr-analyzer/subskills/eval/SKILL.md b/plugins/jfr-analyzer/skills/jfr-analyzer/subskills/eval/SKILL.md
index 4820461..beea508 100644
--- a/plugins/jfr-analyzer/skills/jfr-analyzer/subskills/eval/SKILL.md
+++ b/plugins/jfr-analyzer/skills/jfr-analyzer/subskills/eval/SKILL.md
@@ -139,7 +139,9 @@ Parse `--scenario` and `--multi-judge` flags from $ARGUMENTS.
 
 Run (JBang resolves the Jackson dependency on first use):
 ```bash
-cd <EVAL_DIR>/scripts && jbang Score.java [--scenario <id> if set] [--multi-judge if set]
+cd <EVAL_DIR>/scripts && ./Score.java [--scenario <id> if set] [--multi-judge if set]
 ```
 
+If `./Score.java` is not executable, use `jbang Score.java` with the same flags.
+
 Display the generated report content.
diff --git a/plugins/perf-engineer/README.md b/plugins/perf-engineer/README.md
index 1427a73..82542c3 100644
--- a/plugins/perf-engineer/README.md
+++ b/plugins/perf-engineer/README.md
@@ -17,18 +17,21 @@ The first supervisor implementation manages one async-profiler recording. It val
 enforces a maximum duration, persists state, and supports stop/status/cleanup:
 
 ```sh
-jbang plugins/perf-engineer/scripts/PerfEngineerSession.java start <pid> \
+plugins/perf-engineer/scripts/PerfEngineerSession.java start <pid> \
   --event cpu --duration 30 --output /tmp/profile.jfr
-jbang plugins/perf-engineer/scripts/PerfEngineerSession.java status <session-id>
-jbang plugins/perf-engineer/scripts/PerfEngineerSession.java stop <session-id>
-jbang plugins/perf-engineer/scripts/PerfEngineerSession.java cleanup <session-id>
+plugins/perf-engineer/scripts/PerfEngineerSession.java status <session-id>
+plugins/perf-engineer/scripts/PerfEngineerSession.java stop <session-id>
+plugins/perf-engineer/scripts/PerfEngineerSession.java cleanup <session-id>
 ```
 
+The scripts are executable JBang programs; if the executable bit is lost (for example on a Windows
+checkout), run them as `jbang plugins/perf-engineer/scripts/PerfEngineerSession.java <args>` instead.
+
 Set `ASYNC_PROFILER_HOME` or pass `--profiler` when the async-profiler CLI is not on `PATH`. This
 supervises one recording only; BTrace probes and later analysis remain separate workflow phases.
 
 Run the supervisor regression tests with:
 
 ```sh
-jbang plugins/perf-engineer/scripts/PerfEngineerSessionTest.java
+plugins/perf-engineer/scripts/PerfEngineerSessionTest.java
 ```
diff --git a/plugins/perf-engineer/skills/perf-engineer/SKILL.md b/plugins/perf-engineer/skills/perf-engineer/SKILL.md
index 275447f..8610e19 100644
--- a/plugins/perf-engineer/skills/perf-engineer/SKILL.md
+++ b/plugins/perf-engineer/skills/perf-engineer/SKILL.md
@@ -57,7 +57,7 @@ Before promising a phase, verify that the required capability is actually availa
 
 This plugin currently provides the orchestration contract, not a bundled session-supervisor
 executable. A bounded one-recording supervisor is available at
-`scripts/PerfEngineerSession.java` (run with `jbang`); use it when async-profiler CLI access is available. It does not
+`scripts/PerfEngineerSession.java` (executable; runs via JBang); use it when async-profiler CLI access is available. It does not
 supervise BTrace or later analysis phases. If it is unavailable, use only a bounded recording with
 the hard timeout enforced by the recording command itself. Do not offer “until I say stop,” durable
 orphan recovery, or claim that a session is supervised. If a delegated plugin or host provides a