docs: document the non-OpenAPI routes carve-out (R11)

10 routes are registered manually on the chi router in server.go rather
than generated from openapi.yaml. Added a 'Non-OpenAPI routes' comment
block at the top of NewHandler listing each route with its structural
reason for the carve-out:

  - Auth/infra: /healthz, /api/v1/auth/oidc-*, /oidc-callback — bypass
    auth middleware or aren't JSON API
  - SSE override: /api/v1/events/stream — re-registered for Flush()
  - Ad-hoc aggregations: /knowledge/recent, /knowledge/content/{id},
    /activity/recent, /activity/session/{id}, /learning/timeline,
    /learning/trend — derived shapes with no schema type yet

Updated .agents/dev/CONTRIBUTING.md §OpenAPI codegen with the carve-out
policy: if an ad-hoc route stabilizes, promote it to openapi.yaml with a
proper schema and migrate the serve* function to a strict handler.

.agents/dev/CONTRIBUTING.md

@@ -113,6 +113,23 @@ current phase status). To add a new capability:
   implement it in `internal/httpapi/impl.go`
 - Problem+JSON errors via `internal/httpapi/problem.go` — RFC 9457 format
 - Cursor pagination, If-Match/ETag, idempotency keys, SSE streaming
+- **Non-OpenAPI routes carve-out:** ~10 routes are registered manually on
+  the chi router in `internal/httpapi/server.go` rather than generated from
+  `openapi.yaml`. These fall into three categories:
+  1. **Auth/infra** (`/healthz`, `/api/v1/auth/oidc-*`, `/oidc-callback`) —
+     must bypass the auth middleware or aren't JSON API endpoints.
+  2. **SSE override** (`/api/v1/events/stream`) — in the spec but
+     re-registered manually because the strict handler can't `Flush()` per
+     event.
+  3. **Ad-hoc aggregations** (`/api/v1/knowledge/recent`,
+     `/api/v1/knowledge/content/{id}`, `/api/v1/activity/recent`,
+     `/api/v1/activity/session/{id}`, `/api/v1/learning/timeline`,
+     `/api/v1/learning/trend`) — return derived/aggregate shapes that don't
+     map cleanly to a schema type. If one of these stabilizes, promote it
+     to `openapi.yaml` with a proper schema and migrate the `serve*`
+     function to a strict handler.
+  The full list with reasons is in the "Non-OpenAPI routes" comment block
+  at the top of `NewHandler` in `server.go`.
 
 ## Testing philosophy