From 342efaef8e9b908b273b906d3ba48ac1ada8757a Mon Sep 17 00:00:00 2001
From: Kamil Patryk Kozakowski <kamil.p.kozakowski@gmail.com>
Date: Wed, 15 Jul 2026 19:36:41 +0200
Subject: [PATCH] agents.md from glm 8b

---
 AGENTS.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..4c553f6
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,63 @@
+# AGENTS.md
+
+## Project Overview
+
+Spring State Machine Explorer is a static analysis tool that extracts and visualizes Spring State Machines from source code. It does **not** run Maven/Gradle on target projects.
+
+## Build System
+
+- **Java 21** required (toolchain configured in all build.gradle files)
+- **Gradle** build system with shadow plugin for fat JARs
+- Run from root: `./gradlew <task>`
+
+## Key Commands
+
+### Run the exporter
+```bash
+./gradlew :state_machine_exporter:run --args="-i ./my-project -o ./out -f json"
+```
+
+### Run the HTML generator
+```bash
+./gradlew :state_machine_exporter_html:run --args="-i ./my-project -o ./out_html"
+```
+
+### Update golden test files
+```bash
+./gradlew :state_machine_exporter:runGolden
+```
+
+### Run tests
+```bash
+./gradlew :state_machine_exporter:test
+./gradlew :state_machine_exporter_html:test
+```
+
+## Module Structure
+
+- **state_machine_exporter**: Core Java AST analyzer (Main class: `click.kamil.springstatemachineexporter.Main`)
+- **state_machine_exporter_html**: HTML portal generator (Main class: `click.kamil.springstatemachineexporter.html.Main`)
+- **state_machine_exporter_spring_based**: Spring-based exporter sample
+- **file_combine**: Utility for concatenating Java files
+- **state_machines/**: Sample state machine projects for testing
+
+## Architecture Notes
+
+- **Source-first analysis**: Reads source + build metadata (pom.xml, settings.gradle) statically
+- **Accessor inlining**: Enabled by default (O(1) lookup for trivial getters/setters). Disable with `--no-inline-accessors`
+- **Generated sources**: Scans `target/`/`build/` by default. Control with `--include-generated-sources`
+- **Debug mode**: Use `--debug` flag for verbose logging and unresolved chain diagnostics
+- **Spring profiles**: Pass with `-p, --profiles` for property placeholder resolution
+
+## Testing
+
+- **Golden tests**: JSON/PNG/PUML/DOT/SCXML outputs are compared against golden files in `state_machine_exporter/src/test/resources/golden/`
+- **E2E tests**: Tagged with `@Tag("e2e")` in `PlantUmlE2ETest.java`
+- **Test scenarios**: Defined in `TestScenario.java` record with name, inputPath, goldenPath, baseName, activeProfiles
+
+## Important Constraints
+
+- **No Maven/Gradle execution**: The tool does not run the target project's build
+- **JDT bindings**: Limited to library types (Spring Boot 3.2.0, Spring State Machine 3.2.0) - external JARs not resolved
+- **Monorepo structure**: All modules in root; state_machines/ contains sample projects
+- **Java 21 only**: All modules require Java 21 toolchain
\ No newline at end of file