@marlinjai/clearify 1.11.2 → 1.13.0

package/dist/node/{chunk-PFX7LHRZ.js → chunk-GWYMXKDL.js}

@@ -2,18 +2,23 @@ import {
   parseOpenAPISpec
 } from "./chunk-B2Q23JW3.js";
 import {
+  ClearifyDataSchema,
+  deepMergeJsonWins,
+  loadDataConfig,
   loadUserConfig,
   resolveConfig,
   resolveSections,
-  scanHubProjects
-} from "./chunk-PVTUVUBK.js";
+  scanHubProjects,
+  writeDataConfig
+} from "./chunk-2WML2D77.js";
 import {
   buildSectionData
-} from "./chunk-QTGT76RY.js";
+} from "./chunk-CTL4YL7C.js";
 
 // src/vite-plugin/index.ts
-import { resolve } from "path";
-import { existsSync, readFileSync } from "fs";
+import { resolve, dirname } from "path";
+import { fileURLToPath } from "url";
+import { existsSync, readFileSync, readdirSync, statSync } from "fs";
 import { dereference } from "@scalar/openapi-parser";
 var VIRTUAL_CONFIG = "virtual:clearify/config";
 var RESOLVED_VIRTUAL_CONFIG = "\0" + VIRTUAL_CONFIG;
@@ -29,6 +34,8 @@ var VIRTUAL_OPENAPI_SPEC = "virtual:clearify/openapi-spec";
 var RESOLVED_VIRTUAL_OPENAPI_SPEC = "\0" + VIRTUAL_OPENAPI_SPEC;
 var VIRTUAL_HUB = "virtual:clearify/hub";
 var RESOLVED_VIRTUAL_HUB = "\0" + VIRTUAL_HUB;
