first commit

docs/api-stack/api/api-plugin-user/src/routes/get-me.md

@@ -0,0 +1,57 @@
+# routes/get-me
+
+## Purpose
+
+`buildGetMeRoute` returns the `PluginRouteEntry` for `GET /me`. The
+handler resolves the current Principal from `c.get("user")` (set by
+the auth plugin's session middleware), invokes
+`userService.getCurrent(c)` to merge the Principal with the
+profile-row columns, and responds with the canonical
+`{ success: true, data: UserProfile }` envelope. Successful responses
+emit the `user.profile_reads_total` counter.
+
+## Features
+
+- Single-route builder so the OpenAPI doc registration is co-located
+  with the handler.
+- Defensive 401 raise when the principal is missing — protects the
+  route when `requireAuth()` is bypassed at the host layer.
+- Counter emission only on success — failures are recorded by the
+  host's error-handler middleware via `error.code`.
+
+## Usage: Basic
+
+```ts
+import { buildGetMeRoute } from "@suaveplan/api-plugin-user/routes/routes";
+
+const entry = buildGetMeRoute(userService);
+```
+
+## Usage: Advanced
+
+Composing the handler outside the build-routes loop lets operators
+mount a custom variant on a different path:
+
+```ts
+const { route, handler } = buildGetMeRoute(userService);
+app.openapi({ ...route, path: "/profile" }, handler);
+```
+
+## API Reference
+
+### `buildGetMeRoute(userService: UserService): PluginRouteEntry`
+
+Returns `{ route, handler }`. `route` is a `RouteConfig` built from
+`RouteBuilder`; `handler` is an async `(c: Context) => Promise<Response>`.
+
+## Implementation Notes
+
+- The handler reads `userService.getCurrent` rather than `getById` so
+  the Principal projection (which carries roles + tenantId from the
+  session) survives the round-trip.
+- The 401 raise carries `statusCode: 401` so the host's
+  error-handler middleware emits HTTP 401 with the canonical error
+  envelope.
+- The counter increment happens AFTER the `c.json` response is
+  prepared but is not blocking — OpenTelemetry counters are
+  fire-and-forget.