feat(integration): add java (spring boot) as a full example-based variant

Add a Java integration variant anchored on a real Spring Boot example app
(example-apps/java-spring-boot): the posthog-server client is exposed as a
singleton @bean configured from the environment, flushed and closed on
shutdown via destroyMethod="close". A controller identifies users, captures
events, evaluates feature flags with evaluateFlags, and reports errors as an
explicit event (the Java server SDK has no automatic exception capture,
documented honestly rather than faked).

Ships a full Spring Boot example rather than docs-only so the wizard has a
concrete shape to match for the most common Java backend framework. Adds a
java-server commandments block, keyed java-server (not java) so these backend
rules never fold into the Android skill, which carries the java tag; the
variant is tagged [java, java-server].

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: sarahxsanders

context/commandments.yaml

@@ -97,6 +97,17 @@ commandments:
     - Call `IdentifyAsync` for known users and put PII such as email in person properties, not in event properties
     - Use `CaptureException(exception, distinctId, properties, groups, flags)` for handled exceptions; automatic exception capture is not available in the .NET SDK yet
 
+  # Keyed `java-server` (not `java`) so these backend rules never fold into the Android skill, which carries the `java` tag. The Java variant is tagged [java, java-server].
+  java-server:
+    - posthog-server is the PostHog Java server SDK; add the `com.posthog:posthog-server` dependency via Gradle or Maven and import from `com.posthog.server`
+    - Build one client per process with `PostHogConfig.builder(token).host(host).build()` then `PostHog.with(config)`; share the returned `PostHogInterface` (for example as a singleton Spring `@Bean`), never per request
+    - Read the project token and host from the environment or configuration; never hardcode PostHog secrets
+    - Flush and close on shutdown with `posthog.flush()` and `posthog.close()` (for a Spring `@Bean`, use `destroyMethod = "close"`) so queued events are delivered before exit
+    - Server-side captures must pass a stable `distinctId` as the first argument to `capture(...)` that matches frontend identify calls; avoid anonymous or literal IDs for business events
+    - Identify users by attaching person properties to a capture via `PostHogCaptureOptions.builder().userProperty(...)` / `.userPropertySetOnce(...)`; keep PII in person properties, not event properties
+    - For feature flags, call `posthog.evaluateFlags(distinctId)` once per request, then read values from the snapshot with `isEnabled("flag-key")` / `getFlagPayload("flag-key")`
+    - The Java server SDK has no automatic error tracking, surveys, or session replay; do not promise or scaffold those features
+
   elixir:
     - posthog-elixir is installed as the `posthog` Hex package; add `{:posthog, "~> 2.0"}` to `mix.exs` and run `mix deps.get`
     - Configure PostHog in application config using `api_host`, `api_key`, and `in_app_otp_apps`; read secrets from environment or runtime config, never hardcode them

context/skills/integration/config.yaml

@@ -236,6 +236,15 @@ variants:
     docs_urls:
       - https://posthog.com/docs/libraries/elixir.md
 
+  - id: java
+    framework: java
+    example_paths: example-apps/java-spring-boot
+    display_name: Java (Spring Boot)
+    description: PostHog integration for Java and Spring Boot applications using the posthog-server SDK
+    tags: [java, java-server]
+    docs_urls:
+      - https://posthog.com/docs/libraries/java.md
+
   - id: go
     template: description-go-docs-only.md
     display_name: Go

example-apps/java-spring-boot/.env.example

@@ -0,0 +1,2 @@
+POSTHOG_PROJECT_TOKEN=
+POSTHOG_HOST=https://us.i.posthog.com

example-apps/java-spring-boot/.gitignore

@@ -0,0 +1,6 @@
+.env
+build/
+.gradle/
+*.class
+.idea/
+*.iml

example-apps/java-spring-boot/README.md

