Update llms.txt

Author: rob-bygrave

llms.txt

@@ -1,3 +1,37 @@
+# Ebean ORM — AI Agent & LLM Instructions
+
+> Ebean is a Java and Kotlin ORM (Object Relational Mapping) library for SQL databases. All guides and onboarding templates are designed for both humans and AI agents.
+
+## Key onboarding files
+- [AGENTS.md template](https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/AGENTS.md): Minimal template for agent onboarding and automation in Ebean ORM projects
+- [Guide index](https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/README.md): Full index of the Ebean AI/developer guides, including setup, entities, querying, transactions, testing, and migrations.
+
+## Step-by-step guides (fetch and follow as needed)
+- [Add Ebean + PostgreSQL — Step 1: Maven POM setup](https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-postgres-maven-pom.md)
+- [Add Ebean + PostgreSQL — Step 2: Database configuration](https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-postgres-database-config.md)
+- [Add Ebean + PostgreSQL — Step 3: Test container setup](https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-postgres-test-container.md)
+- [Entity bean creation](https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/entity-bean-creation.md)
+- [Lombok with Ebean entity beans](https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/lombok-with-ebean-entity-beans.md)
+- [Write Ebean queries with query beans](https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/writing-ebean-query-beans.md)
+- [Persisting and transactions with Ebean](https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/persisting-and-transactions-with-ebean.md)
+- [Testing with TestEntityBuilder](https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/testing-with-testentitybuilder.md)
+- [DB migration generation](https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-db-migration-generation.md)
+
+## Always check AGENTS.md and the guide index before automating or generating code for Ebean ORM projects.
+
+## Full Guide Index
+
+- [Guide index](https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/README.md): Full index of the Ebean AI/developer guides, including setup, entities, querying, transactions, testing, and migrations.
+- [Add Ebean + PostgreSQL — Step 1: Maven POM setup](https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-postgres-maven-pom.md): Prescriptive instructions for modifying pom.xml — adds ebean-postgres, postgresql JDBC driver, ebean-maven-plugin, and querybean-generator annotation processor. Handles merging into existing annotationProcessorPaths blocks.
+- [Add Ebean + PostgreSQL — Step 2: Database configuration](https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-postgres-database-config.md): Configure the Ebean Database bean using DataSourceBuilder and DatabaseConfig with Avaje Inject. Covers minimal (master-only) and extended (master + read-only replica) setup. Includes verification steps and troubleshooting table.
+- [Add Ebean + PostgreSQL — Step 3: Test container setup](https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-postgres-test-container.md): Start a PostgreSQL or PostGIS Docker container for tests using ebean-test-containers and a @TestScope @Factory with Avaje Inject. Covers image mirror for CI/ECR, autoReadOnlyDataSource, dumpMetrics, PostGIS variant with optional LW/HexWKB mode, and keeping containers running locally.
+- [Entity bean creation](https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/entity-bean-creation.md): Generate clean, idiomatic Ebean entity beans. Covers required annotations, recommended field patterns, relationships, audit fields, and anti-patterns such as public fields, `Set` collections, or custom equals/hashCode.
+- [Lombok with Ebean entity beans](https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/lombok-with-ebean-entity-beans.md): Which Lombok annotations to use and avoid on entity beans. Explains why @Data is incompatible (hashCode/equals breaks entity identity, toString triggers lazy loading). Prescribes @Getter + @Setter + @Accessors(chain=true). Includes compatibility table for common Lombok annotations.
+- [Write Ebean queries with query beans](https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/writing-ebean-query-beans.md): Prefer Q-bean queries for type-safe ORM queries. Covers choosing `exists()`/`findOne()`/`findList()`/`findPagedList()`, tuning `select()` / `fetch()` / `fetchQuery()` / `FetchGroup`, using `setUnmodifiable(true)` for read-only entity graphs, and projecting to DTOs when entity beans are not the right output.
+- [Persisting and transactions with Ebean](https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/persisting-and-transactions-with-ebean.md): Choose `insert`, `save`, `update`, `delete`, or bulk update based on intent. Covers cascade rules, implicit transactions, `@Transactional`, explicit transactions, and batching for larger write workloads.
+- [Testing with TestEntityBuilder](https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/testing-with-testentitybuilder.md): Rapidly create test entity instances with auto-populated values. Covers relationship handling, cascade-persist behavior, custom value generators, and when TestEntityBuilder is a good fit versus manual fixtures.
+- [DB migration generation](https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-db-migration-generation.md): Add GenerateDbMigration.java to generate schema diff migrations offline (no database needed). Configure the migration runner with ebean.migration.run=true. Understand .sql and .model.xml output files. Covers version naming, multi-platform, pending drops, setPathToResources for multi-module projects, and named database support.
+
 # Ebean ORM
 
 > Ebean is a Java and Kotlin ORM (Object Relational Mapping) library for SQL databases.
