feat: production-harden app and finalize merge-ready UX/theme baseline

- complete tokenized theme preset system and admin style guide visibility
- refine dashboard layout/scroll behavior and shared async/request UI states
- add user nav-visibility settings across API, migration, and frontend stores
- harden security headers/CSP handling and related test coverage
- enforce CI repository hygiene + frontend contract/theme/build quality gates
- update docs/env references and make migration smoke test head-aware

frontend/src/components/layout/AppHeader.vue

@@ -2,7 +2,9 @@
 import { computed } from "vue";
 
 import AppButton from "@/components/ui/AppButton.vue";
+import AppSelect from "@/components/ui/AppSelect.vue";
 import { useThemeStore } from "@/stores/theme";
+import type { ThemePresetId } from "@/theme/presets";
 
 const theme = useThemeStore();
 
@@ -10,6 +12,12 @@ const isDarkTheme = computed(() => theme.active === "dark");
 const toggleThemeLabel = computed(() =>
   isDarkTheme.value ? "Switch to light theme" : "Switch to dark theme",
 );
+const selectedPreset = computed<ThemePresetId>({
+  get: () => theme.preset,
+  set: (value) => theme.setPreset(value),
+});
+const presetOptions = computed(() => theme.availablePresets);
+const themePresetLabel = computed(() => theme.presetLabel);
 
 function onToggleTheme(): void {
   theme.setPreference(isDarkTheme.value ? "light" : "dark");
@@ -17,18 +25,32 @@ function onToggleTheme(): void {
 </script>
 
 <template>
-  <header class="sticky top-0 z-30 border-b border-zinc-200/70 bg-white/90 backdrop-blur dark:border-zinc-800 dark:bg-zinc-900/90">
+  <header class="sticky top-0 z-30 border-b border-stroke-subtle bg-surface-nav/90 backdrop-blur">
     <div class="flex min-h-[4.5rem] w-full items-center justify-between gap-4 px-4 sm:px-6 lg:px-8">
       <div class="flex min-w-0 items-center gap-2">
         <RouterLink
           to="/dashboard"
-          class="rounded-sm font-display text-lg tracking-tight text-zinc-900 transition hover:text-zinc-700 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-brand-500 focus-visible:ring-offset-2 focus-visible:ring-offset-zinc-100 dark:text-zinc-100 dark:hover:text-zinc-300 dark:focus-visible:ring-brand-400 dark:focus-visible:ring-offset-zinc-950"
+          class="rounded-sm font-display text-lg tracking-tight text-ink-primary transition hover:text-ink-secondary focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-focus-ring focus-visible:ring-offset-2 focus-visible:ring-offset-focus-offset"
         >
           scholarr
         </RouterLink>
       </div>
 
-      <div class="flex items-center justify-end">
+      <div class="flex items-center justify-end gap-2">
+        <div class="w-36 sm:w-44">
+          <label for="theme-preset-select" class="sr-only">Theme preset</label>
+          <AppSelect
+            id="theme-preset-select"
+            v-model="selectedPreset"
+            :disabled="presetOptions.length <= 1"
+            :title="`Theme preset: ${themePresetLabel}`"
+            class="py-1.5"
+          >
+            <option v-for="preset in presetOptions" :key="preset.id" :value="preset.id">
+              {{ preset.label }}
+            </option>
+          </AppSelect>
+        </div>
         <AppButton
           variant="ghost"
           class="h-10 w-10 rounded-full p-0"

frontend/src/components/layout/AppNav.vue

@@ -4,24 +4,29 @@ import { useRouter } from "vue-router";
 
 import AppButton from "@/components/ui/AppButton.vue";
 import { useAuthStore } from "@/stores/auth";
+import { useUserSettingsStore } from "@/stores/user_settings";
 
 const auth = useAuthStore();
+const userSettings = useUserSettingsStore();
 const router = useRouter();
 
 const links = computed(() => {
   const base = [
-    { to: "/dashboard", label: "Dashboard" },
-    { to: "/scholars", label: "Scholars" },
-    { to: "/publications", label: "Publications" },
-    { to: "/settings", label: "Settings" },
+    { id: "dashboard", to: "/dashboard", label: "Dashboard", adminOnly: false },
+    { id: "scholars", to: "/scholars", label: "Scholars", adminOnly: false },
+    { id: "publications", to: "/publications", label: "Publications", adminOnly: false },
+    { id: "settings", to: "/settings", label: "Settings", adminOnly: false },
+    { id: "style-guide", to: "/admin/style-guide", label: "Style Guide", adminOnly: true },
+    { id: "runs", to: "/admin/runs", label: "Runs", adminOnly: true },
+    { id: "users", to: "/admin/users", label: "Users", adminOnly: true },
   ];
 
-  if (auth.isAdmin) {
-    base.push({ to: "/admin/runs", label: "Runs" });
-    base.push({ to: "/admin/users", label: "Users" });
-  }
-
-  return base;
+  return base.filter((item) => {
+    if (item.adminOnly && !auth.isAdmin) {
+      return false;
+    }
+    return userSettings.isPageVisible(item.id);
+  });
 });
 
 async function onLogout(): Promise<void> {
@@ -32,7 +37,7 @@ async function onLogout(): Promise<void> {
 
 <template>
   <aside
-    class="min-w-0 border-b border-zinc-200 bg-white/70 px-4 py-4 dark:border-zinc-800 dark:bg-zinc-900/70 lg:h-full lg:min-h-0 lg:overflow-y-auto lg:border-b-0 lg:border-r lg:px-5 lg:py-6"
+    class="min-h-0 min-w-0 overflow-x-hidden border-b border-stroke-subtle bg-surface-nav/70 px-4 py-4 lg:h-full lg:border-b-0 lg:border-r lg:px-5 lg:py-6"
   >
     <div class="flex h-full min-h-0 flex-col gap-4">
       <nav class="grid grid-cols-2 content-start gap-2 sm:grid-cols-3 lg:grid-cols-1" aria-label="Primary">
@@ -40,15 +45,15 @@ async function onLogout(): Promise<void> {
           v-for="link in links"
           :key="link.to"
           :to="link.to"
-          class="inline-flex min-h-10 min-w-0 items-center rounded-lg border border-transparent px-3 py-2 text-sm font-medium text-zinc-600 transition hover:border-zinc-300 hover:bg-zinc-50 hover:text-zinc-900 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-brand-500 focus-visible:ring-offset-2 focus-visible:ring-offset-zinc-100 dark:text-zinc-300 dark:hover:border-zinc-700 dark:hover:bg-zinc-800 dark:hover:text-zinc-100 dark:focus-visible:ring-brand-400 dark:focus-visible:ring-offset-zinc-950"
-          active-class="border-zinc-900 bg-zinc-900 text-white hover:border-zinc-900 hover:bg-zinc-900 hover:text-white dark:border-brand-400 dark:bg-brand-400 dark:text-zinc-950 dark:hover:border-brand-300 dark:hover:bg-brand-300"
+          class="inline-flex min-h-10 min-w-0 items-center rounded-lg border border-transparent px-3 py-2 text-sm font-medium text-ink-secondary transition hover:border-stroke-interactive hover:bg-surface-card-muted hover:text-ink-primary focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-focus-ring focus-visible:ring-offset-2 focus-visible:ring-offset-focus-offset"
+          active-class="border-stroke-interactive bg-surface-nav-active font-semibold text-ink-primary shadow-sm hover:border-stroke-interactive hover:bg-surface-nav-active hover:text-ink-primary"
         >
           {{ link.label }}
         </RouterLink>
       </nav>
 
-      <div class="mt-auto grid gap-2 border-t border-zinc-200 pt-3 dark:border-zinc-800">
-        <p class="truncate text-xs text-zinc-500 dark:text-zinc-400">{{ auth.user?.email }}</p>
+      <div class="mt-auto grid gap-2 border-t border-stroke-subtle pt-3">
+        <p class="truncate text-xs text-ink-muted">{{ auth.user?.email }}</p>
         <AppButton variant="ghost" class="w-full justify-start" @click="onLogout">Logout</AppButton>
       </div>
     </div>

frontend/src/components/layout/AppPage.vue

@@ -1,16 +1,31 @@
 <script setup lang="ts">
-defineProps<{
-  title: string;
-  subtitle?: string;
-}>();
+const props = withDefaults(
+  defineProps<{
+    title: string;
+    subtitle?: string;
+    fill?: boolean;
+  }>(),
+  {
+    fill: false,
+  },
+);
 </script>
 
 <template>
-  <section class="page-stack min-w-0">
+  <section
+    :class="
+      props.fill
+        ? 'min-w-0 flex min-h-0 flex-col gap-6 lg:h-full'
+        : 'page-stack min-w-0'
+    "
+  >
     <header class="space-y-2">
-      <h1 class="page-title">{{ title }}</h1>
-      <p v-if="subtitle" class="page-subtitle">{{ subtitle }}</p>
+      <h1 class="page-title">{{ props.title }}</h1>
+      <p v-if="props.subtitle" class="page-subtitle">{{ props.subtitle }}</p>
     </header>
-    <slot />
+    <div v-if="props.fill" class="min-h-0 flex-1">
+      <slot />
+    </div>
+    <slot v-else />
   </section>
 </template>