feat: api v1 garden bangs routes and openapi

docs/api/README.md

@@ -1,19 +1,27 @@
 # famapp HTTP API (v1)
 
-REST JSON API under `/api/v1/`. Full OpenAPI spec is planned in task 87.3.
+REST JSON API under `/api/v1/`. Full specification: [`openapi.yaml`](openapi.yaml).
 
 ## Authentication
 
 Every endpoint accepts **either**:
 
 - Auth.js session cookie (browser login), or
-- `Authorization: Bearer <household-api-token>` header
+- `Authorization: Bearer <household-api-token>` header (recommended for external clients)
 
 Unauthorized requests return `401` with `{ "error": "Unauthorized" }`.
 
-Generate bearer tokens in **Settings → API tokens**.
+Generate bearer tokens in **Settings → API tokens**. Example:
 
-## Endpoints (87.2)
+```bash
+curl -H "Authorization: Bearer YOUR_TOKEN" https://fam.ginnoir.com/api/v1/calendars
+```
+
+## OpenAPI
+
+See [`openapi.yaml`](openapi.yaml) for paths, request/response schemas, and the `bearerAuth` security scheme. Import into Swagger UI, Postman, or your HTTP client of choice.
+
+## Endpoints
 
 ### Calendars
 
@@ -59,11 +67,30 @@ Generate bearer tokens in **Settings → API tokens**.
 | PATCH  | `/api/v1/notes/:id` | Update note |
 | DELETE | `/api/v1/notes/:id` | Delete note |
 
+### Garden
+
+| Method | Path                            | Description                            |
+| ------ | ------------------------------- | -------------------------------------- |
+| GET    | `/api/v1/garden/containers`     | List containers                        |
+| POST   | `/api/v1/garden/containers`     | Create container                       |
+| GET    | `/api/v1/garden/containers/:id` | Get container with plants              |
+| PATCH  | `/api/v1/garden/containers/:id` | Update container                       |
+| DELETE | `/api/v1/garden/containers/:id` | Delete container                       |
+| GET    | `/api/v1/garden/plants`         | List plants (optional `?containerId=`) |
+| POST   | `/api/v1/garden/plants`         | Create plant                           |
+| GET    | `/api/v1/garden/plants/:id`     | Get plant detail                       |
+| PATCH  | `/api/v1/garden/plants/:id`     | Update plant                           |
+| DELETE | `/api/v1/garden/plants/:id`     | Delete plant                           |
+
+### Bangs
+
+| Method | Path                | Description                                      |
+| ------ | ------------------- | ------------------------------------------------ |
+| GET    | `/api/v1/bangs`     | Stats: `total` + `recent` (optional `?limit=10`) |
+| POST   | `/api/v1/bangs`     | Record bang (optional `occurredOn` YYYY-MM-DD)   |
+| PATCH  | `/api/v1/bangs/:id` | Update `occurredOn`                              |
+| DELETE | `/api/v1/bangs/:id` | Delete bang                                      |
+
 ## Bearer token visibility
 
 Bearer tokens see **household-visible calendars only** (private calendars are hidden). Mutations on calendars require ownership (session) or household visibility (bearer). Activity log records `actorId: null` for bearer mutations.
-
-## Planned (87.3)
-
-- Garden, bangs routes
-- OpenAPI specification