AGENTS.md

1# API Library Guidelines
2 
3`api/` is the public API library: the extension model, service contracts, and security abstractions consumed by the application and by plugins. Changes here affect downstream compatibility.
4 
5## Scope
6 
7- Source: `api/src/main/java/run/halo/app/` (core, extension, plugin, security, migration, theme, and related packages).
8- Tests: `api/src/test/`.
9 
10## Commands
11 
12- `./gradlew :api:test` — run API library tests.
13- `./gradlew spotlessApply` — format Java and Markdown.
14 
15## Conventions
16 
17- Java 21, 4-space indentation, formatted with Spotless.
18- The API is a compatibility surface: prefer additive changes, and flag any breaking signature or contract change for review before merging.
19- Extension definitions and schemas live in `application/src/main/resources/extensions/`; when you change them, update `application/` and `ui/` together.
20- Tests: JUnit 5, named `XxxTest` (unit) or `XxxIntegrationTest` (integration).
21 
22## Boundaries
23 
24- Public API changes in `api/` require explicit approval — treat them as affecting every plugin built against Halo.
25 
26