feat: OpenAPI docs with a Scalar reference at /docs

AGENTS.md

@@ -533,6 +533,29 @@ route". Code lives in `src/routePlanning/`; README documents the contract.
 
 The first deploy applies the `v5` migration (prod and `--env dev`).
 
+## API docs (OpenAPI + Scalar)
+
+`GET /docs` is the Scalar API reference and `GET /openapi.json` its OpenAPI
+3.1 document, on both workers (prod: https://ww-proxy.leviwilkerson.com/docs).
+The repo is public, so the docs are too, admin routes included (they still
+need the token).
+
+- `hono-openapi` builds the document from the routes themselves: each route
+  carries a `describeRoute(...)` middleware, kept in an `openapi.ts` beside its
+  handlers (`src/notesImport/`, `src/buddies/`, `src/accounts/`,
+  `src/routePlanning/`; routes registered in `src/app.ts` use
+  `src/openapi/coreDocs.ts`). Shared helpers and the error envelope are in
+  `src/openapi/schemas.ts`; tags, servers, and the Scalar config in
+  `src/openapi/route.ts`.
+- The schemas describe the wire format for readers; they don't validate.
+  Handlers keep their own parsing, so **a contract change means updating the
+  route's `openapi.ts` in the same PR**.
+- `src/openapi/openapi.test.ts` fails on any route without docs, and on any
+  operation without a tag, summary, or responses.
+- Signed Buddies/accounts ops document the envelope `{p, s}` and list the
+  decoded `p` fields as a table (`signedBody`).
+- The document is built once per isolate. Scalar's UI loads from jsDelivr.
+
 ## Checks before deploy
 
 ```bash

README.md

@@ -113,6 +113,8 @@ GitHub Actions will automatically deploy to Cloudflare Workers. Monitor deployme
 
 ## API Endpoints
 
+Full API reference: [`/docs`](https://ww-proxy.leviwilkerson.com/docs) (Scalar), generated from the routes; the raw OpenAPI 3.1 document is at [`/openapi.json`](https://ww-proxy.leviwilkerson.com/openapi.json). Locally: `http://localhost:8787/docs`.
+
 ### `/autocomplete`
 
 Proxies to HERE Autocomplete API.

package.json

@@ -24,17 +24,19 @@
   },
   "packageManager": "pnpm@10.33.0",
   "dependencies": {
+    "@hot-updater/cloudflare": "1.0.2",
+    "@hot-updater/server": "1.0.2",
     "@openrouter/ai-sdk-provider": "^2.9.1",
     "@peculiar/x509": "^2.0.0",
+    "@scalar/hono-api-reference": "^0.12.12",
     "@sentry/cloudflare": "^8.55.1",
     "ai": "^6.0.208",
     "cbor2": "^2.3.0",
     "drizzle-orm": "0.45.4",
     "hono": "^4.12.12",
+    "hono-openapi": "^1.3.5",
     "reflect-metadata": "^0.2.2",
-    "zod": "^4.4.3",
-    "@hot-updater/cloudflare": "1.0.2",
-    "@hot-updater/server": "1.0.2"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20260411.1",