# Agent guide

Use `jbx` as a command-line surface, not as a guessing game. Prefer commands that print structured facts, keep cache paths explicit in long-running jobs, and read Markdown docs before scraping HTML.

## Website contract

- Prefer the Markdown sibling of any documentation page over scraping HTML when building context.
- Use canonical links under `https://jbx.telegraphic.dev/`.
- Discover command-specific guidance from `jbx skill list` and `jbx skill get <name>` so the installed binary stays the source of truth.

## CLI contract

Prefer these commands for automation:

```bash
jbx skill list
jbx skill get
jbx check <path> --json
jbx search <query> --json
jbx docs <source|dir|GAV> --json
jbx doctor [script.java|url] --json
jbx rewrite patch --recipe <short|fqn> --source <path> --json
jbx rewrite modules [--group groupId] [--rewrite-version version] --json
jbx rewrite recipes <short|GAV> --detail --json
jbx info tools <script.java>
jbx info deps <script.java>
jbx info classpath <script.java>
jbx cache path
```

## Good agent behavior

- Use `jbx skill list` to discover the exact command skills bundled with the installed binary.
- Run the tightest command that answers the question.
- Use `jbx doctor --json` before guessing about broken JDKs, unreachable Maven metadata, unwritable caches, formatter fallback, remote trust, dependency resolution, or optional publishing/native toolchain setup. Add `--cache-dir` for isolated agent runs, `--repo`/`--repos` for extra repositories, `--publish` for GPG checks, and `--native` for GraalVM `native-image` checks.
- Start with `jbx skill get` when you need version-matched workflow guidance for the installed binary.
- Keep local caches between runs where possible; Java dependency downloads are not a personality test.
- Treat `jbx docs` Markdown as context and `--json` as structured lookup data.
- Prefer `jbx rewrite patch` over `jbx rewrite apply` until the generated `rewrite/rewrite.patch` has been inspected.
- Use `jbx rewrite modules [--group groupId] [--rewrite-version version] --json` and `jbx rewrite recipes <module> --detail --json` to discover OpenRewrite modules, recipe short names/FQNs, descriptions, and options instead of guessing. Pass `--group` for non-default recipe module groups and `--rewrite-version` when the emitted coordinates must match a specific OpenRewrite runtime.
- Use `--option key=value` for recipe parameters, `--report dir` for patch location, `--fail-on-changes` for CI-style checks, `--repo id=url` for private recipe modules, `--cache-dir dir` for isolated jobs, and `--rewrite-version version` when reproducing a specific OpenRewrite run.
- Preserve JBang-compatible directives in scripts unless a task explicitly asks to change behavior.
- When publishing, use dry-run and inspect staged artifacts before real release workflows. Put compile-time artifact dependencies in `dependencies` / `//DEPS`; put runtime-only libraries in `runtimeDependencies` / `//RUNTIME` so generated Maven metadata uses runtime scope without adding them to the compile classpath.