diff --git a/Profiles.md b/Profiles.md
new file mode 100644
index 0000000..ddbe144
--- /dev/null
+++ b/Profiles.md
@@ -0,0 +1,79 @@
+# Profiles
+
+Dumpster profiles are customizable per-user. Each user has a profile with the following fields.
+
+## Fields
+
+| Field | Type | Max Length | Notes |
+|-------|------|-----------|-------|
+| `username` | string | 32 | Set at registration, unique, immutable |
+| `display_name` | string | 32 | Nickname, defaults to username |
+| `email` | string | 255 | Used for auth and Gravatar |
+| `avatar` | URL | text | Custom upload or Gravatar fallback |
+| `bio` | string | 250 | One-liner shown on profile popover |
+| `accent_color` | hex | 7 | Overrides default username color in chat |
+| `status` | enum | - | online / idle / dnd / offline (set by presence) |
+| `status_text` | string | 128 | Custom status message |
+
+## Avatar System
+
+### Custom Upload
+
+Users can upload a custom avatar via `POST /api/v1/upload` (multipart form). The uploaded file is stored in minio and the URL is saved to the user's `avatar` field.
+
+### Gravatar Fallback
+
+If no custom avatar is set, the server computes `md5(email)` and serves:
+
+```
+https://www.gravatar.com/avatar/{hash}?d=identicon&s=256
+```
+
+This happens automatically. Users with Graccounts get their Gravatar. Users without get a generated identicon.
+
+## API
+
+### Get Current Profile
+
+```
+GET /api/v1/auth/me
+```
+
+Returns full profile including all fields above.
+
+### Update Profile
+
+```
+PATCH /api/v1/auth/me
+
+{
+  "display_name": "New Name",
+  "bio": "Hello world",
+  "accent_color": "#fe8019",
+  "status_text": "brb"
+}
+```
+
+All fields are optional. Only provided fields are updated.
+
+### Upload Avatar
+
+```
+POST /api/v1/upload
+Content-Type: multipart/form-data
+
+file: <image>
+```
+
+Returns `{ "url": "/files/<uuid>.png", "size": 12345 }`. Set this URL as the avatar field.
+
+## Settings UI
+
+The profile editor is at `/settings` in the web app. Terminal-styled form with:
+
+- `DISPLAY_NAME:` field
+- `BIO:` textarea with char counter
+- `STATUS_TEXT:` field
+- `ACCENT_COLOR:` field with color preview swatch
+- `AVATAR:` current avatar display + upload button
+- `[SAVE]` button
diff --git a/_Sidebar.md b/_Sidebar.md
index ebd0786..4d2cba3 100644
--- a/_Sidebar.md
+++ b/_Sidebar.md
@@ -4,6 +4,7 @@
 - [Getting Started](Getting-Started)
 - [Architecture](Architecture)
 - [API Reference](API-Reference)
+- [Profiles](Profiles)
 - [Frontend Design](Frontend-Design)
 - [Self-Hosting](Self-Hosting)
 - [Roadmap](Roadmap)