domma-cms 0.92.1 → 0.94.0

package/admin/js/templates/docs/api-plugins.html

@@ -69,67 +69,129 @@
   <div class="col-12">
     <div class="docs-body">
 
-<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/plugins</span>
-                  </h3>
-                  <p class="auth-note">Requires Bearer token + admin role.</p>
-                  <p>List all discovered plugins with their current enabled state and settings.</p>
-                  <pre class="code-block"><code>// Response 200
-[
-  {
-    "name": "form-builder",
-    "displayName": "Form Builder",
-    "version": "1.0.0",
-    "description": "Build and manage contact forms.",
-    "author": "Domma Team",
-    "date": "2024-01-01",
-    "icon": "clipboard",
-    "enabled": true,
-    "settings": {}
-  }
-]</code></pre>
-
-                  <h3><span class="method-badge method-put">PUT</span><span
-                          class="endpoint-path">/api/plugins/:name</span></h3>
-                  <p class="auth-note">Requires Bearer token + admin role.</p>
-                  <p>Enable or disable a plugin, or update its settings.</p>
-                  <table class="table table-sm">
-                      <thead>
-                      <tr>
-                          <th>Field</th>
-                          <th>Type</th>
-                          <th>Description</th>
-                      </tr>
-                      </thead>
-                      <tbody>
-                      <tr>
-                          <td><code>enabled</code></td>
-                          <td>boolean</td>
-                          <td>Whether the plugin is active</td>
-                      </tr>
-                      <tr>
-                          <td><code>settings</code></td>
-                          <td>object</td>
-                          <td>Plugin-specific settings object</td>
-                      </tr>
-                      </tbody>
-                  </table>
-                  <pre class="code-block"><code>// Response 200
-{ "success": true }
-
-// Error 404
-{ "error": "Plugin not found" }</code></pre>
-
-                  <h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/plugins/admin-config</span>
-                  </h3>
-                  <p class="auth-note">Requires Bearer token (any role).</p>
-                  <p>Return the merged admin configuration for all enabled plugins - sidebar items, SPA routes, and view
-                      entry points.</p>
-                  <pre class="code-block"><code>// Response 200
-{
-  "sidebar": [ { "id": "form-builder", "text": "Form Settings", "icon": "clipboard", "url": "#/form-settings" } ],
-  "routes": [ { "path": "/form-settings", "view": "formSettings", "title": "Form Settings - Domma CMS" } ],
-  "views": { "formSettings": { "entry": "form-builder/admin/views/settings.js", "exportName": "formSettingsView" } }
-}</code></pre>
+<p>These endpoints drive the <strong>Marketplace</strong> screen (System &gt; Plugins, <code>#/plugins</code>). They
+    need the <code>plugins</code> permission for the action named: <code>read</code>, <code>create</code> (install),
+    <code>update</code> (switch on or off, settings) or <code>develop</code> (the source editor, export and restart).
+    Installing from, and uninstalling through, the managed catalogue needs an admin (role level 0 or 1).</p>
+<p><strong>Restarts.</strong> A plugin's routes and screens are read when the server starts, so switching a plugin
+    or a built-in Tool on or off restarts the server by itself, about a second and a half after the reply, when
+    something will bring it back (the fleet manager, or pm2) and <code>restartOnPluginToggle</code> in
+    <code>config/server.json</code> is not <code>false</code>. The reply says what happened:
+    <code>restartRequired</code>, <code>supervised</code>, <code>restarting</code>. Installing, updating and
+    uninstalling do not restart; the new code runs after the next restart.</p>
+
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/plugins</span></h3>
+<p class="auth-note">Requires Bearer token + <code>plugins</code> read permission.</p>
+<p>Every installed plugin, with its state.</p>
+<pre class="code-block"><code>// Response 200
+[ { "name": "blog", "displayName": "Blog", "version": "1.9.0", "description": "...", "author": "...", "icon": "edit",
+    "core": false, "enabled": true, "closedSource": false, "licence": "...",
+    "entitlement": null,          // for a licensed plugin: valid, grace, expired, support-ended, unlicensed...
+    "supersededBy": null,         // enabled but replaced by another plugin (a Pro edition)
+    "blockedBy": null,            // enabled but not running: something it requires is off
+    "locked": false,              // the site's manager holds this switch
+    "requires": [], "uses": {},
+    "settings": {}, "settingsSchema": null, "effectiveSettings": {} } ]</code></pre>
+<p>Secret settings come back masked; sending the mask back keeps the stored value.</p>
+
+<h3><span class="method-badge method-put">PUT</span><span class="endpoint-path">/api/plugins/:name</span></h3>
+<p class="auth-note">Requires Bearer token + <code>plugins</code> update permission.</p>
+<p>Switch a plugin on or off, or save its settings. A switch goes through the same check as the screen: a switch
+    the site's manager has locked is refused with 423, and one that changes other Tools or plugins (a plugin that
+    requires this one goes off with it; switching one on brings on what it requires) answers 409 with the
+    <code>plan</code> until repeated with <code>"cascade": true</code>. A built-in plugin cannot be switched off.</p>
+<table class="table table-sm">
+    <thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead>
+    <tbody>
+    <tr><td><code>enabled</code></td><td>boolean</td><td>On or off</td></tr>
+    <tr><td><code>settings</code></td><td>object</td><td>The plugin's settings</td></tr>
+    <tr><td><code>cascade</code></td><td>boolean</td><td>Confirm the knock-on changes in a 409's plan</td></tr>
+    </tbody>
+</table>
+<pre class="code-block"><code>// Response 200 - a switch
+{ "success": true, "restartRequired": true, "supervised": true, "restarting": true }
+// Error 409 - confirm first
+{ "error": "This switch changes other Tools too.", "needsConfirm": true, "plan": { ... } }</code></pre>
+
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/tools</span></h3>
+<p class="auth-note">Requires Bearer token + <code>plugins</code> read permission.</p>
+<p>The built-in Tools that can be switched off - Contacts, Notes, Todo, Analytics and SEO - with their state and the
+    plugins that depend on each. <code>GET /api/tools/enabled</code> (any signed-in user) answers just
+    <code>{"notes": true, ...}</code>.</p>
+<pre class="code-block"><code>// Response 200
+[ { "name": "contacts", "displayName": "Contacts", "enabled": true, "locked": false,
+    "requiredBy": [ { "name": "contacts-pro", "displayName": "Contacts Pro" } ],
+    "usedBy": [ { "name": "calendar", "displayName": "Calendar", "reason": "Invite a contact group" } ] } ]</code></pre>
+
+<h3><span class="method-badge method-put">PUT</span><span class="endpoint-path">/api/tools/:name</span></h3>
+<p class="auth-note">Requires Bearer token + <code>plugins</code> update permission.</p>
+<p>Switch a built-in Tool on or off (<code>{"enabled": false}</code>). Nothing is deleted; switched back on,
+    everything is where it was. The same 423 / 409-with-plan / <code>cascade</code> rules and restart as a plugin.</p>
+
+<h3><span class="method-badge method-post">POST</span><span class="endpoint-path">/api/plugins/install-upload</span></h3>
+<p class="auth-note">Requires Bearer token + <code>plugins</code> create permission. Content-Type:
+    <code>multipart/form-data</code>.</p>
+<p>Install or update a plugin from a <code>.dcmsplugin</code> file (Install from file). The plugin is named by the
+    manifest inside, not the file name. Refusals come back as questions to confirm with form fields set to
+    <code>true</code>: <code>confirmUpgrade</code> (it is already installed - 409, <code>code: "already-installed"</code>),
+    <code>confirmDowngrade</code> and <code>confirmUnsigned</code> (a file not signed by the Marketplace; a site
+    with <code>requireSignedPlugins</code> refuses those outright). A plugin whose <code>minCmsVersion</code> is newer
+    than this site is refused, naming both versions, and an update leaves the installed version in place. A
+    licensed plugin's licence travels in the file. A new plugin arrives switched off.</p>
+<pre class="code-block"><code>// Response 200
+{ "success": true, "name": "invoices", "action": "install", "from": null, "version": "1.6.1", "restartRequired": true }
+// Error 400
+{ "error": "Invoices needs Domma CMS 0.93.0 or later; this site runs 0.92.2. Update the CMS first." }</code></pre>
+
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/plugins/marketplace</span></h3>
+<p class="auth-note">Requires Bearer token + an admin role (level 0 or 1).</p>
+<p>The Browse tab: what this site can get from its manager, with what is installed and what can be updated. A
+    site that is not managed answers <code>{"available": false, "catalogue": []}</code> and installs from a file
+    instead.</p>
+<pre class="code-block"><code>// Response 200
+{ "available": true, "site": "my-site",
+  "catalogue": [ { "slug": "invoices", "version": "1.6.1", "installed": true, "installedVersion": "1.6.0", "updatable": true, ... } ] }</code></pre>
+
+<h3><span class="method-badge method-post">POST</span><span class="endpoint-path">/api/plugins/marketplace/install</span></h3>
+<p class="auth-note">Requires Bearer token + an admin role (level 0 or 1). Managed sites only.</p>
+<p>Fetch a plugin from the manager and install it, licensed to this site; <code>"update": true</code> updates one
+    already installed. If the update fails, the installed version is put back. A refusal from the manager (no
+    licence) answers 403 with its reason; 503 when the manager cannot be reached.</p>
+<pre class="code-block"><code>// Request body
+{ "slug": "invoices", "version": "1.6.1", "update": true }
+// Response 200
+{ "success": true, "name": "invoices", "action": "upgrade", "from": "1.6.0", "version": "1.6.1", "restartRequired": true }</code></pre>
+
+<h3><span class="method-badge method-delete">DELETE</span><span class="endpoint-path">/api/plugins/marketplace/:slug</span></h3>
+<p class="auth-note">Requires Bearer token + an admin role (level 0 or 1).</p>
+<p>Uninstall a plugin. Its files and its <code>data/</code> folder are removed, roles it added are removed and their
+    users moved to <code>user</code>. Restart to finish.</p>
+<pre class="code-block"><code>// Response 200
+{ "success": true }</code></pre>
+
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/plugins/admin-config</span></h3>
+<p class="auth-note">Requires Bearer token (any role).</p>
+<p>What the admin needs from the running plugins: sidebar items, screens (routes) and the scripts behind them.</p>
+<pre class="code-block"><code>// Response 200
+{ "sidebar": [ { "id": "blog", "text": "Blog", "icon": "edit", "url": "#/plugins/blog" } ],
+  "routes": [ { "path": "/plugins/blog", "view": "plugin-blog", "title": "Blog - Domma CMS" } ],
+  "views": { "plugin-blog": { "entry": "blog/admin/views/blog.js", "exportName": "blogView" } } }</code></pre>
+
+<h3><span class="method-badge method-post">POST</span><span class="endpoint-path">/api/plugins/scaffold</span></h3>
+<p class="auth-note">Requires Bearer token + <code>plugins</code> create permission.</p>
+<p>Start a new plugin from the template (New plugin). It is created switched on and runs after the next restart.</p>
+<pre class="code-block"><code>// Request body
+{ "slug": "my-plugin", "displayName": "My Plugin", "description": "...", "author": "...", "icon": "package" }
+// Response 200
+{ "success": true, "name": "my-plugin", "files": [ ... ], "restartRequired": true }</code></pre>
+
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/plugins/:name/export</span></h3>
+<p class="auth-note">Requires Bearer token + <code>plugins</code> develop permission.</p>
+<p>Download a plugin as an unsigned <code>.dcmsplugin</code> file (<code>?includeData=1</code> adds its data).
+    Licensed plugins cannot be exported (403). The source editor uses <code>GET /api/plugins/:name/files</code> and
+    <code>GET</code>, <code>PUT</code>, <code>DELETE /api/plugins/:name/file</code>, and
+    <code>POST /api/plugins/restart</code> restarts the server to run edited code; a licensed plugin's source is open
+    only to the level-0 role.</p>
 
     </div>
   </div>

