webui: human-readable labels + section titles/descriptors in Settings (closes #436)

__tests__/services/config-schema.test.ts

@@ -1,5 +1,9 @@
 import { describe, it, expect } from '@jest/globals';
-import { defaultConfig } from '../../src/services/config-schema.js';
+import {
+  defaultConfig,
+  settingsMetadata,
+  categoryMetadata,
+} from '../../src/services/config-schema.js';
 
 describe('Config Schema', () => {
   describe('defaultConfig', () => {
@@ -63,4 +67,52 @@ describe('Config Schema', () => {
       expect(typeof defaultConfig['ratelimit.bypass_admin']).toBe('boolean');
     });
   });
+
+  describe('settingsMetadata', () => {
+    it('has a non-empty label, description, and category for every key in defaultConfig', () => {
+      const missingLabel: string[] = [];
+      const missingDescription: string[] = [];
+      const missingCategory: string[] = [];
+      for (const key of Object.keys(defaultConfig)) {
+        const meta = settingsMetadata[key as keyof typeof settingsMetadata];
+        if (!meta) {
+          missingLabel.push(key);
+          missingDescription.push(key);
+          missingCategory.push(key);
+          continue;
+        }
+        if (!meta.label || meta.label.trim() === '') missingLabel.push(key);
+        if (!meta.description || meta.description.trim() === '')
+          missingDescription.push(key);
+        if (!meta.category || meta.category.trim() === '')
+          missingCategory.push(key);
+      }
+      expect(missingLabel).toEqual([]);
+      expect(missingDescription).toEqual([]);
+      expect(missingCategory).toEqual([]);
+    });
+
+    it('does not have stale entries for keys that no longer exist in defaultConfig', () => {
+      const orphans = Object.keys(settingsMetadata).filter(
+        (k) => !(k in defaultConfig),
+      );
+      expect(orphans).toEqual([]);
+    });
+  });
+
+  describe('categoryMetadata', () => {
+    it('covers every category referenced by settingsMetadata', () => {
+      const usedCategories = new Set(
+        Object.values(settingsMetadata).map((m) => m.category),
+      );
+      const missing: string[] = [];
+      for (const cat of usedCategories) {
+        const meta = categoryMetadata[cat];
+        if (!meta || !meta.title.trim() || !meta.description.trim()) {
+          missing.push(cat);
+        }
+      }
+      expect(missing).toEqual([]);
+    });
+  });
 });

__tests__/web/admin-views.test.ts

@@ -81,6 +81,65 @@ describe("renderBootstrapPage", () => {
 });
 
 describe("renderSettingsPage", () => {
+  it("renders the human label as primary text and the dotted key as a muted reference", () => {
+    const html = renderSettingsPage({
+      ...COMMON,
+      groups: [
+        {
+          category: "voicechannels",
+          rows: [
+            {
+              key: "voicechannels.enabled",
+              label: "Voice Channel Management enabled",
+              current: true,
+              defaultValue: false,
+              type: "boolean",
+              description: "Enable VC mgmt",
+              category: "voicechannels",
+            },
+          ],
+        },
+      ],
+    });
+    // Human label appears as bold primary text.
+    expect(html).toContain(
+      "<strong>Voice Channel Management enabled</strong>",
+    );
+    // Raw dotted key still rendered, but de-emphasised as a small code ref.
+    expect(html).toMatch(
+      /<code class="mono muted"[^>]*>voicechannels\.enabled<\/code>/,
+    );
+  });
+
+  it("renders the category title and description from categoryMetadata", () => {
+    const html = renderSettingsPage({
+      ...COMMON,
+      groups: [
+        {
+          category: "voicechannels",
+          rows: [
+            {
+              key: "voicechannels.enabled",
+              label: "Voice Channel Management enabled",
+              current: true,
+              defaultValue: false,
+              type: "boolean",
+              description: "Enable VC mgmt",
+              category: "voicechannels",
+            },
+          ],
+        },
+      ],
+    });
+    // Human title, not the slug.
+    expect(html).toContain("<h2>Voice Channels</h2>");
+    expect(html).not.toContain("<h2>voicechannels</h2>");
+    // Category description rendered as muted helper text under the title.
+    expect(html).toMatch(
+      /<p class="muted"[^>]*>Dynamic voice channel management/,
+    );
+  });
+
   it("renders one section per category and one row per setting", () => {
     const html = renderSettingsPage({
       ...COMMON,