diff --git a/docs/api/user-profile.md b/docs/api/user-profile.md
index 610d0ff6..fa905821 100644
--- a/docs/api/user-profile.md
+++ b/docs/api/user-profile.md
@@ -95,17 +95,19 @@ Get a user profile.
 ### Path Parameters
 | Param | Type | Description |
 |-------|------|-------------|
-| `uuid` | string (UUID) | Profile UUID |
+| `uuid` | string (UUID) | **Profile UUID or the owning User UUID** — both are accepted |
+
+> **Auto-resolve & lazy-create:** `{uuid}` is first looked up as a profile uuid, then as a user uuid. If it is the **current user's** (or, for admins, any user's) uuid and that user has **no profile yet**, an empty profile is created and returned (HTTP 200) — so a freshly registered user always gets an editable profile instead of a 404. The response includes both the profile `uuid` and `user_uuid`; keep the profile `uuid` for subsequent PATCHes.
 
 ### Response `200`
-Full profile object including all fields.
+Full profile object including all fields (all `null` for a newly created empty profile). Response is double-nested: extract with `data.data`.
 
 ### Errors
 | Code | HTTP | Description |
 |------|------|-------------|
 | `ERR_AUTH_001` | 401 | Missing token |
 | `ERR_FORBIDDEN_001` | 403 | Not authorized to view this profile |
-| `ERR_NOT_FOUND_001` | 404 | Profile not found |
+| `ERR_VALIDATION_002` | 404 | No profile or user matches the uuid |
 
 ---
 
@@ -118,7 +120,7 @@ Update a user profile.
 ### Path Parameters
 | Param | Type | Description |
 |-------|------|-------------|
-| `uuid` | string (UUID) | Profile UUID |
+| `uuid` | string (UUID) | **Profile UUID or the owning User UUID** — both accepted; the profile is created if the current user has none yet |
 
 ### Request Body
 Same fields as POST — all optional.