Changeset 0.28.0.4 (#176)

docs/ICD/admin.md

@@ -5,15 +5,19 @@ Cross-cutting admin operations that don't belong to a specific domain.
 ### User Management
 
 ```
-GET    /admin/users                  → { "users": [...] }
+GET    /admin/users                  → { "users": [...], "total": N }
 POST   /admin/users                  ← { "username", "password", "email", "role" }
 PUT    /admin/users/:id/role         ← { "role": "admin|user" }
-PUT    /admin/users/:id/active       ← { "active": false }
+PUT    /admin/users/:id/active       ← { "is_active": false }
 DELETE /admin/users/:id
-POST   /admin/users/:id/reset-password  ← { "new_password": "..." }
+POST   /admin/users/:id/reset-password  ← { "password": "..." }
 POST   /admin/users/:id/vault/reset     → destroys user's UEK (BYOK keys lost)
 ```
 
+`PUT /admin/users/:id/role` refuses to demote the last remaining admin
+(returns 409). `DELETE /admin/users/:id` also refuses if the target is
+the last admin, and destroys the user's vault before deleting the row.
+
 ### Global Settings & Policies
 
 Settings are key-value pairs in `global_settings`. Policies are
@@ -45,11 +49,14 @@ GET /settings/public
   "policies": {
     "allow_registration": "true",
     "allow_user_byok": "true",
-    "allow_user_personas": "true"
+    "allow_user_personas": "true",
+    "channel_retention_mode": "flexible"
   }
 }
 ```
 
+Note: policy values are strings (`"true"` / `"false"`), not booleans.
+
 ### Banner Configuration
 
 The environment banner is stored as a single `global_config` entry
@@ -104,20 +111,33 @@ GET /admin/vault/status              → { "encryption_key_set", "user_vaults_co
 ### Audit Log
 
 ```
-GET /admin/audit?page=1&per_page=50&action=user.create&actor_id=uuid
+GET /admin/audit?page=1&per_page=50&action=user.create&actor_id=uuid&resource_type=...
 GET /admin/audit/actions             → { "actions": ["user.create", "policy.update", ...] }
 ```
 
-Audit entry:
+The list endpoint returns a paginated envelope:
+
+```json
+{
+  "data": [...],
+  "total": 128,
+  "page": 1,
+  "per_page": 50
+}
+```
+
+Audit entry shape:
 
 ```json
 {
   "id": "uuid",
   "actor_id": "uuid",
+  "actor_name": "admin",
   "action": "user.create",
   "resource_type": "user",
   "resource_id": "uuid",
-  "metadata": {},
+  "metadata": "{}",
+  "ip_address": "10.0.0.1",
   "created_at": "..."
 }
 ```
@@ -126,13 +146,31 @@ Audit entry:
 
 ```
 GET /admin/usage                     → { "totals", "results" }
-GET /admin/usage/teams/:id           → team-specific usage
-GET /admin/usage/users/:id           → user-specific usage
-GET /admin/pricing                   → { "data": [...] }
-PUT /admin/pricing                   ← { "provider", "model", "input_per_m", "output_per_m" }
-DELETE /admin/pricing/:provider/:model
+GET /admin/usage/teams/:id           → { "results": [...] }
+GET /admin/usage/users/:id           → { "results": [...] }
+GET /admin/pricing                   → [ ... ]
+PUT /admin/pricing                   ← { "provider_config_id", "model_id", "input_per_m", "output_per_m" }
+DELETE /admin/pricing/:provider_config_id/:model_id
 ```
 
+`GET /admin/pricing` returns a bare array (no envelope).
+
+`PUT /admin/pricing` accepts the full `PricingEntry` shape:
+
+```json
+{
+  "provider_config_id": "uuid",
+  "model_id": "gpt-4o",
+  "input_per_m": 2.50,
+  "output_per_m": 10.00,
+  "cache_create_per_m": 1.25,
+  "cache_read_per_m": 0.50,
+  "currency": "USD"
+}
+```
+
+Pricing cannot be set for personal BYOK providers (403).
+
 **Personal usage** (non-admin):
 
 ```
@@ -156,22 +194,22 @@ POST   /admin/roles/:role/test       ← test role permissions
 POST /admin/notifications/test-email
 ```
 
-```json
-{ "to": "admin@example.com" }
-```
-
-Sends a test email using the configured SMTP settings.
+No request body required. Sends a test email to the authenticated
+admin's own email address using the configured SMTP settings.
 
 ---
 
 ### Archived Channels
 
 ```
-GET    /admin/channels/archived      → { "data": [...] }
+GET    /admin/channels/archived      → { "channels": [...], "total", "page", "per_page", "retention_mode" }
 DELETE /admin/channels/:id/purge     → permanent delete (ignores retention)
 ```
 
-**Auth:** Platform admin.
+Both endpoints require platform admin auth. `GET` accepts
+`?page=1&per_page=50` query parameters (max 100 per page).
+`DELETE` verifies the channel is archived before purging and cleans
+up associated file storage blobs.
 
 ### Surfaces Admin