Performance-engineer-in-a-box: a findings model, MCP groundwork, and ask — an investigation inside the shells

[jbachorik]

Turns Jafar's existing surface — the MCP server, four shells, four query languages, the heap
analyses — into something that carries methodology, not just capability. Two directions, and
they meet in the middle:

• Outward: a findings model and MCP groundwork, so an external agent driving the server knows
  which analysis to run and can merge results from several tools. The Claude Code plugin that
  carries that methodology is published separately — see §1.
• Inward: ask — a model inside the shells themselves, which investigates a question over
  several queries, prints every one of them with the rows it returned, and concludes. Multi-provider,
  including a fully local one.

Then the two meet: the analyses the MCP server exposes as jfr_diagnose, jfr_use and jfr_tsa
moved into shell-core, so the in-shell investigation calls the same code rather than trying to
rebuild that judgement out of queries.

While this PR is open the branch is a series of self-contained commits, so it can be reviewed a
piece at a time; the two design documents come first deliberately, so the implementation can be read
against a stated plan. The sections below follow that order.

---

1. jafar-perf — the methodology layer (separate repository)

A Claude Code plugin carrying what the tools do not: nine skills (triage, cpu, latency,
gc, memory-leak, heap-diff, compare, jfrpath, report) and seven agents — a
perf-lead coordinator plus five specialists with narrow tool allowlists. It bundles .mcp.json,
so installing it registers the MCP server too.

/plugin marketplace add btraceio/jafar-perf-box
/plugin install jafar-perf@btraceio

It is not in this repository. /plugin marketplace add clones the marketplace's repository, so
shipping it here would have cost a ~18 MB clone — 9.6 MB of it binary JFR test recordings — to
deliver 160 KB of Markdown. It is published from
btraceio/jafar-perf-box, which is that 160 KB.

The split has one real cost, and it is now enforced rather than merely documented: the skills name
MCP tools and parameters explicitly, and nothing in this repository's tests covers them, so a tool
rename here would silently break a skill there. scripts/check_tool_references.py in the plugin
repository starts the published server, asks it for tools/list, and fails if any tool named in a
skill or agent is missing — running weekly, because the drift originates here and a push trigger
on that repository would never fire at the moment it matters. AGENTS.md states the obligation too.

2. MCP groundwork so results compose

• A unified Finding model. jfr_diagnose, jfr_use, jfr_tsa, jfr_compare, pprof_use,
  otlp_use and hdump_report now emit one shape with a stable id, so results from several
  tools merge and de-duplicate instead of being reconciled from prose. Heuristic findings say so.
• jfr_diagnose runs the analyses it used to only recommend — USE and TSA — merges their
  findings, and reports capabilityGaps separately: what the recording cannot answer is not a
  negative answer. depth=quick opts out.
• jfr_compare, new: baseline versus candidate, normalised for duration and sampling rate,
  with an explicit comparability block and a noise floor.
• MCP prompts and resources, so the methodology reaches clients that do not install the plugin.

3. ask — an investigation inside the shells

jfr> ask why is this workload slow
* diagnose
  done

> events/jdk.ObjectAllocationSample | groupBy(objectClass/name) | top(3, by=count)
  3 rows
| count | key               |
+-------+-------------------+
| 5109  | byte[]            |
| 812   | java.lang.String  |
| 344   | java.util.HashMap |

The diagnosis flagged high GC pressure (609 collections, 20.2 ms average pause) and the
allocation breakdown is dominated by byte[]. Look at the allocation call sites.

Transcript: ~/.jafar/investigations/ask-20260913-202249.jfrs

ask <question> — ? for short, analyze and investigate as word aliases — runs a query, reads
the result, decides what to look at next, and concludes. as-query <question> is the one-shot form,
which expresses the question as a single query, prints it, and runs it. Also explain [--dry-run],
llm status, llm cost. Wired into both jfr-shell and the unified jafar-shell — the latter
is the only entry point that opens all four formats, so a question about a heap dump gets HdumpPath
and one about a profile gets the samples grammar.

