v0.33.7

docs/API.md

@@ -76,6 +76,37 @@ rejection, 409 for already-completed setup, 422 for password policy and 429 for
 throttling/busy workers. Error objects usually contain an `error` code/string;
 framework extraction failures are not guaranteed to have that JSON shape.
 
+## Administrator Overview layout presets (0.33.7)
+
+The dashboard preset endpoints are private control-plane routes and use the
+existing administrator session cookie. The same Origin, request-marker and
+CSRF rules as other settings writes apply. They do **not** change the proxy
+configuration revision and cannot be called from public vhosts.
+
+| Method / path | Request or result |
+|---|---|
+| `GET /api/dashboard-presets` | Array of named layouts for the authenticated administrator |
+| `PUT /api/dashboard-presets/{name}` | Create/overwrite a named layout; JSON body described below; returns 204 |
+| `PATCH /api/dashboard-presets/{name}` | Rename using `{ "name": "new name" }`; returns 204 |
+| `DELETE /api/dashboard-presets/{name}` | Delete the named layout; returns 204 |
+
+A layout is `{ "dashboard_widgets": ["..."], "dashboard_hidden_widgets": ["..."],
+"dashboard_widget_sizes": null, "dashboard_density": "compact",
+"overview_samples": 600 }`, using registered widget IDs and the same
+width/density validation as administrator view preferences. History accepts
+60, 120, 300 or 600 samples. For sizes, `null` preserves legacy grouped
+placement; an object maps widget IDs to valid 12-column spans. The account
+may store at most 16 named layouts; names are 1-64 UTF-8 bytes with no
+control characters, surrounding whitespace or slash. Invalid values receive
+422; full capacity or a conflicting rename receives 409. Unknown delete
+returns 404. All write endpoints require a session-bound CSRF token.
+
+The data resides in SQLite schema 10 (`dashboard_presets`), separate from
+`admin_preferences`; the factory preset is not stored as a mutable row.
+The browser saves the chosen history sample count using its existing local
+preference when loading a preset. The client does not use JSON configuration
+files to store named presets.
+
 ## Configuration and observations
 
 | Method / path | Result |
@@ -107,7 +138,7 @@ and rechecks session validity. It does not queue an unlimited per-viewer event l
 or guarantee replay. The browser falls back to compact status/log polling only after SSE fails and stops polling after its recovery. Invalid SSE intervals are rejected with 422. An active dashboard renews
 idle activity, not the absolute session deadline.
 
-Configuration history, introduced in SQLite schema 8 and retained in current schema 9, keeps the newest 512 successful manual/configuration revisions. `GET /api/config/history` is session-protected like the rest of the administration API; `limit` is bounded to 512 and `revision` selects one retained revision for diff/inspection. `POST /api/config/history/restore` also requires the normal CSRF/request-marker protections, rejects stale `expected_revision`, and never rewinds the revision counter: restoring revision 85 while current revision is 120 creates revision 121.
+Configuration history, introduced in SQLite schema 8 and retained in current schema 10, keeps the newest 512 successful manual/configuration revisions. `GET /api/config/history` is session-protected like the rest of the administration API; `limit` is bounded to 512 and `revision` selects one retained revision for diff/inspection. `POST /api/config/history/restore` also requires the normal CSRF/request-marker protections, rejects stale `expected_revision`, and never rewinds the revision counter: restoring revision 85 while current revision is 120 creates revision 121.
 
 Configuration updates return 409 for a stale revision, 422 for validation failure
 and 429 when the eight-operation update admission bound is reached. Persistence and