add-java-code-snippets-in-docs

## When to use

Adding Java code blocks alongside existing Kotlin blocks in mkdocs documentation (`docs/docs/**.md`). Typical triggers: "add Java examples to <file>", "add Java tabs", "complete the Java side of <doc>", "fix the Java block in <doc>".

**Do NOT use this skill for:**

- Writing brand-new Kotlin docs (no precursor Kotlin block to mirror).
- Splitting source files between JVM and non-JVM source sets — use the **`split-jvm-nonjvm`** skill instead.
- Java examples outside the mkdocs/Knit pipeline.

## Prerequisites

JDK 17. Gradle 8.x fails cryptically on newer JDKs. If the default JDK is newer, prefix every `./gradlew` command in this workflow with `JAVA_HOME=/path/to/jdk-17`.

## Before starting

Read **one** reference doc to anchor on the established pattern:

- `docs/docs/features/tracing.md` — full Tracing feature (blocks 1–6).
- `docs/docs/agent-events.md` — custom `FeatureMessageProcessor` subclass (suspend bridge methods `handleMessage` / `handleClose`).
- `docs/docs/testing.md` — `MockPromptExecutor` builder, tool mocking, comment-only blocks for Kotlin-only DSL.
- `docs/docs/features/open-telemetry/index.md` — OpenTelemetry examples.
- `docs/docs/features/open-telemetry/opentelemetry-langfuse-exporter.md` — Langfuse exporter.
- `docs/docs/features/open-telemetry/opentelemetry-weave-exporter.md` — Weave exporter.

## Workflow

For each Kotlin code block in the target `.md`:

1. **Read** the Kotlin block: INCLUDE, visible code, SUFFIX, KNIT directive.
2. **Check existing Java tab.** If absent → add one. If it has empty `/** */` placeholder content → replace entirely. If it has real content → update.
3. **Consider Kotlin-side alignment.** If the Kotlin block uses Kotlin-only APIs (`kotlinx.io`, `MutableStateFlow`, `KLogger`, inline `Duration`), consider whether the Kotlin example should switch to a JVM `create()` factory (e.g., `TraceFeatureMessageFileWriter.create(path)`). This keeps the two examples structurally aligned. See `reference/factory-classes.md`.
4. **Add `@JavaAPI` bridge methods if missing.** If the Java code needs a bridge that doesn't exist yet (e.g., a builder method on `MockExecutorBuilder`), add it before writing the Java tab. This may pause the doc work for a source-code change — flag it to the user before proceeding.
5. **Write the Java tab** immediately after the Kotlin tab, using the template below.
6. **If renaming Knit files** (e.g., hyphenated `example-feature-java-01.java` → camelCase `exampleFeatureJava01.java`), delete the old generated files first.
7. **Generate and compile** (see Verification at the bottom).
8. **Read the generated `.java`** to confirm correctness. Fix and repeat 7–8 on failure.

## Mkdocs / Knit tab structure

Java tabs go immediately after the Kotlin tab. All content inside a tab is indented 4 spaces. `<!--- INCLUDE -->`, `<!--- SUFFIX -->`, `<!--- KNIT -->` are Knit directives (HTML comments — invisible when rendered), not mkdocs syntax.

```markdown
=== "Kotlin"

    <!--- INCLUDE
    import ...
    -->
    ```kotlin
    // visible code
    ```
    <!--- KNIT example-feature-01.kt -->

=== "Java"

    <!--- INCLUDE
    import ...;
    public class exampleFeatureJava01 {
        public static void main(String[] args) {
    -->
    <!--- SUFFIX
        }
    }
    -->
    ```java
    // visible code
    ```
    <!--- KNIT exampleFeatureJava01.java -->
```

### KNIT naming — capital "Java" matters

`docs/knit.code.include` has the check `<#if !knit.name?contains("Java")>package ...`. Files with capital "Java" in the name skip the `package` declaration; lowercase "java" or hyphenated names emit a `package` line that breaks compilation.

- ✅ `exampleFeatureJava01.java`, `exampleTestingJava13.java`
- ❌ `example-feature-java-01.java`, `examplefeaturejava01.java`

### Knit rules

- INCLUDE + visible code + SUFFIX must concatenate into a valid Java file.
- Hidden variables in Kotlin INCLUDE (`outputPath`, `input`, etc.) must also appear in Java INCLUDE.
- Visible-code indentation in `.md` is 4 spaces (tab content). Knit strips that when generating.
- Always import in INCLUDE; never use FQNs in visible code.
- Never use file-level annotations (`@file:Suppress`, `@file:OptIn`) — scope to specific declarations.

## Structural matching (the most important rule)

**The Java visible code must match the Kotlin visible code in scope and structure.**

- If Kotlin shows no `main()`, Java must hide `main()` in INCLUDE/SUFFIX.
- If Kotlin shows `install(Feature) { ... }`, Java must show `.install(Feature.Feature, config -> { })`.
- If Kotlin creates a writer before the agent, Java must too.
- If Kotlin shows `agent.run(input)`, Java must too.

Read both visible blocks side-by-side after writing. They should read as equivalent code in their respective languages.

### When Kotlin uses APIs with no Java bridge

Some Kotlin DSLs (graph testing: `testGraph`, `assertSubgraphByName`, `assertNodes`, `assertEdges`, `verifySubgraph`, `assertReachable`) have no `@JavaAPI` bridges. To check: grep for `@JavaAPI` in the source file — if absent, treat as Kotlin-only.

When the Kotlin block uses an entirely Kotlin-only API:

1. **Do NOT leave the Java tab empty.** Write a compilable Java class with explanatory comments.
2. The class must have a valid `main` so it compiles.
3. Comments explain what the Kotlin DSL does and the recommended Java alternative.

```java
// Graph structure testing (testGraph, assertSubgraphByName, assertEdges,
// verifySubgraph, assertReachable) is available through the Kotlin testing DSL.
//
// In Java, test agent behavior by running and asserting on the result:
//   String result = agent.run("test input");
//   assert "expected".equals(result);
```

## Deep references

Load these only when you need them:

- **`reference/interop-tables.md`** — Kotlin↔Java mapping table, suspend bridges (`@JvmName("run")`, `handleMessage`, `handleClose`), abstract-property rules, key source files to grep for `@JavaAPI`.
- **`reference/factory-cla