Five decisions shape it:

• The model composes queries; it never sees raw events. The query engine is already the right
  reducer, so a 900 MB recording costs the same as a 2 MB one and the recording never leaves the
  machine.
• Every query is printed before it runs, with the rows it returned underneath — the same rows
  the model was given, capped at llm.max-rows — so a wrong guess is visible, the numbers behind
  the conclusion are checkable, and the user learns the query language rather than being insulated
  from it.
• The investigation leaves a re-runnable artifact. Each run writes its queries to a .jfrs
  script: the conclusion came from a model and is not reproducible, but the evidence is a file that
  can be opened, re-run, and disagreed with. That converts the loop's weakest property into a
  verifiable one.
• Recording content is untrusted input. Thread names and heap string values are
  attacker-controllable when the recording came from a third party, so they are fenced in explicit
  data markers, the system prompt declares them data, and the tool surface is read-only.
• Optional at every level. The SPI is in shell-core with no new dependencies; provider code
  lives in modules taken as runtimeOnly and discovered via ServiceLoader. Drop those lines and
  no provider dependency is present at all — air-gapped use is a supported configuration.

The loop speaks a text protocol, not a provider's tool-calling API. A reply is a QUERY:,
FIELDS:, ANALYSIS: or ANSWER: line. This is a deliberate departure from the handoff document's
§3.1, which expected a completeWithTools method on LlmBackend: tool use exists on the hosted
providers and not on a small local model behind an OpenAI-compatible endpoint, so building on it
would have made the loop hosted-only and split the SPI in two. Bounded on two axes because an
unbounded loop against a paid API loses money quietly — llm.max-steps (6) and
llm.max-total-tokens (200000) — and the remaining step count is in every turn, so the model
concludes rather than being truncated.

llm.confirm turns ask off rather than modifying it. The setting promises a query is shown
before it runs; a loop picks each query from the previous result, so there is no query to show in
advance and no honest way to both honour it and investigate. It refuses before the backend is
resolved, so nothing is sent.

