Document the admin metadata toggle

docs-developers/server/api/reference.md

@@ -53,10 +53,13 @@ it the moment it pairs. `version` is stamped from the release tag (`"dev"` for l
 `transcode` is true only when ffmpeg is configured; `web_player` only when the
 `/web` mount is populated; `upload` and `websocket` are reserved for future
 phases and currently always false. `api_keys` is true on servers that support
-user-minted [personal API keys](#personal-api-keys). `metadata` is true when the
-server has [community metadata lookup](#get-apiv1librariesidmeta) configured
-(`metadata.enabled` and a `metadata.base_url`); clients gate the enriched-book
-section on it.
+user-minted [personal API keys](#personal-api-keys). `metadata` reflects the
+**runtime** state of [community metadata lookup](#get-apiv1librariesidmeta): it
+is true only when a valid `metadata.base_url` is configured **and** the lookup is
+switched on. An admin can flip it on or off at runtime via
+[`PATCH /api/v1/admin/settings`](#patch-apiv1adminsettings) (no restart), so this
+flag can change during a server's lifetime; clients gate the enriched-book
+section on it and should re-read it after reconnecting.
 
 ### `GET /healthz` · `GET /api/v1/healthz`
 
@@ -1314,6 +1317,56 @@ a cross-user "currently listening" feed (up to 200 rows, newest first; `title`/
 }
 ```
 
+## Admin: settings
+
+Runtime-toggleable server settings, surfaced in the console's **Overview**
+section. The envelope is a feature-keyed object so future settings can join it
+without reshaping the wire contract; today it carries only `metadata`.
+
+### `GET /api/v1/admin/settings`
+
+*Admin.* Returns the current runtime settings.
+
+```json
+{
+  "metadata": {
+    "enabled": true,
+    "base_url": "https://meta.audiosilo.app",
+    "available": true
+  }
+}
+```
+
+For `metadata`: `enabled` is the runtime on/off flag; `base_url` is the
+configured metadata service URL (empty when none is set); `available` reports
+whether the lookup **can** be enabled at all - true only when `base_url` is a
+valid absolute `http(s)` URL. When `available` is false the feature is
+permanently off until the server config gains a valid `base_url`, and any attempt
+to enable it is rejected. The live `metadata` [capability](#get-apiv1server) is
+`enabled && available`.
+
+### `PATCH /api/v1/admin/settings`
+
+*Admin.* Flips runtime settings and persists them to `config.yaml` (so the change
+survives a restart). Send only the fields you want to change - an **absent field
+is left unchanged**. Returns the same envelope as `GET` with the new state.
+
+```json
+{ "metadata": { "enabled": false } }
+```
+
+Setting `metadata.enabled` to `true` when the lookup is unavailable (no valid
+`metadata.base_url`) is a **`400`** - configure `metadata.base_url` first.
+Toggling the flag takes effect immediately across the server: it gates
+`GET /libraries/{id}/meta` and the `metadata` capability, so every connected
+player starts or stops showing the enriched-book section without a restart.
+
+| Status | Meaning |
+|---|---|
+| `200` | updated; body is the current settings envelope |
+| `400` | invalid body, or enabling metadata when no valid `metadata.base_url` is configured |
+| `500` | the settings could not be persisted (the in-memory change is rolled back) |
+
 ## Well-known
 
 Native deep-link association files. Both are *Public*, config-driven

docs-developers/server/configuration.md

@@ -119,12 +119,22 @@ off all outbound calls.
 
 | Key | Type / default | Meaning |
 |---|---|---|
-| `metadata.enabled` | bool, `true` | Turn the metadata lookup on. When `false`, the server makes **no outbound metadata calls**, `GET /libraries/{id}/meta` returns 404, and the `metadata` capability reports false so players hide the enriched-book section entirely |
+| `metadata.enabled` | bool, `true` | Turn the metadata lookup on. When `false`, the server makes **no outbound metadata calls**, `GET /libraries/{id}/meta` returns 404, and the `metadata` capability reports false so players hide the enriched-book section entirely. Seeds the initial state only - an admin can flip this at runtime (see below) |
 | `metadata.base_url` | string, `"https://meta.audiosilo.app"` | Base URL of the metadata service (the site is served at `/` and the API at `/api/v1`). **Must be an absolute `http`/`https` URL when metadata is enabled** |
 
-Turning it off is the one-key privacy switch: with `metadata.enabled: false`
-the server never contacts the metadata service, and every player connected to it
-stops showing the section (they gate on the `metadata` capability). Enrichment is
+`metadata.enabled` is **runtime-toggleable**: an admin can switch the lookup on
+or off from the console's **Overview** section (or via
+[`PATCH /admin/settings`](api/reference.md#patch-apiv1adminsettings)) with no
+restart, and the change is **persisted back to `config.yaml`**. The YAML value
+and `AUDIOSILO_METADATA_ENABLED` only **seed** the initial state at startup; the
+admin toggle is the durable source of truth thereafter. `metadata.base_url`
+stays config-only - it defines whether the feature is *available* at all (a valid
+absolute `http(s)` URL), and the toggle can only enable the lookup when a valid
+base URL is set.
+
+Turning it off is the one-key privacy switch: with the lookup disabled the server
+never contacts the metadata service, and every player connected to it stops
+showing the section (they gate on the `metadata` capability). Enrichment is
 strictly additive and cached - a slow or unreachable service degrades to no
 section, never a broken page.
 

docs-users/admin/console-tour.md

@@ -66,7 +66,7 @@ button, the language selector, and the server's version number.
 ![The Overview section with stat cards, per-library counts and the listening feed](/img/screenshots/admin/overview.png)
 
 **Overview** is the console's home screen ("Library size and what people are
-listening to"). It has three parts:
+listening to"). It has four parts:
 
 ### Stat cards
 
@@ -100,6 +100,27 @@ The feed shows saved listening progress as of when you opened the Overview -
 reopen the section to refresh (players report progress periodically while
 playing).
 
+### Community metadata lookup
+
+A single switch that turns the **community metadata lookup** on or off for the
+whole server. When it is on, books that can be matched (they carry an ASIN or
+ISBN) gain an extra "About this book" section in the player - a description,
+production details, and the series they belong to - drawn from the free,
+community-run catalogue at
+[meta.audiosilo.app](https://meta.audiosilo.app). See
+[About this book](../listening/browsing.md#about-this-book) for what listeners
+see.
+
+- Flipping the switch takes effect immediately for **everyone connected**, and
+  the choice is remembered across restarts.
+- Turning it **off** is a one-tap privacy switch: your server stops contacting
+  the metadata service at all, and the extra section disappears from every
+  player.
+- The card also shows the **Source** - the metadata service address your server
+  uses. If no service is configured, the switch is greyed out and a note explains
+  that a service address must be set in the server configuration first (see the
+  metadata setting in the [configuration reference](/developers/server/configuration)).
+
 :::note
 The console holds no special powers of its own - every action it performs is
 checked by the server against your admin account. That's also why nothing

docs-users/listening/browsing.md

@@ -59,7 +59,7 @@ Some books show an extra section below the chapters with more about the title:
 - A **More in this series** row - other books in the same series, each opening its page on the metadata site so you can see what to read next.
 - A **View on AudioSilo Meta** link to the book's full entry.
 
-This information comes from the **AudioSilo community metadata database** at [meta.audiosilo.app](https://meta.audiosilo.app), a free, community-run catalogue of audiobook details. It appears only when the book can be matched (it carries an ASIN or ISBN) and your server has the metadata lookup switched on. If a book has no extra section, it simply isn't matched or your admin has turned the feature off - nothing else on the page changes. A server admin can disable the lookup entirely, in which case no book shows this section (see the metadata setting in the [configuration reference](/developers/server/configuration)).
+This information comes from the **AudioSilo community metadata database** at [meta.audiosilo.app](https://meta.audiosilo.app), a free, community-run catalogue of audiobook details. It appears only when the book can be matched (it carries an ASIN or ISBN) and your server has the metadata lookup switched on. If a book has no extra section, it simply isn't matched or your admin has turned the feature off - nothing else on the page changes. A server admin can switch the lookup on or off at any time from the admin console's Overview section (see the [console tour](../admin/console-tour.md#community-metadata-lookup)); when it is off, no book shows this section.
 
 ## Search