11# AGENTS.md
22
3- > ** ⚡ Token Efficiency Note** : This file contains complete operational instructions (~ 2,500 tokens).
4- > ** Auto-loaded** : NO (load explicitly with ` #file:AGENTS.md ` when you need detailed procedures)
5- > ** When to load** : Complex workflows, troubleshooting, CI/CD setup, detailed architecture questions
3+ > ** ⚡ Token Efficiency Note** : This file contains complete operational instructions (~ 2,500 tokens).
4+ > ** Auto-loaded** : NO (load explicitly with ` #file:AGENTS.md ` when you need detailed procedures)
5+ > ** When to load** : Complex workflows, troubleshooting, CI/CD setup, detailed architecture questions
66> ** Related files** : See ` #file:.github/copilot-instructions.md ` for quick context (auto-loaded, ~ 500 tokens)
77
88---
@@ -76,6 +76,7 @@ open target/site/jacoco/index.html
7676```
7777
7878** Pre-commit checklist** :
79+
79801 . Run ` ./mvnw clean install ` - must pass all tests and build successfully
80812 . Check JaCoCo coverage report - maintain existing coverage levels
81823 . Ensure code compiles without warnings
@@ -85,11 +86,13 @@ open target/site/jacoco/index.html
8586### Build Artifacts
8687
8788After building, JAR file is located at:
89+
8890```
8991target/java.samples.spring.boot-{version}.jar
9092```
9193
9294Run the JAR directly:
95+
9396``` bash
9497java -jar target/java.samples.spring.boot-* .jar
9598```
@@ -99,21 +102,24 @@ java -jar target/java.samples.spring.boot-*.jar
99102This project uses ** H2 in-memory database for tests** and ** SQLite for runtime** .
100103
101104** Runtime (SQLite)** :
105+
102106``` bash
103107# Database auto-initializes on first startup
104- # Pre-seeded database ships in storage/books.db
108+ # Pre-seeded database ships in storage/books-sqlite3 .db
105109
106110# To reset database to seed state
107- rm storage/books.db
108- # Next app startup will recreate via JPA
111+ rm storage/books-sqlite3.db
112+ # WARNING: spring.jpa.hibernate.ddl-auto=none disables schema generation
113+ # Deleting the DB will cause startup failure - restore from backup or manually reinitialize
109114
110- # Database location: storage/books.db
115+ # Database location: storage/books-sqlite3 .db
111116```
112117
113118** Tests (H2)** :
119+
114120- In-memory database per test run
115121- Automatically cleared after each test
116- - Configuration in ` src/test/resources/application-test .properties `
122+ - Configuration in ` src/test/resources/application.properties `
117123
118124## Docker Workflow
119125
@@ -149,13 +155,15 @@ curl http://localhost:8080/actuator/health
149155** Trigger** : Push to ` master ` or PR to ` master `
150156
151157** Jobs** :
158+
1521591 . ** Setup** : JDK 25 installation, Maven dependency caching
1531602 . ** Lint** : Commit message validation (commitlint)
1541613 . ** Build** : ` ./mvnw clean install ` (compile + test + package)
1551624 . ** Test** : Tests already run during install, coverage reports generated
1561635 . ** Coverage** : JaCoCo report upload to Codecov and Codacy
157164
158165** Local validation** (run this before pushing):
166+
159167``` bash
160168# Matches CI exactly
161169./mvnw clean install
@@ -193,6 +201,7 @@ src/test/java/ # Test classes
193201```
194202
195203** Key patterns** :
204+
196205- Spring Boot 4 with Spring MVC
197206- Spring Data JPA for database operations
198207- Custom validation annotations for ISBN and URL
@@ -219,12 +228,14 @@ src/test/java/ # Test classes
219228## Troubleshooting
220229
221230### Port already in use
231+
222232``` bash
223233# Kill process on port 8080
224234lsof -ti:8080 | xargs kill -9
225235```
226236
227237### Maven dependency issues
238+
228239``` bash
229240# Force update dependencies
230241./mvnw clean install -U
@@ -235,6 +246,7 @@ rm -rf ~/.m2/repository
235246```
236247
237248### Compilation errors
249+
238250``` bash
239251# Verify Java version
240252java --version # Should be 25.x
@@ -247,6 +259,7 @@ java --version # Should be 25.x
247259```
248260
249261### Database locked errors
262+
250263``` bash
251264# Stop all running instances
252265pkill -f " spring-boot:run"
@@ -256,6 +269,7 @@ rm storage/books.db
256269```
257270
258271### Test failures
272+
259273``` bash
260274# Run tests with verbose output
261275./mvnw test -X
@@ -265,6 +279,7 @@ rm storage/books.db
265279```
266280
267281### Maven wrapper issues
282+
268283``` bash
269284# Make wrapper executable
270285chmod +x mvnw
@@ -274,6 +289,7 @@ mvn clean install
274289```
275290
276291### Docker issues
292+
277293``` bash
278294# Clean slate
279295docker compose down -v
@@ -284,9 +300,11 @@ docker compose up
284300## Testing the API
285301
286302### Using Swagger UI (Recommended)
287- Open http://localhost:8080/swagger-ui.html - Interactive documentation with "Try it out"
303+
304+ Open < http://localhost:8080/swagger-ui.html > - Interactive documentation with "Try it out"
288305
289306### Using curl
307+
290308``` bash
291309# Health check
292310curl http://localhost:8080/actuator/health
0 commit comments