@@ -0,0 +1,162 @@
+# PostHog Spring Boot example
+
+This is a [Spring Boot](https://spring.io/projects/spring-boot) example demonstrating PostHog integration with product analytics, feature flags, and user identification using the server-side Java SDK.
+
+## Features
+
+- **Product analytics**: Track user events and behaviors
+- **User identification**: Associate events with authenticated users via person properties
+- **Feature flags**: Control feature rollouts with PostHog feature flags
+- **Server-side tracking**: All tracking happens server-side with the `posthog-server` SDK
+- **Single client bean**: One PostHog client for the whole app, flushed on shutdown
+
+> **Note on error tracking:** the PostHog Java server SDK does not have automatic
+> exception capture. This example reports failures as an explicit `error_occurred`
+> event instead. Do not expect session replay or surveys from the server SDK either.
+
+## Getting started
+
+### 1. Configure environment variables
+
+Copy `.env.example` to `.env` and fill in your values, then export them:
+
+```bash
+export POSTHOG_PROJECT_TOKEN=your_posthog_project_token
+export POSTHOG_HOST=https://us.i.posthog.com
+```
+
+Get your PostHog project token from your [PostHog project settings](https://app.posthog.com/project/settings).
+
+### 2. Run the app
+
+```bash
+./gradlew bootRun
+```
+
+Open [http://localhost:8000](http://localhost:8000) with your browser to see the app.
+
+## Project structure
+
+```
+java-spring-boot/
+├── build.gradle                 # Gradle build with the posthog-server dependency
+├── settings.gradle
+├── .env.example                 # Environment variable template
+├── .gitignore
+└── src/main/
+    ├── resources/
+    │   ├── application.properties   # Binds POSTHOG_* env vars into config
+    │   └── templates/               # Thymeleaf pages
+    │       ├── home.html            # Home / login page
+    │       ├── burrito.html         # Event tracking
+    │       ├── dashboard.html       # Feature flag example
+    │       └── profile.html         # Error reporting
+    └── java/com/posthog/example/
+        ├── Application.java         # Spring Boot entry point
+        ├── config/
+        │   └── PostHogConfiguration.java   # The single PostHog client bean
+        └── controller/
+            └── BurritoController.java      # Events, identify, flags, errors
+```
+
+## Key integration points
+
+### PostHog client bean (config/PostHogConfiguration.java)
+
+Create **one client per process** and expose it as a singleton bean. `destroyMethod = "close"` makes Spring flush queued events when the app shuts down.
+
+```java
+@Bean(destroyMethod = "close")
+public PostHogInterface posthog(
+        @Value("${posthog.project-token:}") String projectToken,
+        @Value("${posthog.host:https://us.i.posthog.com}") String host) {
+
+    PostHogConfig config = PostHogConfig
+            .builder(projectToken)
+            .host(host)
+            .build();
+
+    return PostHog.with(config);
+}
+```
+
+### Configuration from the environment (application.properties)
+
+Read the token and host from the environment so secrets never live in source:
+
+```properties
+posthog.project-token=${POSTHOG_PROJECT_TOKEN:}
+posthog.host=${POSTHOG_HOST:https://us.i.posthog.com}
+```
+
+### User identification (controller/BurritoController.java)
+
+The server SDK identifies a user by attaching person properties to a capture with `userProperty(...)`. The `distinctId` (first argument) must match the id your frontend `identify` call uses.
+
+```java
+posthog.capture(
+        userId,
+        "user_logged_in",
+        PostHogCaptureOptions
+                .builder()
+                .userProperty("email", email)
+                .property("login_method", "email")
+                .build());
+```
+
+### Event tracking (controller/BurritoController.java)
+
+```java
+posthog.capture(
+        userId,
+        "burrito_considered",
+        PostHogCaptureOptions
+                .builder()
+                .property("total_considerations", count)
+                .build());
+```
+
+### Feature flags (controller/BurritoController.java)
+
+Evaluate flags once per request, then read individual flags off the snapshot. Avoid the deprecated per-flag helpers.
+
+```java
+PostHogFeatureFlagEvaluations flags = posthog.evaluateFlags(userId);
+boolean showNewFeature = flags.isEnabled("new-dashboard-feature");
+```
+
+### Error reporting (controller/BurritoController.java)
+
+There is no automatic exception capture in the Java server SDK, so report failures as an explicit event:
+
+```java
+try {
+    riskyOperation();
+} catch (RuntimeException e) {
+    posthog.capture(
+            userId,
+            "error_occurred",
+            PostHogCaptureOptions
+                    .builder()
+                    .property("error_type", e.getClass().getSimpleName())
+                    .property("error_message", e.getMessage())
+                    .build());
+}
+```
+
+### Flush and shutdown
+
+`destroyMethod = "close"` on the bean handles this for you at shutdown. If you ever
+manage the client yourself, flush and close explicitly:
+
+```java
+posthog.flush(); // send any remaining events
+posthog.close(); // shut down the client
+```
+
+## Learn more
+
+- [PostHog Java integration](https://posthog.com/docs/libraries/java)
+- [PostHog feature flags](https://posthog.com/docs/feature-flags)
+- [PostHog documentation](https://posthog.com/docs)
+- [Spring Boot documentation](https://spring.io/projects/spring-boot)

example-apps/java-spring-boot/build.gradle

@@ -0,0 +1,24 @@
+plugins {
+    id 'org.springframework.boot' version '3.3.4'
+    id 'io.spring.dependency-management' version '1.1.6'
+    id 'java'
+}
+
+group = 'com.posthog'
+version = '0.0.1'
+
+java {
+    sourceCompatibility = '17'
+}
+
+repositories {
+    mavenCentral()
+}
+
+dependencies {
+    implementation 'org.springframework.boot:spring-boot-starter-web'
+    implementation 'org.springframework.boot:spring-boot-starter-thymeleaf'
+
+    // PostHog server-side Java SDK
+    implementation 'com.posthog:posthog-server:2.+'
+}

example-apps/java-spring-boot/settings.gradle

@@ -0,0 +1 @@
+rootProject.name = 'posthog-java-spring-boot-example'

example-apps/java-spring-boot/src/main/java/com/posthog/example/Application.java

@@ -0,0 +1,23 @@
+package com.posthog.example;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+/**
+ * Entry point for the PostHog Spring Boot example.
+ *
+ * <p>The interesting integration code lives in:
+ * <ul>
+ *   <li>{@link com.posthog.example.config.PostHogConfiguration} &mdash; the single
+ *       PostHog client, exposed as a Spring bean and flushed on shutdown.</li>
+ *   <li>{@link com.posthog.example.controller.BurritoController} &mdash; where events,
+ *       user identification, feature flags, and error reporting happen.</li>
+ * </ul>
+ */
+@SpringBootApplication
+public class Application {
+
+    public static void main(String[] args) {
+        SpringApplication.run(Application.class, args);
+    }
+}

example-apps/java-spring-boot/src/main/java/com/posthog/example/config/PostHogConfiguration.java

@@ -0,0 +1,52 @@
+package com.posthog.example.config;
+
+import com.posthog.server.PostHog;
+import com.posthog.server.PostHogConfig;
+import com.posthog.server.PostHogInterface;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+/**
+ * Wires a single PostHog client into the Spring context.
+ *
+ * <p>Key integration points demonstrated here:
+ * <ul>
+ *   <li><b>One client per process.</b> The client is a {@code @Bean}, so Spring
+ *       creates exactly one instance and injects it everywhere. Never construct a
+ *       new client per request.</li>
+ *   <li><b>Config from the environment.</b> The project token and host are read
+ *       from configuration (backed by env vars) &mdash; secrets are never hardcoded.</li>
+ *   <li><b>Flush on shutdown.</b> {@code destroyMethod = "close"} makes Spring call
+ *       {@link PostHogInterface#close()} when the context shuts down, so queued
+ *       events are flushed before the JVM exits.</li>
+ *   <li><b>Fail loudly, but never break the app.</b> A missing token logs a clear
+ *       warning instead of throwing, so a misconfigured environment is obvious in
+ *       dev without taking the whole service down.</li>
+ * </ul>
+ */
+@Configuration
+public class PostHogConfiguration {
+
+    private static final Logger log = LoggerFactory.getLogger(PostHogConfiguration.class);
+
+    @Bean(destroyMethod = "close")
+    public PostHogInterface posthog(
+            @Value("${posthog.project-token:}") String projectToken,
+            @Value("${posthog.host:https://us.i.posthog.com}") String host) {
+
+        if (projectToken == null || projectToken.isBlank()) {
+            log.warn("POSTHOG_PROJECT_TOKEN is not set. PostHog events will not be delivered. "
+                    + "Set it in your environment (see .env.example) to enable analytics.");
+        }
+
+        PostHogConfig config = PostHogConfig
+                .builder(projectToken)
+                .host(host)
+                .build();
+
+        return PostHog.with(config);
+    }
+}