# Repository Guidelines

## Project Structure & Modules
- `src/main/java/com/clortox/agent`: Spring Boot app code (`AgentApplication`, support classes).
- `src/main/resources`: Config (e.g., `application.yml`). SQLite DB path: `./data/agent.db`.
- `src/test/java/com/clortox/agent`: JUnit 5 tests (Spring test support).
- `target/`: Build outputs. Not checked in.
- `data/`: Created at startup for local DB. Do not commit.

## Build, Test, and Run
- Build: `./mvnw clean verify` — compile, run tests, package the app.
- Package (skip tests): `./mvnw -DskipTests package` — produces JAR in `target/`.
- Run locally: `./mvnw spring-boot:run` — starts the API with SQLite.
- Run JAR: `java -jar target/agent-0.0.1-SNAPSHOT.jar` — same as above.
- Java version: JDK 21 is enforced by the build (enforcer plugin).

## Coding Style & Naming
- Language: Java 21. Indentation: 4 spaces; 120-col soft wrap.
- Packages: `com.clortox.agent.*`. Class names are PascalCase; methods/fields camelCase.
- Spring components: annotate appropriately (`@RestController`, `@Service`, `@Entity`). Favor constructor injection.
- Lombok: allowed where present (e.g., `@Getter`, `@RequiredArgsConstructor`). Avoid overuse that obscures intent.

## Testing Guidelines
- Frameworks: JUnit 5 with Spring Boot test starter; Modulith test starter is available.
- Naming: `*Tests.java` per class or feature (e.g., `AgentApplicationTests`).
- Run tests: `./mvnw test`. Prefer slice tests where possible; use `@SpringBootTest` only when needed.
- Aim for meaningful coverage on domain logic; avoid brittle tests against logs or timing.

## Commit & Pull Requests
- Commits: imperative, concise subject (≤72 chars). Example: `Add SQLite dialect and datasource config`.
- Include context in body: rationale, notable trade-offs, follow-up TODOs.
- PRs: clear description, linked issues (`Fixes #123`), test evidence (logs or screenshots), and manual run steps.
- Ensure: `./mvnw clean verify` passes locally and no files added to `data/` or `target/`.

## Configuration Tips
- DB location: `application.yml` points to `jdbc:sqlite:./data/agent.db`. Override via CLI:
  `./mvnw spring-boot:run -Dspring-boot.run.arguments="--spring.datasource.url=jdbc:sqlite:/tmp/agent.db"`.
- The app creates `./data` at startup; avoid hardcoding absolute paths.