API contract hardening

docs/api-contract.md

@@ -0,0 +1,34 @@
+# API Contract Policy
+
+The public HTTP API is currently version `0.1.0`. Until a versioned path such as
+`/api/v1` is introduced, compatibility is governed by the OpenAPI contract
+published at `/openapi.json` and covered by the test suite.
+
+Agent-facing endpoints are considered stable when their path, method, tag, and
+success response model appear in the OpenAPI contract snapshot test. A change to
+one of those fields is allowed, but it must update the snapshot test in the same
+change so the break is explicit during review.
+
+Compatible changes include:
+
+- adding optional request fields with defaults
+- adding response fields that clients may ignore
+- adding new endpoints
+- adding new examples or descriptions
+
+Breaking changes include:
+
+- removing or renaming an endpoint
+- changing an endpoint method or tag
+- changing the success response model
+- removing or renaming a response field
+- making an optional request field required
+- changing the shape of common error responses
+
+Common application errors use:
+
+```json
+{"detail": "repository 999 was not found"}
+```
+
+Validation errors remain FastAPI's standard `422` validation response.