@@ -25,20 +59,6 @@ Key concepts:
 - [First entity](https://ebean.io/docs/getting-started/first-entity): Create an entity bean, add ebean.mf, run first test
 - [ebean-test setup](https://ebean.io/docs/getting-started/ebean-test): Configure Ebean for testing with application-test.yaml
 
-## Guides
-
-Step-by-step guides written for AI agents and developers for common Ebean tasks:
-
-- [Guide index](https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/README.md): Full index of the Ebean AI/developer guides, including setup, entities, querying, transactions, testing, and migrations.
-- [Add Ebean + PostgreSQL — Step 1: Maven POM setup](https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-postgres-maven-pom.md): Prescriptive instructions for modifying pom.xml — adds ebean-postgres, postgresql JDBC driver, ebean-maven-plugin, and querybean-generator annotation processor. Handles merging into existing annotationProcessorPaths blocks.
-- [Add Ebean + PostgreSQL — Step 2: Database configuration](https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-postgres-database-config.md): Configure the Ebean Database bean using DataSourceBuilder and DatabaseConfig with Avaje Inject. Covers minimal (master-only) and extended (master + read-only replica) setup. Includes verification steps and troubleshooting table.
-- [Add Ebean + PostgreSQL — Step 3: Test container setup](https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-postgres-test-container.md): Start a PostgreSQL or PostGIS Docker container for tests using ebean-test-containers and a @TestScope @Factory with Avaje Inject. Covers image mirror for CI/ECR, autoReadOnlyDataSource, dumpMetrics, PostGIS variant with optional LW/HexWKB mode, and keeping containers running locally.
-- [Entity Bean Creation](https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/entity-bean-creation.md): Generate clean, idiomatic Ebean entity beans. Covers required annotations, recommended field patterns, relationships, audit fields, and anti-patterns such as public fields, `Set` collections, or custom equals/hashCode.
-- [Lombok with Ebean entity beans](https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/lombok-with-ebean-entity-beans.md): Which Lombok annotations to use and avoid on entity beans. Explains why @Data is incompatible (hashCode/equals breaks entity identity, toString triggers lazy loading). Prescribes @Getter + @Setter + @Accessors(chain=true). Includes compatibility table for common Lombok annotations.
-- [Write Ebean queries with query beans](https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/writing-ebean-query-beans.md): Prefer Q-bean queries for type-safe ORM queries. Covers choosing `exists()`/`findOne()`/`findList()`/`findPagedList()`, tuning `select()` / `fetch()` / `fetchQuery()` / `FetchGroup`, using `setUnmodifiable(true)` for read-only entity graphs, and projecting to DTOs when entity beans are not the right output.
-- [Persisting and transactions with Ebean](https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/persisting-and-transactions-with-ebean.md): Choose `insert`, `save`, `update`, `delete`, or bulk update based on intent. Covers cascade rules, implicit transactions, `@Transactional`, explicit transactions, and batching for larger write workloads.
-- [Testing with TestEntityBuilder](https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/testing-with-testentitybuilder.md): Rapidly create test entity instances with auto-populated values. Covers relationship handling, cascade-persist behavior, custom value generators, and when TestEntityBuilder is a good fit versus manual fixtures.
-- [DB migration generation](https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-db-migration-generation.md): Add GenerateDbMigration.java to generate schema diff migrations offline (no database needed). Configure the migration runner with ebean.migration.run=true. Understand .sql and .model.xml output files. Covers version naming, multi-platform, pending drops, setPathToResources for multi-module projects, and named database support.
 
 ## Entities and Mapping