+var VIRTUAL_ADMIN_ENABLED = "virtual:clearify/admin-enabled";
+var RESOLVED_VIRTUAL_ADMIN_ENABLED = "\0" + VIRTUAL_ADMIN_ENABLED;
 function findFirstNavPath(items) {
   for (const item of items) {
     if (item.path) return item.path;
@@ -52,7 +59,8 @@ function clearifyPlugin(options = {}) {
   function getRootFiles() {
     return {
       changelogPath: resolve(userRoot, "CHANGELOG.md"),
-      roadmapPath: resolve(userRoot, "ROADMAP.md")
+      roadmapPath: resolve(userRoot, "ROADMAP.md"),
+      ...config.includeReadme ? { readmePath: resolve(userRoot, "README.md") } : {}
     };
   }
   async function refreshDocs() {
@@ -241,6 +249,7 @@ ${routeEntries.join(",\n")}
       if (id === VIRTUAL_MERMAID_SVGS) return RESOLVED_VIRTUAL_MERMAID_SVGS;
       if (id === VIRTUAL_OPENAPI_SPEC) return RESOLVED_VIRTUAL_OPENAPI_SPEC;
       if (id === VIRTUAL_HUB) return RESOLVED_VIRTUAL_HUB;
+      if (id === VIRTUAL_ADMIN_ENABLED) return RESOLVED_VIRTUAL_ADMIN_ENABLED;
       return null;
     },
     async load(id) {
@@ -266,6 +275,10 @@ ${routeEntries.join(",\n")}
         const hubData = config.hub ?? null;
         return `export default ${JSON.stringify(hubData)};`;
       }
+      if (id === RESOLVED_VIRTUAL_ADMIN_ENABLED) {
+        const enabled = resolvedViteConfig.command === "serve";
+        return `export default ${enabled};`;
+      }
       return null;
     },
     configureServer(server) {
@@ -273,7 +286,7 @@ ${routeEntries.join(",\n")}
         server.watcher.add(section.docsDir);
       }
       const rootFiles = getRootFiles();
-      for (const rootFile of [rootFiles.changelogPath, rootFiles.roadmapPath]) {
+      for (const rootFile of [rootFiles.changelogPath, rootFiles.roadmapPath, rootFiles.readmePath]) {
         if (rootFile && existsSync(rootFile)) {
           server.watcher.add(rootFile);
         }
@@ -395,8 +408,9 @@ ${routeEntries.join(",\n")}
       server.watcher.on("all", (event, path) => {
         const isChangelog = path === rootFiles.changelogPath;
         const isRoadmap = path === rootFiles.roadmapPath;
+        const isReadme = path === rootFiles.readmePath;
         const isInSection = visibleSections.some((s) => path.startsWith(s.docsDir));
-        if (!isChangelog && !isRoadmap && !isInSection) return;
+        if (!isChangelog && !isRoadmap && !isReadme && !isInSection) return;
         if (!path.endsWith(".md") && !path.endsWith(".mdx")) return;
         if (event === "add" || event === "unlink" || event === "change") {
           refreshDocs().then(() => {
@@ -410,6 +424,118 @@ ${routeEntries.join(",\n")}
           });
         }
       });
+      const dataJsonPath = resolve(userRoot, "clearify.data.json");
+      server.watcher.add(dataJsonPath);
+      server.watcher.on("change", (changedPath) => {
+        if (changedPath === dataJsonPath) {
+          for (const resolvedId of [
+            RESOLVED_VIRTUAL_CONFIG,
+            RESOLVED_VIRTUAL_ROUTES,
+            RESOLVED_VIRTUAL_NAVIGATION,
+            RESOLVED_VIRTUAL_SEARCH_INDEX
+          ]) {
+            const mod = server.moduleGraph.getModuleById(resolvedId);
+            if (mod) server.moduleGraph.invalidateModule(mod);
+          }
+          server.ws.send({ type: "full-reload" });
+        }
+      });
+      function readJsonBody(req) {
+        return new Promise((resolve2, reject) => {
+          const chunks = [];
+          req.on("data", (chunk) => chunks.push(chunk));
+          req.on("end", () => {
+            try {
+              resolve2(JSON.parse(Buffer.concat(chunks).toString()));
+            } catch {
+              reject(new Error("Invalid JSON"));
+            }
+          });
+          req.on("error", reject);
+        });
+      }
+      server.middlewares.use(async (req, res, next) => {
+        const url = req.url?.split("?") ?? [""];
+        const pathname = url[0];
+        const query = new URLSearchParams(url[1] ?? "");
+        if (!pathname.startsWith("/__clearify/api/")) return next();
+        res.setHeader("Content-Type", "application/json");
+        try {
+          if (req.method === "GET" && pathname === "/__clearify/api/config") {
+            res.end(JSON.stringify(config));
+            return;
+          }
+          if (req.method === "GET" && pathname === "/__clearify/api/config/data") {
+            const data = loadDataConfig(userRoot);
+            res.end(JSON.stringify(data));
+            return;
+          }
+          if (req.method === "PUT" && pathname === "/__clearify/api/config/data") {
+            const body = await readJsonBody(req);
+            const result = ClearifyDataSchema.safeParse(body);
+            if (!result.success) {
+              res.statusCode = 400;
+              res.end(JSON.stringify({ error: "Validation failed", issues: result.error.issues }));
+              return;
+            }
+            writeDataConfig(userRoot, body);
+            res.end(JSON.stringify({ ok: true }));
+            return;
+          }
+          if (req.method === "PATCH" && pathname === "/__clearify/api/config/data") {
+            const body = await readJsonBody(req);
+            const existing = loadDataConfig(userRoot);
+            const merged = deepMergeJsonWins(existing, body);
+            const result = ClearifyDataSchema.safeParse(merged);
+            if (!result.success) {
+              res.statusCode = 400;
+              res.end(JSON.stringify({ error: "Validation failed", issues: result.error.issues }));
+              return;
+            }
+            writeDataConfig(userRoot, merged);
+            res.end(JSON.stringify({ ok: true }));
+            return;
+          }
+          if (req.method === "GET" && pathname === "/__clearify/api/config/schema") {
+            const pkgDir = dirname(fileURLToPath(import.meta.url));
+            const schemaPath = resolve(pkgDir, "../../dist/config-schema.json");
+            if (existsSync(schemaPath)) {
+              res.end(readFileSync(schemaPath, "utf-8"));
+            } else {
+              res.statusCode = 404;
+              res.end(JSON.stringify({ error: "Schema file not found" }));
+            }
+            return;
+          }
+          if (req.method === "GET" && pathname === "/__clearify/api/fs/dirs") {
+            const rootParam = query.get("root") ?? ".";
+            const target = resolve(userRoot, rootParam);
+            if (!target.startsWith(userRoot)) {
+              res.statusCode = 403;
+              res.end(JSON.stringify({ error: "Path outside project root" }));
+              return;
+            }
+            if (!existsSync(target)) {
+              res.end(JSON.stringify({ dirs: [] }));
+              return;
+            }
+            const dirs = readdirSync(target).filter((entry) => {
+              try {
+                return statSync(resolve(target, entry)).isDirectory();
+              } catch {
+                return false;
+              }
+            });
+            res.end(JSON.stringify({ dirs }));
+            return;
+          }
+          res.statusCode = 404;
+          res.end(JSON.stringify({ error: "Not found" }));
+        } catch (err) {
+          res.statusCode = err.message === "Invalid JSON" ? 400 : 500;
+          res.end(JSON.stringify({ error: err.message ?? "Internal server error" }));
+        }
+      });
       return () => {
         server.middlewares.use((req, _res, next) => {
           if (req.method !== "GET" || !req.headers.accept?.includes("text/html")) {

package/dist/node/{chunk-NGWAMBXS.js → chunk-HZRIVY25.js}

@@ -2,10 +2,10 @@ import {
   loadUserConfig,
   resolveConfig,
   resolveSections
-} from "./chunk-PVTUVUBK.js";
+} from "./chunk-2WML2D77.js";
 import {
   scanDocs
-} from "./chunk-QTGT76RY.js";
+} from "./chunk-CTL4YL7C.js";
 
 // src/node/check.ts
 import { resolve, relative } from "path";

package/dist/node/{chunk-EMM4VLF7.js → chunk-XR4WG237.js}

@@ -8,15 +8,15 @@ import {
 } from "./chunk-SCZZB7OE.js";
 import {
   clearifyPlugin
-} from "./chunk-PFX7LHRZ.js";
+} from "./chunk-GWYMXKDL.js";
 import {
   loadUserConfig,
   resolveConfig,
   resolveSections
-} from "./chunk-PVTUVUBK.js";
+} from "./chunk-2WML2D77.js";
 import {
   buildSectionData
-} from "./chunk-QTGT76RY.js";
+} from "./chunk-CTL4YL7C.js";
 
 // src/node/build.ts
 import { build as viteBuild } from "vite";
@@ -157,7 +157,8 @@ async function buildSite() {
   const productionSections = allSections.filter((s) => !s.draft);
   const rootFiles = {
     changelogPath: resolve(userRoot, "CHANGELOG.md"),
-    roadmapPath: resolve(userRoot, "ROADMAP.md")
+    roadmapPath: resolve(userRoot, "ROADMAP.md"),
+    ...config.includeReadme ? { readmePath: resolve(userRoot, "README.md") } : {}
   };
   const sectionDataList = productionSections.map(
     (section) => buildSectionData(section, rootFiles, config.navigation)

package/dist/node/core/config.d.ts

@@ -1,10 +1,86 @@
-import { ClearifyConfig, ResolvedSection } from '../types/index.js';
+import { z } from 'zod';
+import { ClearifyConfig, ClearifyDataConfig, ResolvedSection } from '../types/index.js';
 export { defineConfig } from '../types/index.js';
 
+/** Zod schema for clearify.data.json — Tier 1+2 visual-config fields, all optional. */
+declare const ClearifyDataSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    siteUrl: z.ZodOptional<z.ZodString>;
+    theme: z.ZodOptional<z.ZodObject<{
+        primaryColor: z.ZodOptional<z.ZodString>;
+        mode: z.ZodOptional<z.ZodEnum<{
+            light: "light";
+            dark: "dark";
+            auto: "auto";
+        }>>;
+    }, z.core.$strip>>;
+    logo: z.ZodOptional<z.ZodObject<{
+        light: z.ZodOptional<z.ZodString>;
+        dark: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    links: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    sections: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        docsDir: z.ZodString;
+        basePath: z.ZodOptional<z.ZodString>;
+        draft: z.ZodOptional<z.ZodBoolean>;
+        sitemap: z.ZodOptional<z.ZodBoolean>;
+        exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        git: z.ZodOptional<z.ZodObject<{
+            repo: z.ZodString;
+            ref: z.ZodOptional<z.ZodString>;
+            path: z.ZodOptional<z.ZodString>;
+            sparse: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+    hub: z.ZodOptional<z.ZodObject<{
+        projects: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            description: z.ZodString;
+            href: z.ZodOptional<z.ZodString>;
+            repo: z.ZodOptional<z.ZodString>;
+            status: z.ZodDefault<z.ZodEnum<{
+                active: "active";
+                beta: "beta";
+                planned: "planned";
+                deprecated: "deprecated";
+            }>>;
+            icon: z.ZodOptional<z.ZodString>;
+            tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            group: z.ZodOptional<z.ZodString>;
+            mode: z.ZodOptional<z.ZodEnum<{
+                link: "link";
+                embed: "embed";
+                inject: "inject";
+            }>>;
+            git: z.ZodOptional<z.ZodObject<{
+                repo: z.ZodString;
+                ref: z.ZodOptional<z.ZodString>;
+                path: z.ZodOptional<z.ZodString>;
+                sparse: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strip>>;
+            embedSections: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodLiteral<"public">, z.ZodArray<z.ZodString>]>>;
+            injectInto: z.ZodOptional<z.ZodString>;
+            docsPath: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        scan: z.ZodOptional<z.ZodString>;
+        cacheDir: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Deep-merge utility where JSON (overlay) values win over base values.
+ * Plain objects merge recursively. Arrays are replaced entirely.
+ * Undefined values in the overlay are skipped.
+ */
+declare function deepMergeJsonWins<T extends Record<string, any>>(base: T, json: Partial<T>): T;
+/** Load and validate clearify.data.json from a project root. Returns `{}` on missing/invalid file. */
+declare function loadDataConfig(root: string): ClearifyDataConfig;
+/** Validate and atomically write clearify.data.json. */
+declare function writeDataConfig(root: string, data: unknown): void;
 declare const defaultConfig: ClearifyConfig;
 declare function loadUserConfig(root: string): Promise<Partial<ClearifyConfig>>;
 declare function resolveConfig(userConfig?: Partial<ClearifyConfig>, root?: string): ClearifyConfig;
 declare function resolveSections(config: ClearifyConfig, root: string): Promise<ResolvedSection[]>;
 declare function scanHubProjects(config: ClearifyConfig, root: string): Promise<ClearifyConfig>;
 
-export { defaultConfig, loadUserConfig, resolveConfig, resolveSections, scanHubProjects };
+export { ClearifyDataSchema, deepMergeJsonWins, defaultConfig, loadDataConfig, loadUserConfig, resolveConfig, resolveSections, scanHubProjects, writeDataConfig };

package/dist/node/core/config.js

@@ -1,19 +1,27 @@
 import {
+  ClearifyDataSchema,
+  deepMergeJsonWins,
   defaultConfig,
+  loadDataConfig,
   loadUserConfig,
   resolveConfig,
   resolveSections,
-  scanHubProjects
-} from "../chunk-PVTUVUBK.js";
+  scanHubProjects,
+  writeDataConfig
+} from "../chunk-2WML2D77.js";
 import "../chunk-AJBCHKBP.js";
 import {
   defineConfig
 } from "../chunk-V7LLYIRO.js";
 export {
+  ClearifyDataSchema,
+  deepMergeJsonWins,
   defaultConfig,
   defineConfig,
+  loadDataConfig,
   loadUserConfig,
   resolveConfig,
   resolveSections,
-  scanHubProjects
+  scanHubProjects,
+  writeDataConfig
 };

package/dist/node/core/navigation.js

@@ -3,7 +3,7 @@ import {
   buildRoutes,
   buildSectionData,
   scanDocs
-} from "../chunk-QTGT76RY.js";
+} from "../chunk-CTL4YL7C.js";
 import "../chunk-5TD7NQIW.js";
 export {
   buildNavigation,

package/dist/node/core/search.d.ts

@@ -29,6 +29,7 @@ interface SectionData {
 interface RootFileOptions {
     changelogPath?: string;
     roadmapPath?: string;
+    readmePath?: string;
 }
 declare function buildSectionData(section: ResolvedSection, rootFiles?: RootFileOptions, customNavigation?: NavigationItem[] | null): SectionData;
 

package/dist/node/node/build.js

@@ -1,14 +1,14 @@
 import {
   buildSite
-} from "../chunk-EMM4VLF7.js";
+} from "../chunk-XR4WG237.js";
 import "../chunk-PRTER35L.js";
 import "../chunk-SCZZB7OE.js";
-import "../chunk-PFX7LHRZ.js";
+import "../chunk-GWYMXKDL.js";
 import "../chunk-B2Q23JW3.js";
-import "../chunk-PVTUVUBK.js";
+import "../chunk-2WML2D77.js";
 import "../chunk-AJBCHKBP.js";
 import "../chunk-V7LLYIRO.js";
-import "../chunk-QTGT76RY.js";
+import "../chunk-CTL4YL7C.js";
 import "../chunk-5TD7NQIW.js";
 export {
   buildSite

package/dist/node/node/check.js

@@ -1,11 +1,11 @@
 import {
   checkFrontmatter,
   checkLinks
-} from "../chunk-NGWAMBXS.js";
-import "../chunk-PVTUVUBK.js";
+} from "../chunk-HZRIVY25.js";
+import "../chunk-2WML2D77.js";
 import "../chunk-AJBCHKBP.js";
 import "../chunk-V7LLYIRO.js";
-import "../chunk-QTGT76RY.js";
+import "../chunk-CTL4YL7C.js";
 import "../chunk-5TD7NQIW.js";
 export {
   checkFrontmatter,

package/dist/node/node/index.js

@@ -1,13 +1,13 @@
 import {
   buildSite
-} from "../chunk-EMM4VLF7.js";
+} from "../chunk-XR4WG237.js";
 import {
   remarkMermaidToComponent
 } from "../chunk-PRTER35L.js";
 import "../chunk-SCZZB7OE.js";
 import {
   clearifyPlugin
-} from "../chunk-PFX7LHRZ.js";
+} from "../chunk-GWYMXKDL.js";
 import "../chunk-B2Q23JW3.js";
 import {
   init
@@ -15,14 +15,14 @@ import {
 import {
   checkFrontmatter,
   checkLinks
-} from "../chunk-NGWAMBXS.js";
+} from "../chunk-HZRIVY25.js";
 import {
   loadUserConfig,
   resolveConfig
-} from "../chunk-PVTUVUBK.js";
+} from "../chunk-2WML2D77.js";
 import "../chunk-AJBCHKBP.js";
 import "../chunk-V7LLYIRO.js";
-import "../chunk-QTGT76RY.js";
+import "../chunk-CTL4YL7C.js";
 import "../chunk-5TD7NQIW.js";
 
 // src/node/index.ts

package/dist/node/types/index.d.ts

@@ -61,6 +61,7 @@ interface ClearifyConfig {
     hubProject?: Omit<HubProject, 'name'>;
     customCss?: string;
     headTags?: string[];
+    includeReadme?: boolean;
 }
 interface NavigationItem {
     label: string;
@@ -102,15 +103,36 @@ interface HubProject {
     group?: string;
     hubUrl?: string;
     hubName?: string;
-    mode?: 'link' | 'embed';
+    mode?: 'link' | 'embed' | 'inject';
     git?: RemoteGitSource;
     embedSections?: 'all' | 'public' | string[];
+    injectInto?: string;
+    docsPath?: string;
 }
 interface HubConfig {
     projects: HubProject[];
     scan?: string;
     cacheDir?: string;
 }
+/** Tier 1+2 fields that can live in clearify.data.json for visual editing. */
+interface ClearifyDataConfig {
+    name?: string;
+    siteUrl?: string;
+    theme?: {
+        primaryColor?: string;
+        mode?: 'light' | 'dark' | 'auto';
+    };
+    logo?: {
+        light?: string;
+        dark?: string;
+    };
+    links?: {
+        github?: string;
+        [key: string]: string | undefined;
+    };
+    sections?: SectionConfig[];
+    hub?: HubConfig;
+}
 declare function defineConfig(config: Partial<ClearifyConfig>): Partial<ClearifyConfig>;
 
-export { type ClearifyConfig, type DocCategory, type HubConfig, type HubProject, type NavigationItem, type PageFrontmatter, type RemoteGitSource, type ResolvedSection, type RouteEntry, type SectionConfig, type SectionNavigation, defineConfig };
+export { type ClearifyConfig, type ClearifyDataConfig, type DocCategory, type HubConfig, type HubProject, type NavigationItem, type PageFrontmatter, type RemoteGitSource, type ResolvedSection, type RouteEntry, type SectionConfig, type SectionNavigation, defineConfig };

package/dist/node/vite-plugin/index.js

@@ -1,11 +1,11 @@
 import {
   clearifyPlugin
-} from "../chunk-PFX7LHRZ.js";
+} from "../chunk-GWYMXKDL.js";
 import "../chunk-B2Q23JW3.js";
-import "../chunk-PVTUVUBK.js";
+import "../chunk-2WML2D77.js";
 import "../chunk-AJBCHKBP.js";
 import "../chunk-V7LLYIRO.js";
-import "../chunk-QTGT76RY.js";
+import "../chunk-CTL4YL7C.js";
 import "../chunk-5TD7NQIW.js";
 export {
   clearifyPlugin

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marlinjai/clearify",
-  "version": "1.11.2",
+  "version": "1.13.0",
   "description": "An open-source documentation site generator. Turn markdown into beautiful docs.",
   "type": "module",
   "bin": {
@@ -14,7 +14,8 @@
     "./config": {
       "types": "./dist/node/core/config.d.ts",
       "import": "./dist/node/core/config.js"
-    }
+    },
+    "./config-schema.json": "./dist/config-schema.json"
   },
   "files": [
     "bin",
@@ -24,6 +25,7 @@
   ],
   "scripts": {
     "build": "tsup",
+    "postbuild": "node scripts/generate-schema.mjs",
     "dev:self": "node bin/clearify.js dev",
     "prepare": "husky",
     "release": "semantic-release"

package/src/client/App.tsx

@@ -7,12 +7,20 @@ import routes from 'virtual:clearify/routes';
 import config from 'virtual:clearify/config';
 // @ts-expect-error virtual module
 import sections from 'virtual:clearify/navigation';
+// @ts-expect-error virtual module
+import adminEnabled from 'virtual:clearify/admin-enabled';
 import { Layout } from '../theme/Layout.js';
 import { Head } from '../theme/Head.js';
 import { NotFound } from '../theme/NotFound.js';
 import { mdxComponents } from '../theme/MDXComponents.js';
 import '../theme/styles/globals.css';
 
+const AdminLayout = React.lazy(() => import('../theme/admin/AdminLayout.js'));
+const AdminDashboard = React.lazy(() => import('../theme/admin/AdminDashboard.js'));
+const ProjectsManager = React.lazy(() => import('../theme/admin/ProjectsManager.js'));
+const SectionsManager = React.lazy(() => import('../theme/admin/SectionsManager.js'));
+const SiteSettings = React.lazy(() => import('../theme/admin/SiteSettings.js'));
+
 interface RouteEntry {
   path: string;
   component?: () => Promise<any>;
@@ -74,24 +82,59 @@ function PageWrapper({ loader, fallbackFrontmatter }: { loader: () => Promise<an
   );
 }
 
+function AdminDisabled() {
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'center', minHeight: '100vh', color: 'var(--clearify-text-secondary)', fontFamily: 'var(--font-sans)' }}>
+      Admin panel is only available in dev mode.
+    </div>
+  );
+}
+
 function AppRoutes() {
   return (
-    <Layout config={config} sections={sections}>
-      <Routes>
-        {(routes as RouteEntry[]).map((route) =>
-          route.redirectTo ? (
-            <Route key={route.path} path={route.path} element={<Navigate to={route.redirectTo} replace />} />
-          ) : (
-            <Route
-              key={route.path}
-              path={route.path}
-              element={<PageWrapper loader={route.component!} fallbackFrontmatter={route.frontmatter} />}
-            />
-          )
-        )}
-        <Route path="*" element={<NotFound />} />
-      </Routes>
-    </Layout>
+    <Routes>
+      {/* Admin routes — outside Layout, lazy-loaded */}
+      {adminEnabled ? (
+        <Route
+          path="/admin"
+          element={
+            <React.Suspense fallback={<div style={{ padding: '2rem', color: 'var(--clearify-text-secondary)' }}>Loading...</div>}>
+              <AdminLayout />
+            </React.Suspense>
+          }
+        >
+          <Route index element={<AdminDashboard />} />
+          <Route path="projects" element={<ProjectsManager />} />
+          <Route path="sections" element={<SectionsManager />} />
+          <Route path="settings" element={<SiteSettings />} />
+        </Route>
+      ) : (
+        <Route path="/admin/*" element={<AdminDisabled />} />
+      )}
+
+      {/* Docs routes — wrapped in Layout */}
+      <Route
+        path="*"
+        element={
+          <Layout config={config} sections={sections}>
+            <Routes>
+              {(routes as RouteEntry[]).map((route) =>
+                route.redirectTo ? (
+                  <Route key={route.path} path={route.path} element={<Navigate to={route.redirectTo} replace />} />
+                ) : (
+                  <Route
+                    key={route.path}
+                    path={route.path}
+                    element={<PageWrapper loader={route.component!} fallbackFrontmatter={route.frontmatter} />}
+                  />
+                )
+              )}
+              <Route path="*" element={<NotFound />} />
+            </Routes>
+          </Layout>
+        }
+      />
+    </Routes>
   );
 }