docs: update notification channel and API docs for form-based management

- NOTIFICATIONS.md: document owner/private fields, channel visibility
  rules, and user-created channels; add troubleshooting note for
  private channel visibility
- HTTP_API.md: add notification channel API endpoints table and full
  endpoint reference (GET types, GET/POST/PUT/DELETE channels)
- USERS.md: add missing PUT /api/0/users/me endpoint documentation
  with all three update modes (identity, channels, password)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs/NOTIFICATIONS.md

@@ -30,9 +30,17 @@ Set `base_url` so notification links point to your hbd instance:
 base_url: https://hbd.example.com
 ```
 
-### Global channel definitions
+### Channel definitions
 
-Define channels once; reference them by name from user configs:
+Channels are defined under `notification_channels`. Each entry specifies a delivery type and its credentials. Two optional metadata fields control visibility:
+
+| Field | Default | Description |
+|---|---|---|
+| `owner` | *(absent)* | Username who created/owns this channel. Absent = admin-created. |
+| `private` | `false` | When `true`, only the owner can see and select this channel. |
+| `min_level` | `WARNING` | Minimum alert level this channel receives. |
+
+**Admin-created channels** (set in the config file or via the admin settings UI) are public by default — all users can select them:
 
 ```yaml
 notification_channels:
@@ -41,7 +49,7 @@ notification_channels:
     type: pushover
     token: your-app-token
     user: your-user-key
-    min_level: WARNING        # optional, default: WARNING
+    min_level: WARNING
 
   email_ops:
     type: email
@@ -58,14 +66,14 @@ notification_channels:
     homeserver: https://matrix.example.org
     access_token: syt_xxx
     room_id: "!abc:matrix.example.org"
-    min_level: CRITICAL       # only send critical alerts to this room
+    min_level: CRITICAL
 
   sms_oncall:
     type: sms_voipms
     api_user: me@example.com
     api_password: secret
-    did: "5551234567"         # your voip.ms DID number
-    dst: "5559876543"         # destination number
+    did: "5551234567"
+    dst: "5559876543"
     min_level: CRITICAL
 
   signal_ops:
@@ -82,9 +90,30 @@ notification_channels:
     username: heartbeat-bot
 ```
 
+**User-created channels** are written by authenticated users through the API or their profile page. They carry an `owner` field and optionally `private: true`:
+
+```yaml
+notification_channels:
+
+  alice_personal:
+    type: pushover
+    token: personal-token
+    user: personal-key
+    owner: alice          # created by alice
+    private: true         # only alice can see this channel
+```
+
+### Channel visibility
+
+| Channel | Who can see / select it |
+|---|---|
+| No `private` field (or `private: false`) | All users |
+| `private: true` | Only the `owner` |
+| Any channel | Admins always see everything |
+
 ### Users with notification channels
 
-Each user lists which global channels they receive notifications on:
+Each user lists which channels they receive notifications on. Users can manage their own selection from the profile page:
 
 ```yaml
 users:
@@ -270,6 +299,7 @@ Called once at startup from `main.py`. Pass the running asyncio event loop so Ma
 - Check that the host has an `owner` or `managers` set
 - Check that users have `notification_channels` listed
 - Check that the channel names in user config match keys under `notification_channels:`
+- If a user can't select a channel, check whether it is `private: true` and owned by someone else
 
 **min_level filtering too aggressive:**
 - Default is `WARNING` — both WARNING and CRITICAL are sent