Egress is controlled: result rows are redacted by field name (reusing the scrubber's model),
truncated with the truncation declared, and --dry-run prints the exact bytes a real call would
send without sending them. On ask that is the opening request only, since later steps depend on
what earlier ones return.

4. The analyses moved out of the MCP server

jfr_diagnose and the rest lived in JfrAnalysisTools, written against jfr-mcp's own
SessionRegistry.SessionInfo and calling the server's sendProgress directly — which is why they
were reachable only over MCP. diagnose, use, tsa, summary, hotmethods and exceptions are
now io.jafar.shell.core.analysis.JfrAnalyses in shell-core (2,467 lines moved;
JfrAnalysisTools went from 3,371 lines to 1,217, its handlers now thin delegations that preserve
the exact error strings). Three small types carry what they used to take from the server:
AnalysisTarget, Progress, and JfrQuerySource.

So ANALYSIS: diagnose in the shell and jfr_diagnose over MCP reach the same conclusions rather
than similar ones — one copy, with the thresholds, the USE and TSA passes, and the capabilityGaps.

A move this size is only safe with a net, so the characterization tests came first, in their own
commit: they pin the current output of every analysis before anything moved. They earned it — the
extraction dropped the query-engine injection (new JfrPathEvaluator() in place of the caller's),
which ConsumeEdgeCasesTest relies on, and the net caught it. JfrQuerySource exists to make that
injection explicit rather than incidental.

5. What the model is told about the recording

The model was given a bare list of type names, which left it choosing an event type by whether the
name happened to share a word with the question, and inventing field paths from there. A recording
documents itself, so that guessing is unnecessary:

• Labels and descriptions, from the recording's own metadata (@Label("CPU Load"),
  @Description("Information about the recent CPU usage of the JVM process")). Measured on a 10 s
  recording: 181 event types, 177 with a label, 96 with a description. This lives in the cached
  prompt prefix, being fixed per recording — which only pays off if the text is byte-stable, so
  the rendering sorts, and two consecutive --dry-run calls were checked to produce prefixes
  identical to the byte.

• Fields on demand. JFR is self-describing: an event's fields are whatever that recording
  declares, differ between JDK versions, and for a custom event are unknowable in advance. Sending
  all of them costs ~9,800 tokens (181 types, 994 fields), almost all about types the question never
  touches. So the model may answer FIELDS: <types> and is sent those types' fields plus the types
  those fields lead to — one level, which is what makes sampledThread/javaName derivable rather
  than invented, and renders array dimension so frames[0] is too. One extra round trip and ~1,200
  characters instead of ~24,000. Capped at 8 types and one round; a model that keeps asking is
  reported, not looped on.

• Event counts, and which types are empty. JFR metadata declares every type the JVM
  registered, whether or not it emitted anything — so a recording made by an agent that ships its
  own sampler lists an empty jdk.ExecutionSample beside a vendor type holding thousands of events,
  and a model told only the names picks the one it recognises. That was observed, not theorised.
  The shell now counts the events once, lists the types that have data with their counts, and
  collapses the rest into one line the model is told not to query.

  An earlier revision of this description said counts could not be sent because computing them means
  scanning the recording. That was wrong: the query answering the question makes the same pass
  anyway. The count is cached under $XDG_CACHE_HOME/jafar/event-counts (else ~/.cache/jafar/),
  keyed by the file's path, size and modification time, so later sessions reuse it and a replaced
  file does not answer from a stale count. llm.count-events = false skips it.

6. Multi-provider, and a local option

llm.backend	Module	Talks to	Credential
anthropic	llm-anthropic	api.anthropic.com	API key or keyless OAuth profile
openai	llm-openai	api.openai.com	OPENAI_API_KEY
ollama	llm-openai	localhost:11434	none

llm-openai carries no provider SDK — OpenAI chat-completions over the JDK HttpClient.
openai and ollama are the same class with different Profile defaults, so any other server
speaking that protocol (vLLM, LM Studio, Groq, Together, OpenRouter, Ollama Cloud) is reachable by
setting llm.base-url, with no new code.

Not privileging a provider had four concrete consequences: LlmConfig lost its model default (each
backend supplies its own, because a model id set for one provider is meaningless to the next); no
Authorization header is sent when there is no key (an empty bearer breaks several local servers);
a loopback base URL is probed with GET /models so llm status reports reachability rather than
hanging at request time; and cached tokens are split out of prompt_tokens so usage adds up the
same way across backends.

A local model changes the privacy story, not just the cost one. With ollama nothing leaves
the machine — which is the configuration for a recording that came from a customer. It only works
because of the next item.

7. Validate before running, and adapt to the model

A small local model writes invalid queries often enough that this would be unusable without it. The
candidate query is parsed with the same parser that would execute it; on rejection the parser's
own error goes back with a request to correct it, bounded by llm.max-retries (default 1, capped
at 3). The shell prints 1 correction(s) next to the token usage rather than hiding the round trip.
If the retry does not rescue it, the query and the parser's complaint are shown and nothing runs.

The output ceiling discovers reasoning models rather than listing them. llm.max-tokens stays
at 2048 — the size of an answer, and the cap on a runaway — but a model that reasons before
answering spends that budget thinking, hits the ceiling mid-thought and returns no query at all,
billing the full amount for nothing. When a reply stops on length without a query, the shell
raises the ceiling to 16384, says so, retries, and remembers it for that model for the session. The
trigger is the reply's own stop reason; a list of reasoning-model names would be stale within a
month and says nothing about a local model someone renamed. A ceiling set by the user is never
lowered.

8. A credential belongs in a file, not the environment

llm status used to tell you to export an API key. An environment variable is inherited by every
child process the shell spawns and shows up in ps e and in crash dumps, so a key now also resolves
from a settings file — $JAFAR_LLM_CONFIG, else $XDG_CONFIG_HOME/jafar/llm.properties, else
~/.config/jafar/llm.properties — consulted after set and the environment, so nothing that worked
before changes. A group- or world-readable file is called out with the fix to apply. llm status
now reports which layer answered for each setting, because a stale environment variable quietly
shadowing the file looks exactly like the file not being read at all.

The setup docs also stopped assuming ant is on the machine: it is the Anthropic CLI, it is not
installed on a stock macOS, and the instructions now say where to get it — including that the tap
owner is anthropics, plural, and that plain brew install ant is Apache Ant, a different tool
that installs cleanly and then has no idea what auth login means.

9. AGENTS.md became an entry point

It was 544 lines, one section of which ran to 241, and nothing in it said which part to read for the
change you were making. It is now 159 lines — the map, the module list, the quick start, and the
rules — with the detail moved verbatim into doc/agents/: Build, Architecture, Shells, Mcp,
Llm, Release.

Two of the new files are not moved text:

• doc/agents/Verification.md — ten rules for knowing a change
  works in this repository, each with the case file that produced it, drawn from the bugs below.
  Type it into the built artifact; enumerate every path; a fallback that hides a misconfiguration is
  a bug; documentation is code, run it; prove the test fails without the fix; compare failure sets
  by name, not count; one source of truth for any list two places must agree on; say what you did
  not verify; inspect the payload, not the exit status; when you move code, pin the behaviour first.
• doc/agents/DataShapes.md — five bugs in this repository that
  share one shape: code reads a structure by assuming what is inside it, the assumption is wrong,
  and nothing complains. A wrapped string constant, a display list mistaken for a data list, a
  declared type mistaken for a present one, a count field that is not a count, and a missing column
  that sorts silently. It exists because the sixth one will look exactly like these.

The knowledge base also carries a standing rule to maintain itself — "Leave this knowledge base
better than you found it" — with a runnable link checker, so the next change is expected to fold its
own lessons back in rather than leave them in a commit message.

---

Bugs found while verifying against real artifacts

These were not the task; they surfaced because the work was checked end to end rather than only
unit-tested. Nearly all of them had green tests.

In existing code:

• Heap-to-JFR correlation was unreachable over MCP. hdump_query was passed a bare
  SessionResolver, so the documented cross-type join always threw "Cross-type join requires a
  CrossSessionContext". The server now supplies an McpCrossSessionContext.
• That join then still produced only nulls. AllocationAggregator read objectClass.name as a
  plain string, but the untyped parser wraps string constants — so every real recording
  aggregated to nothing. The existing tests all fed a flattened shape the parser never emits.
• groupBy on a field the event type does not have returned zero rows and no complaint. An
  empty result reads exactly like "this recording has no such events", so the reader moves on
  instead of fixing the name. Found in a real ask gc behaviour in detail run, where the model
  grouped jdk.GarbageCollection by a gcType the type does not have. It now counts the events the
  key was offered and names the key, the count, and the fields the type does have. The check only
  fires where the result would have been empty anyway.
• top(n, by=value) silently returned the wrong rows. groupBy names its output key and the
  aggregate after the function, so by=value resolved to null on every row;
  compareValues(null, null) is 0, so the sort kept the input order and returned the first n rows
  as the top n. Both top(10, by=value) lines in the model-facing language reference were affected.
  sortBy(value) had the same gap but failed loudly, which is how it was noticed at all. Both now
  read value as the aggregate column — only where no real column of that name exists, so a
  recording's own value field is never shadowed.
• JfrPath rejected the duration suffixes jfr_help has always documented. [duration>10ms]
  was a parse error despite appearing in four places in the help text. Added ns/us/ms/s, with no
  minute suffix, since m already means mebibytes.
• JfrQueryEvaluator.evaluate rejected a raw query string, though its own interface documents
  "parsed query object or raw query string" and the Hdump, pprof and OTLP evaluators all accept
  both.
• The MCP server told every client the wrong version. serverInfo.version in the handshake was
  a literal "0.10.0" that was never updated, so sixteen releases — 0.26.2 included — identified
  themselves as 0.10.0, and anything gating on the version was misled. It is now read from the jar
  manifest (Implementation-Version, which the shadow-jar build stamps), so it cannot drift again.

In this PR's own new code, found by driving the built jars rather than the test harness:

• The LLM commands reached nothing in the interactive jfr-shell. CommandDispatcher runs
  JfrPath two ways — via a JfrSelector when supplied, via JfrPathEvaluator directly when not —
  and io.jafar.shell.Shell builds it the second way. The host adapter knew only the first, so
  every question ended in "No query evaluator available for this session" while every fake-host
  unit test stayed green. LlmHostAdapterTest now covers both paths; verified it fails against
  the old adapter.
• set llm.backend = ollama was impossible to run. The command appears in five documents, in
  the help text, in llm status's own advice and in tab completion, and had never been typed into
  the shell: set rejects dotted names, because ${a.b} means field access in an expression.
  Allowing the name exposed two more failures underneath, each of which looked like success — a
  bare word went down the expression path and was read as a query ("Unknown root: ollama"), and a
  bare integer was coerced to a double, so set llm.max-rows = 20 stored 20.0, failed to parse
  as an int, and silently fell back to the default while the shell printed a confirmation.
• llm.api-key reached two backends of three. The settings file the README recommends did
  nothing for Anthropic, which asked the SDK alone and inspected only the environment — so a key
  sitting in the file produced "No credentials found". Found by following this PR's own README
  advice on a machine where it should have worked.
• finish_reason was read by both backends and consumed by nobody. A reply truncated
  mid-thought reported only "No query could be extracted from the model's reply", with the token
  count that would have explained it printed on the next line.
• The field metadata came back empty, with no error. The class map carries fields as rendered
  display strings and fieldsByName as the structured map; reading the first and testing each
  element for a Map yields an empty list silently. Same shape of bug as AllocationAggregator
  above, caught by looking at the bytes the stub received.
• Redaction replaced every wrapped string constant, and looked like it was working. The parser
  delivers a string constant as {string=[B}, and string is in the default redact list — meaning
  a field named string — so class names, symbols and group-by keys reaching the model became
  {string=<redacted>}. Pre-existing, and it affected explain too. The wrapper is now unwrapped
  before the decision, which is taken on the outer field's real name.
• The extraction dropped a dependency injection. An analysis that quietly built its own
  JfrPathEvaluator ignored the double ConsumeEdgeCasesTest supplies and went to the recording
  instead — precisely the sort of difference a refactor is supposed not to make. Caught by the
  characterization net written before the move, and confirmed to be this PR's by stashing.
• explain described the wrong result after a question. The shell keeps one "last result",
  written only by queries typed directly; the LLM commands recorded theirs on a handler object that
  explain then overwrote from that older memory. So show ... ; ask ... ; explain described the
  show, presented as the query just run.
• ask in jafar-shell passed the raw string where a parsed query was expected.
• Token usage was not reported when the generated query then failed to run — the request was
  paid for either way.
• LlmCommands.helpText() was unreachable and contained an unformatted %s. Now wired to
  help ask / help as-query / help explain / help llm.
• The new commands had neither tab-completion nor a help entry in either shell, so the only way
  to discover them or any of the sixteen llm.* settings was to read the source. Both completers
  now know them, the settings complete with one-line descriptions, and a test reads LlmConfig.java
  so a setting added later that is never offered fails the build. The interactive jfr-shell's own
  help listed none of the LLM commands at all until the last commit.

On the command names

ask originally named the one-shot translation, and the investigation was called analyze. That
was backwards: "ask" is what someone does when they have a question, and a single query answers
almost no real performance question. So ask is the investigation, ? is short for it, and
as-query is the one-shot form — analyze and investigate remain as word aliases.

? is taken before the line is split into words, so ?why is this slow and ask why is this slow
are one command rather than two spellings of which only the second works. Nothing legal is shadowed:
every query root is a bare word.

# was considered for the one-shot and rejected: it is the comment character in .jfrs scripts and
the shebang and description marker in the script reader, so # what allocates the most? would work
when typed and be silently skipped in a script or a recorded session. The asymmetry is the
problem, not the collision.

The method names deliberately do not follow: LlmCommands.analyze implements ask and
LlmCommands.asQuery implements as-query, because the methods are named after what they do and
the commands after what a user is doing. CommandDispatcher's switch is the mapping, and
doc/agents/Llm.md says so.

Verification

Against real artifacts, generated locally:

• jfr_compare attributes an engineered profile shift — Workload.alpha 54.13% → 93.35% of
  samples — between two recordings of a synthetic workload.
• The heap-to-JFR correlation resolves byte[] to 3494 allocation samples with
  topAllocSite=Workload.main.
• The two query-language fixes listed under Bugs were reproduced on a recording before being
  touched, and the fixed behaviour re-checked in the rebuilt shell jar.

The question path, in both built shells, against stub OpenAI-compatible servers scripted to
reproduce each behaviour in turn — an invalid query then a valid one, a reply truncated on length,
a FIELDS: request, an ANALYSIS: request, a multi-step investigation ending in ANSWER:. The
fixtures in this tree are stripped and several do not parse, so the recordings used were made for
the purpose (JDK 25, 10 s, settings=profile):

round 1: system=21,327 chars (cached), conversation=42 chars
round 2: system=21,327 chars (identical, so a cache read), conversation=1,188 chars
events/jdk.ExecutionSample | groupBy(sampledThread/javaName) | top(5, by=count)
| 136   | main |

Tests. llm-openai is driven against a real com.sun.net.httpserver.HttpServer on loopback
rather than a mocked client, because what is most likely wrong there is on the wire: JSON shape,
headers, usage accounting, error-to-remedy mapping.

./gradlew test --continue, run on this branch and on a worktree of origin/main and compared
name-by-name:

module	origin/main	this branch
parser-core	155 tests, 2 failed	155 tests, 2 failed
parser-codegen	98 tests, 24 failed	98 tests, 24 failed
tools	36 tests, 5 failed	36 tests, 5 failed
jfr-mcp	213 tests, 5 failed	241 tests, 5 failed
shell-core	212 tests, 5 failed	326 tests, 5 failed
jfr-shell	717 tests, 126 failed	771 tests, 126 failed
total	1431 tests, 167 failed	1627 tests, 167 failed

167 failures on both sides, an identical set by name — comm on the sorted failure names
reports nothing on either side alone. All 167 fail with NoSuchFileException on binary recordings
get_resources.sh downloads and this environment cannot fetch; substituting a different recording
makes them worse, not better, so they are left absent. CI, which does have those recordings, is
green on a8a386d — the last commit carrying code — across Tests (JDK 8), Tests (JDK 21)
and Combined Test Report.

New tests are checked against the code they fix, per R5: SetLlmSettingTest fails 6 of 7 against
the previous dispatcher, ThinkingModelCeilingTest 3 of 5 with the escalation disabled,
GroupByColumnsTest 5 of 9 without the query-language fix, and AnalyzeCommandTest 5 of 7 without
the row rendering. In each case the remainder are the guards that unaffected behaviour stays
unaffected, and correctly pass either way.

One CI failure, investigated

An earlier run failed McpOtlpTransportTest.otlpSummaryReturnsSampleInfo, 1 of 274, reported only
as AssertionFailedError at McpOtlpTransportTest.java:101. It did not reproduce in 13 full local
runs of that suite, and every CI run since has been green. Ruled out: the OtlpTools change here
touches only otlp_use, not handleOtlpSummary; a handshake timeout fails differently (at
McpTransportHarness:111, across all 7 tests in the class); japicmp was SKIPPED; and jfr-mcp
pins toolchain 25, so the JDK 21 job label is not a JDK difference.

Rather than leave it at "probably flaky", a later commit makes the next occurrence self-diagnosing:
assertSuccess now includes the response in every message (a timeout names the timeout, a tool
error prints the tool's own text), and the 12 previously unasserted otlp_open / pprof_open setup
calls are asserted, so a failed open no longer surfaces two lines later as a failure of the call
under test. Nothing is skipped, disabled or quarantined. Two order- and timing-dependent candidates
remain open, neither touching the code under test: the suite shares one session file at a fixed
tmpdir path (jfr-mcp/build.gradle:63), and callTool has a 15 s per-call timeout while CI runs
several test JVMs in parallel.

What is not verified

Stated plainly because the docs state it too (doc/plans/llm-in-the-shell-handoff.md §6, and R8 in
doc/agents/Verification.md):

• No hosted provider has ever been called from this repository's tests, or from the environment
  this work was written in. Spending someone else's money from a test is not acceptable, so the
  Anthropic request shape, real cache_read_input_tokens on a second call, and each provider's
  401/403/429/404 message strings are untested here. The author has run the shell against a hosted
  model by hand (see the next item), but nothing automated covers it. The cheapest way to close most
  of that costs nothing: ollama serve, set llm.backend = ollama, ask.
• FIELDS: has never been chosen by a real model here. It is proven as a mechanism — a scripted
  stub exercises the exchange end to end and the protocol handling is unit-tested — but whether a
  model asks rather than guesses is instruction-following, and a small local model may well ignore
  it. The correction loop still catches a bad query, just without the saving. ANALYSIS: and
  QUERY: fare better: one real multi-step run against a hosted model opened with
  ANALYSIS: diagnose, followed with queries, and concluded correctly — it is also where the two
  query-language bugs above came from — but that run never asked for fields, which is exactly how
  it came to group by a field the type does not have.
• QueryProposal is tested against hand-written reply shapes and the stubs' output, not against a
  real model.
• One unexplained failure. A single ?gc behaviour run printed rejected: big.jfr from
  runQuery on a query that works. It did not reproduce in six subsequent runs, including the
  identical input and a cold event-count cache. No cause is claimed.
• The plugin repository's tool-drift workflow has never executed on GitHub. The script it runs is
  verified locally in both directions — passing on the current skills, and failing with exact
  locations when a tool is renamed — but the workflow itself will first run on that repository.
• The plugin's .mcp.json still launches the MCP server through the JBang catalog, which resolves
  to the latest published release. Pinning it to an exact version waits on 0.27.0 being released,
  since 0.26.2 — still the latest — carries neither jfr_compare nor the findings shape the skills
  rely on.

Docs

doc/plans/performance-engineer-in-a-box.md and doc/plans/llm-in-the-shell.md (the two design
documents, left as written — they record what was proposed at the time, including the plugin living
in-tree and ask being a single translation), doc/plans/llm-in-the-shell-handoff.md (what shipped,
the seams, and the verification gaps), doc/agents/** (new), doc/cli/LlmSetup.md,
doc/cli/AskTutorial.md, doc/cli/LlmPrivacy.md, doc/cli/JFRPath.md, doc/mcp/WhenToUseWhich.md,
plus AGENTS.md, README.md and CHANGELOG.md.

Follow-up, deliberately not in this PR

• jafar-shell still has no set command (gap G8), so llm.* there comes from JAFAR_LLM_*
  environment variables or the settings file.
• Pinning the plugin's .mcp.json to an exact version, once 0.27.0 is released.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Y7GJQkDcorE3bC1gaCmmSx

[github-actions]

Combined JUnit Test Report

• Total: 2169
• Passed: 2153
• Failures: 0
• Errors: 0
• Skipped: 16

HTML Test Reports

Run artifacts: https://github.com/btraceio/jafar/actions/runs/34811598504

• JDK 8: HTML report artifact
• JDK 21: HTML report artifact