From 54706231974caf089e4a4ca422c83e6ee0cc3dca Mon Sep 17 00:00:00 2001
From: OpenVelo Agent <openvelo-agent@openvelo.org>
Date: Wed, 22 Jul 2026 12:31:57 +0000
Subject: [PATCH] docs: update documentation to OKF v0.1 format

---
 docs/api/admin.md                     |  3 ++-
 docs/guides/admin-general-settings.md | 10 ++++++++--
 2 files changed, 10 insertions(+), 3 deletions(-)

diff --git a/docs/api/admin.md b/docs/api/admin.md
index b534c0c..445e7ce 100644
--- a/docs/api/admin.md
+++ b/docs/api/admin.md
@@ -41,7 +41,8 @@ removes the row.
 
 `PUT /settings` is validated by `GeneralSettingsSchema` (zod):
 
-* `pageTitle` 1–120 chars
+* `pageTitle` is trimmed server-side and must be 1–120 chars after
+  trimming (whitespace-only values are rejected).
 * `logo` up to 2048 chars (a public URL — uploaded separately)
 * `welcomeMarkdown` up to 64 000 chars
 * `themeKey` is one of `THEME_IDS`
diff --git a/docs/guides/admin-general-settings.md b/docs/guides/admin-general-settings.md
index b5442dc..b9feecf 100644
--- a/docs/guides/admin-general-settings.md
+++ b/docs/guides/admin-general-settings.md
@@ -38,7 +38,7 @@ The page is a single reactive form with these controls (every
 
 | Label                  | `data-testid`             | Backend field           | Notes |
 |------------------------|---------------------------|-------------------------|-------|
-| Page title             | `general-pageTitle`       | `pageTitle`             | Required, max 120 chars. |
+| Page title             | `general-pageTitle`       | `pageTitle`             | Required, non-blank, max 120 chars; trimmed server-side. |
 | Logo (file picker)     | `general-logo-file`       | `logo` (public URL)     | Uploads via `POST /api/v1/uploads/logo`; the returned `publicUrl` is bound to a hidden input `general-logo`. |
 | Logo upload status     | `general-logo-uploading` / `general-logo-error` / `general-logo-current` | — | Inline status text under the file picker. |
 | Global theme           | `general-themeKey`        | `themeKey`              | `<select>` populated from `/themes`. Value is one of `THEME_IDS`. |
@@ -75,7 +75,13 @@ The page is a single reactive form with these controls (every
   `general-endBeforeStart` appears under the end input. Save remains
   disabled.
 * **Save:** clicking Save sends `PUT /api/v1/admin/general/settings`
-  with all fields. On success the form is patched with the response,
+  with all fields. The Page title input is validated client-side for
+  non-blank content; an empty or whitespace-only Page title disables the
+  Save button and renders `general-pageTitle-error` so the request is
+  never issued. The server trims surrounding whitespace and re-validates
+  against the same 1–120 character rule, so invalid payloads return
+  `400 VALIDATION_FAILED` and the stored Page title is unchanged.
+  On success the form is patched with the response,
   `general-save-ok` renders briefly, and the backend emits an SSE
   `general` event via `SseHubService` so other tabs refresh their theme.
 * **Error states:** load failures render `general-error`; save failures