package/admin/js/templates/docs/api-scaffold.html

@@ -0,0 +1,185 @@
+<div class="view-header">
+  <h1><span data-icon="code"></span> API · Scaffold API</h1>
+  <a href="#/api-reference" class="btn btn-ghost btn-sm"><span data-icon="arrow-left"></span> API overview</a>
+</div>
+<style>
+    .method-badge {
+        display: inline-block;
+        font-size: 11px;
+        font-weight: 700;
+        letter-spacing: 0.5px;
+        padding: 2px 7px;
+        border-radius: 4px;
+        font-family: var(--dm-font-mono, monospace);
+        margin-right: 6px;
+        vertical-align: middle;
+    }
+
+    .method-get {
+        background: color-mix(in srgb, var(--dm-success) 15%, transparent);
+        color: var(--dm-success);
+    }
+
+    .method-post {
+        background: color-mix(in srgb, var(--dm-primary) 15%, transparent);
+        color: var(--dm-primary);
+    }
+
+    .method-put {
+        background: color-mix(in srgb, var(--dm-warning) 15%, transparent);
+        color: var(--dm-warning-dark);
+    }
+
+    .method-patch {
+        background: color-mix(in srgb, var(--dm-info) 15%, transparent);
+        color: var(--dm-info);
+    }
+
+    .method-delete {
+        background: color-mix(in srgb, var(--dm-danger) 15%, transparent);
+        color: var(--dm-danger);
+    }
+
+    .endpoint-path {
+        font-family: var(--dm-font-mono, monospace);
+        font-size: 14px;
+    }
+
+    .auth-note {
+        font-size: 12px;
+        color: var(--dm-text-muted, #6b7280);
+        margin: 4px 0 12px;
+    }
+
+    .auth-note code {
+        font-size: 11px;
+    }
+
+    .docs-body h3 {
+        margin-top: 24px;
+        margin-bottom: 8px;
+    }
+
+    .docs-body h3:first-child {
+        margin-top: 0;
+    }
+</style>
+
+
+<div class="row">
+  <div class="col-12">
+    <div class="docs-body">
+
+<p>The scaffolder builds a working system - collection, form, Actions and optionally a project, roles, users, menus,
+    API tokens and API Builder endpoints - from a bundled <strong>recipe</strong> in one call. In the admin it is
+    the "scaffold a working system in one click" panel in the page editor's CRUD shortcut slideover and on the
+    Building a CRUD App tutorial. Full recipe format: <code>docs/scaffolding.md</code>.</p>
+
+<h2>Endpoints</h2>
+
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/scaffold/recipes</span></h3>
+<p class="auth-note">Requires: <code>collections.create</code></p>
+<p>List the bundled recipes with just what a picker needs.</p>
+<pre class="code-block"><code class="language-json">// Response 200
+{ "recipes": [
+  { "slug": "contact-list", "name": "Contact list (CRM-lite)", "description": "...", "icon": "...",
+    "options": [
+      { "name": "collectionSlug", "label": "Collection slug", "default": "contacts", "hint": "..." },
+      { "name": "formSlug",       "label": "Form slug",       "default": "contact-quick-add" },
+      { "name": "actionPrefix",   "label": "Action slug prefix", "default": "contact" }
+    ] }
+] }</code></pre>
+
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/scaffold/recipes/:slug</span></h3>
+<p class="auth-note">Requires: <code>collections.create</code></p>
+<p>The whole recipe document, unresolved (placeholders such as <code>&#123;&#123;collectionSlug&#125;&#125;</code> still in place) -
+    the preview of what apply will create. <code>404</code> for an unknown recipe. There is no separate dry-run
+    endpoint.</p>
+
+<h3><span class="method-badge method-post">POST</span><span class="endpoint-path">/api/scaffold/apply</span></h3>
+<p class="auth-note">Requires: <code>collections.create</code></p>
+<p>Apply a recipe. <code>options</code> overrides the recipe's option defaults by name; anything omitted or blank
+    keeps its default.</p>
+<pre class="code-block"><code class="language-bash">curl -X POST https://example.com/api/scaffold/apply \
+  -H 'Authorization: Bearer &lt;access_token&gt;' \
+  -H 'Content-Type: application/json' \
+  -d '{"recipe":"contact-list","options":{"collectionSlug":"leads","formSlug":"lead-form"&#125;&#125;'</code></pre>
+<pre class="code-block"><code class="language-json">// Response 200
+{
+  "created": {
+    "collection": "leads",
+    "form": "lead-form",
+    "actions": ["contact-followup"],
+    "roles": [], "users": [], "menus": [],
+    "apiTokens": [],
+    "apiEndpoints": []
+  },
+  "skipped": [],
+  "warnings": [],
+  "snippet": "[form name=\"lead-form\" /]\n\n## Contacts\n\n[collection slug=\"leads\" ...]"
+}
+// Error 400
+{ "error": "recipe slug is required" }
+// Error 409 - something the recipe would create already exists
+{ "error": "Cannot apply recipe - conflicts: ...", "conflicts": ["Collection \"leads\" already exists"] }</code></pre>
+<p><code>snippet</code> is Markdown ready to paste into a page - usually the form embed plus a collection
+    display.</p>
+
+<h2>What apply creates</h2>
+<p>In this order, with every option value substituted into the recipe first:</p>
+<ol>
+    <li><strong>Project</strong> - when the recipe has a <code>project</code> block, the <code>namespace</code>
+        option is the project slug. Created if missing, left alone if it exists. A failure here aborts with
+        <code>400</code>.</li>
+    <li><strong>Pre-flight</strong> - the collection, form, each Action and each menu must not exist yet;
+        otherwise <code>409</code> with the full list and nothing below runs.</li>
+    <li><strong>Roles</strong> - an existing role name is skipped with a warning (its permissions are not
+        changed).</li>
+    <li><strong>Menus</strong> - written, and mapped to their <code>locations</code> slots unless a slot is already
+        taken (warning) or the menu says <code>force: true</code>.</li>
+    <li><strong>Collection</strong> - schema, API access rules and <code>rowAccess</code>.</li>
+    <li><strong>Form</strong> - its collection action points at the new collection.</li>
+    <li><strong>Users</strong> - only when the recipe supplies a password; an existing email or a missing password
+        is skipped with a warning. Users in a project recipe get <code>projects: [namespace]</code>.</li>
+    <li><strong>Actions</strong> - need MongoDB; without it each is skipped with the warning
+        <code>MongoDB not configured - action "..." skipped (Pro feature)</code>. When the form's
+        <code>settings.actionSlug</code> is <code>""</code>, it is wired to the first Action created.</li>
+    <li><strong>API tokens</strong> (<code>apiTokens: [{name, scopes?, expiresAt?}]</code>) - bound to the recipe's
+        project (else the <code>namespace</code> option, else <code>core</code>). The plaintext is returned once
+        in <code>created.apiTokens[].token</code>; a token with the same name in that project is skipped and never
+        re-issued. See <a href="#/docs/api/external">External API</a>.</li>
+    <li><strong>API endpoints</strong> (<code>apiEndpoints: [{path, collection, filter, ...}]</code>) - same project
+        rule; a definition with the same path shape is skipped. See
+        <a href="#/docs/api/builder">API Builder</a>.</li>
+</ol>
+<p>Everything a project recipe creates is tagged <code>meta.project: &lt;namespace&gt;</code>. Recipes cannot create
+    pages, blocks or views.</p>
+
+<h2>Partial results</h2>
+<p>Apply is not a transaction. Pre-flight keeps the main pieces from colliding, but after it a failing role, menu,
+    user, Action, token or endpoint becomes a warning and the rest carries on. Read <code>skipped</code> (entries
+    such as <code>role:hr</code>, <code>user:hr@example.com</code>, <code>apiToken:mobile</code>,
+    <code>apiEndpoint:/latest</code> or an Action slug) and <code>warnings</code> to see what did not land. A
+    project created in step 1 stays even when pre-flight then refuses.</p>
+
+<h2>Recipes and options</h2>
+<p>Recipes are JSON files in <code>server/services/recipes/</code> (bundled: <code>contact-list</code> and
+    <code>onboarding</code>); a new file is listed on the next request. Each <code>options[]</code> entry has a
+    <code>name</code>, <code>label</code>, <code>default</code> and <code>hint</code>. A default may refer to an
+    earlier option (<code>"default": "&#123;&#123;namespace&#125;&#125;-form"</code>).</p>
+<ul>
+    <li><code>&#123;&#123;optionName&#125;&#125;</code> is replaced throughout the recipe at apply time.</li>
+    <li>Runtime placeholders such as <code>&#123;&#123;entry.data.email&#125;&#125;</code>, <code>&#123;&#123;user.id&#125;&#125;</code> and
+        <code>&#123;&#123;now&#125;&#125;</code> are left for the Action to resolve when it runs.</li>
+    <li>Every value supplied in <code>options</code> is slugified (lower case, anything other than letters and
+        digits becomes a hyphen) - including options that are not slugs.</li>
+</ul>
+
+<h2>Permissions</h2>
+<p>All three endpoints need a signed-in user whose role holds <code>collections.create</code>. No other permission
+    is checked, although a recipe can also create roles, users, menus, API tokens and endpoints - grant
+    <code>collections.create</code> only to roles you would trust with those.</p>
+
+    </div>
+  </div>
+</div>

package/admin/js/templates/docs/api-settings.html

@@ -69,80 +69,88 @@
   <div class="col-12">
     <div class="docs-body">
 
-<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/settings</span>
-                  </h3>
-                  <p class="auth-note">Requires Bearer token + <code>settings</code> permission.</p>
-                  <p>Return the full site settings object from <code>config/site.json</code>.</p>
-                  <pre class="code-block"><code>// Response 200
-{ "siteName": "My Site", "adminTheme": "charcoal-dark", "smtp": { ... }, ... }</code></pre>
-
-                  <h3><span class="method-badge method-put">PUT</span><span class="endpoint-path">/api/settings</span>
-                  </h3>
-                  <p class="auth-note">Requires Bearer token + <code>settings</code> permission.</p>
-                  <p>Replace the site settings object. Send the full merged object - partial updates overwrite the
-                      entire config.</p>
-                  <pre class="code-block"><code>// Request body - full site settings object
-{ "siteName": "My Site", "adminTheme": "ocean-dark", ... }
-
+<p>Site settings live in <code>config/site.json</code> and are edited at System &gt; Site Settings. They need the
+    <code>settings</code> permission (read or update). The theme has its own endpoints, under Theme below.</p>
+
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/settings</span></h3>
+<p class="auth-note">Requires Bearer token + <code>settings</code> read permission.</p>
+<p>The site settings. The SMTP password is always sent back empty.</p>
+<pre class="code-block"><code>// Response 200
+{ "title": "My Site", "tagline": "...", "baseUrl": "https://example.com", "adminHome": "/",
+  "smtp": { "host": "...", "pass": "", ... }, "footer": { ... }, "seo": { ... }, ... }</code></pre>
+
+<h3><span class="method-badge method-put">PUT</span><span class="endpoint-path">/api/settings</span></h3>
+<p class="auth-note">Requires Bearer token + <code>settings</code> update permission.</p>
+<p>Save settings. Send only what changes: top-level keys are merged into the stored settings, and objects such as
+    <code>smtp</code> or <code>footer</code> are merged one level deep. An empty <code>smtp.pass</code> keeps the
+    stored password. An unknown key is refused with 400, so a typo cannot be saved silently. The public pages'
+    cache is cleared.</p>
+<table class="table table-sm">
+    <thead><tr><th>Key</th><th>What it is</th></tr></thead>
+    <tbody>
+    <tr><td><code>title</code>, <code>tagline</code>, <code>description</code>, <code>logo</code>,
+        <code>favicon</code></td><td>The site's name and identity</td></tr>
+    <tr><td><code>baseUrl</code></td><td>Site URL - an origin only (<code>https://example.com</code>, no path). Canonical
+        links, the sitemap and password reset links are built on it.</td></tr>
+    <tr><td><code>adminHome</code></td><td>The admin screen <code>#/</code> opens, e.g. <code>/plugins/blog</code>;
+        empty for the Dashboard</td></tr>
+    <tr><td><code>smtp</code></td><td>Mail server: <code>host</code>, <code>port</code>, <code>user</code>,
+        <code>pass</code>, <code>secure</code>, <code>fromAddress</code>, <code>fromName</code></td></tr>
+    <tr><td><code>seo</code>, <code>footer</code>, <code>social</code>, <code>backToTop</code>,
+        <code>cookieConsent</code>, <code>breadcrumbs</code>, <code>layoutOptions</code></td><td>The Site Settings
+        tabs of the same names</td></tr>
+    <tr><td><code>theme</code>, <code>adminTheme</code>, <code>autoTheme</code>, <code>fontFamily</code>,
+        <code>fontSize</code>, <code>adminBrand</code>, <code>locale</code>, <code>analytics</code>, <code>brand</code>,
+        <code>url</code>, <code>baseTheme</code></td><td>Also accepted; most are set from Theme or kept for older
+        sites</td></tr>
+    </tbody>
+</table>
+<pre class="code-block"><code>// Request body
+{ "tagline": "Fresh bread daily", "smtp": { "port": 465, "secure": true } }
 // Response 200
-{ "success": true }</code></pre>
+{ "success": true }
+// Error 400
+{ "error": "Unknown settings keys: siteName" }</code></pre>
 
-                  <h3><span class="method-badge method-post">POST</span><span class="endpoint-path">/api/settings/test-email</span>
-                  </h3>
-                  <p class="auth-note">Requires Bearer token + <code>settings</code> permission.</p>
-                  <p>Send a test email using the stored SMTP configuration.</p>
-                  <table class="table table-sm">
-                      <thead>
-                      <tr>
-                          <th>Field</th>
-                          <th>Type</th>
-                          <th>Description</th>
-                      </tr>
-                      </thead>
-                      <tbody>
-                      <tr>
-                          <td><code>to</code></td>
-                          <td>string</td>
-                          <td>Optional. Recipient address. Defaults to the configured From Address.</td>
-                      </tr>
-                      </tbody>
-                  </table>
-                  <pre class="code-block"><code>// Response 200
+<h3><span class="method-badge method-post">POST</span><span class="endpoint-path">/api/settings/test-email</span></h3>
+<p class="auth-note">Requires Bearer token + <code>settings</code> read permission.</p>
+<p>Send a test email with the saved SMTP settings.</p>
+<pre class="code-block"><code>// Request body (optional - defaults to the From address)
+{ "to": "alice@example.com" }
+// Response 200
 { "success": true, "message": "Test email sent to alice@example.com" }
-
 // Error 400
 { "error": "SMTP is not configured. Save your SMTP settings first." }</code></pre>
 
-                  <h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/settings/custom-css</span>
-                  </h3>
-                  <p class="auth-note">Requires Bearer token + <code>settings</code> permission.</p>
-                  <p>Return the current custom CSS from <code>content/custom.css</code>.</p>
-                  <pre class="code-block"><code>// Response 200
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/settings/db-status</span></h3>
+<p class="auth-note">Requires Bearer token + <code>settings</code> read permission.</p>
+<p>Whether any MongoDB connection is set up (<code>config/connections.json</code>).</p>
+<pre class="code-block"><code>// Response 200
+{ "configured": true, "connections": ["default"] }</code></pre>
+
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/settings/custom-css</span></h3>
+<p class="auth-note">Requires Bearer token + <code>settings</code> update permission.</p>
+<p>The site-wide custom CSS (<code>content/custom.css</code>), which is inlined into every public page.</p>
+<pre class="code-block"><code>// Response 200
 { "css": "body { font-family: sans-serif; }" }</code></pre>
 
-                  <h3><span class="method-badge method-put">PUT</span><span class="endpoint-path">/api/settings/custom-css</span>
-                  </h3>
-                  <p class="auth-note">Requires Bearer token + <code>settings</code> permission.</p>
-                  <p>Write CSS to <code>content/custom.css</code>. Maximum size is 100 KB.</p>
-                  <table class="table table-sm">
-                      <thead>
-                      <tr>
-                          <th>Field</th>
-                          <th>Type</th>
-                          <th>Description</th>
-                      </tr>
-                      </thead>
-                      <tbody>
-                      <tr>
-                          <td><code>css</code></td>
-                          <td>string</td>
-                          <td>CSS string (max 100 KB)</td>
-                      </tr>
-                      </tbody>
-                  </table>
-                  <pre class="code-block"><code>// Response 200
+<h3><span class="method-badge method-put">PUT</span><span class="endpoint-path">/api/settings/custom-css</span></h3>
+<p class="auth-note">Requires Bearer token + <code>settings</code> update permission.</p>
+<p>Replace the custom CSS (at most 100 KB). The public pages' cache is cleared.</p>
+<pre class="code-block"><code>// Request body
+{ "css": "..." }
+// Response 200
 { "success": true }</code></pre>
 
+<h3 style="margin-top:24px;font-size:15px;text-transform:uppercase;letter-spacing:.5px;opacity:.6">Theme</h3>
+
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/theme</span></h3>
+<p class="auth-note">Requires Bearer token + <code>theme</code> read permission.</p>
+<p>The site's theme settings (<code>config/theme.json</code>): the public and admin themes, day/night switching,
+    fonts and any custom themes. <code>PUT /api/theme</code> (update permission) saves them, answering 400 with the
+    problems if they do not validate. <code>GET /api/theme/catalog</code> lists the themes and colour tokens
+    available, and <code>GET /api/theme/themes/:id</code> one theme's token values.</p>
+
     </div>
   </div>
 </div>