From 6b6640e145038fe41def747f84cd67d1c509e238 Mon Sep 17 00:00:00 2001
From: Ravi Suhag <suhag.ravi@gmail.com>
Date: Wed, 2 Sep 2026 17:56:43 -0500
Subject: [PATCH 01/10] fix: keep navigation inside the section it belongs to
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A content directory is a section: its own folder, its own URL prefix, its own
navigation. Four things were leaking across those boundaries or losing them.

`filterPageTreeByContentDir` was called twice on the same tree — once by
`entry-server` before serialising, once by `DocsLayout` on what it was handed —
and the second pass had no way to tell an already narrowed tree from a wide one.
It looked for a folder whose urls all start with the prefix, which on a narrowed
tree matches the first sub-folder instead. So the docs site rendered an empty
sidebar, the basic example showed only its `guides` folder, and a versioned site
showed only its first content directory.

Telling the two apart needs three signals, because url shapes alone are
ambiguous: `root → [folder Docs (/docs/*)]` and
`root → [folder guides (/docs/guides/*)]` look identical to a prefix test. A
folder is the content directory when every url inside it belongs to the
directory, when it holds every url in the tree that belongs to the directory,
and when it has a page directly below the prefix rather than only pages nested
deeper. A page sitting at the prefix settles it earlier: that is the directory's
own page, so the tree is already its contents.

`filterPageTreeByVersion` had the same double-call problem and now recognises an
already narrowed tree too.

Previous and next were chained across the whole site, so the last page of Docs
offered the first page of Ops Guide — walking a reader out of the section they
chose. Both implementations now chain per section, sharing
`contentSectionPrefixes` and `sectionOf` so the server and the static build
cannot drift apart.

The fanfold header printed "DOCS / DOCS / GETTING STARTED": `getBreadcrumbItems`
starts at the tree root, whose name is the section's own label. Any name that
repeats the one before it is dropped, which also covers a folder whose index
page carries the folder's title. Its workaround for the scoping bug goes with
it — the filters are safe to apply twice now.
---
 .../src/cli/commands/static-generate.ts       | 42 +++++++----
 packages/chronicle/src/lib/source.ts          | 27 +++++--
 .../chronicle/src/lib/version-source.test.ts  | 63 ++++++++++++++++
 packages/chronicle/src/lib/version-source.ts  | 74 ++++++++++++++++++-
 .../chronicle/src/themes/fanfold/Page.tsx     | 37 ++++++----
 5 files changed, 207 insertions(+), 36 deletions(-)

diff --git a/packages/chronicle/src/cli/commands/static-generate.ts b/packages/chronicle/src/cli/commands/static-generate.ts
index 10760b2b..ee6e410e 100644
--- a/packages/chronicle/src/cli/commands/static-generate.ts
+++ b/packages/chronicle/src/cli/commands/static-generate.ts
@@ -22,7 +22,7 @@ import { buildLlmsTxt, type LlmsPage } from '@/lib/llms';
 import { DEFAULT_WIDTH, DEFAULT_QUALITY, isLocalImage, isSvg, splitVersion } from '@/lib/image-utils';
 import { isAnimatedImage } from '@/lib/image-animation';
 import { getAssetVersion } from '@/lib/asset-version';
-import type { VersionContext } from '@/lib/version-source';
+import { contentSectionPrefixes, sectionOf, type VersionContext } from '@/lib/version-source';
 import type { Frontmatter, PageNavLink } from '@/types';
 import { buildAuthorIndex } from '@/lib/author-index';
 import { normalizeAuthorList, resolveAuthors } from '@/lib/authors';
@@ -367,19 +367,33 @@ function flattenTreeUrls(tree: PageTreeRoot): { url: string; title: string }[] {
   return result;
 }
 
-function computeNavigation(tree: PageTreeRoot): Map<string, { prev: PageNavLink | null; next: PageNavLink | null }> {
+function computeNavigation(
+  tree: PageTreeRoot,
+  config: ChronicleConfig,
+): Map<string, { prev: PageNavLink | null; next: PageNavLink | null }> {
   const navMap = new Map<string, { prev: PageNavLink | null; next: PageNavLink | null }>();
-  const ordered = flattenTreeUrls(tree);
-
-  for (let i = 0; i < ordered.length; i++) {
-    navMap.set(ordered[i].url, {
-      prev: i > 0
-        ? { url: ordered[i - 1].url, title: ordered[i - 1].title }
-        : null,
-      next: i < ordered.length - 1
-        ? { url: ordered[i + 1].url, title: ordered[i + 1].title }
-        : null,
-    });
+
+  // Chained per section, matching the dev server. See `getNavMap` in source.ts.
+  const prefixes = contentSectionPrefixes(config);
+  const bySection = new Map<string, ReturnType<typeof flattenTreeUrls>>();
+  for (const entry of flattenTreeUrls(tree)) {
+    const key = sectionOf(entry.url, prefixes) ?? '';
+    const group = bySection.get(key);
+    if (group) group.push(entry);
+    else bySection.set(key, [entry]);
+  }
+
+  for (const ordered of bySection.values()) {
+    for (let i = 0; i < ordered.length; i++) {
+      navMap.set(ordered[i].url, {
+        prev: i > 0
+          ? { url: ordered[i - 1].url, title: ordered[i - 1].title }
+          : null,
+        next: i < ordered.length - 1
+          ? { url: ordered[i + 1].url, title: ordered[i + 1].title }
+          : null,
+      });
+    }
   }
 
   return navMap;
@@ -1064,7 +1078,7 @@ export async function generateStaticSite(options: StaticGenerateOptions): Promis
   const contentMirror = path.resolve(packageRoot, '.content');
   const folderMeta = await scanFolderMeta(contentMirror, config);
   const tree = buildPageTree(pages, config, folderMeta);
-  const navMap = computeNavigation(tree);
+  const navMap = computeNavigation(tree, config);
 
   // Generate all static assets
   console.log(chalk.gray('  Generating page data files...'));
diff --git a/packages/chronicle/src/lib/source.ts b/packages/chronicle/src/lib/source.ts
index c377bd9a..6c58d291 100644
--- a/packages/chronicle/src/lib/source.ts
+++ b/packages/chronicle/src/lib/source.ts
@@ -19,9 +19,11 @@ import {
   loadConfig,
 } from './config';
 import {
+  contentSectionPrefixes,
   filterPagesByVersion,
   filterPageTreeByVersion,
   resolveVersionFromUrl,
+  sectionOf,
   type VersionContext,
 } from './version-source';
 import type { Frontmatter, PageNav, PageNavLink } from '@/types';
@@ -303,12 +305,27 @@ async function getNavMap(): Promise<Map<string, PageNav>> {
         ? p.name
         : titleFromUrl(p.url)
   });
+
+  // Chain within a section, not across the whole site. The last page of "Docs"
+  // used to offer the first page of the next content directory as its next
+  // link, dropping the reader into a different audience's material.
+  const prefixes = contentSectionPrefixes(loadConfig());
+  const bySection = new Map<string, typeof pages>();
+  for (const page of pages) {
+    const key = sectionOf(page.url, prefixes) ?? '';
+    const group = bySection.get(key);
+    if (group) group.push(page);
+    else bySection.set(key, [page]);
+  }
+
   const navMap = new Map<string, PageNav>();
-  for (let i = 0; i < pages.length; i++) {
-    navMap.set(pages[i].url, {
-      prev: i > 0 ? toLink(pages[i - 1]) : null,
-      next: i < pages.length - 1 ? toLink(pages[i + 1]) : null
-    });
+  for (const group of bySection.values()) {
+    for (let i = 0; i < group.length; i++) {
+      navMap.set(group[i].url, {
+        prev: i > 0 ? toLink(group[i - 1]) : null,
+        next: i < group.length - 1 ? toLink(group[i + 1]) : null
+      });
+    }
   }
   cachedNavMap = navMap;
   return cachedNavMap;
diff --git a/packages/chronicle/src/lib/version-source.test.ts b/packages/chronicle/src/lib/version-source.test.ts
index 2953c104..e585f83c 100644
--- a/packages/chronicle/src/lib/version-source.test.ts
+++ b/packages/chronicle/src/lib/version-source.test.ts
@@ -126,6 +126,19 @@ describe('filterPageTreeByVersion', () => {
     )
     expect(filtered.children).toEqual([])
   })
+
+  test('leaves an already scoped tree alone', () => {
+    // `entry-server` scopes the tree before serialising it, and then a layout
+    // scopes what it is handed. The second pass used to mistake v1's first
+    // content folder for the version folder and drop the rest.
+    const scoped: Root = { name: 'root', children: v1Folder.children }
+    const filtered = filterPageTreeByVersion(
+      scoped,
+      { dir: 'v1', urlPrefix: '/v1' },
+      config,
+    )
+    expect(filtered.children).toEqual(v1Folder.children)
+  })
 })
 
 describe('filterPageTreeByContentDir', () => {
@@ -160,4 +173,54 @@ describe('filterPageTreeByContentDir', () => {
       filterPageTreeByContentDir(tree, ctx, 'dev').children,
     ).toEqual(v1Dev.children)
   })
+
+  test('unwraps the content-dir folder on a single-content-dir site', () => {
+    // The whole tree is under /docs here, so an "every url matches the prefix"
+    // test would call it already scoped and leave the wrapper in place — its
+    // label then shows as a heading above every page in the sidebar.
+    const wrapped: Root = {
+      name: 'root',
+      children: [
+        {
+          type: 'folder',
+          name: 'Docs',
+          index: page('/docs'),
+          children: [page('/docs/a'), page('/docs/b')],
+        } as Folder,
+      ],
+    }
+    const out = filterPageTreeByContentDir(wrapped, LATEST_CONTEXT, 'docs')
+    expect(out.children).toEqual([page('/docs/a'), page('/docs/b')])
+  })
+
+  test('does not mistake a sub-folder for the content dir', () => {
+    // Already scoped, and its only child is a folder. `guides` sits at
+    // /docs/guides, not /docs, so it is not the wrapper.
+    const scoped: Root = {
+      name: 'root',
+      children: [folder('guides', [page('/docs/guides/a'), page('/docs/guides/b')])],
+    }
+    const out = filterPageTreeByContentDir(scoped, LATEST_CONTEXT, 'docs')
+    expect(out.children).toEqual(scoped.children)
+  })
+
+  test('leaves an already scoped flat tree alone', () => {
+    // A single content directory with no sub-folders: after `entry-server`
+    // scopes it the children are the pages themselves, and looking for a
+    // wrapping folder again found none and emptied the navigation.
+    const scoped: Root = { name: 'root', children: latestDocs.children }
+    const out = filterPageTreeByContentDir(scoped, LATEST_CONTEXT, 'docs')
+    expect(out.children).toEqual(latestDocs.children)
+  })
+
+  test('leaves an already scoped tree with sub-folders alone', () => {
+    // Same tree, but with sub-folders: the second pass used to match the first
+    // sub-folder — every url in it is under `/docs` — and show only its pages.
+    const scoped: Root = {
+      name: 'root',
+      children: [page('/docs'), folder('guides', [page('/docs/guides/a')])],
+    }
+    const out = filterPageTreeByContentDir(scoped, LATEST_CONTEXT, 'docs')
+    expect(out.children).toEqual(scoped.children)
+  })
 })
diff --git a/packages/chronicle/src/lib/version-source.ts b/packages/chronicle/src/lib/version-source.ts
index 1de0685b..5ddf6fec 100644
--- a/packages/chronicle/src/lib/version-source.ts
+++ b/packages/chronicle/src/lib/version-source.ts
@@ -1,5 +1,6 @@
 import type { Folder, Node, Root } from 'fumadocs-core/page-tree'
 import type { ChronicleConfig } from '@/types'
+import { getLatestContentRoots, getVersionContentRoots } from './config'
 
 export interface VersionContext {
   dir: string | null
@@ -66,12 +67,30 @@ function nodeMatchesVersion(
   return urls.every((u) => !prefixes.some((pre) => isUnderPrefix(u, pre)))
 }
 
+/**
+ * True when every page already in `tree` sits under `prefix`, so the tree has
+ * been narrowed to that prefix once already.
+ *
+ * Both filters below are called twice on the same tree: `entry-server` narrows
+ * it before serialising, and then a layout or theme narrows what it is handed.
+ * Without this check the second pass mistakes the first sub-folder for the
+ * thing it is looking for and returns only that folder's pages — or, for a flat
+ * directory with no sub-folder at all, returns nothing and empties the
+ * navigation. Recognising an already-narrowed tree makes both filters safe to
+ * apply as many times as callers like.
+ */
+function isAlreadyScoped(tree: Root, prefix: string): boolean {
+  const urls = tree.children.flatMap(nodeUrls)
+  return urls.length > 0 && urls.every((u) => isUnderPrefix(u, prefix))
+}
+
 export function filterPageTreeByVersion(
   tree: Root,
   ctx: VersionContext,
   config: ChronicleConfig,
 ): Root {
   if (ctx.dir !== null) {
+    if (isAlreadyScoped(tree, ctx.urlPrefix)) return tree
     const versionFolder = tree.children.find(
       (n): n is Folder =>
         n.type === 'folder' && nodeMatchesVersion(n, ctx, config),
@@ -91,11 +110,60 @@ export function filterPageTreeByContentDir(
 ): Root {
   if (contentDir === null) return tree
   const expectedPrefix = `${ctx.urlPrefix}/${contentDir}`
+
+  // A page sitting directly at or under the prefix is one of the content
+  // directory's own pages, so the tree is its contents, not a container of it.
+  const holdsOwnPages = tree.children.some(
+    (n) => n.type === 'page' && isUnderPrefix(n.url, expectedPrefix),
+  )
+  if (holdsOwnPages) return tree
+
+  // Otherwise look for the one folder that *is* this content directory. Three
+  // things have to hold, and a sub-folder — whose urls also all start with the
+  // prefix — fails the last two:
+  //   1. every url inside it belongs to the directory,
+  //   2. it holds every url in the tree that belongs to the directory,
+  //   3. it has a page of its own directly below the prefix, rather than only
+  //      pages nested further down.
+  const depth = (url: string) => url.split('/').filter(Boolean).length
+  const prefixDepth = depth(expectedPrefix)
+  const underPrefix = tree.children
+    .flatMap(nodeUrls)
+    .filter((u) => isUnderPrefix(u, expectedPrefix))
   const match = tree.children.find((n): n is Folder => {
     if (n.type !== 'folder') return false
     const urls = nodeUrls(n)
-    return urls.length > 0 && urls.every((u) => isUnderPrefix(u, expectedPrefix))
+    if (urls.length === 0 || urls.length !== underPrefix.length) return false
+    if (!urls.every((u) => isUnderPrefix(u, expectedPrefix))) return false
+    return urls.some((u) => u === expectedPrefix || depth(u) === prefixDepth + 1)
   })
-  if (!match) return { ...tree, children: [] }
-  return { ...tree, children: match.children }
+  if (match) return { ...tree, children: match.children }
+
+  if (isAlreadyScoped(tree, expectedPrefix)) return tree
+  return { ...tree, children: [] }
+}
+
+/**
+ * Every content section's URL prefix — `/docs`, `/dev`, `/v1/docs` — longest
+ * first, so `/v1/docs` is tested before `/v1` could ever shadow it.
+ */
+export function contentSectionPrefixes(config: ChronicleConfig): string[] {
+  const prefixes = [
+    ...getLatestContentRoots(config).map((r) => r.urlPrefix),
+    ...(config.versions ?? []).flatMap((v) =>
+      getVersionContentRoots(config, v.dir).map((r) => r.urlPrefix),
+    ),
+  ]
+  return prefixes.sort((a, b) => b.length - a.length)
+}
+
+/**
+ * The section a page belongs to, or null if it sits outside every one.
+ *
+ * Previous and next links are chained inside a section rather than across the
+ * whole site: sections exist to keep separate audiences apart, so walking off
+ * the end of one into another undoes the point of having them.
+ */
+export function sectionOf(url: string, prefixes: string[]): string | null {
+  return prefixes.find((p) => isUnderPrefix(url, p)) ?? null
 }
diff --git a/packages/chronicle/src/themes/fanfold/Page.tsx b/packages/chronicle/src/themes/fanfold/Page.tsx
index 9ea0535a..5d44f8b5 100644
--- a/packages/chronicle/src/themes/fanfold/Page.tsx
+++ b/packages/chronicle/src/themes/fanfold/Page.tsx
@@ -81,20 +81,19 @@ export function Page({ page, config, tree }: ThemePageProps) {
    * The printed header reads as a report on one section, so the trail and the
    * page counter are both scoped to the content directory being read.
    *
-   * The tree may or may not already be scoped: `entry-server` unwraps it itself
-   * when a site has a single content directory. Scoping an unwrapped tree again
-   * silently returns its first sub-folder — or nothing, for a flat directory —
-   * which emptied the trail and dropped the counter. So the narrower tree is
-   * only taken when it still contains the page being rendered.
+   * The tree handed here may already be scoped — `entry-server` narrows it when
+   * a site has a single content directory — but both filters recognise that and
+   * hand such a tree back untouched.
    */
-  const sectionTree = useMemo(() => {
-    const versioned = filterPageTreeByVersion(tree, version, config);
-    const scoped = filterPageTreeByContentDir(versioned, version, contentDir);
-    const holdsThisPage = flattenTree(scoped.children).some(
-      p => p.url === pathname
-    );
-    return holdsThisPage ? scoped : versioned;
-  }, [tree, version, config, contentDir, pathname]);
+  const sectionTree = useMemo(
+    () =>
+      filterPageTreeByContentDir(
+        filterPageTreeByVersion(tree, version, config),
+        version,
+        contentDir
+      ),
+    [tree, version, config, contentDir]
+  );
 
   const shorts = useMemo(
     () => collectShortNames(sectionTree.children),
@@ -119,7 +118,17 @@ export function Page({ page, config, tree }: ThemePageProps) {
   }, [sectionTree, pathname]);
   const title = page.frontmatter.title ?? '';
 
-  const trail = [section, ...crumbs].filter(Boolean).join(' / ');
+  /**
+   * The trail leads with the section, then the crumbs. `getBreadcrumbItems`
+   * starts at the tree root, and that root's name is the section's own label,
+   * so the two met and the header read "DOCS / DOCS / GETTING STARTED".
+   * Dropping any name that repeats the one before it also covers a folder whose
+   * index page carries the folder's title.
+   */
+  const trail = [section, ...crumbs]
+    .filter(Boolean)
+    .filter((name, i, all) => i === 0 || name !== all[i - 1])
+    .join(' / ');
 
   /**
    * The lines under the trail. A page that states its own identifiers — the

From aed1e2748a48884c000426e27bf393aad96cf908 Mon Sep 17 00:00:00 2001
From: Ravi Suhag <suhag.ravi@gmail.com>
Date: Wed, 2 Sep 2026 17:56:52 -0500
Subject: [PATCH 02/10] fix: give every page one title
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`RootHead` rendered the site title and every route then rendered its own, so two
`<title>` tags reached the document. A browser reads the first one, and
`RootHead` renders before the page — so every tab in the site said "Chronicle"
no matter which page was open.

Dropped the one in `RootHead`, which keeps the site-level JSON-LD and nothing
else. Every real route already renders `<Head>`; the two that did not were the
404 and the render-error page, which showed whatever title the previous page had
left behind. Both name themselves now.
---
 packages/chronicle/src/pages/NotFound.tsx    |  7 +++++++
 packages/chronicle/src/pages/RenderError.tsx |  5 +++++
 packages/chronicle/src/server/App.tsx        | 21 +++++++++++---------
 3 files changed, 24 insertions(+), 9 deletions(-)

diff --git a/packages/chronicle/src/pages/NotFound.tsx b/packages/chronicle/src/pages/NotFound.tsx
index 7ae60c2a..e9dfe6e8 100644
--- a/packages/chronicle/src/pages/NotFound.tsx
+++ b/packages/chronicle/src/pages/NotFound.tsx
@@ -1,10 +1,17 @@
 import { FileTextIcon } from '@/components/ui/icons';
 import { EmptyState } from '@raystack/apsara';
+import { Head } from '@/lib/head';
+import { usePageContext } from '@/lib/page-context';
 import styles from './NotFound.module.css';
 
 export function NotFound() {
+  const { config } = usePageContext();
+
   return (
     <div className={styles.emptyStateHost}>
+      {/* The page that was asked for renders no `<Head>` of its own, so
+          without this the tab would carry whatever the last page set. */}
+      <Head title='Page not found' config={config} />
       <EmptyState
         icon={<FileTextIcon width={32} height={32} />}
         heading="404"
diff --git a/packages/chronicle/src/pages/RenderError.tsx b/packages/chronicle/src/pages/RenderError.tsx
index e797e18b..bd9fa813 100644
--- a/packages/chronicle/src/pages/RenderError.tsx
+++ b/packages/chronicle/src/pages/RenderError.tsx
@@ -1,10 +1,15 @@
 import { WarningIcon } from '@/components/ui/icons';
 import { EmptyState } from '@raystack/apsara';
+import { Head } from '@/lib/head';
+import { usePageContext } from '@/lib/page-context';
 import styles from './NotFound.module.css';
 
 export function RenderError({ message }: { message: string | null }) {
+  const { config } = usePageContext();
+
   return (
     <div className={styles.emptyStateHost}>
+      <Head title='Failed to render page' config={config} />
       <EmptyState
         icon={<WarningIcon width={32} height={32} />}
         heading="Failed to render page"
diff --git a/packages/chronicle/src/server/App.tsx b/packages/chronicle/src/server/App.tsx
index 667dd892..5cd92ce0 100644
--- a/packages/chronicle/src/server/App.tsx
+++ b/packages/chronicle/src/server/App.tsx
@@ -80,6 +80,12 @@ function PageFallback() {
   );
 }
 
+/**
+ * Site-wide head tags. The page title is deliberately not among them: every
+ * route renders its own `<Head>`, and a title here would be hoisted into the
+ * document ahead of that one. The browser reads the first `<title>` it finds,
+ * so the tab said "Chronicle" on every page instead of naming the page.
+ */
 function RootHead({ config }: { config: ChronicleConfig }) {
   const siteJsonLd = config.url
     ? {
@@ -91,15 +97,12 @@ function RootHead({ config }: { config: ChronicleConfig }) {
       }
     : null;
 
+  if (!siteJsonLd) return null;
+
   return (
-    <>
-      <title>{config.site.title}</title>
-      {siteJsonLd && (
-        <script
-          type='application/ld+json'
-          dangerouslySetInnerHTML={{ __html: JSON.stringify(siteJsonLd, null, 2) }}
-        />
-      )}
-    </>
+    <script
+      type='application/ld+json'
+      dangerouslySetInnerHTML={{ __html: JSON.stringify(siteJsonLd, null, 2) }}
+    />
   );
 }

From 78559a41d7ee51252deac896b860c81ccf2e1687 Mon Sep 17 00:00:00 2001
From: Ravi Suhag <suhag.ravi@gmail.com>
Date: Wed, 2 Sep 2026 17:57:02 -0500
Subject: [PATCH 03/10] fix: build sites that declare versions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`chronicle build` failed on any site with a `versions:` key, so no versioned
site could ship. Dev mode was fine, which is why it went unnoticed — the error
only appears when the production bundle is assembled.

`remarkResolveImages` located a page's content root by looking for `/content/`
in its path and returned when it found none. Versioned pages live under
`versions/v1/docs/`, so every one of them took that path and returned before
setting `file.data.images`. The mdx config names `images` in `valueToExport`, so
the build then died with a missing-export error on the first versioned page it
reached.

It now recognises `versions/` as well. The path below the marker is also the
path under `/_content/` — `content/docs/` mirrors as `docs/` and
`versions/v1/docs/` as `v1/docs/` — so versioned pages get working image
resolution rather than only a build that finishes.

`images` is also initialised before any early return. A page that resolves to
neither root still exports an empty list, so a path shape nobody anticipated
cannot break a build again.
---
 .../src/lib/remark-resolve-images.test.ts     | 45 +++++++++++++++++++
 .../src/lib/remark-resolve-images.ts          | 35 +++++++++++++--
 2 files changed, 76 insertions(+), 4 deletions(-)

diff --git a/packages/chronicle/src/lib/remark-resolve-images.test.ts b/packages/chronicle/src/lib/remark-resolve-images.test.ts
index c4d9d1a7..ebd975e8 100644
--- a/packages/chronicle/src/lib/remark-resolve-images.test.ts
+++ b/packages/chronicle/src/lib/remark-resolve-images.test.ts
@@ -141,3 +141,48 @@ describe('remark-resolve-images version stamping', () => {
     expect(firstImageUrl(tree)).toBe(`/_content/docs/img.png?v=${PNG_HASH}`);
   });
 });
+
+describe('versioned pages', () => {
+  function setupVersionsDir(): string {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'chronicle-remark-v-'));
+    const versionsDir = path.join(root, 'versions');
+    fs.mkdirSync(path.join(versionsDir, 'v1', 'docs'), { recursive: true });
+    fs.writeFileSync(path.join(versionsDir, 'v1', 'docs', 'img.png'), PNG_BYTES);
+    return versionsDir;
+  }
+
+  test('exports images for a page under versions/', async () => {
+    // `valueToExport` names `images`, so a page that never sets it fails the
+    // production build with a missing-export error. Every versioned page used
+    // to take that path, which meant no versioned site could be built.
+    const versionsDir = setupVersionsDir();
+    const { file } = await transform(
+      'no images here',
+      undefined,
+      versionsDir,
+      path.join(versionsDir, 'v1', 'docs', 'page.mdx')
+    );
+    expect(file.data.images).toEqual([]);
+  });
+
+  test('resolves a relative image under versions/ against the mirror path', async () => {
+    const versionsDir = setupVersionsDir();
+    const { tree } = await transform(
+      '![alt](./img.png)',
+      { optimize: false },
+      versionsDir,
+      path.join(versionsDir, 'v1', 'docs', 'page.mdx')
+    );
+    expect(firstImageUrl(tree)).toBe(`/_content/v1/docs/img.png?v=${PNG_HASH}`);
+  });
+
+  test('exports an empty list when the path is outside any content root', async () => {
+    const { file } = await transform(
+      'stray file',
+      undefined,
+      '/tmp',
+      '/tmp/elsewhere/page.mdx'
+    );
+    expect(file.data.images).toEqual([]);
+  });
+});
diff --git a/packages/chronicle/src/lib/remark-resolve-images.ts b/packages/chronicle/src/lib/remark-resolve-images.ts
index 836de3e7..39d9bbed 100644
--- a/packages/chronicle/src/lib/remark-resolve-images.ts
+++ b/packages/chronicle/src/lib/remark-resolve-images.ts
@@ -57,18 +57,45 @@ function finalizeUrl(url: string, optimize: boolean, version?: string): string {
 
 const IMG_SRC_PATTERN = /(<img\b[^>]*\bsrc=["'])([^"']+)(["'])/gi
 
+/**
+ * Where a page's own tree starts on disk, and where it sits inside it.
+ *
+ * The current version lives under `content/`, and older versions under
+ * `versions/`. Both are mirrored into `.content/` — `content/docs/` as `docs/`
+ * and `versions/v1/docs/` as `v1/docs/` — so the path below the split is also
+ * the path under `/_content/`, which is what image URLs are built from.
+ *
+ * `versions/` used to be unrecognised, so every versioned page returned before
+ * exporting `images` and the production build failed on the first one it hit.
+ */
+function splitContentRoot(
+  filePath: string,
+): { root: string; relative: string } | null {
+  for (const marker of ['/versions/', '/content/']) {
+    const idx = filePath.lastIndexOf(marker)
+    if (idx === -1) continue
+    const end = idx + marker.length
+    return { root: filePath.slice(0, end), relative: filePath.slice(end) }
+  }
+  return null
+}
+
 const remarkResolveImages: Plugin<[RemarkResolveImagesOptions?]> = (options) => {
   const optimize = options?.optimize ?? true
   return async (tree, file) => {
+    // Always export something. `valueToExport` names `images`, so a page that
+    // returns before setting it fails the build with a missing-export error
+    // rather than simply having no images.
+    file.data.images = []
+
     const filePath = file.path?.replace(/\\/g, '/')
     if (!filePath) return
 
-    const contentIdx = filePath.lastIndexOf('/content/')
-    if (contentIdx === -1) return
+    const split = splitContentRoot(filePath)
+    if (!split) return
 
-    const relative = filePath.slice(contentIdx + '/content/'.length)
+    const { root: contentRoot, relative } = split
     const dir = path.posix.dirname(relative)
-    const contentRoot = filePath.slice(0, contentIdx + '/content/'.length)
 
     const seen = new Set<string>()
     const images: string[] = []

From 0817b64dd3797783ef10133d87ed10a4d82653fd Mon Sep 17 00:00:00 2001
From: Ravi Suhag <suhag.ravi@gmail.com>
Date: Wed, 2 Sep 2026 17:57:15 -0500
Subject: [PATCH 04/10] feat: honour theme.colors
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`theme.colors` has been in the config schema, documented as "custom color
overrides", and read by nothing. A site could set it, pass validation, and see
no change.

The alternative was deleting the key, but the schema is `.strict()` — a config
that sets it would go from silently ignored to failing at startup. Better to
make the promise true.

Keys name an Apsara colour token and take the `--rs-color-` prefix
automatically; a key written as a full custom property is used as-is, which is
how a theme's own variables like `--paper-ink` are reached. The declarations go
into the head after the stylesheets so they win, and under `:root` plus both
`[data-theme]` selectors, because Apsara defines its dark values behind that
attribute and a bare `:root` would lose to them once a reader picks a theme.

One value covers both themes, since the config holds one value per token. A
token that needs to differ is better left to the theme.

Values are checked against a colour-shaped pattern before they reach the
stylesheet. This string comes from a config file and is written into CSS, so
anything that could close a declaration or open a rule has to be impossible
rather than unlikely.
---
 .../chronicle/src/lib/theme-colors.test.ts    | 65 +++++++++++++++++++
 packages/chronicle/src/lib/theme-colors.ts    | 54 +++++++++++++++
 .../chronicle/src/server/entry-server.tsx     |  8 +++
 3 files changed, 127 insertions(+)
 create mode 100644 packages/chronicle/src/lib/theme-colors.test.ts
 create mode 100644 packages/chronicle/src/lib/theme-colors.ts

diff --git a/packages/chronicle/src/lib/theme-colors.test.ts b/packages/chronicle/src/lib/theme-colors.test.ts
new file mode 100644
index 00000000..5a8d1e88
--- /dev/null
+++ b/packages/chronicle/src/lib/theme-colors.test.ts
@@ -0,0 +1,65 @@
+import { describe, expect, test } from 'bun:test'
+import { buildThemeColorCss } from './theme-colors'
+
+describe('buildThemeColorCss', () => {
+  test('returns nothing when no colours are set', () => {
+    expect(buildThemeColorCss(undefined)).toBe('')
+    expect(buildThemeColorCss({})).toBe('')
+  })
+
+  test('prefixes a bare token name', () => {
+    const css = buildThemeColorCss({ 'background-base-primary': '#ffffff' })
+    expect(css).toContain('--rs-color-background-base-primary: #ffffff;')
+  })
+
+  test('leaves a full custom property alone', () => {
+    const css = buildThemeColorCss({ '--paper-ink': '#101010' })
+    expect(css).toContain('--paper-ink: #101010;')
+    expect(css).not.toContain('--rs-color---paper-ink')
+  })
+
+  test('wins in both themes', () => {
+    // Apsara defines its dark values behind `[data-theme]`, which outranks a
+    // bare `:root` — so an override listed only there would never apply.
+    const css = buildThemeColorCss({ 'foreground-base-primary': 'red' })
+    expect(css).toContain(":root[data-theme='dark']")
+    expect(css).toContain(":root[data-theme='light']")
+  })
+
+  test('accepts colour functions and variable references', () => {
+    const css = buildThemeColorCss({
+      a: 'rgb(10, 20, 30)',
+      b: 'color-mix(in srgb, #fff 50%, #000)',
+      c: 'var(--rs-color-background-base-primary)',
+    })
+    expect(css).toContain('rgb(10, 20, 30)')
+    expect(css).toContain('color-mix(in srgb, #fff 50%, #000)')
+    expect(css).toContain('var(--rs-color-background-base-primary)')
+  })
+
+  test('drops anything that could break out of the declaration', () => {
+    const css = buildThemeColorCss({
+      good: '#fff',
+      'bad-value': 'red; } body { display: none',
+      'bad;key': '#000',
+      'url-value': 'url(https://evil.example/x.png)',
+      'at-rule': '@import "evil.css"',
+    })
+    expect(css).toContain('--rs-color-good: #fff;')
+    expect(css).not.toContain('display: none')
+    expect(css).not.toContain('bad;key')
+    expect(css).not.toContain('evil.example')
+    expect(css).not.toContain('@import')
+  })
+
+  test('drops empty and non-string values', () => {
+    const css = buildThemeColorCss({
+      good: '#fff',
+      empty: '',
+      nope: undefined as unknown as string,
+    })
+    expect(css).toContain('--rs-color-good')
+    expect(css).not.toContain('--rs-color-empty')
+    expect(css).not.toContain('--rs-color-nope')
+  })
+})
diff --git a/packages/chronicle/src/lib/theme-colors.ts b/packages/chronicle/src/lib/theme-colors.ts
new file mode 100644
index 00000000..f440a351
--- /dev/null
+++ b/packages/chronicle/src/lib/theme-colors.ts
@@ -0,0 +1,54 @@
+/**
+ * Turns `theme.colors` from `chronicle.yaml` into a stylesheet.
+ *
+ * Keys name an Apsara colour token. Write the token on its own —
+ * `background-base-primary` — and the `--rs-color-` prefix is added, or write
+ * the whole custom property yourself if you need one outside that family.
+ *
+ * The same value applies in light and dark, because the config takes one value
+ * per token. A site that needs two different colours should leave the token
+ * alone and let the theme pick.
+ */
+
+/** A token name, or a full custom property. Nothing else can reach the CSS. */
+const KEY_PATTERN = /^(--)?[a-z][a-z0-9-]*$/
+
+/**
+ * Colours only: hex, `rgb()`, `hsl()`, `color-mix()`, a named colour, or
+ * another custom property. Deliberately narrow — this string is written into a
+ * stylesheet, so anything that could close a declaration or open a rule has to
+ * be impossible.
+ */
+const VALUE_PATTERN = /^[a-zA-Z0-9#(),.%\s/_-]+$/
+
+function toCustomProperty(key: string): string {
+  return key.startsWith('--') ? key : `--rs-color-${key}`
+}
+
+/**
+ * The declarations for a config's colours, or an empty string when there are
+ * none to write. Entries that do not look like a token and a colour are
+ * dropped rather than passed through.
+ */
+export function buildThemeColorCss(
+  colors: Record<string, string> | undefined,
+): string {
+  if (!colors) return ''
+
+  const declarations = Object.entries(colors)
+    .filter(
+      ([key, value]) =>
+        KEY_PATTERN.test(key) &&
+        typeof value === 'string' &&
+        value.length > 0 &&
+        VALUE_PATTERN.test(value),
+    )
+    .map(([key, value]) => `${toCustomProperty(key)}: ${value.trim()};`)
+
+  if (declarations.length === 0) return ''
+
+  // Both `data-theme` selectors are listed so an override still wins once a
+  // reader picks a theme explicitly — Apsara defines its dark values behind
+  // that attribute, which outranks a bare `:root`.
+  return `:root,\n:root[data-theme='light'],\n:root[data-theme='dark'] {\n  ${declarations.join('\n  ')}\n}`
+}
diff --git a/packages/chronicle/src/server/entry-server.tsx b/packages/chronicle/src/server/entry-server.tsx
index 0d4b7662..b6fada3d 100644
--- a/packages/chronicle/src/server/entry-server.tsx
+++ b/packages/chronicle/src/server/entry-server.tsx
@@ -14,6 +14,7 @@ import { getPage, getPageTree, isDraft, getPageNav, loadPageModule, extractFront
 import { getFirstApiUrl } from '@/lib/api-routes';
 import { StatusCodes } from 'http-status-codes';
 import { resolvePageAndSlug, resolveDocsRedirect, compactTree } from '@/lib/tree-utils';
+import { buildThemeColorCss } from '@/lib/theme-colors';
 import { filterPageTreeByVersion, filterPageTreeByContentDir } from '@/lib/version-source';
 import { getActiveContentDir } from '@/lib/navigation';
 import { getLatestContentRoots, getVersionContentRoots } from '@/lib/config';
@@ -173,6 +174,8 @@ export default {
       ? clientAssets.merge(serverAssets, ...routeAssets)
       : clientAssets.merge(...routeAssets);
 
+    const themeColorCss = buildThemeColorCss(config.theme?.colors);
+
     const renderStart = performance.now();
     // prerender (vs renderToReadableStream) waits for all Suspense content;
     // the huge progressiveChunkSize stops React from "outlining" large completed
@@ -191,6 +194,11 @@ export default {
           {assets.js.map((attr: { href: string }) => (
             <link key={attr.href} rel="modulepreload" {...attr} />
           ))}
+          {/* After the stylesheets, so a site's own colours win over the
+              theme's defaults. */}
+          {themeColorCss && (
+            <style dangerouslySetInnerHTML={{ __html: themeColorCss }} />
+          )}
           {[...new Set(pageImages)].map((src: string) => {
             const { base, version } = splitVersion(src);
             const href = isLocalImage(base) && !isSvg(base)

From 5c657a89a91b50f0f23b3ca695cabc4d9df5bbc6 Mon Sep 17 00:00:00 2001
From: Ravi Suhag <suhag.ravi@gmail.com>
Date: Wed, 2 Sep 2026 17:57:36 -0500
Subject: [PATCH 05/10] feat: give every theme a logo, and put a folder's index
 in the sidebar
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Four things in the sidebars, all of them about what a reader could not see.

A site that set no `logo` got a book icon in the default theme and nothing at
all in paper or fanfold. The Raystack mark is the fallback now, in all three,
drawn from the brand file in `raystack/website` with `currentColor` so it works
on either ground. `SidebarLogo` moves to `components/ui/logo.tsx` and resolves
`logo.light` / `logo.dark` for every theme, so a site that sets one gets it
everywhere rather than only where a theme happened to look.

In fanfold the mark sits above the site name rather than beside it. The rail is
a fixed 240px and the display face is wide, so sharing a line started breaking
titles mid-word.

A folder's index page never appeared in the sidebar. `SidebarNode` and
`ChapterNav` render a folder's children and its group label is a collapse
trigger rather than a link, so the page existed with no route into it. Both
render it as the group's first row now — which is what fanfold's `Nav` already
did.

Top-level groups were never collapsible, because `collapsible={depth >= 1}` was
written when the content-root wrapper made every real group a level deeper.
Every group can be collapsed now, with top-level ones open on arrival and nested
ones open only when they hold the page being read.

Two spacing corrections fall out of the above. `.navGroup[data-depth='0']` set a
top margin on every top-level group including the first, which doubled the
padding `.sidebarMain` already applies — 48px above the first label. Apsara
guards its own nav-group margin with `:not(:first-child)`; that guard is
restored and the rest of the rule is dropped, since Apsara's spacing was
winning on source order anyway. The content-directory links then needed a margin
of their own: they are a separate block above the tree, and the tree may start
with a plain page carrying no margin, so the two ran together.
---
 packages/chronicle/src/components/ui/logo.tsx | 75 +++++++++++++++++++
 .../src/themes/default/Layout.module.css      | 13 +++-
 .../chronicle/src/themes/default/Layout.tsx   | 23 ++++--
 .../src/themes/default/SidebarLogo.tsx        | 26 -------
 .../src/themes/fanfold/Layout.module.css      | 12 +++
 .../chronicle/src/themes/fanfold/Layout.tsx   |  2 +
 .../chronicle/src/themes/paper/ChapterNav.tsx |  8 ++
 .../src/themes/paper/Layout.module.css        |  9 +++
 .../chronicle/src/themes/paper/Layout.tsx     | 52 +++++++------
 9 files changed, 166 insertions(+), 54 deletions(-)
 create mode 100644 packages/chronicle/src/components/ui/logo.tsx
 delete mode 100644 packages/chronicle/src/themes/default/SidebarLogo.tsx

diff --git a/packages/chronicle/src/components/ui/logo.tsx b/packages/chronicle/src/components/ui/logo.tsx
new file mode 100644
index 00000000..483ffaec
--- /dev/null
+++ b/packages/chronicle/src/components/ui/logo.tsx
@@ -0,0 +1,75 @@
+'use client';
+
+import { useTheme } from '@raystack/apsara';
+import type { ChronicleConfig } from '@/types';
+
+/**
+ * The Raystack mark, from `raystack/website` (`public/brand/logo.svg`).
+ *
+ * Drawn with `currentColor` rather than the brand navy so it reads on a dark
+ * page as well as a light one, and so a theme can tint it by setting a text
+ * colour on the element around it. The single path is the shape as the brand
+ * file draws it, with its flat radial gradient replaced by that fill.
+ */
+export function RaystackMark({
+  width = 28,
+  height = 28,
+  className,
+}: {
+  width?: number;
+  height?: number;
+  className?: string;
+}) {
+  return (
+    <svg
+      xmlns='http://www.w3.org/2000/svg'
+      viewBox='0 0 103.923048 116.287187'
+      width={width}
+      height={height}
+      className={className}
+      role='img'
+      aria-label='Raystack'
+      fill='currentColor'
+    >
+      <path d='M1.0995468,30.0536799 L101.718938,88.1466179 C100.73439,89.5383643 99.4491496,90.7266003 97.9230485,91.6076952 L57.9615242,114.679492 C54.2487113,116.823085 49.6743371,116.823085 45.9615242,114.679492 L6,91.6076952 C2.28718708,89.4641016 0,85.5025774 0,81.2153903 L0,35.0717968 C0,33.3095155 0.386462402,31.6022611 1.0995468,30.0536799 Z M18.757,17.313 L103.923,66.483 L103.923048,81.2153903 C103.923048,81.7371223 103.889176,82.2540313 103.822983,82.7634277 L4.70864397,25.540743 C5.11691976,25.2284994 5.54789032,24.9405176 6,24.6794919 L18.757,17.313 Z M35.253,7.789 L103.923,47.435 L103.923,59.885 L24.471,14.014 L35.253,7.789 Z M57.9615242,1.60769515 L97.9230485,24.6794919 C101.635861,26.8230855 103.923048,30.7846097 103.923048,35.0717968 L103.923,40.838 L40.967,4.49 L45.9615242,1.60769515 C49.6743371,-0.535898385 54.2487113,-0.535898385 57.9615242,1.60769515 Z' />
+    </svg>
+  );
+}
+
+interface LogoProps {
+  config: ChronicleConfig;
+  /** Box the logo is drawn in, in px. Square. */
+  size?: number;
+  className?: string;
+}
+
+/**
+ * A site's logo: whichever of `logo.light` / `logo.dark` suits the active
+ * theme, falling back to the Raystack mark when a site declares neither.
+ *
+ * Shared by every theme so the fallback is the same picture everywhere, and so
+ * a site that sets one logo gets it in all three.
+ */
+export function Logo({ config, size = 28, className }: LogoProps) {
+  const { resolvedTheme } = useTheme();
+  const logo = config.logo;
+
+  const src =
+    resolvedTheme === 'dark'
+      ? (logo?.dark ?? logo?.light)
+      : (logo?.light ?? logo?.dark);
+
+  if (src) {
+    return (
+      <img
+        src={src}
+        alt={config.site.title}
+        width={size}
+        height={size}
+        className={className}
+      />
+    );
+  }
+
+  return <RaystackMark width={size} height={size} className={className} />;
+}
diff --git a/packages/chronicle/src/themes/default/Layout.module.css b/packages/chronicle/src/themes/default/Layout.module.css
index e150cb59..03f691ed 100644
--- a/packages/chronicle/src/themes/default/Layout.module.css
+++ b/packages/chronicle/src/themes/default/Layout.module.css
@@ -82,6 +82,11 @@
   display: flex;
   flex-direction: column;
   gap: 0;
+  /* These are the site's sections; the tree below belongs to the one you are
+     in. Without this they run together, because the tree may start with a plain
+     page rather than a group carrying its own top margin. Matches the spacing
+     Apsara puts between groups. */
+  margin-bottom: var(--rs-space-4);
 }
 
 .topLinkItem {
@@ -203,8 +208,12 @@
   margin-top: 0;
 }
 
-.navGroup[data-depth='0'] {
-  margin-top: var(--rs-space-7);
+/* Apsara spaces consecutive nav groups itself and skips the first one, which is
+   the behaviour we want. The only thing to add is the case it cannot see: a
+   first group that follows the content-directory links, which are a separate
+   block above the tree rather than a group. `.topLinks` carries that margin. */
+.navGroup[data-depth='0']:first-child {
+  margin-top: 0;
 }
 
 .navGroup :global([data-slot='sidebar-group-header']) {
diff --git a/packages/chronicle/src/themes/default/Layout.tsx b/packages/chronicle/src/themes/default/Layout.tsx
index 87348f6a..7b75d546 100644
--- a/packages/chronicle/src/themes/default/Layout.tsx
+++ b/packages/chronicle/src/themes/default/Layout.tsx
@@ -10,6 +10,7 @@ import { useApiOperation } from '@/lib/use-api-operation';
 const PlaygroundDialog = lazy(() => import('@/components/api/playground-dialog').then(m => ({ default: m.PlaygroundDialog })));
 import { ClientThemeSwitcher } from '@/components/ui/client-theme-switcher';
 import { Search } from '@/components/ui/search';
+import { Logo } from '@/components/ui/logo';
 import { SidebarLinks } from '@/components/ui/sidebar-links';
 import { Breadcrumbs } from '@/components/ui/breadcrumbs';
 import { getLandingEntries } from '@/lib/config';
@@ -21,7 +22,6 @@ import { NodeType } from '@/lib/tree-utils';
 import type { ThemeLayoutProps } from '@/types';
 import styles from './Layout.module.css';
 import { OpenInAI } from './OpenInAI';
-import { SidebarLogo } from './SidebarLogo';
 
 import { VersionSwitcher } from './VersionSwitcher';
 
@@ -111,7 +111,7 @@ export function Layout({
   return (
     <Flex direction='column' className={cx(styles.layout, classNames?.layout)}>
       <div className={styles.mobileHeader}>
-        <SidebarLogo config={config} />
+        <Logo config={config} className={styles.sidebarLogo} />
         <Flex align='center' gap={3}>
           {config.search?.enabled && <Search />}
           <ClientThemeSwitcher size={16} />
@@ -190,7 +190,7 @@ export function Layout({
             className={cx(styles.sidebar, classNames?.sidebar)}
           >
             <Sidebar.Header className={styles.sidebarHeader}>
-              <SidebarLogo config={config} />
+              <Logo config={config} className={styles.sidebarLogo} />
               <Flex gap={3} align='center'>
                 {config.search?.enabled && <Search />}
                 <ClientThemeSwitcher size={16} />
@@ -350,9 +350,22 @@ function SidebarNode({
         data-depth={depth}
         label={item.name?.toString() ?? ''}
         leadingIcon={icon ?? undefined}
-        collapsible={depth >= 1}
-        defaultOpen={hasActiveChild}
+        // Every group can be collapsed. Top-level ones start open so the whole
+        // site is visible on arrival; nested ones open only when they hold the
+        // page being read.
+        collapsible
+        defaultOpen={depth === 0 || hasActiveChild}
       >
+        {/* A folder's own index page. The group label is a collapse trigger,
+            not a link, so without this row the index page has no way into it
+            from the sidebar at all. */}
+        {item.index ? (
+          <SidebarNode
+            item={item.index}
+            pathname={pathname}
+            depth={depth + 1}
+          />
+        ) : null}
         {item.children.map((child, i) => (
           <SidebarNode
             key={child.type === 'page' ? child.url : (child.name?.toString() ?? i)}
diff --git a/packages/chronicle/src/themes/default/SidebarLogo.tsx b/packages/chronicle/src/themes/default/SidebarLogo.tsx
deleted file mode 100644
index e31c3721..00000000
--- a/packages/chronicle/src/themes/default/SidebarLogo.tsx
+++ /dev/null
@@ -1,26 +0,0 @@
-'use client';
-
-import { BookOpenIcon } from '@/components/ui/icons';
-import { useTheme } from '@raystack/apsara';
-import type { ChronicleConfig } from '@/types';
-import styles from './Layout.module.css';
-
-interface SidebarLogoProps {
-  config: ChronicleConfig;
-}
-
-export function SidebarLogo({ config }: SidebarLogoProps) {
-  const { resolvedTheme } = useTheme();
-  const logo = config.logo;
-
-  if (logo) {
-    const src = resolvedTheme === 'dark'
-      ? logo.dark ?? logo.light
-      : logo.light ?? logo.dark;
-    if (src) {
-      return <img src={src} alt={config.site.title} className={styles.sidebarLogo} />;
-    }
-  }
-
-  return <BookOpenIcon width={28} height={28} />;
-}
diff --git a/packages/chronicle/src/themes/fanfold/Layout.module.css b/packages/chronicle/src/themes/fanfold/Layout.module.css
index 384c377e..78889a0b 100644
--- a/packages/chronicle/src/themes/fanfold/Layout.module.css
+++ b/packages/chronicle/src/themes/fanfold/Layout.module.css
@@ -254,6 +254,15 @@
   text-decoration: none;
 }
 
+/* The mark sits above the name, letterhead fashion, rather than beside it. The
+   rail is a fixed 240px and the display face is wide: put the mark on the
+   name's line and a title of any length starts breaking mid-word. */
+.brandLogo {
+  display: block;
+  margin-bottom: 10px;
+  color: var(--fan-ink);
+}
+
 .brandName {
   font-family: var(--fan-display);
   font-weight: 800;
@@ -262,6 +271,9 @@
   letter-spacing: 0.06em;
   text-transform: uppercase;
   color: var(--fan-ink);
+  /* The rail is a fixed 240px, so a title with one long word has to break
+     rather than run off the edge. */
+  overflow-wrap: break-word;
 }
 
 .brandVersion {
diff --git a/packages/chronicle/src/themes/fanfold/Layout.tsx b/packages/chronicle/src/themes/fanfold/Layout.tsx
index efe3e1d9..f4e21829 100644
--- a/packages/chronicle/src/themes/fanfold/Layout.tsx
+++ b/packages/chronicle/src/themes/fanfold/Layout.tsx
@@ -5,6 +5,7 @@ import { useTheme } from '@raystack/apsara';
 import { cx } from 'class-variance-authority';
 import { useEffect, useState } from 'react';
 import { Link as RouterLink, useLocation } from 'react-router';
+import { Logo } from '@/components/ui/logo';
 import { useSearch } from '@/components/ui/search';
 import { SidebarLinks } from '@/components/ui/sidebar-links';
 import {
@@ -82,6 +83,7 @@ function Brand() {
 
   return (
     <RouterLink to={version.urlPrefix || '/'} className={styles.brand}>
+      <Logo config={config} size={20} className={styles.brandLogo} />
       <span className={styles.brandName}>{config.site.title}</span>
       {label ? <span className={styles.brandVersion}>~/{label}</span> : null}
     </RouterLink>
diff --git a/packages/chronicle/src/themes/paper/ChapterNav.tsx b/packages/chronicle/src/themes/paper/ChapterNav.tsx
index 11a36b65..562cba5a 100644
--- a/packages/chronicle/src/themes/paper/ChapterNav.tsx
+++ b/packages/chronicle/src/themes/paper/ChapterNav.tsx
@@ -31,6 +31,11 @@ export function ChapterNav({ tree }: ChapterNavProps) {
                   {item.name}
                 </span>
                 <ul className={styles.chapterItems}>
+                  {/* The chapter label is plain text, so a folder's index page
+                      needs a row of its own or it is unreachable here. */}
+                  {item.index ? (
+                    <ChapterItem item={item.index} pathname={pathname} />
+                  ) : null}
                   {item.children.map(child => (
                     <ChapterItem
                       key={child.type === 'page' ? child.url : (child.name?.toString() ?? '')}
@@ -70,6 +75,9 @@ function ChapterItem({
       <li className={styles.subFolder}>
         <span className={styles.subLabel}>{item.name}</span>
         <ul className={styles.chapterItems}>
+          {item.index ? (
+            <ChapterItem item={item.index} pathname={pathname} />
+          ) : null}
           {item.children.map(child => (
             <ChapterItem
               key={child.type === 'page' ? child.url : (child.name?.toString() ?? '')}
diff --git a/packages/chronicle/src/themes/paper/Layout.module.css b/packages/chronicle/src/themes/paper/Layout.module.css
index e6fdf96b..8aa2d343 100644
--- a/packages/chronicle/src/themes/paper/Layout.module.css
+++ b/packages/chronicle/src/themes/paper/Layout.module.css
@@ -32,11 +32,19 @@
 .header {
   display: flex;
   align-items: center;
+  gap: var(--rs-space-3);
   height: 48px;
   padding: 0 var(--rs-space-5);
   flex-shrink: 0;
 }
 
+/* The mark keeps its own width so the drawing is never squeezed, and never
+   gives ground to a long site title. */
+.logo {
+  flex-shrink: 0;
+  color: var(--rs-color-foreground-accent-primary);
+}
+
 .contentDirTrigger {
   border: none;
   outline: none;
@@ -107,6 +115,7 @@
 .mobileHeaderTitle {
   display: flex;
   align-items: center;
+  gap: var(--rs-space-3);
   min-width: 0;
   overflow: hidden;
 }
diff --git a/packages/chronicle/src/themes/paper/Layout.tsx b/packages/chronicle/src/themes/paper/Layout.tsx
index b04e2af5..4a4204dc 100644
--- a/packages/chronicle/src/themes/paper/Layout.tsx
+++ b/packages/chronicle/src/themes/paper/Layout.tsx
@@ -6,6 +6,7 @@ import { cx } from 'class-variance-authority';
 import { useEffect, useState } from 'react';
 import { useLocation, useNavigate } from 'react-router';
 import { ClientThemeSwitcher } from '@/components/ui/client-theme-switcher';
+import { Logo } from '@/components/ui/logo';
 import { SidebarLinks } from '@/components/ui/sidebar-links';
 import { getLandingEntries } from '@/lib/config';
 import { getActiveContentDir } from '@/lib/navigation';
@@ -25,9 +26,12 @@ function SidebarHeader({ config }: { config: ThemeLayoutProps['config'] }) {
 
   if (entries.length <= 1) {
     return (
-      <Text size="regular" weight="medium" className={styles.title}>
-        {config.site.title}
-      </Text>
+      <>
+        <Logo config={config} size={20} className={styles.logo} />
+        <Text size="regular" weight="medium" className={styles.title}>
+          {config.site.title}
+        </Text>
+      </>
     );
   }
 
@@ -36,24 +40,30 @@ function SidebarHeader({ config }: { config: ThemeLayoutProps['config'] }) {
     entries.find(e => e.contentDir === activeDir) ?? entries[0];
 
   return (
-    <Select
-      value={activeEntry.contentDir}
-      onValueChange={(val: string) => {
-        const entry = entries.find(e => e.contentDir === val);
-        if (entry) navigate(entry.href);
-      }}
-    >
-      <Select.Trigger size='small' className={styles.contentDirTrigger}>
-        <Select.Value placeholder={activeEntry.label} className={styles.title} />
-      </Select.Trigger>
-      <Select.Content>
-        {entries.map(entry => (
-          <Select.Item key={entry.href} value={entry.contentDir}>
-            {entry.label}
-          </Select.Item>
-        ))}
-      </Select.Content>
-    </Select>
+    <>
+      <Logo config={config} size={20} className={styles.logo} />
+      <Select
+        value={activeEntry.contentDir}
+        onValueChange={(val: string) => {
+          const entry = entries.find(e => e.contentDir === val);
+          if (entry) navigate(entry.href);
+        }}
+      >
+        <Select.Trigger size='small' className={styles.contentDirTrigger}>
+          <Select.Value
+            placeholder={activeEntry.label}
+            className={styles.title}
+          />
+        </Select.Trigger>
+        <Select.Content>
+          {entries.map(entry => (
+            <Select.Item key={entry.href} value={entry.contentDir}>
+              {entry.label}
+            </Select.Item>
+          ))}
+        </Select.Content>
+      </Select>
+    </>
   );
 }
 

From c38a3bd1b46d9f0c8194212dbe5799e60df018f7 Mon Sep 17 00:00:00 2001
From: Ravi Suhag <suhag.ravi@gmail.com>
Date: Wed, 2 Sep 2026 17:58:05 -0500
Subject: [PATCH 06/10] docs: rebuild the documentation around reader tasks
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The docs were organised around the framework's own parts. Nine pages, each named
after a thing — Configuration, Frontmatter, Components, Themes — so a reader who
arrived with a job had to guess which noun held the answer. Twenty-four pages in
six groups now, named after the jobs: start here, writing docs, guides, themes,
reference, deploy and operate.

`features.mdx` is gone. It was doing three jobs at once: a marketing bullet
list, a feature index, and the only documentation in the whole site for five
topics. Sorting and `meta.json` went to Navigation, redirects to Links and
redirects, markdown URLs and `llms.txt` to Generated routes, the playground to
API reference, health checks to Monitoring. What was left became an
Introduction.

Versioning, API references and deployment each had a config key and a bullet and
no guide, despite being three of the strongest reasons to pick Chronicle.
Deployment was the sharpest case: the last step of the job was three words in a
config reference. They have guides now, along with search, multiple content
sections, and moving an existing docs site over.

`configuration.mdx` was 468 lines, nearly a third of the site, and was where
people were forced to learn versioning and API specs because there was nowhere
else. It is a reference again, with a link to the guide for each large key. The
frontmatter page leads with a table, and its `draft` section is no longer pasted
into the middle of `authors`, which had split that field's prose in half.

Writing the guides meant reading the source, which turned up four things the
docs had wrong. Only three deploy presets were listed where the code has eight,
four of them static. Search was called "powered by Fumadocs" on one page and
"SQLite FTS5" on another; it is SQLite full-text search on a server build and a
downloaded index in the browser on a static one, which decides how large a
static site can sensibly get. A static build is a single-page app rather than
pre-rendered HTML, so a host has to rewrite unknown paths to `index.html` —
undocumented, and the usual reason a deep link 404s. And it optimises images at
build time, which the old page denied.

Seven permanent redirects cover every URL that moved, so no existing link
breaks. `url` is set, which the sitemap, canonical tags and social cards all
needed and none of them had.

Content elsewhere gets the same treatment as the pages: every file opened with
an `# H1` repeating its own frontmatter title, so both examples and the `init`
scaffold showed the same words twice. Removed, and the rule is written down under
`title` in the frontmatter reference. The one exception is the basic example's
heading-levels demo, which now starts at `##` and says why.
---
 docs/chronicle.yaml                           |  26 +++
 docs/content/docs/deploy/build.mdx            | 107 ++++++++++
 docs/content/docs/{ => deploy}/docker.mdx     |   6 +-
 docs/content/docs/deploy/hosting.mdx          | 186 ++++++++++++++++++
 docs/content/docs/deploy/meta.json            |   1 +
 docs/content/docs/deploy/monitoring.mdx       | 119 +++++++++++
 docs/content/docs/features.mdx                | 146 --------------
 docs/content/docs/guides/api-reference.mdx    | 143 ++++++++++++++
 docs/content/docs/guides/meta.json            |   1 +
 docs/content/docs/guides/migrate.mdx          | 133 +++++++++++++
 docs/content/docs/guides/search.mdx           |  76 +++++++
 docs/content/docs/guides/sections.mdx         | 125 ++++++++++++
 docs/content/docs/guides/versioning.mdx       | 178 +++++++++++++++++
 docs/content/docs/index.mdx                   | 118 +++++------
 docs/content/docs/quick-start.mdx             |  91 +++++++++
 docs/content/docs/{ => reference}/cli.mdx     |  19 +-
 .../config.mdx}                               |  85 +++++---
 .../docs/{ => reference}/frontmatter.mdx      |  91 ++++-----
 docs/content/docs/reference/meta.json         |   1 +
 docs/content/docs/reference/routes.mdx        | 122 ++++++++++++
 docs/content/docs/structure.mdx               | 117 +++++++++++
 docs/content/docs/themes/index.mdx            |  79 ++++++++
 docs/content/docs/themes/meta.json            |   1 +
 .../docs/{themes.mdx => themes/options.mdx}   |  46 +++--
 docs/content/docs/writing/authors.mdx         |  85 ++++++++
 .../content/docs/{ => writing}/components.mdx |   6 +-
 .../images.mdx}                               |  38 +++-
 docs/content/docs/writing/links.mdx           |  98 +++++++++
 docs/content/docs/writing/meta.json           |   1 +
 docs/content/docs/writing/navigation.mdx      | 139 +++++++++++++
 docs/content/docs/writing/pages.mdx           | 119 +++++++++++
 examples/basic/content/docs/api/endpoints.mdx |   2 -
 examples/basic/content/docs/api/overview.mdx  |   2 -
 examples/basic/content/docs/components.mdx    |   2 -
 examples/basic/content/docs/features.mdx      |   2 -
 .../basic/content/docs/getting-started.mdx    |   2 -
 .../content/docs/guides/configuration.mdx     |   2 -
 .../basic/content/docs/guides/deployment.mdx  |   2 -
 .../content/docs/guides/installation.mdx      |   2 -
 examples/basic/content/docs/index.mdx         |   3 +-
 examples/basic/content/docs/tips-&-tricks.mdx |   2 -
 examples/versioned/content/dev/api.mdx        |   2 -
 examples/versioned/content/dev/index.mdx      |   2 -
 examples/versioned/content/docs/guide.mdx     |   2 -
 examples/versioned/content/docs/index.mdx     |   2 -
 examples/versioned/versions/v1/dev/index.mdx  |   2 -
 examples/versioned/versions/v1/docs/index.mdx |   2 -
 examples/versioned/versions/v2/docs/guide.mdx |   2 -
 examples/versioned/versions/v2/docs/index.mdx |   2 -
 packages/chronicle/src/cli/commands/init.ts   |   4 +-
 50 files changed, 2177 insertions(+), 367 deletions(-)
 create mode 100644 docs/content/docs/deploy/build.mdx
 rename docs/content/docs/{ => deploy}/docker.mdx (94%)
 create mode 100644 docs/content/docs/deploy/hosting.mdx
 create mode 100644 docs/content/docs/deploy/meta.json
 create mode 100644 docs/content/docs/deploy/monitoring.mdx
 delete mode 100644 docs/content/docs/features.mdx
 create mode 100644 docs/content/docs/guides/api-reference.mdx
 create mode 100644 docs/content/docs/guides/meta.json
 create mode 100644 docs/content/docs/guides/migrate.mdx
 create mode 100644 docs/content/docs/guides/search.mdx
 create mode 100644 docs/content/docs/guides/sections.mdx
 create mode 100644 docs/content/docs/guides/versioning.mdx
 create mode 100644 docs/content/docs/quick-start.mdx
 rename docs/content/docs/{ => reference}/cli.mdx (82%)
 rename docs/content/docs/{configuration.mdx => reference/config.mdx} (83%)
 rename docs/content/docs/{ => reference}/frontmatter.mdx (74%)
 create mode 100644 docs/content/docs/reference/meta.json
 create mode 100644 docs/content/docs/reference/routes.mdx
 create mode 100644 docs/content/docs/structure.mdx
 create mode 100644 docs/content/docs/themes/index.mdx
 create mode 100644 docs/content/docs/themes/meta.json
 rename docs/content/docs/{themes.mdx => themes/options.mdx} (68%)
 create mode 100644 docs/content/docs/writing/authors.mdx
 rename docs/content/docs/{ => writing}/components.mdx (99%)
 rename docs/content/docs/{image-optimization.mdx => writing/images.mdx} (71%)
 create mode 100644 docs/content/docs/writing/links.mdx
 create mode 100644 docs/content/docs/writing/meta.json
 create mode 100644 docs/content/docs/writing/navigation.mdx
 create mode 100644 docs/content/docs/writing/pages.mdx

diff --git a/docs/chronicle.yaml b/docs/chronicle.yaml
index 305a6594..8199c714 100644
--- a/docs/chronicle.yaml
+++ b/docs/chronicle.yaml
@@ -2,6 +2,8 @@ site:
   title: Chronicle
   description: Config-driven documentation framework
 
+url: https://chronicle.raystack.org
+
 content:
   - dir: docs
     label: Docs
@@ -18,6 +20,30 @@ search:
   enabled: true
   placeholder: Search docs...
 
+# The docs were reorganised into groups. These keep every old link working.
+redirects:
+  - from: /docs/features
+    to: /docs
+    permanent: true
+  - from: /docs/cli
+    to: /docs/reference/cli
+    permanent: true
+  - from: /docs/configuration
+    to: /docs/reference/config
+    permanent: true
+  - from: /docs/frontmatter
+    to: /docs/reference/frontmatter
+    permanent: true
+  - from: /docs/components
+    to: /docs/writing/components
+    permanent: true
+  - from: /docs/image-optimization
+    to: /docs/writing/images
+    permanent: true
+  - from: /docs/docker
+    to: /docs/deploy/docker
+    permanent: true
+
 telemetry:
   enabled: true
 
diff --git a/docs/content/docs/deploy/build.mdx b/docs/content/docs/deploy/build.mdx
new file mode 100644
index 00000000..55a9151a
--- /dev/null
+++ b/docs/content/docs/deploy/build.mdx
@@ -0,0 +1,107 @@
+---
+title: Build and serve
+description: What a production build produces, and how presets change it.
+order: 1
+---
+
+```bash
+chronicle build
+chronicle start
+```
+
+`build` writes the production site. `start` serves what `build` produced — it
+does not build for you, so the order matters. `chronicle serve` runs both, which
+is handy locally and wrong in a deployment, where you want the build to happen
+once and the server to start many times.
+
+## Two kinds of output
+
+The `preset` decides which you get, and it is the only decision that really
+matters here.
+
+**A server build** produces a small server. Pages are rendered per request,
+which is what makes search, image resizing and the API request tester work.
+This is the default.
+
+**A static build** produces a single-page app: one `index.html`, a JavaScript
+bundle, and a small JSON file per page that the app fetches as the reader
+navigates. There is no process to run and nothing to keep alive.
+
+```yaml
+preset: static
+```
+
+Or per build:
+
+```bash
+chronicle build --preset static
+```
+
+## What you give up going static
+
+There is no server, so the parts that needed one change:
+
+| | Server build | Static build |
+|---|---|---|
+| Page HTML | Rendered per request, works with JavaScript off | One shell; pages filled in by JavaScript |
+| Search | Queried per request | Whole index downloaded, searched in the browser |
+| Images | Resized on demand, then cached | Resized once, during the build |
+| API request tester | Proxies through your server | Not available |
+| Health and readiness | `/api/health`, `/api/ready` | Not available |
+| Redirects | Served by Chronicle | Your host has to do them |
+
+Everything else is generated either way: navigation, versions, the API
+reference, markdown URLs, `llms.txt`, the sitemap and social cards.
+
+The first row matters most. A server build sends finished HTML, so a crawler or
+a reader with JavaScript off gets the page. A static build sends a shell, so
+they get very little. If search ranking matters to you, that is the argument for
+a server build.
+
+Pick static for a small or medium site you want on a CDN with nothing to
+operate. Pick a server build for a large site, when search needs to stay fast,
+or when the request tester matters.
+
+## Where the output goes
+
+| Preset | Output directory |
+|---|---|
+| unset, `node-server`, `cloudflare` | `.output/` |
+| `static`, `cloudflare-pages`, `github-pages` | `.output/public/` |
+| `vercel`, `vercel-static` | `.vercel/output/` |
+
+A static host has to send unknown paths to `index.html`, because every page
+shares that one file. Getting this wrong is the usual reason a deep link 404s
+while the home page works — see [Deploy](/docs/deploy/hosting).
+
+Gitignore whichever applies. `chronicle init` adds `.output` for you.
+
+## Build failures
+
+The build stops on a page it cannot parse, and names the file and the line. This
+is deliberate — a docs site that silently drops a broken page is worse than one
+that refuses to build.
+
+The usual cause is MDX being stricter than markdown about `<` and `{`, which it
+reads as the start of a component or an expression. Wrap the character in
+backticks.
+
+## In CI
+
+```bash
+bun install
+bun run chronicle build --preset static
+```
+
+Then publish the output directory. The build needs no network access beyond
+installing packages, and no services.
+
+If your build machine is not the machine that serves the site, remember `start`
+needs the `.output/` directory that `build` wrote — copy it, or build on the
+host.
+
+## Next
+
+- [Deploy](/docs/deploy/hosting) — putting the output on a host
+- [Docker](/docs/deploy/docker) — running from the container image
+- [Monitoring](/docs/deploy/monitoring) — health checks and metrics
diff --git a/docs/content/docs/docker.mdx b/docs/content/docs/deploy/docker.mdx
similarity index 94%
rename from docs/content/docs/docker.mdx
rename to docs/content/docs/deploy/docker.mdx
index 75eaf10a..edb3cdec 100644
--- a/docs/content/docs/docker.mdx
+++ b/docs/content/docs/deploy/docker.mdx
@@ -1,11 +1,9 @@
 ---
 title: Docker
-description: Run Chronicle with Docker.
-order: 8
+description: Run Chronicle from the official container image.
+order: 3
 ---
 
-# Docker
-
 Chronicle is available as a Docker image on [Docker Hub](https://hub.docker.com/r/raystack/chronicle).
 
 ## Pull the Image
diff --git a/docs/content/docs/deploy/hosting.mdx b/docs/content/docs/deploy/hosting.mdx
new file mode 100644
index 00000000..a35cdde7
--- /dev/null
+++ b/docs/content/docs/deploy/hosting.mdx
@@ -0,0 +1,186 @@
+---
+title: Deploy
+description: Put a built site on Vercel, Cloudflare, a Node host, or any static host.
+order: 2
+---
+
+Pick the preset that matches your host, build, and publish the output. The
+preset is the only Chronicle-specific part — everything after it is your host's
+normal workflow.
+
+Set it in the config so every build agrees:
+
+```yaml
+preset: vercel
+```
+
+Or pass it per build, which is what you want if the same repository deploys to
+more than one place:
+
+```bash
+chronicle build --preset static
+```
+
+## Vercel
+
+```yaml
+preset: vercel
+```
+
+```bash
+chronicle build
+```
+
+The build writes `.vercel/output`, which is the directory Vercel deploys
+directly. Set the build command to `chronicle build` and leave the output
+directory at its default.
+
+For a site that does not need per-request search or the API request tester, use
+`vercel-static` instead. Same output location, built as a single-page app.
+
+## Cloudflare
+
+For Workers:
+
+```yaml
+preset: cloudflare
+```
+
+The build writes `.output/`. Deploy it with Wrangler.
+
+For Pages, use the static preset built for it:
+
+```yaml
+preset: cloudflare-pages
+```
+
+That writes `.output/public/`. Point your Pages project at that directory.
+
+## A Node host
+
+Any host that runs a Node process — a VM, a container platform, a PaaS.
+
+```yaml
+preset: node-server
+```
+
+```bash
+chronicle build
+chronicle start --port 3000 --host 0.0.0.0
+```
+
+`--host 0.0.0.0` matters. The default binds to localhost, which works on your
+machine and refuses connections from outside a container.
+
+Point the platform's health check at `/api/health`, and its readiness check at
+`/api/ready` if it has a separate one. See
+[Monitoring](/docs/deploy/monitoring).
+
+There is a container image if you would rather not build your own — see
+[Docker](/docs/deploy/docker).
+
+## GitHub Pages
+
+```yaml
+preset: github-pages
+```
+
+The build writes `.output/public/`. A workflow that builds and publishes it:
+
+```yaml
+name: docs
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install
+      - run: bun run chronicle build --preset github-pages
+      # GitHub Pages cannot rewrite unknown paths, but it does serve 404.html
+      # for them — so a copy of the app shell makes deep links work.
+      - run: cp .output/public/index.html .output/public/404.html
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: .output/public
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: github-pages
+    steps:
+      - uses: actions/deploy-pages@v4
+```
+
+## Any other static host
+
+```yaml
+preset: static
+```
+
+`chronicle build` writes `.output/public/`. Upload it to S3, Netlify, a CDN, or
+an nginx document root. There is nothing to run.
+
+### Send unknown paths to index.html
+
+This one step catches most people. A static build is a single-page app, so every
+page is served by the same `index.html`. Without a rewrite rule the home page
+works and `/docs/quick-start` returns a 404.
+
+On nginx:
+
+```nginx
+location / {
+  try_files $uri $uri/ /index.html;
+}
+```
+
+On Netlify, a `_redirects` file in the published directory:
+
+```
+/*  /index.html  200
+```
+
+Most CDNs call this a "SPA fallback" or "rewrite to index". Whatever the name,
+it is the same rule.
+
+## Set `url` before you ship
+
+```yaml
+url: https://docs.example.com
+```
+
+Without it there are no absolute URLs for the sitemap, no canonical link tags,
+and no social cards — a social network needs an absolute address to fetch a card
+image from. It is the single easiest thing to forget and the one most visible
+once the site is public.
+
+## Redirects survive the move
+
+If your docs used to live somewhere else, or you moved pages during the
+migration, `redirects` in the config are served by Chronicle itself. They work
+the same on every server preset.
+
+Static presets have no server to run them, so on a static host use the host's
+own redirect mechanism — the same place you configured the rewrite above. See
+[Links and redirects](/docs/writing/links).
+
+## A checklist
+
+Before you call it done:
+
+- `url` is set
+- `/sitemap.xml` and `/robots.txt` return something sensible
+- Search finds a page you know exists
+- A shared link shows a social card
+- Old URLs still resolve, if any moved
+- Health check points at `/api/health`, on a server build
+- A deep link like `/docs/quick-start` loads directly, on a static build
diff --git a/docs/content/docs/deploy/meta.json b/docs/content/docs/deploy/meta.json
new file mode 100644
index 00000000..d1fda0e2
--- /dev/null
+++ b/docs/content/docs/deploy/meta.json
@@ -0,0 +1 @@
+{ "title": "Deploy and operate", "order": 8 }
diff --git a/docs/content/docs/deploy/monitoring.mdx b/docs/content/docs/deploy/monitoring.mdx
new file mode 100644
index 00000000..efd43918
--- /dev/null
+++ b/docs/content/docs/deploy/monitoring.mdx
@@ -0,0 +1,119 @@
+---
+title: Monitoring
+description: Health checks, Prometheus metrics, and page analytics for a running site.
+order: 4
+---
+
+Everything here applies to a server build. A static site has no server, so it has
+nothing to report — see [Build and serve](/docs/deploy/build).
+
+## Health and readiness
+
+Two endpoints, and they answer different questions. Most platforms want both.
+
+### /api/health
+
+Is the process alive? Always returns `200` while the server is running. Wire
+your platform's liveness check here — if this stops answering, restart the
+process.
+
+```bash
+curl -i https://docs.example.com/api/health
+```
+
+### /api/ready
+
+Is it ready to serve properly? Returns `200` once the search index has finished
+building, and `503` before that.
+
+```json
+{ "status": "ready", "search": true }
+```
+
+```json
+{ "status": "not_ready", "search": false }
+```
+
+The index is built in the background at startup, so a large site is briefly up
+but not ready. Point your readiness or startup check here and a rolling deploy
+will not send traffic to an instance whose search is still empty.
+
+Using `/api/health` for both is the common mistake. It reports success
+immediately, so traffic arrives before search works.
+
+## Prometheus metrics
+
+Off by default. Turn it on and metrics are exported on a separate port:
+
+```yaml
+telemetry:
+  enabled: true
+  serviceName: my-docs
+  port: 9090
+```
+
+```bash
+curl http://localhost:9090/metrics
+```
+
+The output is standard Prometheus exposition format, carrying request counts,
+status codes and durations by route.
+
+The separate port is deliberate — it lets you scrape metrics from inside your
+network without exposing them on the public site. Do not publish port 9090.
+
+A scrape config:
+
+```yaml
+scrape_configs:
+  - job_name: docs
+    static_configs:
+      - targets: ['docs-internal:9090']
+```
+
+`serviceName` is the name your traces and metrics are tagged with. Set it if you
+run more than one docs site, or every one of them reports as `chronicle`.
+
+## Page analytics
+
+Separate from the above, and about readers rather than the server:
+
+```yaml
+analytics:
+  enabled: true
+  googleAnalytics:
+    measurementId: G-XXXXXXXXXX
+```
+
+Both fields are needed — `enabled: true` on its own does nothing without a
+measurement ID.
+
+Page views are tracked as readers navigate, including navigation within the site
+that never reloads the page.
+
+### Outbound link tracking
+
+Links in the sidebar footer, set through `links`, are tagged with UTM parameters
+so the destination can see where the visit came from:
+
+| Parameter | Value |
+|---|---|
+| `utm_source` | The docs site's hostname |
+| `utm_medium` | Your site title, slugified |
+| `utm_content` | The path the reader clicked from |
+
+This needs nothing turned on and works whether or not analytics is enabled. It
+is the destination's analytics that benefits. See
+[`links`](/docs/reference/config).
+
+## What to watch
+
+For a docs site, the numbers worth an alert are few:
+
+- `/api/health` failing — the process is gone
+- `/api/ready` stuck at `503` well past startup — the index is failing to build
+- A rise in 404s — usually a moved page with no redirect. See
+  [Links and redirects](/docs/writing/links)
+
+Response times rarely need watching. Pages are rendered from files already in
+memory, and there is no database behind them.
diff --git a/docs/content/docs/features.mdx b/docs/content/docs/features.mdx
deleted file mode 100644
index 21551220..00000000
--- a/docs/content/docs/features.mdx
+++ /dev/null
@@ -1,146 +0,0 @@
----
-title: Features
-description: Overview of Chronicle features
-order: 2
----
-
-# Features
-
-Chronicle is a self-hosted documentation platform built with Vite + Nitro.
-
-## Content
-
-- **MDX support** — write documentation in MDX with React component embedding
-- **Frontmatter** — `title`, `short`, `description`, `identifiers`, `order`, `icon`, `lastModified`, `authors`, `draft`
-- **Directory metadata** — `meta.json` for folder titles, ordering, and sidebar config
-- **Remark plugins** — directives, admonitions, image resolution, link resolution, mermaid, reading time
-- **Syntax highlighting** — powered by Shiki via Apsara CodeBlock
-- **Versioning** — multiple documentation versions with URL-based routing
-
-## API Reference
-
-- **OpenAPI / Swagger support** — auto-generates API reference pages from specs (OpenAPI 3.x and Swagger 2.0)
-- **Read-only overview** — field names, types, required badges, examples, response schemas
-- **Playground dialog** — test requests with editable fields, JSON body editor, auth switching
-- **Auth types** — API Key, Bearer Token, Basic Auth (auto-detected from spec `securitySchemes`)
-- **Code snippets** — cURL, Python, Go, TypeScript with language switcher
-- **Response panel** — status code tabs with JSON syntax highlighting
-- **`.md` export** — every API endpoint has a `.md` URL with full documentation
-
-## Navigation
-
-- **Sidebar** — auto-generated from file structure, configurable via `meta.json`
-- **Breadcrumbs** — shows path hierarchy for docs and API pages
-- **Prev/Next** — arrow navigation between pages and API endpoints
-- **Search** — full-text search with SQLite FTS5 across titles, headings, and body content
-- **Folder sorting** — via `order` in `meta.json`
-- **Page sorting** — via `order` in frontmatter or `pages` array in `meta.json`
-
-## Themes
-
-- **Default theme** — sidebar + content layout with sub-navigation bar
-- **Paper theme** — book-style single-column with reading progress
-- **Fanfold theme** — continuous-form line printer paper, monospace throughout
-- **Dark/light mode** — system preference or manual toggle
-
-## SEO & AI
-
-- **Meta tags** — auto-generated title, description, Open Graph, Twitter Card
-- **Sitemap** — auto-generated `sitemap.xml`
-- **robots.txt** — auto-generated
-- **llms.txt** — AI-discoverable documentation index
-- **`.md` URLs** — every page (docs and API) has a markdown URL for AI tools
-- **Open in AI** — copy as markdown, open in ChatGPT or Claude
-
-## Developer Experience
-
-- **CLI** — `chronicle dev`, `chronicle build`, `chronicle start`
-- **Hot reload** — instant updates during development
-- **Monorepo support** — works as a package in monorepos
-- **Docker support** — containerized deployment
-- **Zod-validated config** — `chronicle.yaml` with schema validation
-
-## Redirects
-
-Configure URL redirects in `chronicle.yaml` for migrating old routes.
-
-```yaml
-redirects:
-  - from: /old-page
-    to: /docs/getting-started
-  - from: /legacy/api
-    to: /apis
-    permanent: true
-```
-
-- `permanent: false` (default) — 307 temporary redirect
-- `permanent: true` — 308 permanent redirect
-
-See [Configuration](/docs/configuration#redirects) for full reference.
-
-## Sorting
-
-### Pages
-
-Add `order` to frontmatter. Lower numbers appear first.
-
-```mdx
----
-title: Introduction
-order: 1
----
-```
-
-Or use `pages` array in `meta.json`:
-
-```json
-{
-  "pages": ["introduction", "installation", "configuration"]
-}
-```
-
-### Folders
-
-Add `order` to the folder's `meta.json`:
-
-```json
-{
-  "title": "Getting Started",
-  "order": 1
-}
-```
-
-Folder sorting is controlled only by `meta.json` `order`. The index page frontmatter `order` does not affect folder position.
-
-## Markdown URLs
-
-Every page has a `.md` URL that returns raw markdown:
-
-- **Docs pages** — `/{slug}.md` returns the raw MDX content
-- **API endpoints** — `/apis/{spec}/{operationId}.md` generates markdown with parameters, examples, responses, and cURL
-
-```bash
-curl https://docs.example.com/docs/getting-started.md
-curl https://docs.example.com/apis/petstore/findPetsByStatus.md
-```
-
-The "Open in AI" dropdown uses these URLs to copy markdown, open in ChatGPT, or open in Claude.
-
-## API Reference Page
-
-### Overview
-
-The read-only overview shows endpoint title, method badge, path, authorisation fields, query/path parameters, request body, and response schemas. The right column has code snippets and response JSON.
-
-### Playground
-
-Click **Test request** in the navbar to open the playground dialog with editable fields, JSON body editor, auth type switching, and live response with status and timing.
-
-### View Documentation
-
-If the OpenAPI spec has `externalDocs`, a **View documentation** button appears in the navbar.
-
-## Health & Readiness
-
-- `GET /api/health` — liveness probe, always returns `200`
-- `GET /api/ready` — readiness probe, returns `200` when search index is built, `503` otherwise
diff --git a/docs/content/docs/guides/api-reference.mdx b/docs/content/docs/guides/api-reference.mdx
new file mode 100644
index 00000000..cbed26e8
--- /dev/null
+++ b/docs/content/docs/guides/api-reference.mdx
@@ -0,0 +1,143 @@
+---
+title: API reference
+description: Turn an OpenAPI spec into browsable endpoint pages with a request tester.
+order: 2
+---
+
+Point Chronicle at an OpenAPI file and it renders a reference: one page per
+endpoint, with parameters, request and response schemas, code samples in four
+languages, and a panel for sending real requests.
+
+You write no pages for this. The spec is the source.
+
+## Set it up
+
+Put the spec next to `chronicle.yaml` and add an `api` entry:
+
+```yaml
+api:
+  - name: Petstore API
+    spec: ./petstore.yaml
+    basePath: /apis
+    server:
+      url: https://petstore.swagger.io/v2
+      description: Production
+```
+
+Restart and the reference is at `/apis`. Each endpoint gets its own URL under
+that, and they all appear in the sidebar grouped by tag, with a coloured badge
+for the method.
+
+`spec` accepts JSON or YAML, and both OpenAPI 3.x and Swagger 2.0. A Swagger 2.0
+file is converted as it loads, so you do not have to migrate it first.
+
+Several APIs at once is just several entries, each with its own `basePath`:
+
+```yaml
+api:
+  - name: Public API
+    spec: ./public.yaml
+    basePath: /apis
+    server: { url: https://api.example.com }
+  - name: Admin API
+    spec: ./admin.yaml
+    basePath: /admin-apis
+    server: { url: https://admin.example.com }
+```
+
+## What a reader gets
+
+**The endpoint page.** Method and path at the top, then the parameters — path,
+query and header — with types, required markers, descriptions and examples. Then
+the request body schema, then a response schema per status code. Nested objects
+expand in place.
+
+**Code samples.** cURL, Python, Go and TypeScript, generated from the endpoint
+and switchable from a tab strip. They include the real server URL and the auth
+header, so they are ready to paste.
+
+**A request tester.** The **Test request** button opens a panel with the
+parameters as editable fields and a JSON editor for the body. Sending shows the
+status, the timing, and the response body with syntax highlighting.
+
+**A markdown version.** Every endpoint answers at a `.md` URL with the whole
+thing — parameters, examples, responses and a cURL command — as plain text, for
+handing to an AI tool.
+
+## Authentication
+
+Declare how the API authenticates and the reference picks it up:
+
+```yaml
+api:
+  - name: Petstore API
+    spec: ./petstore.yaml
+    basePath: /apis
+    server:
+      url: https://petstore.swagger.io/v2
+    auth:
+      type: apiKey
+      header: Authorization
+      placeholder: "Bearer your-token"
+```
+
+The auth field then appears on every endpoint page and in the request tester,
+and the value a reader types is written into the code samples.
+
+If the spec declares `securitySchemes`, Chronicle reads those instead and offers
+the schemes it finds — API key, bearer token or basic auth. The `auth` config
+above is for a spec that does not say.
+
+Whatever a reader types stays in their browser. It is never sent anywhere except
+to the API they are testing against.
+
+### The request tester and CORS
+
+Requests go through a proxy on your docs server rather than straight from the
+browser. That is deliberate: most APIs do not allow cross-origin requests from a
+docs site, so a direct call would fail before it left the page.
+
+This means the API has to be reachable from wherever your docs are hosted. An
+API on a private network works when you run `chronicle dev` on the same network
+and does not work from a public host.
+
+## Linking to your own guides
+
+If the spec has an `externalDocs` entry, a **View documentation** button appears
+on the endpoint page. Use it to send someone from a bare endpoint to the guide
+that explains why they would call it.
+
+## One spec per version
+
+A versioned site can give each version its own spec, pointed at that version's
+server:
+
+```yaml
+versions:
+  - dir: v1
+    label: "1.0"
+    content:
+      - dir: docs
+        label: Docs
+    api:
+      - name: REST API (v1)
+        spec: ./v1-openapi.yaml
+        basePath: /apis
+        server:
+          url: https://api.example.com/v1
+```
+
+That serves at `/v1/apis/...`. See
+[Versioned documentation](/docs/guides/versioning).
+
+## Things to know
+
+**The spec is read at startup.** Change the file and restart the dev server.
+
+**Endpoints are indexed for search** alongside your written pages, by method,
+path and summary, so `POST /pets` finds the endpoint.
+
+**A spec that fails to parse fails the build** rather than rendering an empty
+reference. The error names the file.
+
+See [`api`](/docs/reference/config) for every field.
diff --git a/docs/content/docs/guides/meta.json b/docs/content/docs/guides/meta.json
new file mode 100644
index 00000000..c9867da9
--- /dev/null
+++ b/docs/content/docs/guides/meta.json
@@ -0,0 +1 @@
+{ "title": "Guides", "order": 5 }
diff --git a/docs/content/docs/guides/migrate.mdx b/docs/content/docs/guides/migrate.mdx
new file mode 100644
index 00000000..5ac58058
--- /dev/null
+++ b/docs/content/docs/guides/migrate.mdx
@@ -0,0 +1,133 @@
+---
+title: Move an existing docs site
+description: Point Chronicle at markdown you already have.
+order: 5
+---
+
+If you already have a folder of markdown, you do not need to move or rename any
+of it. Chronicle can read the folder where it sits.
+
+## Point init at your folder
+
+```bash
+chronicle init -c docs
+```
+
+This writes a `chronicle.yaml` that treats your existing `docs/` as the content
+directory. Nothing is moved, and the sample page is skipped because the folder
+already has files.
+
+Then:
+
+```bash
+chronicle dev
+```
+
+Most of a markdown site renders on the first try. What follows is the short list
+of things that usually need a look.
+
+## Add a title to every page
+
+`title` is the one required field. A page without it falls back to `Untitled` in
+the sidebar and the browser tab.
+
+If your pages open with an `# H1` and no frontmatter, that heading is the title —
+move it up:
+
+```mdx
+# Installing the CLI          →   ---
+                                  title: Installing the CLI
+The CLI ships as a binary.        ---
+
+                                  The CLI ships as a binary.
+```
+
+Delete the `#` when you do. Every theme prints `title` above the article, so
+leaving both shows the same words twice. See
+[Pages and frontmatter](/docs/writing/pages).
+
+A quick way to find the pages that still need it:
+
+```bash
+grep -rL "^title:" docs --include="*.md" --include="*.mdx"
+```
+
+## Rename .md to .mdx
+
+Both extensions are read, so this is optional. Renaming buys you components —
+callouts, tabs, diagrams — in pages that want them, and costs nothing in pages
+that do not.
+
+MDX is stricter than markdown in one way worth knowing: a bare `<` or `{` is
+read as the start of a component or an expression. If a page fails to parse
+after renaming, that is usually why. Wrap the character in backticks or escape
+it.
+
+## Order the pages
+
+Without `order`, pages sort after every page that has one. Add it to the pages
+whose position matters:
+
+```yaml
+---
+title: Introduction
+order: 1
+---
+```
+
+Folders become sidebar groups named after the folder. Give a folder a better
+name with a `meta.json`:
+
+```json
+{ "title": "Getting started", "order": 2 }
+```
+
+See [Navigation](/docs/writing/navigation).
+
+## Keep your old URLs working
+
+This is the step people skip and regret. If your paths change — a different
+prefix, a renamed folder, a page split in two — add redirects so existing links
+survive:
+
+```yaml
+redirects:
+  - from: /guide/install
+    to: /docs/getting-started/install
+    permanent: true
+```
+
+Check your analytics for the twenty most-visited pages and make sure each one
+still resolves. See [Links and redirects](/docs/writing/links).
+
+## Move your images
+
+Images referenced relatively keep working — put the file next to the page. Ones
+you served from a static folder belong in `public/`, which is served as-is.
+
+Content images get resized and re-encoded for free once they are next to a page,
+which files in `public/` do not. See [Images](/docs/writing/images).
+
+## Coming from a docs site with its own conventions
+
+Chronicle has no plugin system, so anything your previous tool did through
+plugins needs another home:
+
+| You had | In Chronicle |
+|---|---|
+| A sidebar or nav config file | Folders plus `order`. See [Navigation](/docs/writing/navigation) |
+| Custom admonition syntax | The `:::note` directives Chronicle ships. See [Components](/docs/writing/components) |
+| A theme you had customised | One of three themes, plus colour tokens. See [Themes](/docs/themes) |
+| Versioned docs in a plugin | The `versions` key. See [Versioned documentation](/docs/guides/versioning) |
+| A search integration | Built in. See [Search](/docs/guides/search) |
+
+## Check before you ship
+
+```bash
+chronicle build
+```
+
+The build fails on a page that cannot be parsed and names the file, so this is
+the fastest way to find the last few problems. Then look at the sidebar order,
+click through the twenty pages that matter most, and check that search finds
+them.
diff --git a/docs/content/docs/guides/search.mdx b/docs/content/docs/guides/search.mdx
new file mode 100644
index 00000000..2b4bdc1c
--- /dev/null
+++ b/docs/content/docs/guides/search.mdx
@@ -0,0 +1,76 @@
+---
+title: Search
+description: What search indexes, how readers reach it, and how it behaves in a static build.
+order: 3
+---
+
+Search is on by default. There is no service to sign up for and no API key — the
+index is built from your pages when the server starts.
+
+```yaml
+search:
+  enabled: true
+  placeholder: Search docs...
+```
+
+Turn it off with `enabled: false` if your site is small enough that the sidebar
+is faster than typing.
+
+## Reaching it
+
+A reader can click the search button in the sidebar or press <kbd>Cmd</kbd> +
+<kbd>K</kbd> — <kbd>Ctrl</kbd> + <kbd>K</kbd> on Windows and Linux. Results
+appear as they type.
+
+## What gets indexed
+
+Three fields per page, weighted so the best match wins:
+
+| Field | Comes from |
+|---|---|
+| Title | The page's `title` |
+| Headings | Every `##` and below |
+| Body | The page text |
+
+A result tells the reader which of the three matched. A heading match links
+straight to that heading rather than the top of the page, so a hit deep in a
+long page lands where the words actually are.
+
+API endpoints are indexed too, by method, path and summary — so `POST /pets`
+finds the endpoint alongside the guides that mention it.
+
+Pages with `draft: true` are left out, because they are removed from the
+navigation tree before the index is built.
+
+## Scoping to a version and section
+
+On a versioned site the index is per version. A reader on `/v1/docs` searches
+1.0 and does not get 3.0 results. Switching versions switches the index.
+
+Results also carry the content section they came from, so a hit in `Dev Docs` is
+labelled as such rather than looking like a page from the main docs.
+
+## Two engines, same behaviour
+
+Which engine runs depends on how you built the site, and readers should not be
+able to tell.
+
+**Server builds** use SQLite full-text search. The index is built in the
+background when the server starts, which is why `/api/ready` reports not-ready
+until it finishes — see [Monitoring](/docs/deploy/monitoring).
+
+**Static builds** have no server to query, so the index is written to a JSON file
+at build time and searched in the browser. This makes the first search on a
+static site download the index. It is fine for a few hundred pages and gets
+heavy well beyond that, which is a reason to prefer a server build for a large
+site. See [Deploy](/docs/deploy/hosting).
+
+## Things to know
+
+**The index is built once per run.** In development, adding a page updates the
+page tree immediately but the search index is built at startup — restart if a
+new page is not being found.
+
+**There is no ranking you can tune.** No per-page boost, no synonyms, no
+stop-word list. If a page is hard to find, the fix is a clearer `title` and
+better headings, which helps readers who never search anyway.
diff --git a/docs/content/docs/guides/sections.mdx b/docs/content/docs/guides/sections.mdx
new file mode 100644
index 00000000..35357829
--- /dev/null
+++ b/docs/content/docs/guides/sections.mdx
@@ -0,0 +1,125 @@
+---
+title: Multiple content sections
+description: Split a site into separate sections with their own navigation.
+order: 4
+---
+
+Some docs serve two audiences that share nothing. A product guide for people
+using the thing, and a developer guide for people building against it. Putting
+both in one sidebar makes each harder to read.
+
+A content directory is a section: its own folder, its own URL prefix, its own
+navigation tree.
+
+## Declaring sections
+
+Each entry in `content` is a section:
+
+```yaml
+content:
+  - dir: docs
+    label: Docs
+  - dir: dev
+    label: Dev Docs
+```
+
+```
+content/
+├── docs/          → /docs/...
+└── dev/           → /dev/...
+```
+
+The directory name is the URL prefix. The label is what readers see.
+
+## What changes with two or more
+
+A switcher appears at the top of the sidebar. The tree below it shows only the
+section you are in, so a reader in `Dev Docs` sees developer pages and nothing
+else. Previous and next links stay inside the section too.
+
+Search still covers everything, but each result is labelled with the section it
+came from — so a reader who searches across both can tell which is which.
+
+## Descriptions and icons
+
+On a landing page each section becomes a card, and these two fields are what
+make the card worth reading:
+
+```yaml
+content:
+  - dir: docs
+    label: Docs
+    description: Install it, configure it, and get your first site running.
+    icon: /icons/book.svg
+  - dir: dev
+    label: Dev Docs
+    description: Build against the API, extend the themes, run it in CI.
+    icon: /icons/code.svg
+```
+
+`icon` takes a path to a file in `public/`, or inline SVG markup.
+
+## The landing page
+
+With one section, `/` redirects straight into it — a landing page listing one
+thing is a wasted click.
+
+With several, you probably want the choice. Turn it on:
+
+```yaml
+latest:
+  label: "3.0"
+  landing: true
+```
+
+Now `/` lists the sections as cards. Leave it off and `/` redirects to the first
+section in the list.
+
+The `fanfold` theme prints its own landing page here instead of the card grid —
+see [Theme options](/docs/themes/options).
+
+## Where a section's root lands
+
+Visiting `/docs` normally serves `content/docs/index.mdx`. Set `index_page` to
+send it to a different page instead:
+
+```yaml
+content:
+  - dir: docs
+    label: Docs
+    index_page: overview
+```
+
+Now `/docs` resolves to `/docs/overview`. Useful when the page you want readers
+to start on is not the one called `index`.
+
+## Sections and versions
+
+Each version declares its own sections, so they can change over releases:
+
+```yaml
+content:
+  - dir: docs
+    label: Docs
+  - dir: dev
+    label: Dev Docs
+
+versions:
+  - dir: v1
+    label: "1.0"
+    content:
+      - dir: docs
+        label: Docs          # 1.0 had no developer guide
+```
+
+A version may rename a section, drop one, or add one the current version does
+not have. See [Versioned documentation](/docs/guides/versioning).
+
+## Things to know
+
+**Section names must be unique**, and cannot collide with a version directory
+name. The config check catches both.
+
+**Two sections is usually enough.** Every section you add is another thing a
+reader has to choose between before they start reading. Folders inside one
+section are cheaper — see [Navigation](/docs/writing/navigation).
diff --git a/docs/content/docs/guides/versioning.mdx b/docs/content/docs/guides/versioning.mdx
new file mode 100644
index 00000000..7dde9e7a
--- /dev/null
+++ b/docs/content/docs/guides/versioning.mdx
@@ -0,0 +1,178 @@
+---
+title: Versioned documentation
+description: Keep docs for old releases online while you write the next one.
+order: 1
+---
+
+When you ship a new major version, the people still on the old one need its docs.
+Chronicle serves every version at once: the current one at the plain URLs, and
+each older one behind its own prefix.
+
+## The layout
+
+The current version lives in `content/`, exactly as it does on an unversioned
+site. Older versions live in `versions/`, one folder each:
+
+```
+my-docs/
+├── chronicle.yaml
+├── content/                  ← the current version
+│   └── docs/
+│       └── index.mdx         → /docs
+└── versions/
+    ├── v2/
+    │   └── docs/
+    │       └── index.mdx     → /v2/docs
+    └── v1/
+        └── docs/
+            └── index.mdx     → /v1/docs
+```
+
+The folder name under `versions/` becomes the URL prefix. Nothing else derives
+from it, so `v1`, `2024-06` and `legacy` are all fine.
+
+## The config
+
+Two keys. `latest` describes the version in `content/`, and `versions` lists the
+older ones:
+
+```yaml
+content:
+  - dir: docs
+    label: Docs
+
+latest:
+  label: "3.0"
+
+versions:
+  - dir: v2
+    label: "2.0"
+    content:
+      - dir: docs
+        label: Docs
+
+  - dir: v1
+    label: "1.0"
+    content:
+      - dir: docs
+        label: Docs
+```
+
+`latest` becomes required the moment you declare `versions` — without it the
+switcher has no name for the current version. The config check will tell you so
+at startup rather than letting the site render a blank entry.
+
+Each version declares its own `content`, because the sections of your docs
+change over releases. A version can rename a section, drop one, or add one that
+the current version does not have.
+
+## Cutting a new version
+
+The move is to copy the current docs sideways, then keep writing in `content/`:
+
+```bash
+# freeze today's docs as 2.0
+cp -r content versions/v2
+```
+
+Then add the entry to `versions`, and change `latest.label` to the new number:
+
+```yaml
+latest:
+  label: "3.0"        # was 2.0
+
+versions:
+  - dir: v2
+    label: "2.0"      # the copy you just made
+    content:
+      - dir: docs
+        label: Docs
+```
+
+`content/` is now 3.0 and `/v2/docs` serves what you froze. No page needed
+editing to make that happen.
+
+## What readers see
+
+A switcher appears in the sidebar, listing `latest` and every version. Picking
+one keeps them on the equivalent page where possible.
+
+Everything else scopes to the version they are in. The sidebar shows that
+version's pages, search only returns that version's results, and previous and
+next links stay inside it. A reader on `/v1/docs` will not be dropped into 3.0
+material by accident.
+
+## Marking a version deprecated
+
+Add a badge and it shows next to the version's name in the switcher:
+
+```yaml
+versions:
+  - dir: v1
+    label: "1.0"
+    badge:
+      label: deprecated
+      variant: warning
+    content:
+      - dir: docs
+        label: Docs
+```
+
+`variant` takes `accent`, `warning`, `danger`, `success`, `neutral` or
+`gradient`. `warning` for something you would rather people left, `danger` for
+one that is no longer supported at all.
+
+## Version landing pages
+
+By default, hitting a version's root redirects to its first content directory —
+`/v1` sends the reader to `/v1/docs`.
+
+Set `landing: true` to render a page listing that version's sections instead:
+
+```yaml
+versions:
+  - dir: v1
+    label: "1.0"
+    landing: true
+    content: [...]
+```
+
+This is worth it for a version with several sections and not worth it for one
+with a single section, where the landing page is a list of one.
+
+`latest.landing` does the same for `/`.
+
+## Versioned API references
+
+A version can carry its own OpenAPI spec, served under its prefix:
+
+```yaml
+versions:
+  - dir: v1
+    label: "1.0"
+    content:
+      - dir: docs
+        label: Docs
+    api:
+      - name: REST API (v1)
+        spec: ./v1-openapi.yaml
+        basePath: /apis
+        server:
+          url: https://api.example.com/v1
+```
+
+That renders at `/v1/apis/...`, pointing at the v1 server. See
+[API reference](/docs/guides/api-reference).
+
+## Things to know
+
+**A version directory name cannot collide with a content directory name.** If
+your content has `dir: docs`, no version may be called `docs` — the URLs would be
+ambiguous. The config check catches this.
+
+**Old versions are frozen by hand, not by git.** Chronicle reads whatever is in
+`versions/`. If you fix a typo in the current docs and want the fix in 2.0 as
+well, you edit both.
+
+**Every version is built and served.** Ten versions of a large site means ten
+sites' worth of pages in one build. Prune the versions nobody reads.
diff --git a/docs/content/docs/index.mdx b/docs/content/docs/index.mdx
index 4240051e..305360c2 100644
--- a/docs/content/docs/index.mdx
+++ b/docs/content/docs/index.mdx
@@ -1,95 +1,71 @@
 ---
-title: Getting Started
-description: Install and set up Chronicle, a config-driven documentation framework.
+title: Introduction
+description: What Chronicle is, when to reach for it, and where to go next.
 order: 1
 ---
 
-# Getting Started
+Chronicle turns a folder of MDX files into a documentation site. You write pages,
+you describe the site in one YAML file, and that is the whole setup. There is no
+JavaScript config, no plugin list, and no build script to maintain.
 
-Chronicle is a config-driven documentation framework built on Vite, Nitro, and Apsara UI components. Write MDX content, configure with a single YAML file, and get a fully themed documentation site.
+It is built on Vite and Nitro, and renders with Apsara components. Pages are
+server-rendered, so they work with JavaScript turned off and load fast on a
+slow connection.
 
-## Installation
+## When to reach for it
 
-```bash
-bun add @raystack/chronicle
-```
-
-## Quick Start
-
-### 1. Initialize a new project
-
-```bash
-chronicle init
-```
+Chronicle suits a project that needs more than a README and less than a custom
+site. It is a good fit when you want:
 
-This creates:
-- `chronicle.yaml` — your site configuration
-- `content/` — content directory with a sample `index.mdx`
-- `.gitignore` — with `node_modules`, `dist`, `.output` entries
+- **Docs in your repository.** Pages are files. They review like code.
+- **More than one version live at once.** Old versions stay reachable at their
+  own URLs while you keep writing the new one.
+- **An API reference from your OpenAPI spec.** Point at the spec file and you
+  get browsable endpoint pages with a request tester.
+- **Something to hand to an AI tool.** Every page has a plain markdown URL, and
+  the site publishes an index at `llms.txt`.
 
-To use an existing directory as content (e.g. `docs/`):
+It is a poor fit if you need a full marketing site, a CMS with a web editor, or
+a design you control down to the pixel. Chronicle gives you a choice of three
+themes and no way to write a fourth.
 
-```bash
-chronicle init -c docs
-```
+## What you get
 
-### 2. Start the development server
+Write MDX and Chronicle handles the rest of a docs site: navigation built from
+your folders, full-text search, a table of contents per page, breadcrumbs,
+previous and next links, dark mode, social cards, a sitemap, and redirects for
+URLs you have moved.
 
-```bash
-chronicle dev
-```
+The pieces you will touch most often:
 
-Your docs site is now running at [http://localhost:3000](http://localhost:3000).
+| You want to | Go to |
+|---|---|
+| Get a site running | [Quick start](/docs/quick-start) |
+| Write and organise pages | [Writing docs](/docs/writing/pages) |
+| Publish a second version | [Versioned documentation](/docs/guides/versioning) |
+| Publish an API reference | [API reference](/docs/guides/api-reference) |
+| Look up a config key | [chronicle.yaml](/docs/reference/config) |
+| Put it on the internet | [Deploy](/docs/deploy/hosting) |
 
-### 3. Add content
+## How a project is laid out
 
-Create `.mdx` files in your content directory. Each file becomes a page. Use folders to create nested navigation.
+One config file, one content folder:
 
 ```
 my-docs/
-├── chronicle.yaml
+├── chronicle.yaml       # the whole site config
 ├── content/
-│   ├── index.mdx
-│   ├── getting-started.mdx
-│   └── guides/
-│       ├── installation.mdx
-│       └── configuration.mdx
+│   └── docs/            # a content directory
+│       ├── index.mdx    # → /docs
+│       └── guides/
+│           └── setup.mdx  # → /docs/guides/setup
 └── .output/             # build output, gitignored
 ```
 
-### 4. Build for production
-
-```bash
-chronicle build
-chronicle start
-```
-
-Or use the combined command:
-
-```bash
-chronicle serve
-```
-
-## Project Structure
-
-A minimal Chronicle project looks like:
-
-```
-my-docs/
-├── chronicle.yaml      # Site configuration
-├── content/
-│   ├── index.mdx       # Home page
-│   └── guides/
-│       └── setup.mdx   # Nested page at /guides/setup
-└── .output/             # Build output, gitignored
-```
-
-All configuration is done through `chronicle.yaml`. No additional config files needed.
+Files become URLs. Folders become groups in the sidebar. See
+[Project structure](/docs/structure) for how the pieces fit together.
 
-## Next Steps
+## Next
 
-- [CLI Commands](/docs/cli) — All available CLI commands and flags
-- [Configuration](/docs/configuration) — Full `chronicle.yaml` reference
-- [Frontmatter](/docs/frontmatter) — Page-level metadata options
-- [Components](/docs/components) — MDX components and admonitions
-- [Themes](/docs/themes) — Available themes and customization
+Start with the [quick start](/docs/quick-start) — it takes about two minutes and
+ends with a site running on your machine.
diff --git a/docs/content/docs/quick-start.mdx b/docs/content/docs/quick-start.mdx
new file mode 100644
index 00000000..92fba3b7
--- /dev/null
+++ b/docs/content/docs/quick-start.mdx
@@ -0,0 +1,91 @@
+---
+title: Quick start
+description: Install Chronicle and get a documentation site running on your machine.
+order: 2
+---
+
+This gets you from nothing to a running site. It takes about two minutes.
+
+## Install
+
+```bash
+bun add @raystack/chronicle
+```
+
+## Create a project
+
+```bash
+chronicle init
+```
+
+That writes three things:
+
+- `chronicle.yaml` — your site config
+- `content/docs/` — a content directory with a sample `index.mdx`
+- `.gitignore` — entries for `node_modules`, `dist` and `.output`
+
+Already have a docs folder you want to keep? Point `init` at it instead of
+letting it make a new one:
+
+```bash
+chronicle init -c docs
+```
+
+Nothing is overwritten. If the directory already has files, the sample page is
+skipped. See [Move an existing docs site](/docs/guides/migrate) for the longer
+version.
+
+## Start the dev server
+
+```bash
+chronicle dev
+```
+
+Your site is at [http://localhost:3000](http://localhost:3000). Edit a page and
+the browser updates without a reload.
+
+## Write a page
+
+Create `content/docs/hello.mdx`:
+
+```mdx
+---
+title: Hello
+description: My first page.
+order: 2
+---
+
+This is a page. It lives at `/docs/hello`.
+
+## A section
+
+Sections use `##` and below. The heading above the article comes from `title`,
+so a page never needs its own `#`.
+```
+
+Reload and it appears in the sidebar, in search, and in the previous and next
+links. Nothing else to register.
+
+## Build for production
+
+```bash
+chronicle build
+chronicle start
+```
+
+Or do both in one step while you are trying things out:
+
+```bash
+chronicle serve
+```
+
+`build` writes to `.output/`. `start` serves what `build` produced — it does not
+build for you, so run them in that order. See
+[Build and serve](/docs/deploy/build) for what the output contains and how
+presets change it.
+
+## Next
+
+- [Project structure](/docs/structure) — what each file and folder is for
+- [Pages and frontmatter](/docs/writing/pages) — every field a page can set
+- [chronicle.yaml](/docs/reference/config) — the full config reference
diff --git a/docs/content/docs/cli.mdx b/docs/content/docs/reference/cli.mdx
similarity index 82%
rename from docs/content/docs/cli.mdx
rename to docs/content/docs/reference/cli.mdx
index 3d615a27..3ea28eb0 100644
--- a/docs/content/docs/cli.mdx
+++ b/docs/content/docs/reference/cli.mdx
@@ -1,11 +1,9 @@
 ---
-title: CLI Commands
-description: Chronicle CLI commands reference.
-order: 2
+title: CLI commands
+description: Every Chronicle command and flag.
+order: 3
 ---
 
-# CLI Commands
-
 Chronicle provides a CLI to initialize, develop, build, and serve your documentation site.
 
 ## init
@@ -54,7 +52,7 @@ chronicle build [options]
 |------|-------------|---------|
 | `--content <path>` | Content directory | `content` |
 | `--config <path>` | Path to `chronicle.yaml` | `./chronicle.yaml` |
-| `--preset <preset>` | Deploy preset (`vercel`, `cloudflare`, `node-server`) | — |
+| `--preset <preset>` | Deploy preset. See [`preset`](/docs/reference/config) for the values | — |
 
 ## start
 
@@ -84,9 +82,9 @@ chronicle serve [options]
 | `--config <path>` | Path to `chronicle.yaml` | `./chronicle.yaml` |
 | `-p, --port <port>` | Port number | `3000` |
 | `--host <host>` | Host address | `localhost` |
-| `--preset <preset>` | Deploy preset (`vercel`, `cloudflare`, `node-server`) | — |
+| `--preset <preset>` | Deploy preset. See [`preset`](/docs/reference/config) for the values | — |
 
-## Resolution Order
+## Resolution order
 
 CLI flags take precedence over `chronicle.yaml` values, which take precedence over defaults.
 
@@ -95,3 +93,8 @@ CLI flags take precedence over `chronicle.yaml` values, which take precedence ov
 | Content directory | `--content` | `content` | `content` |
 | Deploy preset | `--preset` | `preset` | — |
 | Config path | `--config` | — | `./chronicle.yaml` |
+
+`start` serves what `build` produced. It does not build, so run `build` first —
+or use `serve`, which does both.
+
+See [Build and serve](/docs/deploy/build) for what each preset writes.
diff --git a/docs/content/docs/configuration.mdx b/docs/content/docs/reference/config.mdx
similarity index 83%
rename from docs/content/docs/configuration.mdx
rename to docs/content/docs/reference/config.mdx
index 520b575c..db7c5d6d 100644
--- a/docs/content/docs/configuration.mdx
+++ b/docs/content/docs/reference/config.mdx
@@ -1,30 +1,16 @@
 ---
-title: Configuration
-description: Full chronicle.yaml configuration reference.
-order: 3
+title: chronicle.yaml
+description: Every key the site config accepts.
+order: 1
 ---
 
-# Configuration
-
 All site configuration lives in a single `chronicle.yaml` file in your project root. The config is validated using Zod — invalid fields produce clear errors at startup.
 
-## Project layout
-
-```
-my-docs-site/
-├── chronicle.yaml
-├── content/                     ← latest
-│   ├── docs/
-│   └── dev/
-└── versions/                    ← only if versions: is declared
-    ├── v2/
-    │   └── docs/
-    └── v1/
-        ├── docs/
-        └── dev/
-```
+Only `site.title` and `content` are required. Everything else has a default or
+is optional.
 
-Content dirs declared in top-level `content:` are resolved under `content/<dir>/` for the latest version; each `versions[].content[].dir` is resolved under `versions/<version-dir>/<dir>/`.
+For how the files on disk map to URLs, see
+[Project structure](/docs/structure).
 
 ## Full example
 
@@ -216,14 +202,31 @@ versions:
 | `content` | `{dir, label}[]` | Content dirs for this version. Entries may rename, reorder, or omit top-level content dirs. |
 | `api` | `ApiConfig[]` | Version-scoped API specs, rendered at `/<dir>/apis/...`. Same shape as top-level `api:`. |
 
+See [Versioned documentation](/docs/guides/versioning) for how to cut a new version.
+
 ### preset
 
-Optional deploy preset. Can be overridden by `--preset`.
+Deploy target. Decides what `chronicle build` produces and where it writes.
+Overridden by `--preset`.
 
 ```yaml
-preset: vercel # vercel, cloudflare, or node-server
+preset: vercel
 ```
 
+| Value | Output |
+|-------|--------|
+| — (unset) | A Node server in `.output/` |
+| `node-server` | A Node server in `.output/` |
+| `vercel` | A Vercel function build in `.vercel/output/` |
+| `cloudflare` | A Cloudflare Workers build in `.output/` |
+| `static` | Pre-rendered HTML in `.output/public/` |
+| `vercel-static` | Pre-rendered HTML in `.vercel/output/` |
+| `cloudflare-pages` | Pre-rendered HTML in `.output/public/` |
+| `github-pages` | Pre-rendered HTML in `.output/public/` |
+
+The four static presets pre-render every page at build time and need no server
+to run. See [Deploy](/docs/deploy/hosting).
+
 ### logo
 
 Logo with theme-aware variants.
@@ -251,9 +254,25 @@ theme:
 | Field | Type | Description | Default |
 |-------|------|-------------|---------|
 | `name` | `'default' \| 'paper' \| 'fanfold'` | Theme to use | `default` |
-| `colors` | `Record<string, string>` | Custom color overrides | — |
+| `colors` | `Record<string, string>` | Colour overrides, keyed by design token | — |
 
-See [Themes](/docs/themes) for details on each theme.
+```yaml
+theme:
+  name: default
+  colors:
+    background-base-primary: "#fbfaf8"
+    foreground-accent-primary: "#0a3793"
+```
+
+Each key names an Apsara colour token, and the `--rs-color-` prefix is added for
+you. Write the whole custom property yourself — `--paper-ink` — to reach one
+outside that family.
+
+A value applies in both light and dark, since the config holds one value per
+token. Leave a token alone if the two themes should differ.
+
+See [Choosing a theme](/docs/themes) for which one to pick and
+[Theme options](/docs/themes/options) for what each gives you.
 
 ### navigation
 
@@ -318,7 +337,7 @@ Any query string already on `href` is preserved, and a `utm_*` param you set you
 
 ### search
 
-Search functionality powered by Fumadocs. Automatically scoped to the active version.
+Full-text search over titles, headings and page bodies. Scoped to the active version.
 
 ```yaml
 search:
@@ -333,6 +352,8 @@ search:
 
 When enabled, search is accessible via the navbar button or keyboard shortcut `Cmd+K` / `Ctrl+K`. Active version comes from the URL; switching versions scopes the index.
 
+See [Search](/docs/guides/search) for what gets indexed.
+
 ### api
 
 OpenAPI specification configuration at the top level applies to the latest version (served at `/apis/...`). Version-scoped specs live under each `versions[].api`.
@@ -363,6 +384,8 @@ api:
 | `auth.header` | `string` | Header name for auth token |
 | `auth.placeholder` | `string` | Placeholder text in auth input |
 
+See [API reference](/docs/guides/api-reference) for what readers get from a spec.
+
 ### redirects
 
 URL redirects for migrating old routes to new ones. Checked before all other routes.
@@ -384,6 +407,8 @@ redirects:
 
 Use `permanent: true` when the old URL should never be used again — search engines and browsers will cache the redirect.
 
+See [Links and redirects](/docs/writing/links) for when to use each status.
+
 ### analytics
 
 Analytics integration for tracking page views.
@@ -400,6 +425,8 @@ analytics:
 | `enabled` | `boolean` | Enable/disable analytics | `false` |
 | `googleAnalytics.measurementId` | `string` | Google Analytics measurement ID | — |
 
+See [Monitoring](/docs/deploy/monitoring) for what else a running site reports.
+
 ### authors
 
 Optional registry of the people who write your docs. Pages reference an entry by
@@ -430,9 +457,11 @@ authors: [jane]
 
 A frontmatter string that matches no key is still valid — it renders as a plain
 name, so occasional contributors need no registry entry. See
-[Frontmatter](/docs/frontmatter) for the field itself, and browse the people
+[Frontmatter](/docs/reference/frontmatter) for the field itself, and browse the people
 writing a site at `/authors`.
 
+See [Authors and bylines](/docs/writing/authors) for how bylines and author pages work.
+
 ### telemetry
 
 Prometheus metrics export via OpenTelemetry. Served on a separate port.
@@ -452,6 +481,8 @@ telemetry:
 
 Metrics are available at `http://localhost:<port>/metrics` in Prometheus exposition format.
 
+See [Monitoring](/docs/deploy/monitoring) for the health and readiness endpoints.
+
 ## Defaults
 
 When `chronicle.yaml` is missing or fields are omitted, these defaults apply:
diff --git a/docs/content/docs/frontmatter.mdx b/docs/content/docs/reference/frontmatter.mdx
similarity index 74%
rename from docs/content/docs/frontmatter.mdx
rename to docs/content/docs/reference/frontmatter.mdx
index 38a811ae..e8c8d48d 100644
--- a/docs/content/docs/frontmatter.mdx
+++ b/docs/content/docs/reference/frontmatter.mdx
@@ -1,14 +1,13 @@
 ---
-title: Frontmatter
-description: Page-level metadata options for MDX files.
-order: 4
+title: Frontmatter fields
+description: Every field a page can set in its frontmatter.
+order: 2
 ---
 
-# Frontmatter
-
-Every MDX file supports YAML frontmatter at the top of the file for page-level configuration.
+Every field a page can set. Only `title` is required.
 
-## Example
+For how to write a page day to day, see
+[Pages and frontmatter](/docs/writing/pages).
 
 ```mdx
 ---
@@ -21,11 +20,23 @@ authors:
   - Jane Doe <jane@example.com>
 ---
 
-# Getting Started
-
 Your content here...
 ```
 
+## Fields at a glance
+
+| Field | Type | What it does |
+|---|---|---|
+| `title` | `string` | **Required.** Heading, sidebar label, browser tab |
+| `description` | `string` | Line under the heading, meta description, social card |
+| `order` | `number` | Sidebar position. Lower first. Decimals allowed |
+| `draft` | `boolean` | `true` removes the page from the site |
+| `short` | `string` | Shorter sidebar label. Read by `fanfold` |
+| `identifiers` | `string[]` | Extra header lines. Read by `fanfold` |
+| `icon` | `string` | Sidebar icon |
+| `authors` | `string \| string[]` | Byline, author pages, structured data |
+| `lastModified` | `string` | Date the page states as its last update |
+
 ## Fields
 
 ### title
@@ -36,6 +47,11 @@ Your content here...
 title: Installation Guide
 ```
 
+Every theme prints this title above the article, so start your content with the
+first section rather than repeating the title as a `#` heading. A page that opens
+with `# Installation Guide` shows the same words twice. Use `##` and below for
+sections — those are what the table of contents lists.
+
 ### short
 
 Optional short label for the sidebar. Use it when the full title is too long for
@@ -140,19 +156,6 @@ authors:
   - Sam Patel
 ```
 
-### draft
-
-Set `draft: true` to keep a page out of the site. It is dropped from the
-navigation tree, so it does not appear in the sidebar, in breadcrumbs, in search,
-or in the previous/next links.
-
-```yaml
-draft: true
-```
-
-The file stays where it is, so this is the way to leave a page in the repository
-while it is still being written.
-
 A single author can be written without the list:
 
 ```yaml
@@ -167,7 +170,7 @@ and on the generated social card. Every author also gets a page at
 A byline shows two authors at most, collapsing the rest into a `+N` counter that
 names them on hover. The avatar beside each name is drawn from the author's
 initials unless the author has an `avatar` in the
-[authors registry](/docs/configuration).
+[authors registry](/docs/reference/config).
 
 Registry keys work here too, and bring the author's bio, avatar, and profile
 link along with them:
@@ -176,38 +179,20 @@ link along with them:
 authors: [jane]
 ```
 
-## Navigation Ordering
-
-Sidebar navigation is determined by:
-
-1. **Frontmatter `order`** — Pages sorted by `order` value (ascending)
-2. **Decimal values** — Use `1`, `1.5`, `2` for fine-grained positioning
-3. **Folders** — Directories become collapsible groups, auto-named from the folder name (capitalized)
-4. **No `meta.json` required** — Ordering is entirely frontmatter-based
+### draft
 
-### Example structure
+Set `draft: true` to keep a page out of the site. It is dropped from the
+navigation tree, so it does not appear in the sidebar, in breadcrumbs, in search,
+or in the previous/next links.
 
+```yaml
+draft: true
 ```
-content/
-├── index.mdx          # order: 1
-├── quickstart.mdx     # order: 2
-├── guides/
-│   ├── setup.mdx      # order: 1
-│   └── advanced.mdx   # order: 2
-└── reference/
-    ├── cli.mdx        # order: 1
-    └── config.mdx     # order: 2
-```
 
-This produces sidebar navigation:
+The file stays where it is, so this is the way to leave a page in the repository
+while it is still being written.
+
+## Where ordering is explained
 
-```
-Home (order: 1)
-Quickstart (order: 2)
-▸ Guides
-    Setup (order: 1)
-    Advanced (order: 2)
-▸ Reference
-    CLI (order: 1)
-    Config (order: 2)
-```
+`order`, `short` and folder `meta.json` all shape the sidebar together. See
+[Navigation](/docs/writing/navigation).
diff --git a/docs/content/docs/reference/meta.json b/docs/content/docs/reference/meta.json
new file mode 100644
index 00000000..e79619ed
--- /dev/null
+++ b/docs/content/docs/reference/meta.json
@@ -0,0 +1 @@
+{ "title": "Reference", "order": 7 }
diff --git a/docs/content/docs/reference/routes.mdx b/docs/content/docs/reference/routes.mdx
new file mode 100644
index 00000000..c2ed9baa
--- /dev/null
+++ b/docs/content/docs/reference/routes.mdx
@@ -0,0 +1,122 @@
+---
+title: Generated routes
+description: The URLs Chronicle serves that you never wrote a page for.
+order: 4
+---
+
+Beyond your pages, a Chronicle site answers at a set of URLs it generates
+itself. None of them need configuring. They are listed here so you know what is
+public and what you can point other tools at.
+
+## For search engines
+
+### /sitemap.xml
+
+Every page on the site, for crawlers.
+
+Absolute URLs need to know the site's address, so set `url` in the config or the
+sitemap has nothing to build them from:
+
+```yaml
+url: https://docs.example.com
+```
+
+On a versioned site, older versions are included alongside the current one.
+
+### /robots.txt
+
+Allows everything, and points at the sitemap:
+
+```
+User-agent: *
+Allow: /
+
+Sitemap: https://docs.example.com/sitemap.xml
+```
+
+The `Sitemap` line appears only when `url` is set.
+
+## For AI tools
+
+### The `.md` URL of any page
+
+Every page answers at its own path plus `.md`, returning the raw markdown with
+the frontmatter stripped:
+
+```bash
+curl https://docs.example.com/docs/quick-start.md
+```
+
+API endpoints do the same, and generate a full markdown document — parameters,
+examples, responses and a cURL command:
+
+```bash
+curl https://docs.example.com/apis/petstore/findPetsByStatus.md
+```
+
+This is what the **Open in AI** menu on each page copies, and what it hands to
+ChatGPT or Claude when a reader picks one.
+
+### /llms.txt
+
+An index of the site in the format AI tools look for: the site title, its
+description, and a link to every page's markdown URL.
+
+```
+# Chronicle
+
+Config-driven documentation framework
+
+- [Introduction](/docs.md)
+- [Quick start](/docs/quick-start.md)
+```
+
+Nothing to turn on. Every page you add appears here.
+
+## For social cards
+
+### /og
+
+Renders a social card as a PNG — the image people see when a page is shared in
+Slack, on a social network, or in a chat app.
+
+Pages point at this themselves in their meta tags, so you rarely call it
+directly. It takes what it draws from the query string:
+
+| Parameter | What it draws |
+|---|---|
+| `title` | The headline. Falls back to the site title |
+| `description` | A line under the headline |
+| `authors` | A `By …` line |
+
+Cards are only referenced when `url` is set, because a social network needs an
+absolute URL to fetch the image from.
+
+## For the site itself
+
+These serve the running site's own front end. They are documented because they
+are reachable, not because you need them.
+
+| Route | What it returns |
+|---|---|
+| `/api/search` | Search results for a query, scoped to a version |
+| `/api/page` | A page's metadata, fetched when navigating |
+| `/api/specs` | The parsed OpenAPI specs for a version |
+| `/api/image` | A resized, re-encoded content image |
+| `/api/authors` | The author index |
+| `/api/health` | Liveness. Always `200` |
+| `/api/ready` | Readiness. `200` once the search index is built, `503` before |
+
+`/api/health` and `/api/ready` are the two worth wiring into a deployment. See
+[Monitoring](/docs/deploy/monitoring).
+
+## In a static build
+
+A static build has no server, so everything that would be computed per request
+is written out as a file during the build instead. `sitemap.xml`, `robots.txt`,
+`llms.txt`, every `.md` file and every social card are all generated then.
+
+The `/api/*` routes have no equivalent. Search reads an index file downloaded
+into the browser, images are resized during the build rather than on demand, and
+the health, readiness and API proxy routes do not exist. See
+[Build and serve](/docs/deploy/build).
diff --git a/docs/content/docs/structure.mdx b/docs/content/docs/structure.mdx
new file mode 100644
index 00000000..f821fee2
--- /dev/null
+++ b/docs/content/docs/structure.mdx
@@ -0,0 +1,117 @@
+---
+title: Project structure
+description: What each file and folder in a Chronicle project is for.
+order: 3
+---
+
+A Chronicle project is a config file and a folder of MDX. Everything else is
+either static files you supply or output Chronicle writes.
+
+```
+my-docs/
+├── chronicle.yaml       # the whole site config
+├── content/             # pages for the current version
+│   ├── docs/
+│   └── dev/
+├── versions/            # only if you declare versions:
+│   ├── v2/
+│   │   └── docs/
+│   └── v1/
+│       ├── docs/
+│       └── dev/
+├── public/              # static files served as-is
+├── .output/             # build output, gitignored
+└── .cache/              # optimized images, gitignored
+```
+
+## chronicle.yaml
+
+Every setting lives here. There is no second config file and no JavaScript
+config. The file is checked against a schema when the server starts, so a typo
+or a wrong type fails immediately with a message naming the field rather than
+breaking a page later.
+
+Only two keys are required: `site.title` and `content`. See
+[chronicle.yaml](/docs/reference/config) for all seventeen.
+
+## content
+
+Pages for the current version. This folder does not become a URL segment — the
+directories inside it do.
+
+Each directory you name in `content:` is a **content directory**, a top-level
+section of the site with its own navigation:
+
+```yaml
+content:
+  - dir: docs
+    label: Docs
+  - dir: dev
+    label: Dev Docs
+```
+
+That maps `content/docs/` to `/docs/...` and `content/dev/` to `/dev/...`. A site
+with two or more content directories gets a switcher for moving between them —
+see [Multiple content sections](/docs/guides/sections).
+
+### Files become URLs
+
+```
+content/docs/index.mdx              → /docs
+content/docs/hello.mdx              → /docs/hello
+content/docs/guides/setup.mdx       → /docs/guides/setup
+```
+
+`index.mdx` is the page for the directory holding it. `readme.mdx` works the same
+way, which is handy when the folder is also read on GitHub.
+
+Folders become groups in the sidebar. See
+[Navigation](/docs/writing/navigation) for naming and ordering them.
+
+## versions
+
+Only present if you declare `versions:` in the config. Each version is a folder,
+and the folder name doubles as the URL prefix:
+
+```
+versions/v1/docs/index.mdx          → /v1/docs
+```
+
+The current version stays in `content/` with no prefix. See
+[Versioned documentation](/docs/guides/versioning).
+
+## public
+
+Static files, served from the root of the site with their paths unchanged.
+`public/logo.svg` is available at `/logo.svg`, which is what a `logo:` entry in
+the config points at.
+
+Use it for logos, favicons, and downloads. Images you reference from a page are
+better placed next to the page — see [Images](/docs/writing/images).
+
+## .output
+
+What `chronicle build` writes. Gitignore it.
+
+For a server build it holds a runnable server that `chronicle start` serves. For
+a static build it holds `.output/public`, a folder of HTML and assets you can
+upload anywhere. Building with the `vercel` preset writes to `.vercel/output`
+instead. See [Build and serve](/docs/deploy/build).
+
+## .cache
+
+Resized and re-encoded images, kept between restarts so the work is done once.
+Gitignore it. See [Images](/docs/writing/images).
+
+## Using it inside a monorepo
+
+Chronicle takes the config path as a flag, so the docs site does not have to sit
+at the repository root:
+
+```bash
+chronicle dev --config docs/chronicle.yaml
+```
+
+Paths inside the config resolve relative to `chronicle.yaml`, not to where you
+ran the command. A `spec: ./openapi.yaml` next to the config is found whichever
+directory you start from.
diff --git a/docs/content/docs/themes/index.mdx b/docs/content/docs/themes/index.mdx
new file mode 100644
index 00000000..a2626617
--- /dev/null
+++ b/docs/content/docs/themes/index.mdx
@@ -0,0 +1,79 @@
+---
+title: Choosing a theme
+description: Three built-in themes, and which one suits your docs.
+order: 1
+---
+
+Chronicle ships three themes. Set one in `chronicle.yaml`:
+
+```yaml
+theme:
+  name: default
+```
+
+You cannot write a fourth, so pick the one whose shape fits your material. You
+can recolour whichever you pick — see [Theme options](/docs/themes/options).
+
+## Which one
+
+| Theme | Shape | Reach for it when |
+|---|---|---|
+| `default` | Sidebar, content, table of contents | Reference docs people navigate and search |
+| `paper` | One column, reading progress | Guides and long explanations people read start to finish |
+| `fanfold` | Line-printer paper, monospace throughout | Systems and protocol docs, where a printed look fits the material |
+
+### default
+
+The layout most documentation uses, and the right first choice. A navigation
+tree on the left, the page in the middle, its headings on the right. Readers
+already know how to use it, and nothing about it will surprise them.
+
+Pick it when people arrive knowing what they want and need to find it.
+
+### paper
+
+A single column at a reading width, with a progress indicator down the side and
+no table of contents competing for attention. Typography is tuned for long
+stretches of prose.
+
+Pick it when your docs are more explanation than reference — a handbook, a set
+of guides, something read in order rather than searched.
+
+### fanfold
+
+Continuous-form line printer paper: tractor-feed strips down both edges, faint
+zebra banding behind the text, monospace type, and a printed header block on
+every page carrying the breadcrumb trail and a page counter.
+
+It reads two frontmatter fields the others ignore. `short` gives a page a code
+for the narrow rail, and `identifiers` prints extra lines in the header — the
+standard a page implements, its package, its command.
+
+Pick it for material that is already technical and enumerated: protocols, wire
+formats, command references. It is a strong look, and it is the wrong choice for
+a friendly product guide.
+
+## Trying them
+
+Switching costs one line, and no page content has to change:
+
+```yaml
+theme:
+  name: paper
+```
+
+Restart the dev server and click through your five longest pages. A theme that
+suits your material is obvious quickly, and so is one that does not.
+
+Two fields are only read by `fanfold`, so a page that sets `short` or
+`identifiers` loses nothing by moving to another theme — the fields are ignored,
+not broken.
+
+## Dark mode
+
+All three do light and dark, following the reader's system preference with a
+toggle to override it. There is nothing to configure.
+
+Check both when you pick a theme, and again if you set your own colours — a
+look that works in one is not guaranteed to work in the other, and half your
+readers will see each.
diff --git a/docs/content/docs/themes/meta.json b/docs/content/docs/themes/meta.json
new file mode 100644
index 00000000..93a3a105
--- /dev/null
+++ b/docs/content/docs/themes/meta.json
@@ -0,0 +1 @@
+{ "title": "Themes", "order": 6 }
diff --git a/docs/content/docs/themes.mdx b/docs/content/docs/themes/options.mdx
similarity index 68%
rename from docs/content/docs/themes.mdx
rename to docs/content/docs/themes/options.mdx
index 238a335d..a4215a49 100644
--- a/docs/content/docs/themes.mdx
+++ b/docs/content/docs/themes/options.mdx
@@ -1,19 +1,18 @@
 ---
-title: Themes
-description: Available themes and customization options.
-order: 7
+title: Theme options
+description: What each built-in theme gives you, and how to tune its colours.
+order: 2
 ---
 
-# Themes
-
-Chronicle ships with three built-in themes. Set the theme in your `chronicle.yaml`:
+What each theme gives you. For help picking one, see
+[Choosing a theme](/docs/themes).
 
 ```yaml
 theme:
   name: default
 ```
 
-## Default Theme
+## Default theme
 
 A traditional documentation layout with three-column design.
 
@@ -37,7 +36,7 @@ theme:
 - Breadcrumb navigation
 - Active heading tracking in table of contents
 
-## Paper Theme
+## Paper theme
 
 A book-style layout optimized for long-form reading.
 
@@ -59,7 +58,7 @@ theme:
 - Optimized typography for long content
 - Light and dark mode
 
-## Fanfold Theme
+## Fanfold theme
 
 A continuous-form line printer look — tractor-feed strips down both edges, faint
 zebra banding behind the page, and monospace type throughout.
@@ -78,7 +77,7 @@ theme:
 ### Features
 
 - Header block prints the breadcrumb trail and a page counter, then whatever the
-  page gives as [`identifiers`](/docs/frontmatter) — falling back to the site
+  page gives as [`identifiers`](/docs/reference/frontmatter) — falling back to the site
   name and path
 - Page title set in a dot-matrix face that steps down in size as titles get longer
 - Everything on the sheet is held to one 80-column measure, so prose, tables,
@@ -90,7 +89,7 @@ theme:
   prose in it has its columns measured at build time, and folds that column under
   each row behind a toggle, so the paragraph reads at the full width of the sheet
   instead of a narrow column
-- Uses a page's [`short`](/docs/frontmatter) label in the rail and the header trail
+- Uses a page's [`short`](/docs/reference/frontmatter) label in the rail and the header trail
 - Its own landing page: a masthead over a register of every section
 - Light and dark mode
 
@@ -107,3 +106,28 @@ Set it in `chronicle.yaml`:
 latest:
   landing: true
 ```
+
+## Recolouring a theme
+
+Every theme draws from a set of colour tokens. Override any of them under
+`theme.colors`:
+
+```yaml
+theme:
+  name: default
+  colors:
+    background-base-primary: "#fbfaf8"
+    foreground-accent-primary: "#0a3793"
+    border-base-primary: "#e6e1d8"
+```
+
+The `--rs-color-` prefix is added for you, so name the token on its own. To
+reach a variable outside that family — the ones a theme defines for itself, like
+`--paper-ink` or `--fan-rule` — write the whole property name instead.
+
+One value covers both light and dark. If a token needs to differ between them,
+leave it out and let the theme decide.
+
+Values have to look like colours: a hex code, `rgb()`, `hsl()`, `color-mix()`, a
+named colour, or a `var()` reference. Anything else is ignored rather than
+written into the page.
diff --git a/docs/content/docs/writing/authors.mdx b/docs/content/docs/writing/authors.mdx
new file mode 100644
index 00000000..2ea7aadb
--- /dev/null
+++ b/docs/content/docs/writing/authors.mdx
@@ -0,0 +1,85 @@
+---
+title: Authors and bylines
+description: Credit the people who write your docs, and give each of them a page.
+order: 6
+---
+
+Naming an author puts a byline on the page, credits them in the page's structured
+data and on its social card, and gives them a page listing everything they wrote.
+
+## Crediting a page
+
+Add `authors` to the page's frontmatter. Each entry is a plain string — either
+`Name <email>` or just a name:
+
+```yaml
+authors:
+  - Jane Doe <jane@example.com>
+  - Sam Patel
+```
+
+A single author does not need the list:
+
+```yaml
+authors: Jane Doe <jane@example.com>
+```
+
+That is all you need. Nothing has to be registered first, which keeps the door
+open for an occasional contributor.
+
+## The byline
+
+The byline shows two names at most. Any more collapse into a `+N` counter that
+names the rest on hover, so a page with six authors does not push its own title
+down the screen.
+
+Each name carries an avatar. Without a picture to use, it is drawn from the
+author's initials.
+
+## The authors registry
+
+Writing the same name and email on forty pages gets old, and it means forty
+places to edit when something changes. Put the details in `chronicle.yaml`
+instead:
+
+```yaml
+authors:
+  jane:
+    name: Jane Doe
+    bio: Writes about distributed systems.
+    avatar: /team/jane.png
+    url: https://github.com/jane
+    email: jane@example.com
+```
+
+Then reference the key from a page:
+
+```yaml
+authors: [jane]
+```
+
+The bio, avatar and profile link come along with it. See
+[`authors`](/docs/reference/config) for the full field list.
+
+A frontmatter string that matches no key is still valid — it renders as a plain
+name. So you can register the people who write often and spell out the rest.
+
+## Author pages
+
+Every author gets a page at `/authors/<slug>` listing everything they wrote, and
+every byline name links to it. The site's full list is at `/authors`.
+
+An author's `url` and `email` are shown on their page rather than in the byline,
+which keeps the byline to names and the contact details in one predictable place.
+
+## Where else authors show up
+
+| Place | What it uses |
+|---|---|
+| The byline | Name and avatar |
+| The author's page | Name, bio, avatar, `url`, `email` |
+| `Article` structured data | Author names, for search engines |
+| The social card | Author names, under the title |
+
+The social card is the image people see when a page is shared. See
+[Generated routes](/docs/reference/routes) for how it is made.
diff --git a/docs/content/docs/components.mdx b/docs/content/docs/writing/components.mdx
similarity index 99%
rename from docs/content/docs/components.mdx
rename to docs/content/docs/writing/components.mdx
index 84f3633a..434a3343 100644
--- a/docs/content/docs/components.mdx
+++ b/docs/content/docs/writing/components.mdx
@@ -1,11 +1,9 @@
 ---
 title: Components
 description: MDX components and admonitions supported in Chronicle.
-order: 6
+order: 3
 ---
 
-# Components
-
 Chronicle provides built-in MDX components that enhance standard markdown with interactive elements and styled content.
 
 ## Callout
@@ -243,7 +241,7 @@ Images support both local and external sources:
 Links are automatically handled:
 
 ```mdx
-[Internal link](/docs/configuration)
+[Internal link](/docs/reference/config)
 [External link](https://github.com)
 [Anchor link](#section)
 ```
diff --git a/docs/content/docs/image-optimization.mdx b/docs/content/docs/writing/images.mdx
similarity index 71%
rename from docs/content/docs/image-optimization.mdx
rename to docs/content/docs/writing/images.mdx
index a3d82f5a..35b6f9d4 100644
--- a/docs/content/docs/image-optimization.mdx
+++ b/docs/content/docs/writing/images.mdx
@@ -1,14 +1,40 @@
 ---
-title: Image Optimization
-description: Automatic image optimization with on-demand resizing and format conversion.
-order: 5
+title: Images
+description: How images resolve, and the resizing and format conversion Chronicle does for you.
+order: 4
 ---
 
-# Image Optimization
+## Adding an image
 
-Chronicle automatically optimizes content images via an on-demand `/api/image` endpoint. Images are resized, converted to modern formats (WebP/AVIF), and cached on disk.
+Put the file next to the page that uses it and reference it relatively:
 
-## How It Works
+```mdx
+![Architecture overview](./architecture.png)
+```
+
+A path starting with `/` is resolved from the root of the content directory
+instead, which is what you want for an image several pages share:
+
+```mdx
+![Logo](/shared/logo.svg)
+```
+
+Either way Chronicle rewrites the URL at build time and appends a hash of the
+file's contents. That hash is why an image can be cached forever by a browser and
+still update the moment you change the file.
+
+Images in `public/` are different — they are served exactly as you put them
+there, with no rewriting and no optimization. Use `public/` for a favicon or a
+download, and keep content images next to their pages.
+
+## Optimization
+
+Everything below happens on its own. There is nothing to turn on.
+
+Content images are resized, re-encoded to a modern format, and cached on disk,
+through an on-demand `/api/image` endpoint.
+
+## How it works
 
 1. The remark plugin rewrites all image URLs to route through `/api/image`
 2. On first request, the image is resized and converted based on browser support
diff --git a/docs/content/docs/writing/links.mdx b/docs/content/docs/writing/links.mdx
new file mode 100644
index 00000000..ae9a4203
--- /dev/null
+++ b/docs/content/docs/writing/links.mdx
@@ -0,0 +1,98 @@
+---
+title: Links and redirects
+description: How links between pages resolve, and how to keep old URLs working after you move one.
+order: 5
+---
+
+## Linking between pages
+
+Use the page's URL, starting from the root:
+
+```mdx
+See [Navigation](/docs/writing/navigation) for ordering.
+```
+
+Internal links are resolved when the page is built, so a link to a page that
+does not exist is caught then rather than becoming a 404 for a reader. Internal
+links also navigate without a full page load.
+
+Relative links work too, and are resolved against the current page:
+
+```mdx
+See [Navigation](./navigation) for ordering.
+```
+
+Prefer absolute paths for anything that crosses a folder. A relative link breaks
+quietly when you move the page holding it; an absolute one keeps working.
+
+### Linking to a section
+
+Add the heading's slug. Slugs are the heading text, lowercased, with spaces
+turned into hyphens:
+
+```mdx
+[Ordering pages](/docs/writing/navigation#ordering-pages)
+```
+
+### External links
+
+Write them as normal. They open in a new tab.
+
+```mdx
+[Nitro](https://nitro.build)
+```
+
+## Redirects
+
+Move or rename a page and its old URL stops working. Add a redirect so anyone
+holding the old link — a bookmark, a blog post, a search result — still lands in
+the right place.
+
+```yaml
+redirects:
+  - from: /docs/old-page
+    to: /docs/writing/pages
+  - from: /legacy/api
+    to: /apis
+    permanent: true
+```
+
+Redirects are checked before every other route, so they win over a real page at
+the same path.
+
+| Field | What it does |
+|---|---|
+| `from` | The old path |
+| `to` | Where to send it |
+| `permanent` | `true` sends 308, `false` (default) sends 307 |
+
+### Which status to use
+
+Use `permanent: true` when the old URL is never coming back. Browsers and search
+engines cache a 308 hard, so a mistake is expensive to undo — a reader whose
+browser cached it will keep being redirected after you remove the rule.
+
+Use the default 307 while you are still deciding. Nothing is cached, so you can
+change your mind.
+
+### A worked example
+
+Say you split one page into a folder of three. The old URL was `/docs/config`:
+
+```yaml
+redirects:
+  - from: /docs/config
+    to: /docs/reference/config
+    permanent: true
+```
+
+Anyone following an old link arrives at the new page. Meanwhile, update the
+links inside your own pages to point at the new URL directly — a redirect is for
+links you do not control, not a substitute for fixing your own.
+
+## Markdown links to your own pages
+
+Every page also answers at a `.md` URL that returns its raw source. This is what
+the "Open in AI" menu copies, and what an AI tool reads when it follows
+`llms.txt`. You do not have to do anything to get it. See
+[Generated routes](/docs/reference/routes).
diff --git a/docs/content/docs/writing/meta.json b/docs/content/docs/writing/meta.json
new file mode 100644
index 00000000..14b976ad
--- /dev/null
+++ b/docs/content/docs/writing/meta.json
@@ -0,0 +1 @@
+{ "title": "Writing docs", "order": 4 }
diff --git a/docs/content/docs/writing/navigation.mdx b/docs/content/docs/writing/navigation.mdx
new file mode 100644
index 00000000..65ebe326
--- /dev/null
+++ b/docs/content/docs/writing/navigation.mdx
@@ -0,0 +1,139 @@
+---
+title: Navigation
+description: Order pages, name folders, and shape the sidebar with meta.json.
+order: 2
+---
+
+The sidebar is built from your folders. You do not write a navigation file — you
+name and order what is already there.
+
+## Ordering pages
+
+Add `order` to a page's frontmatter. Lower numbers come first.
+
+```mdx
+---
+title: Installation
+order: 1
+---
+```
+
+Pages with no `order` come after every page that has one, so you can order the
+important pages and leave the rest.
+
+### Slotting a page between two others
+
+`order` takes decimals. This is the whole reason it does — you can insert a page
+without renumbering its neighbours:
+
+```
+introduction.mdx    order: 1
+installation.mdx    order: 1.5   ← new page, lands between the two
+configuration.mdx   order: 2
+```
+
+## Folders become groups
+
+A folder is a group in the sidebar. Its name is derived from the folder name,
+capitalised:
+
+```
+content/docs/
+├── index.mdx
+├── quick-start.mdx
+└── guides/
+    ├── setup.mdx
+    └── advanced.mdx
+```
+
+```
+Quick start
+▸ Guides
+    Setup
+    Advanced
+```
+
+Pages sitting directly in the content directory appear before the folders.
+
+## meta.json
+
+Drop a `meta.json` in a folder to control the folder itself. The folder name is
+only a fallback.
+
+```json
+{
+  "title": "Getting started",
+  "order": 2
+}
+```
+
+| Field | What it does |
+|---|---|
+| `title` | The group label. Overrides the capitalised folder name |
+| `order` | Where the group sits. Shares one scale with page `order` |
+| `pages` | Explicit page order, by filename without the extension |
+| `root` | `true` makes this folder a navigation boundary |
+
+A folder's position comes from `meta.json` only. The `order` in its `index.mdx`
+frontmatter positions that page inside the group — it does not move the group.
+
+### One scale for pages and folders
+
+Pages and folders sort against each other using the same numbers, so a group can
+sit between two loose pages:
+
+```
+index.mdx           order: 1
+quick-start.mdx     order: 2
+guides/meta.json    order: 3   ← the group lands here
+reference/meta.json order: 4
+```
+
+### Ordering by filename
+
+If you would rather list the pages than number them, use `pages`:
+
+```json
+{
+  "title": "Guides",
+  "pages": ["introduction", "installation", "configuration"]
+}
+```
+
+Anything not listed follows the listed pages.
+
+## Short labels for a narrow rail
+
+When a title is too long for the sidebar but the page is known by a code its
+readers already use, add `short`:
+
+```yaml
+title: Space Packet Protocol
+short: SPP
+```
+
+The sidebar shows `SPP` and keeps the full title on the link's tooltip. Headings,
+breadcrumbs, the browser tab and search all keep using `title`.
+
+This is read by the `fanfold` theme, whose rail is narrow enough to need it. The
+`default` and `paper` themes always show `title`.
+
+## Icons
+
+`icon` puts a small graphic next to a sidebar entry:
+
+```yaml
+icon: rectangle-stack
+```
+
+The available values are listed under
+[`icon`](/docs/reference/frontmatter) in the frontmatter reference.
+
+## What else the navigation drives
+
+The same tree feeds the breadcrumbs at the top of a page, the previous and next
+links at the bottom, and the order results come back in from search. Order the
+tree well and all four improve at once.
+
+A page with `draft: true` is removed from the tree, so it disappears from all of
+them. See [Pages and frontmatter](/docs/writing/pages).
diff --git a/docs/content/docs/writing/pages.mdx b/docs/content/docs/writing/pages.mdx
new file mode 100644
index 00000000..5ef31469
--- /dev/null
+++ b/docs/content/docs/writing/pages.mdx
@@ -0,0 +1,119 @@
+---
+title: Pages and frontmatter
+description: How a file becomes a page, and the frontmatter you will use every day.
+order: 1
+---
+
+A page is an `.mdx` file in a content directory. Create the file and it is on the
+site — there is nothing to register.
+
+## Files become URLs
+
+The path under a content directory is the URL:
+
+```
+content/docs/index.mdx              → /docs
+content/docs/hello.mdx              → /docs/hello
+content/docs/guides/setup.mdx       → /docs/guides/setup
+content/docs/guides/index.mdx       → /docs/guides
+```
+
+`index.mdx` is the page for the folder that holds it. `readme.mdx` does the same
+job, which is useful when the folder is also browsed on GitHub.
+
+## Frontmatter
+
+Every page opens with a YAML block. Only `title` is required:
+
+```mdx
+---
+title: Installing the CLI
+description: Get the command line tool onto your machine.
+order: 2
+---
+
+The CLI ships as a single binary.
+
+## Requirements
+```
+
+The four fields you will use on nearly every page:
+
+| Field | What it does |
+|---|---|
+| `title` | **Required.** The heading above the article, the sidebar label, the browser tab |
+| `description` | The line under the heading, plus the meta description and social card |
+| `order` | Where the page sits in the sidebar. Lower first |
+| `draft` | `true` keeps the page out of the site while you write it |
+
+There are nine more fields for narrower jobs. See
+[Frontmatter fields](/docs/reference/frontmatter) for the full list.
+
+## Do not repeat the title
+
+Every theme prints `title` above the article. A page that opens with its own
+`# Installing the CLI` shows the same words twice.
+
+```mdx
+---
+title: Installing the CLI
+---
+
+# Installing the CLI      ← delete this
+
+The CLI ships as a single binary.
+```
+
+Start with your first sentence, and use `##` and below for sections. Those are
+what the table of contents lists — a `#` in the body never appears there.
+
+## Writing MDX
+
+MDX is markdown plus components. Everything you expect from markdown works:
+headings, lists, tables, links, code fences, block quotes, bold and italic.
+
+On top of that Chronicle gives you callouts, tabs, badges, collapsible sections
+and Mermaid diagrams. See [Components](/docs/writing/components).
+
+Code fences are highlighted by Shiki. Name the language on the fence:
+
+````mdx
+```bash
+chronicle dev
+```
+````
+
+A fence with no language is rendered as plain text rather than failing, so an
+ASCII diagram is safe to paste in.
+
+## Hiding a page while you write it
+
+Set `draft: true`:
+
+```mdx
+---
+title: Not finished yet
+draft: true
+---
+```
+
+The file stays where it is, but the page is dropped from the navigation tree — so
+it is out of the sidebar, breadcrumbs, search, and the previous and next links.
+This is how you keep unfinished work in the repository.
+
+## Reading time and last modified
+
+Reading time is measured from the page body and shown by the themes that have
+somewhere to put it. You do not set it.
+
+`lastModified` is a date you set yourself when you want the page to state one:
+
+```yaml
+lastModified: "2026-03-30"
+```
+
+## Next
+
+- [Navigation](/docs/writing/navigation) — ordering pages and naming folders
+- [Components](/docs/writing/components) — callouts, tabs, diagrams
+- [Frontmatter fields](/docs/reference/frontmatter) — all thirteen fields
diff --git a/examples/basic/content/docs/api/endpoints.mdx b/examples/basic/content/docs/api/endpoints.mdx
index 68b236cb..2b76578c 100644
--- a/examples/basic/content/docs/api/endpoints.mdx
+++ b/examples/basic/content/docs/api/endpoints.mdx
@@ -4,8 +4,6 @@ description: Available CLI commands
 order: 2
 ---
 
-# CLI Commands
-
 ## chronicle init
 
 Initialize a new Chronicle project.
diff --git a/examples/basic/content/docs/api/overview.mdx b/examples/basic/content/docs/api/overview.mdx
index 2b36a29b..10be0a63 100644
--- a/examples/basic/content/docs/api/overview.mdx
+++ b/examples/basic/content/docs/api/overview.mdx
@@ -4,8 +4,6 @@ description: Overview of the Chronicle API
 order: 1
 ---
 
-# API Overview
-
 Chronicle provides a simple API for building documentation.
 
 ## Core Concepts
diff --git a/examples/basic/content/docs/components.mdx b/examples/basic/content/docs/components.mdx
index 94d62759..eb777adc 100644
--- a/examples/basic/content/docs/components.mdx
+++ b/examples/basic/content/docs/components.mdx
@@ -5,8 +5,6 @@ order: 3
 authors: [jane]
 ---
 
-# Components
-
 Live rendering of the MDX components Chronicle registers for content files.
 
 ## Badge
diff --git a/examples/basic/content/docs/features.mdx b/examples/basic/content/docs/features.mdx
index 6c31410b..c4761783 100644
--- a/examples/basic/content/docs/features.mdx
+++ b/examples/basic/content/docs/features.mdx
@@ -5,8 +5,6 @@ order: 2
 draft: true
 ---
 
-# Features
-
 Chronicle is a self-hosted documentation platform built with Vite + Nitro. Here's what it offers.
 
 ## Content
diff --git a/examples/basic/content/docs/getting-started.mdx b/examples/basic/content/docs/getting-started.mdx
index 69f16e5a..716cb179 100644
--- a/examples/basic/content/docs/getting-started.mdx
+++ b/examples/basic/content/docs/getting-started.mdx
@@ -7,8 +7,6 @@ authors:
   - Sam Patel
 ---
 
-# Getting Started
-
 Get up and running with Chronicle in minutes.
 
 ## Prerequisites
diff --git a/examples/basic/content/docs/guides/configuration.mdx b/examples/basic/content/docs/guides/configuration.mdx
index 95f5ac18..24494649 100644
--- a/examples/basic/content/docs/guides/configuration.mdx
+++ b/examples/basic/content/docs/guides/configuration.mdx
@@ -4,8 +4,6 @@ description: Configure Chronicle options
 order: 2
 ---
 
-# Configuration
-
 Chronicle uses a `chronicle.yaml` file for configuration.
 
 ## Basic Configuration
diff --git a/examples/basic/content/docs/guides/deployment.mdx b/examples/basic/content/docs/guides/deployment.mdx
index 89f54f1d..c6e9827d 100644
--- a/examples/basic/content/docs/guides/deployment.mdx
+++ b/examples/basic/content/docs/guides/deployment.mdx
@@ -4,8 +4,6 @@ description: Deploy Chronicle to production
 order: 3
 ---
 
-# Deployment
-
 Chronicle builds to a standalone Node.js server that can be deployed anywhere.
 
 ## Build
diff --git a/examples/basic/content/docs/guides/installation.mdx b/examples/basic/content/docs/guides/installation.mdx
index f43dc85c..8447adc1 100644
--- a/examples/basic/content/docs/guides/installation.mdx
+++ b/examples/basic/content/docs/guides/installation.mdx
@@ -4,8 +4,6 @@ description: Detailed installation instructions
 order: 1
 ---
 
-# Installation
-
 ## System Requirements
 
 | Requirement | Version |
diff --git a/examples/basic/content/docs/index.mdx b/examples/basic/content/docs/index.mdx
index 450435a2..1938c8af 100644
--- a/examples/basic/content/docs/index.mdx
+++ b/examples/basic/content/docs/index.mdx
@@ -4,7 +4,8 @@ description: Getting started with Chronicle documentation
 order: 1
 ---
 
-# Heading 1
+The page title above comes from frontmatter, so the headings below start at
+`##`. A page body has no `#` of its own.
 
 ## Heading 2
 
diff --git a/examples/basic/content/docs/tips-&-tricks.mdx b/examples/basic/content/docs/tips-&-tricks.mdx
index 9a89d35b..3bc5ec30 100644
--- a/examples/basic/content/docs/tips-&-tricks.mdx
+++ b/examples/basic/content/docs/tips-&-tricks.mdx
@@ -4,6 +4,4 @@ description: Useful tips and tricks
 order: 10
 ---
 
-# Tips & Tricks
-
 Some helpful tips and tricks for using Chronicle.
diff --git a/examples/versioned/content/dev/api.mdx b/examples/versioned/content/dev/api.mdx
index ec45b23a..a00284e4 100644
--- a/examples/versioned/content/dev/api.mdx
+++ b/examples/versioned/content/dev/api.mdx
@@ -4,8 +4,6 @@ order: 2
 authors: [jane, Sam Patel, Ana Ruiz <ana@example.com>]
 ---
 
-# Dev API notes — latest
-
 Latest `/dev/api`.
 
 - [Dev Home](./index.mdx)
diff --git a/examples/versioned/content/dev/index.mdx b/examples/versioned/content/dev/index.mdx
index 1ff62d55..a9056ff6 100644
--- a/examples/versioned/content/dev/index.mdx
+++ b/examples/versioned/content/dev/index.mdx
@@ -3,8 +3,6 @@ title: Dev home (3.0)
 order: 1
 ---
 
-# Dev — latest
-
 Latest `/dev`.
 
 - [API Notes](./api.mdx)
diff --git a/examples/versioned/content/docs/guide.mdx b/examples/versioned/content/docs/guide.mdx
index 30d3ba21..2dffea7b 100644
--- a/examples/versioned/content/docs/guide.mdx
+++ b/examples/versioned/content/docs/guide.mdx
@@ -4,8 +4,6 @@ order: 2
 authors: [jane]
 ---
 
-# Guide — latest docs
-
 Latest `/docs/guide`.
 
 - [Docs Home](./index.mdx)
diff --git a/examples/versioned/content/docs/index.mdx b/examples/versioned/content/docs/index.mdx
index 289077b8..b24e5d4c 100644
--- a/examples/versioned/content/docs/index.mdx
+++ b/examples/versioned/content/docs/index.mdx
@@ -4,8 +4,6 @@ description: Latest docs landing
 order: 1
 ---
 
-# Docs — latest
-
 This is `/docs` on latest (3.0).
 
 ## Links
diff --git a/examples/versioned/versions/v1/dev/index.mdx b/examples/versioned/versions/v1/dev/index.mdx
index e92a6fe5..0b6d3154 100644
--- a/examples/versioned/versions/v1/dev/index.mdx
+++ b/examples/versioned/versions/v1/dev/index.mdx
@@ -3,6 +3,4 @@ title: Developer Guide (1.0)
 order: 1
 ---
 
-# Developer Guide — v1
-
 In v1, `dev/` was relabeled "Developer Guide" and came first.
diff --git a/examples/versioned/versions/v1/docs/index.mdx b/examples/versioned/versions/v1/docs/index.mdx
index 1da05910..481cc0f4 100644
--- a/examples/versioned/versions/v1/docs/index.mdx
+++ b/examples/versioned/versions/v1/docs/index.mdx
@@ -3,6 +3,4 @@ title: Docs home (1.0)
 order: 2
 ---
 
-# Docs — v1
-
 `/v1/docs` landing. Legacy version.
diff --git a/examples/versioned/versions/v2/docs/guide.mdx b/examples/versioned/versions/v2/docs/guide.mdx
index 100acedd..90ca2011 100644
--- a/examples/versioned/versions/v2/docs/guide.mdx
+++ b/examples/versioned/versions/v2/docs/guide.mdx
@@ -3,6 +3,4 @@ title: Guide (v2)
 order: 2
 ---
 
-# Guide — v2
-
 `/v2/docs/guide`.
diff --git a/examples/versioned/versions/v2/docs/index.mdx b/examples/versioned/versions/v2/docs/index.mdx
index bb623bbb..bed465b7 100644
--- a/examples/versioned/versions/v2/docs/index.mdx
+++ b/examples/versioned/versions/v2/docs/index.mdx
@@ -3,6 +3,4 @@ title: Docs home (2.0)
 order: 1
 ---
 
-# Docs — v2
-
 `/v2/docs` landing.
diff --git a/packages/chronicle/src/cli/commands/init.ts b/packages/chronicle/src/cli/commands/init.ts
index 39fe84bb..80146a66 100644
--- a/packages/chronicle/src/cli/commands/init.ts
+++ b/packages/chronicle/src/cli/commands/init.ts
@@ -15,14 +15,14 @@ export const defaultInitConfig: ChronicleConfig = {
   search: { enabled: true, placeholder: 'Search documentation...' }
 };
 
+// No `# Welcome` heading: every theme prints the frontmatter title above the
+// article, so a heading here would show the same words twice.
 const sampleMdx = `---
 title: Welcome
 description: Getting started with your documentation
 order: 1
 ---
 
-# Welcome
-
 This is your documentation home page.
 `;
 

From 4a8d8d0d95735c5c688bffe694e57a76337fd582 Mon Sep 17 00:00:00 2001
From: Ravi Suhag <suhag.ravi@gmail.com>
Date: Wed, 2 Sep 2026 19:08:29 -0500
Subject: [PATCH 07/10] fix: address review findings, and trim the commentary
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CodeRabbit flagged eight things on #185. Seven were real.

The serious one: identifying a content directory by the shape of its urls broke
a section that holds only sub-folders. No index page and no page directly under
the prefix meant the wrapper failed the depth check, and with a sibling section
present the tree came back empty — an empty sidebar.

The heuristic is gone. `buildFiles` already marks every content root with
`root: true`, and fumadocs carries that onto the folder node; it was only
missing because `compactTree` dropped it before the tree reached a layout.
Keeping it on folders makes the check explicit, and the three-signal guess with
it. `KEEP_FIELDS` gains `root` for folders only — it means nothing on a page or
a separator, and a test already pinned that.

`splitContentRoot` took the first marker in array order rather than the deepest
in the path, so a project inside a directory named `versions` resolved its
images against the wrong root.

Sidebar groups used `defaultOpen`, which is read once on mount. Client-side
navigation does not remount the tree, so a group the reader collapsed stayed
shut over the page they then opened. Controlled now, reopening when it holds the
active page and otherwise leaving the reader's choice alone.

`Logo` gained a `labelled` option. Fanfold and paper render the site name beside
it, where announcing it again is noise — and the fallback is Raystack's mark,
which should not speak for a site that is not theirs.

Four documentation corrections, all mine. The request tester's proxy means an
auth token reaches the docs server, so "stays in their browser" was wrong and
worth being plain about. The search index is built on the first readiness or
search request, not at startup — nothing calls `ensureIndex` before then. A page
without `title` renders as `Untitled` rather than failing, so "required" was
overstating it in three places. And pages do not sort before folders: they share
one scale, as the same page said two sections later.

The eighth finding misread the mark's label as the site title. Skipped.

Comments throughout this branch were doing too much explaining. Cut back to what
the code cannot say for itself.
---
 docs/content/docs/deploy/monitoring.mdx       |  7 +-
 docs/content/docs/guides/api-reference.mdx    |  8 +-
 docs/content/docs/guides/migrate.mdx          |  5 +-
 docs/content/docs/reference/frontmatter.mdx   |  6 +-
 docs/content/docs/writing/navigation.mdx      |  3 +-
 docs/content/docs/writing/pages.mdx           |  4 +-
 packages/chronicle/src/cli/commands/init.ts   |  3 +-
 .../src/cli/commands/static-generate.ts       |  2 +-
 packages/chronicle/src/components/ui/logo.tsx | 41 +++++----
 .../src/lib/remark-resolve-images.test.ts     | 14 ++++
 .../src/lib/remark-resolve-images.ts          | 25 +++---
 packages/chronicle/src/lib/source.ts          |  4 +-
 packages/chronicle/src/lib/theme-colors.ts    | 32 ++-----
 packages/chronicle/src/lib/tree-utils.test.ts |  5 +-
 packages/chronicle/src/lib/tree-utils.ts      |  6 +-
 .../chronicle/src/lib/version-source.test.ts  | 36 +++++---
 packages/chronicle/src/lib/version-source.ts  | 49 ++---------
 packages/chronicle/src/pages/NotFound.tsx     |  3 +-
 packages/chronicle/src/server/App.tsx         |  6 +-
 .../chronicle/src/server/entry-server.tsx     |  3 +-
 .../src/themes/default/Layout.module.css      | 12 +--
 .../chronicle/src/themes/default/Layout.tsx   | 83 +++++++++++--------
 .../src/themes/fanfold/Layout.module.css      |  8 +-
 .../chronicle/src/themes/fanfold/Layout.tsx   |  2 +-
 .../chronicle/src/themes/fanfold/Page.tsx     | 10 +--
 .../src/themes/paper/Layout.module.css        |  3 +-
 .../chronicle/src/themes/paper/Layout.tsx     |  2 +-
 27 files changed, 186 insertions(+), 196 deletions(-)

diff --git a/docs/content/docs/deploy/monitoring.mdx b/docs/content/docs/deploy/monitoring.mdx
index efd43918..e339b40f 100644
--- a/docs/content/docs/deploy/monitoring.mdx
+++ b/docs/content/docs/deploy/monitoring.mdx
@@ -34,9 +34,10 @@ building, and `503` before that.
 { "status": "not_ready", "search": false }
 ```
 
-The index is built in the background at startup, so a large site is briefly up
-but not ready. Point your readiness or startup check here and a rolling deploy
-will not send traffic to an instance whose search is still empty.
+The first request to this endpoint is what starts the index building, in the
+background. A large site is briefly up but not ready. Point your readiness or
+startup check here and a rolling deploy will not send traffic to an instance
+whose search is still empty — and will get the indexing under way.
 
 Using `/api/health` for both is the common mistake. It reports success
 immediately, so traffic arrives before search works.
diff --git a/docs/content/docs/guides/api-reference.mdx b/docs/content/docs/guides/api-reference.mdx
index cbed26e8..cf18793a 100644
--- a/docs/content/docs/guides/api-reference.mdx
+++ b/docs/content/docs/guides/api-reference.mdx
@@ -88,15 +88,17 @@ If the spec declares `securitySchemes`, Chronicle reads those instead and offers
 the schemes it finds — API key, bearer token or basic auth. The `auth` config
 above is for a spec that does not say.
 
-Whatever a reader types stays in their browser. It is never sent anywhere except
-to the API they are testing against.
-
 ### The request tester and CORS
 
 Requests go through a proxy on your docs server rather than straight from the
 browser. That is deliberate: most APIs do not allow cross-origin requests from a
 docs site, so a direct call would fail before it left the page.
 
+It also means the token a reader types reaches your docs server on its way to
+the API. It is not stored or logged, but the server does handle it — so tell
+readers to use a test credential on a docs site you do not control, and treat
+your own docs host as something that needs the same trust as the API behind it.
+
 This means the API has to be reachable from wherever your docs are hosted. An
 API on a private network works when you run `chronicle dev` on the same network
 and does not work from a public host.
diff --git a/docs/content/docs/guides/migrate.mdx b/docs/content/docs/guides/migrate.mdx
index 5ac58058..1a3fa742 100644
--- a/docs/content/docs/guides/migrate.mdx
+++ b/docs/content/docs/guides/migrate.mdx
@@ -28,8 +28,9 @@ of things that usually need a look.
 
 ## Add a title to every page
 
-`title` is the one required field. A page without it falls back to `Untitled` in
-the sidebar and the browser tab.
+Give every page a `title`. Nothing fails without one — the page renders as
+`Untitled` in the sidebar and the browser tab, which is easy to miss until a
+reader finds it.
 
 If your pages open with an `# H1` and no frontmatter, that heading is the title —
 move it up:
diff --git a/docs/content/docs/reference/frontmatter.mdx b/docs/content/docs/reference/frontmatter.mdx
index e8c8d48d..93671112 100644
--- a/docs/content/docs/reference/frontmatter.mdx
+++ b/docs/content/docs/reference/frontmatter.mdx
@@ -27,7 +27,7 @@ Your content here...
 
 | Field | Type | What it does |
 |---|---|---|
-| `title` | `string` | **Required.** Heading, sidebar label, browser tab |
+| `title` | `string` | Heading, sidebar label, browser tab. Falls back to `Untitled` |
 | `description` | `string` | Line under the heading, meta description, social card |
 | `order` | `number` | Sidebar position. Lower first. Decimals allowed |
 | `draft` | `boolean` | `true` removes the page from the site |
@@ -41,7 +41,9 @@ Your content here...
 
 ### title
 
-**Required.** The page title used in navigation, browser tab, and page heading.
+The page title used in navigation, the browser tab, and the heading above the
+article. A page without one renders as `Untitled`, so treat it as required even
+though nothing enforces it.
 
 ```yaml
 title: Installation Guide
diff --git a/docs/content/docs/writing/navigation.mdx b/docs/content/docs/writing/navigation.mdx
index 65ebe326..13a14ce7 100644
--- a/docs/content/docs/writing/navigation.mdx
+++ b/docs/content/docs/writing/navigation.mdx
@@ -53,7 +53,8 @@ Quick start
     Advanced
 ```
 
-Pages sitting directly in the content directory appear before the folders.
+Pages and folders sort against each other on one scale, so where a folder lands
+depends on its `order`, not on it being a folder. Without one it goes last.
 
 ## meta.json
 
diff --git a/docs/content/docs/writing/pages.mdx b/docs/content/docs/writing/pages.mdx
index 5ef31469..3c2cb1f7 100644
--- a/docs/content/docs/writing/pages.mdx
+++ b/docs/content/docs/writing/pages.mdx
@@ -23,7 +23,7 @@ job, which is useful when the folder is also browsed on GitHub.
 
 ## Frontmatter
 
-Every page opens with a YAML block. Only `title` is required:
+Every page opens with a YAML block. `title` is the only one you always want:
 
 ```mdx
 ---
@@ -41,7 +41,7 @@ The four fields you will use on nearly every page:
 
 | Field | What it does |
 |---|---|
-| `title` | **Required.** The heading above the article, the sidebar label, the browser tab |
+| `title` | The heading above the article, the sidebar label, the browser tab. Always set it |
 | `description` | The line under the heading, plus the meta description and social card |
 | `order` | Where the page sits in the sidebar. Lower first |
 | `draft` | `true` keeps the page out of the site while you write it |
diff --git a/packages/chronicle/src/cli/commands/init.ts b/packages/chronicle/src/cli/commands/init.ts
index 80146a66..dd1a4989 100644
--- a/packages/chronicle/src/cli/commands/init.ts
+++ b/packages/chronicle/src/cli/commands/init.ts
@@ -15,8 +15,7 @@ export const defaultInitConfig: ChronicleConfig = {
   search: { enabled: true, placeholder: 'Search documentation...' }
 };
 
-// No `# Welcome` heading: every theme prints the frontmatter title above the
-// article, so a heading here would show the same words twice.
+// No `# Welcome`: themes print the frontmatter title above the article.
 const sampleMdx = `---
 title: Welcome
 description: Getting started with your documentation
diff --git a/packages/chronicle/src/cli/commands/static-generate.ts b/packages/chronicle/src/cli/commands/static-generate.ts
index ee6e410e..b61be5f4 100644
--- a/packages/chronicle/src/cli/commands/static-generate.ts
+++ b/packages/chronicle/src/cli/commands/static-generate.ts
@@ -373,7 +373,7 @@ function computeNavigation(
 ): Map<string, { prev: PageNavLink | null; next: PageNavLink | null }> {
   const navMap = new Map<string, { prev: PageNavLink | null; next: PageNavLink | null }>();
 
-  // Chained per section, matching the dev server. See `getNavMap` in source.ts.
+  // Chained per section, matching `getNavMap` in source.ts.
   const prefixes = contentSectionPrefixes(config);
   const bySection = new Map<string, ReturnType<typeof flattenTreeUrls>>();
   for (const entry of flattenTreeUrls(tree)) {
diff --git a/packages/chronicle/src/components/ui/logo.tsx b/packages/chronicle/src/components/ui/logo.tsx
index 483ffaec..4bcf620f 100644
--- a/packages/chronicle/src/components/ui/logo.tsx
+++ b/packages/chronicle/src/components/ui/logo.tsx
@@ -4,21 +4,20 @@ import { useTheme } from '@raystack/apsara';
 import type { ChronicleConfig } from '@/types';
 
 /**
- * The Raystack mark, from `raystack/website` (`public/brand/logo.svg`).
- *
- * Drawn with `currentColor` rather than the brand navy so it reads on a dark
- * page as well as a light one, and so a theme can tint it by setting a text
- * colour on the element around it. The single path is the shape as the brand
- * file draws it, with its flat radial gradient replaced by that fill.
+ * The Raystack mark, from `raystack/website` (`public/brand/logo.svg`). Drawn
+ * with `currentColor` so it reads on either ground and a theme can tint it.
  */
 export function RaystackMark({
   width = 28,
   height = 28,
   className,
+  label,
 }: {
   width?: number;
   height?: number;
   className?: string;
+  /** Omit to hide the mark from assistive technology. */
+  label?: string;
 }) {
   return (
     <svg
@@ -27,8 +26,9 @@ export function RaystackMark({
       width={width}
       height={height}
       className={className}
-      role='img'
-      aria-label='Raystack'
+      role={label ? 'img' : undefined}
+      aria-label={label}
+      aria-hidden={label ? undefined : true}
       fill='currentColor'
     >
       <path d='M1.0995468,30.0536799 L101.718938,88.1466179 C100.73439,89.5383643 99.4491496,90.7266003 97.9230485,91.6076952 L57.9615242,114.679492 C54.2487113,116.823085 49.6743371,116.823085 45.9615242,114.679492 L6,91.6076952 C2.28718708,89.4641016 0,85.5025774 0,81.2153903 L0,35.0717968 C0,33.3095155 0.386462402,31.6022611 1.0995468,30.0536799 Z M18.757,17.313 L103.923,66.483 L103.923048,81.2153903 C103.923048,81.7371223 103.889176,82.2540313 103.822983,82.7634277 L4.70864397,25.540743 C5.11691976,25.2284994 5.54789032,24.9405176 6,24.6794919 L18.757,17.313 Z M35.253,7.789 L103.923,47.435 L103.923,59.885 L24.471,14.014 L35.253,7.789 Z M57.9615242,1.60769515 L97.9230485,24.6794919 C101.635861,26.8230855 103.923048,30.7846097 103.923048,35.0717968 L103.923,40.838 L40.967,4.49 L45.9615242,1.60769515 C49.6743371,-0.535898385 54.2487113,-0.535898385 57.9615242,1.60769515 Z' />
@@ -41,16 +41,18 @@ interface LogoProps {
   /** Box the logo is drawn in, in px. Square. */
   size?: number;
   className?: string;
+  /**
+   * Whether assistive technology should announce the logo. Pass `false` where
+   * the site name is already rendered beside it, or it is read out twice.
+   */
+  labelled?: boolean;
 }
 
 /**
  * A site's logo: whichever of `logo.light` / `logo.dark` suits the active
- * theme, falling back to the Raystack mark when a site declares neither.
- *
- * Shared by every theme so the fallback is the same picture everywhere, and so
- * a site that sets one logo gets it in all three.
+ * theme, falling back to the Raystack mark when a site sets neither.
  */
-export function Logo({ config, size = 28, className }: LogoProps) {
+export function Logo({ config, size = 28, className, labelled = true }: LogoProps) {
   const { resolvedTheme } = useTheme();
   const logo = config.logo;
 
@@ -63,7 +65,7 @@ export function Logo({ config, size = 28, className }: LogoProps) {
     return (
       <img
         src={src}
-        alt={config.site.title}
+        alt={labelled ? config.site.title : ''}
         width={size}
         height={size}
         className={className}
@@ -71,5 +73,14 @@ export function Logo({ config, size = 28, className }: LogoProps) {
     );
   }
 
-  return <RaystackMark width={size} height={size} className={className} />;
+  // The fallback is Raystack's mark, not the site's, so it never speaks for a
+  // site that is not theirs — it is named only where nothing else names it.
+  return (
+    <RaystackMark
+      width={size}
+      height={size}
+      className={className}
+      label={labelled ? config.site.title : undefined}
+    />
+  );
 }
diff --git a/packages/chronicle/src/lib/remark-resolve-images.test.ts b/packages/chronicle/src/lib/remark-resolve-images.test.ts
index ebd975e8..18e2b1b2 100644
--- a/packages/chronicle/src/lib/remark-resolve-images.test.ts
+++ b/packages/chronicle/src/lib/remark-resolve-images.test.ts
@@ -176,6 +176,20 @@ describe('versioned pages', () => {
     expect(firstImageUrl(tree)).toBe(`/_content/v1/docs/img.png?v=${PNG_HASH}`);
   });
 
+  test('takes the deepest marker when a project sits under a versions dir', async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'chronicle-remark-d-'));
+    const nested = path.join(root, 'versions', 'project', 'content');
+    fs.mkdirSync(path.join(nested, 'docs'), { recursive: true });
+    fs.writeFileSync(path.join(nested, 'docs', 'img.png'), PNG_BYTES);
+    const { tree } = await transform(
+      '![alt](./img.png)',
+      { optimize: false },
+      nested,
+      path.join(nested, 'docs', 'page.mdx')
+    );
+    expect(firstImageUrl(tree)).toBe(`/_content/docs/img.png?v=${PNG_HASH}`);
+  });
+
   test('exports an empty list when the path is outside any content root', async () => {
     const { file } = await transform(
       'stray file',
diff --git a/packages/chronicle/src/lib/remark-resolve-images.ts b/packages/chronicle/src/lib/remark-resolve-images.ts
index 39d9bbed..f4469db4 100644
--- a/packages/chronicle/src/lib/remark-resolve-images.ts
+++ b/packages/chronicle/src/lib/remark-resolve-images.ts
@@ -58,34 +58,29 @@ function finalizeUrl(url: string, optimize: boolean, version?: string): string {
 const IMG_SRC_PATTERN = /(<img\b[^>]*\bsrc=["'])([^"']+)(["'])/gi
 
 /**
- * Where a page's own tree starts on disk, and where it sits inside it.
+ * Splits a page's path at its content root. The part below the split is also
+ * its path under `/_content/`, which is what image URLs are built from —
+ * `content/docs/` mirrors as `docs/`, `versions/v1/docs/` as `v1/docs/`.
  *
- * The current version lives under `content/`, and older versions under
- * `versions/`. Both are mirrored into `.content/` — `content/docs/` as `docs/`
- * and `versions/v1/docs/` as `v1/docs/` — so the path below the split is also
- * the path under `/_content/`, which is what image URLs are built from.
- *
- * `versions/` used to be unrecognised, so every versioned page returned before
- * exporting `images` and the production build failed on the first one it hit.
+ * Takes the deepest marker, since a project can sit inside a directory named
+ * `versions` and still keep its pages under `content/`.
  */
 function splitContentRoot(
   filePath: string,
 ): { root: string; relative: string } | null {
+  let end = -1
   for (const marker of ['/versions/', '/content/']) {
     const idx = filePath.lastIndexOf(marker)
-    if (idx === -1) continue
-    const end = idx + marker.length
-    return { root: filePath.slice(0, end), relative: filePath.slice(end) }
+    if (idx !== -1) end = Math.max(end, idx + marker.length)
   }
-  return null
+  if (end === -1) return null
+  return { root: filePath.slice(0, end), relative: filePath.slice(end) }
 }
 
 const remarkResolveImages: Plugin<[RemarkResolveImagesOptions?]> = (options) => {
   const optimize = options?.optimize ?? true
   return async (tree, file) => {
-    // Always export something. `valueToExport` names `images`, so a page that
-    // returns before setting it fails the build with a missing-export error
-    // rather than simply having no images.
+    // `valueToExport` names `images`, so returning without it fails the build.
     file.data.images = []
 
     const filePath = file.path?.replace(/\\/g, '/')
diff --git a/packages/chronicle/src/lib/source.ts b/packages/chronicle/src/lib/source.ts
index 6c58d291..6d9d6646 100644
--- a/packages/chronicle/src/lib/source.ts
+++ b/packages/chronicle/src/lib/source.ts
@@ -306,9 +306,7 @@ async function getNavMap(): Promise<Map<string, PageNav>> {
         : titleFromUrl(p.url)
   });
 
-  // Chain within a section, not across the whole site. The last page of "Docs"
-  // used to offer the first page of the next content directory as its next
-  // link, dropping the reader into a different audience's material.
+  // Chained per section: the last page of one should not lead into another.
   const prefixes = contentSectionPrefixes(loadConfig());
   const bySection = new Map<string, typeof pages>();
   for (const page of pages) {
diff --git a/packages/chronicle/src/lib/theme-colors.ts b/packages/chronicle/src/lib/theme-colors.ts
index f440a351..c1f35008 100644
--- a/packages/chronicle/src/lib/theme-colors.ts
+++ b/packages/chronicle/src/lib/theme-colors.ts
@@ -1,35 +1,20 @@
 /**
- * Turns `theme.colors` from `chronicle.yaml` into a stylesheet.
- *
- * Keys name an Apsara colour token. Write the token on its own —
- * `background-base-primary` — and the `--rs-color-` prefix is added, or write
- * the whole custom property yourself if you need one outside that family.
- *
- * The same value applies in light and dark, because the config takes one value
- * per token. A site that needs two different colours should leave the token
- * alone and let the theme pick.
+ * Turns `theme.colors` from `chronicle.yaml` into a stylesheet. A bare key is
+ * an Apsara token and takes the `--rs-color-` prefix; a full custom property is
+ * used as written.
  */
 
-/** A token name, or a full custom property. Nothing else can reach the CSS. */
+/** A token name or a full custom property. Nothing else reaches the CSS. */
 const KEY_PATTERN = /^(--)?[a-z][a-z0-9-]*$/
 
-/**
- * Colours only: hex, `rgb()`, `hsl()`, `color-mix()`, a named colour, or
- * another custom property. Deliberately narrow — this string is written into a
- * stylesheet, so anything that could close a declaration or open a rule has to
- * be impossible.
- */
+/** Colours only. This is written into a stylesheet, so keep it narrow. */
 const VALUE_PATTERN = /^[a-zA-Z0-9#(),.%\s/_-]+$/
 
 function toCustomProperty(key: string): string {
   return key.startsWith('--') ? key : `--rs-color-${key}`
 }
 
-/**
- * The declarations for a config's colours, or an empty string when there are
- * none to write. Entries that do not look like a token and a colour are
- * dropped rather than passed through.
- */
+/** Declarations for a config's colours. Malformed entries are dropped. */
 export function buildThemeColorCss(
   colors: Record<string, string> | undefined,
 ): string {
@@ -47,8 +32,7 @@ export function buildThemeColorCss(
 
   if (declarations.length === 0) return ''
 
-  // Both `data-theme` selectors are listed so an override still wins once a
-  // reader picks a theme explicitly — Apsara defines its dark values behind
-  // that attribute, which outranks a bare `:root`.
+  // Apsara's dark values sit behind `[data-theme]`, which outranks a bare
+  // `:root` — so both selectors are needed for an override to hold.
   return `:root,\n:root[data-theme='light'],\n:root[data-theme='dark'] {\n  ${declarations.join('\n  ')}\n}`
 }
diff --git a/packages/chronicle/src/lib/tree-utils.test.ts b/packages/chronicle/src/lib/tree-utils.test.ts
index 0c4aaca8..be508a57 100644
--- a/packages/chronicle/src/lib/tree-utils.test.ts
+++ b/packages/chronicle/src/lib/tree-utils.test.ts
@@ -181,7 +181,7 @@ describe('compactTree', () => {
     expect(result.children[0]).toEqual({ type: 'page', name: 'Intro', url: '/docs/intro' })
   })
 
-  test('strips description and root from folder nodes', () => {
+  test('strips description from folder nodes but keeps root', () => {
     const tree: Root = {
       name: 'root',
       children: [{
@@ -193,7 +193,8 @@ describe('compactTree', () => {
     const result = compactTree(tree)
     const folder = result.children[0] as any
     expect(folder.description).toBeUndefined()
-    expect(folder.root).toBeUndefined()
+    // Layouts scope the tree by `root`, so it has to survive serialisation.
+    expect(folder.root).toBe(true)
     expect(folder.name).toBe('Guides')
     expect(folder.children[0]).toEqual({ type: 'page', name: 'Install', url: '/guides/install' })
   })
diff --git a/packages/chronicle/src/lib/tree-utils.ts b/packages/chronicle/src/lib/tree-utils.ts
index 70eab8a1..c2b07356 100644
--- a/packages/chronicle/src/lib/tree-utils.ts
+++ b/packages/chronicle/src/lib/tree-utils.ts
@@ -14,6 +14,10 @@ const KEEP_FIELDS = new Set([
   'index',
 ]);
 
+// `root` marks a content directory, which layouts scope the tree by. Folders
+// only — it means nothing on a page or a separator.
+const FOLDER_FIELDS = new Set([...KEEP_FIELDS, 'root']);
+
 function compactLeaf(node: Node): Node {
   const out: Record<string, unknown> = {};
   for (const [k, v] of Object.entries(node)) {
@@ -27,7 +31,7 @@ function compactNode(node: Node): Node {
   if (node.type !== 'folder') return compactLeaf(node);
   const out: Record<string, unknown> = {};
   for (const [k, v] of Object.entries(node)) {
-    if (!KEEP_FIELDS.has(k)) continue;
+    if (!FOLDER_FIELDS.has(k)) continue;
     if (k === 'children') out.children = (v as Node[]).map(compactNode);
     else if (k === 'index') out.index = compactLeaf(v as Node);
     else out[k] = v;
diff --git a/packages/chronicle/src/lib/version-source.test.ts b/packages/chronicle/src/lib/version-source.test.ts
index e585f83c..67d5448c 100644
--- a/packages/chronicle/src/lib/version-source.test.ts
+++ b/packages/chronicle/src/lib/version-source.test.ts
@@ -40,6 +40,15 @@ function folder(name: string, children: (Item | Folder)[]): Folder {
   return { type: 'folder', name, children }
 }
 
+/** A content directory. `buildFiles` marks every one of these with `root`. */
+function contentRoot(
+  name: string,
+  children: (Item | Folder)[],
+  index?: Item,
+): Folder {
+  return { type: 'folder', name, root: true, children, ...(index ? { index } : {}) }
+}
+
 describe('resolveVersionFromUrl', () => {
   const config = makeConfig()
 
@@ -142,8 +151,8 @@ describe('filterPageTreeByVersion', () => {
 })
 
 describe('filterPageTreeByContentDir', () => {
-  const latestDocs = folder('docs', [page('/docs/a'), page('/docs/b')])
-  const latestDev = folder('dev', [page('/dev/x')])
+  const latestDocs = contentRoot('docs', [page('/docs/a'), page('/docs/b')])
+  const latestDev = contentRoot('dev', [page('/dev/x')])
   const latestTree: Root = {
     name: 'root',
     children: [latestDocs, latestDev],
@@ -165,8 +174,8 @@ describe('filterPageTreeByContentDir', () => {
   })
 
   test('uses version urlPrefix to disambiguate within a version', () => {
-    const v1Docs = folder('docs', [page('/v1/docs/a')])
-    const v1Dev = folder('dev', [page('/v1/dev/x')])
+    const v1Docs = contentRoot('docs', [page('/v1/docs/a')])
+    const v1Dev = contentRoot('dev', [page('/v1/dev/x')])
     const ctx = { dir: 'v1', urlPrefix: '/v1' }
     const tree: Root = { name: 'root', children: [v1Docs, v1Dev] }
     expect(
@@ -180,14 +189,7 @@ describe('filterPageTreeByContentDir', () => {
     // label then shows as a heading above every page in the sidebar.
     const wrapped: Root = {
       name: 'root',
-      children: [
-        {
-          type: 'folder',
-          name: 'Docs',
-          index: page('/docs'),
-          children: [page('/docs/a'), page('/docs/b')],
-        } as Folder,
-      ],
+      children: [contentRoot('Docs', [page('/docs/a'), page('/docs/b')], page('/docs'))],
     }
     const out = filterPageTreeByContentDir(wrapped, LATEST_CONTEXT, 'docs')
     expect(out.children).toEqual([page('/docs/a'), page('/docs/b')])
@@ -204,6 +206,16 @@ describe('filterPageTreeByContentDir', () => {
     expect(out.children).toEqual(scoped.children)
   })
 
+  test('unwraps a section that holds only sub-folders', () => {
+    // No index page and no page directly under the prefix. Identifying the
+    // wrapper by url shape alone got this wrong and emptied the sidebar.
+    const docs = contentRoot('Docs', [folder('guides', [page('/docs/guides/a')])])
+    const dev = contentRoot('Dev', [page('/dev/x')])
+    const tree: Root = { name: 'root', children: [docs, dev] }
+    const out = filterPageTreeByContentDir(tree, LATEST_CONTEXT, 'docs')
+    expect(out.children).toEqual(docs.children)
+  })
+
   test('leaves an already scoped flat tree alone', () => {
     // A single content directory with no sub-folders: after `entry-server`
     // scopes it the children are the pages themselves, and looking for a
diff --git a/packages/chronicle/src/lib/version-source.ts b/packages/chronicle/src/lib/version-source.ts
index 5ddf6fec..626c5ac9 100644
--- a/packages/chronicle/src/lib/version-source.ts
+++ b/packages/chronicle/src/lib/version-source.ts
@@ -68,16 +68,9 @@ function nodeMatchesVersion(
 }
 
 /**
- * True when every page already in `tree` sits under `prefix`, so the tree has
- * been narrowed to that prefix once already.
- *
- * Both filters below are called twice on the same tree: `entry-server` narrows
- * it before serialising, and then a layout or theme narrows what it is handed.
- * Without this check the second pass mistakes the first sub-folder for the
- * thing it is looking for and returns only that folder's pages — or, for a flat
- * directory with no sub-folder at all, returns nothing and empties the
- * navigation. Recognising an already-narrowed tree makes both filters safe to
- * apply as many times as callers like.
+ * True when `tree` has already been narrowed to `prefix`. Both filters run
+ * twice on the same tree — `entry-server` before serialising, then a layout —
+ * so both have to be safe to repeat.
  */
 function isAlreadyScoped(tree: Root, prefix: string): boolean {
   const urls = tree.children.flatMap(nodeUrls)
@@ -111,31 +104,12 @@ export function filterPageTreeByContentDir(
   if (contentDir === null) return tree
   const expectedPrefix = `${ctx.urlPrefix}/${contentDir}`
 
-  // A page sitting directly at or under the prefix is one of the content
-  // directory's own pages, so the tree is its contents, not a container of it.
-  const holdsOwnPages = tree.children.some(
-    (n) => n.type === 'page' && isUnderPrefix(n.url, expectedPrefix),
-  )
-  if (holdsOwnPages) return tree
-
-  // Otherwise look for the one folder that *is* this content directory. Three
-  // things have to hold, and a sub-folder — whose urls also all start with the
-  // prefix — fails the last two:
-  //   1. every url inside it belongs to the directory,
-  //   2. it holds every url in the tree that belongs to the directory,
-  //   3. it has a page of its own directly below the prefix, rather than only
-  //      pages nested further down.
-  const depth = (url: string) => url.split('/').filter(Boolean).length
-  const prefixDepth = depth(expectedPrefix)
-  const underPrefix = tree.children
-    .flatMap(nodeUrls)
-    .filter((u) => isUnderPrefix(u, expectedPrefix))
+  // `root` marks a content directory — `buildFiles` sets it on every one. A
+  // sub-folder never carries it, which is what url shapes alone cannot tell us.
   const match = tree.children.find((n): n is Folder => {
-    if (n.type !== 'folder') return false
+    if (n.type !== 'folder' || n.root !== true) return false
     const urls = nodeUrls(n)
-    if (urls.length === 0 || urls.length !== underPrefix.length) return false
-    if (!urls.every((u) => isUnderPrefix(u, expectedPrefix))) return false
-    return urls.some((u) => u === expectedPrefix || depth(u) === prefixDepth + 1)
+    return urls.length > 0 && urls.every((u) => isUnderPrefix(u, expectedPrefix))
   })
   if (match) return { ...tree, children: match.children }
 
@@ -143,6 +117,7 @@ export function filterPageTreeByContentDir(
   return { ...tree, children: [] }
 }
 
+
 /**
  * Every content section's URL prefix — `/docs`, `/dev`, `/v1/docs` — longest
  * first, so `/v1/docs` is tested before `/v1` could ever shadow it.
@@ -157,13 +132,7 @@ export function contentSectionPrefixes(config: ChronicleConfig): string[] {
   return prefixes.sort((a, b) => b.length - a.length)
 }
 
-/**
- * The section a page belongs to, or null if it sits outside every one.
- *
- * Previous and next links are chained inside a section rather than across the
- * whole site: sections exist to keep separate audiences apart, so walking off
- * the end of one into another undoes the point of having them.
- */
+/** The section a page belongs to, or null if it sits outside every one. */
 export function sectionOf(url: string, prefixes: string[]): string | null {
   return prefixes.find((p) => isUnderPrefix(url, p)) ?? null
 }
diff --git a/packages/chronicle/src/pages/NotFound.tsx b/packages/chronicle/src/pages/NotFound.tsx
index e9dfe6e8..bfd33501 100644
--- a/packages/chronicle/src/pages/NotFound.tsx
+++ b/packages/chronicle/src/pages/NotFound.tsx
@@ -9,8 +9,7 @@ export function NotFound() {
 
   return (
     <div className={styles.emptyStateHost}>
-      {/* The page that was asked for renders no `<Head>` of its own, so
-          without this the tab would carry whatever the last page set. */}
+      {/* The requested page renders no `<Head>`, so name the tab here. */}
       <Head title='Page not found' config={config} />
       <EmptyState
         icon={<FileTextIcon width={32} height={32} />}
diff --git a/packages/chronicle/src/server/App.tsx b/packages/chronicle/src/server/App.tsx
index 5cd92ce0..343118c5 100644
--- a/packages/chronicle/src/server/App.tsx
+++ b/packages/chronicle/src/server/App.tsx
@@ -81,10 +81,8 @@ function PageFallback() {
 }
 
 /**
- * Site-wide head tags. The page title is deliberately not among them: every
- * route renders its own `<Head>`, and a title here would be hoisted into the
- * document ahead of that one. The browser reads the first `<title>` it finds,
- * so the tab said "Chronicle" on every page instead of naming the page.
+ * Site-wide head tags. No `<title>` — every route renders its own, and one here
+ * would hoist ahead of it, which is the title the browser would then use.
  */
 function RootHead({ config }: { config: ChronicleConfig }) {
   const siteJsonLd = config.url
diff --git a/packages/chronicle/src/server/entry-server.tsx b/packages/chronicle/src/server/entry-server.tsx
index b6fada3d..7b35e9f1 100644
--- a/packages/chronicle/src/server/entry-server.tsx
+++ b/packages/chronicle/src/server/entry-server.tsx
@@ -194,8 +194,7 @@ export default {
           {assets.js.map((attr: { href: string }) => (
             <link key={attr.href} rel="modulepreload" {...attr} />
           ))}
-          {/* After the stylesheets, so a site's own colours win over the
-              theme's defaults. */}
+          {/* After the stylesheets, so a site's colours win. */}
           {themeColorCss && (
             <style dangerouslySetInnerHTML={{ __html: themeColorCss }} />
           )}
diff --git a/packages/chronicle/src/themes/default/Layout.module.css b/packages/chronicle/src/themes/default/Layout.module.css
index 03f691ed..fe3e2951 100644
--- a/packages/chronicle/src/themes/default/Layout.module.css
+++ b/packages/chronicle/src/themes/default/Layout.module.css
@@ -82,10 +82,8 @@
   display: flex;
   flex-direction: column;
   gap: 0;
-  /* These are the site's sections; the tree below belongs to the one you are
-     in. Without this they run together, because the tree may start with a plain
-     page rather than a group carrying its own top margin. Matches the spacing
-     Apsara puts between groups. */
+  /* Separates the site's sections from the tree below, which may start with a
+     plain page carrying no margin of its own. */
   margin-bottom: var(--rs-space-4);
 }
 
@@ -208,10 +206,8 @@
   margin-top: 0;
 }
 
-/* Apsara spaces consecutive nav groups itself and skips the first one, which is
-   the behaviour we want. The only thing to add is the case it cannot see: a
-   first group that follows the content-directory links, which are a separate
-   block above the tree rather than a group. `.topLinks` carries that margin. */
+/* Apsara skips the first group's margin, which is what we want; `.topLinks`
+   carries the separation when a group follows it. */
 .navGroup[data-depth='0']:first-child {
   margin-top: 0;
 }
diff --git a/packages/chronicle/src/themes/default/Layout.tsx b/packages/chronicle/src/themes/default/Layout.tsx
index 7b75d546..4377bca2 100644
--- a/packages/chronicle/src/themes/default/Layout.tsx
+++ b/packages/chronicle/src/themes/default/Layout.tsx
@@ -17,7 +17,7 @@ import { getLandingEntries } from '@/lib/config';
 import { getActiveContentDir } from '@/lib/navigation';
 import { usePageContext } from '@/lib/page-context';
 import { isAuthorRoute, resolveRoute } from '@/lib/route-resolver';
-import type { Node, Root } from 'fumadocs-core/page-tree';
+import type { Folder, Node, Root } from 'fumadocs-core/page-tree';
 import { NodeType } from '@/lib/tree-utils';
 import type { ThemeLayoutProps } from '@/types';
 import styles from './Layout.module.css';
@@ -327,6 +327,52 @@ function hasActiveDescendant(node: Node, pathname: string): boolean {
   return false;
 }
 
+function SidebarGroupNode({
+  item,
+  pathname,
+  depth
+}: {
+  item: Folder;
+  pathname: string;
+  depth: number;
+}) {
+  const icon = typeof item.icon === 'string' ? iconMap[item.icon] : item.icon;
+  const hasActiveChild = hasActiveDescendant(item, pathname);
+  const [open, setOpen] = useState(depth === 0 || hasActiveChild);
+
+  // Client-side navigation does not remount the tree, so a group the reader
+  // collapsed would stay shut over the page they just opened.
+  useEffect(() => {
+    if (hasActiveChild) setOpen(true);
+  }, [hasActiveChild]);
+
+  return (
+    <Sidebar.Group
+      className={styles.navGroup}
+      data-depth={depth}
+      label={item.name?.toString() ?? ''}
+      leadingIcon={icon ?? undefined}
+      collapsible
+      open={open}
+      onOpenChange={setOpen}
+    >
+      {/* The group label is a collapse trigger, not a link, so a folder's index
+          page needs a row of its own. */}
+      {item.index ? (
+        <SidebarNode item={item.index} pathname={pathname} depth={depth + 1} />
+      ) : null}
+      {item.children.map((child, i) => (
+        <SidebarNode
+          key={child.type === 'page' ? child.url : (child.name?.toString() ?? i)}
+          item={child}
+          pathname={pathname}
+          depth={depth + 1}
+        />
+      ))}
+    </Sidebar.Group>
+  );
+}
+
 function SidebarNode({
   item,
   pathname,
@@ -342,40 +388,7 @@ function SidebarNode({
 
   if (item.type === 'folder') {
     if (depth > MAX_SIDEBAR_DEPTH) return null;
-    const icon = typeof item.icon === 'string' ? iconMap[item.icon] : item.icon;
-    const hasActiveChild = hasActiveDescendant(item, pathname);
-    return (
-      <Sidebar.Group
-        className={styles.navGroup}
-        data-depth={depth}
-        label={item.name?.toString() ?? ''}
-        leadingIcon={icon ?? undefined}
-        // Every group can be collapsed. Top-level ones start open so the whole
-        // site is visible on arrival; nested ones open only when they hold the
-        // page being read.
-        collapsible
-        defaultOpen={depth === 0 || hasActiveChild}
-      >
-        {/* A folder's own index page. The group label is a collapse trigger,
-            not a link, so without this row the index page has no way into it
-            from the sidebar at all. */}
-        {item.index ? (
-          <SidebarNode
-            item={item.index}
-            pathname={pathname}
-            depth={depth + 1}
-          />
-        ) : null}
-        {item.children.map((child, i) => (
-          <SidebarNode
-            key={child.type === 'page' ? child.url : (child.name?.toString() ?? i)}
-            item={child}
-            pathname={pathname}
-            depth={depth + 1}
-          />
-        ))}
-      </Sidebar.Group>
-    );
+    return <SidebarGroupNode item={item} pathname={pathname} depth={depth} />;
   }
 
   const isActive = pathname === item.url;
diff --git a/packages/chronicle/src/themes/fanfold/Layout.module.css b/packages/chronicle/src/themes/fanfold/Layout.module.css
index 78889a0b..f1388021 100644
--- a/packages/chronicle/src/themes/fanfold/Layout.module.css
+++ b/packages/chronicle/src/themes/fanfold/Layout.module.css
@@ -254,9 +254,8 @@
   text-decoration: none;
 }
 
-/* The mark sits above the name, letterhead fashion, rather than beside it. The
-   rail is a fixed 240px and the display face is wide: put the mark on the
-   name's line and a title of any length starts breaking mid-word. */
+/* Above the name, not beside it — the rail is 240px and the display face is
+   wide, so sharing a line breaks titles mid-word. */
 .brandLogo {
   display: block;
   margin-bottom: 10px;
@@ -271,8 +270,7 @@
   letter-spacing: 0.06em;
   text-transform: uppercase;
   color: var(--fan-ink);
-  /* The rail is a fixed 240px, so a title with one long word has to break
-     rather than run off the edge. */
+  /* A single long word has to break rather than run off the 240px rail. */
   overflow-wrap: break-word;
 }
 
diff --git a/packages/chronicle/src/themes/fanfold/Layout.tsx b/packages/chronicle/src/themes/fanfold/Layout.tsx
index f4e21829..0d8c3d1b 100644
--- a/packages/chronicle/src/themes/fanfold/Layout.tsx
+++ b/packages/chronicle/src/themes/fanfold/Layout.tsx
@@ -83,7 +83,7 @@ function Brand() {
 
   return (
     <RouterLink to={version.urlPrefix || '/'} className={styles.brand}>
-      <Logo config={config} size={20} className={styles.brandLogo} />
+      <Logo config={config} size={20} className={styles.brandLogo} labelled={false} />
       <span className={styles.brandName}>{config.site.title}</span>
       {label ? <span className={styles.brandVersion}>~/{label}</span> : null}
     </RouterLink>
diff --git a/packages/chronicle/src/themes/fanfold/Page.tsx b/packages/chronicle/src/themes/fanfold/Page.tsx
index 5d44f8b5..c4134522 100644
--- a/packages/chronicle/src/themes/fanfold/Page.tsx
+++ b/packages/chronicle/src/themes/fanfold/Page.tsx
@@ -77,14 +77,8 @@ export function Page({ page, config, tree }: ThemePageProps) {
   const contentDir = getActiveContentDir(pathname, config);
   const section = config.content?.find(c => c.dir === contentDir)?.label;
 
-  /**
-   * The printed header reads as a report on one section, so the trail and the
-   * page counter are both scoped to the content directory being read.
-   *
-   * The tree handed here may already be scoped — `entry-server` narrows it when
-   * a site has a single content directory — but both filters recognise that and
-   * hand such a tree back untouched.
-   */
+  // The trail and the counter both describe one section. Safe to narrow a tree
+  // `entry-server` may already have narrowed — the filters handle that.
   const sectionTree = useMemo(
     () =>
       filterPageTreeByContentDir(
diff --git a/packages/chronicle/src/themes/paper/Layout.module.css b/packages/chronicle/src/themes/paper/Layout.module.css
index 8aa2d343..7c28cf7f 100644
--- a/packages/chronicle/src/themes/paper/Layout.module.css
+++ b/packages/chronicle/src/themes/paper/Layout.module.css
@@ -38,8 +38,7 @@
   flex-shrink: 0;
 }
 
-/* The mark keeps its own width so the drawing is never squeezed, and never
-   gives ground to a long site title. */
+/* Never squeezed by a long site title. */
 .logo {
   flex-shrink: 0;
   color: var(--rs-color-foreground-accent-primary);
diff --git a/packages/chronicle/src/themes/paper/Layout.tsx b/packages/chronicle/src/themes/paper/Layout.tsx
index 4a4204dc..ad92db66 100644
--- a/packages/chronicle/src/themes/paper/Layout.tsx
+++ b/packages/chronicle/src/themes/paper/Layout.tsx
@@ -27,7 +27,7 @@ function SidebarHeader({ config }: { config: ThemeLayoutProps['config'] }) {
   if (entries.length <= 1) {
     return (
       <>
-        <Logo config={config} size={20} className={styles.logo} />
+        <Logo config={config} size={20} className={styles.logo} labelled={false} />
         <Text size="regular" weight="medium" className={styles.title}>
           {config.site.title}
         </Text>

From 03ea14e8f7356cc218d6fff501b810602bd11c99 Mon Sep 17 00:00:00 2001
From: Ravi Suhag <suhag.ravi@gmail.com>
Date: Wed, 2 Sep 2026 19:26:04 -0500
Subject: [PATCH 08/10] feat: fall back to the site's initial, and use the logo
 as the favicon
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The fallback mark was Raystack's. Fine for a Raystack site, wrong for anyone
else's — a project that forgot to set `logo` shipped someone else's branding.
It is now the site's first letter in a tinted box: plain enough to read as
unfinished rather than borrowed. Codepoint-safe, so an emoji or a non-Latin
title survives being taken apart.

Two places ignored `logo` entirely.

The favicon was hardcoded to `/favicon.ico` and `/favicon.svg`, so a site that
set a logo still had to supply favicon files separately, and one that did
neither got no favicon at all. A configured logo is now the icon; the static
files stay as the fallback, so an explicit favicon still works.

Social cards read `logo.dark` alone. A site that set only `light` got a card
with no mark even though its sidebar showed one. Both variants resolve now, and
a site with no logo gets the same initial the sidebar falls back to.

Drawing the box from `currentColor` looked right but was not: Apsara colours its
text components rather than their containers, so the inherited colour is black
in both themes and the letter vanished on a dark ground. It takes explicit
tokens instead. `.brandLogo` in fanfold was setting `display: block` for an svg,
which killed the flex centring — block-level `flex` keeps both.
---
 docs/content/docs/reference/config.mdx        | 22 +++++--
 docs/content/docs/reference/routes.mdx        |  3 +
 .../src/components/ui/logo.module.css         | 17 +++++
 packages/chronicle/src/components/ui/logo.tsx | 65 ++++++++++---------
 .../chronicle/src/lib/site-initial.test.ts    | 24 +++++++
 packages/chronicle/src/lib/site-initial.ts    |  8 +++
 .../chronicle/src/server/entry-server.tsx     | 19 +++++-
 packages/chronicle/src/server/routes/og.tsx   | 28 +++++++-
 .../src/themes/fanfold/Layout.module.css      |  5 +-
 .../src/themes/paper/Layout.module.css        |  1 -
 10 files changed, 147 insertions(+), 45 deletions(-)
 create mode 100644 packages/chronicle/src/components/ui/logo.module.css
 create mode 100644 packages/chronicle/src/lib/site-initial.test.ts
 create mode 100644 packages/chronicle/src/lib/site-initial.ts

diff --git a/docs/content/docs/reference/config.mdx b/docs/content/docs/reference/config.mdx
index db7c5d6d..f7ce2822 100644
--- a/docs/content/docs/reference/config.mdx
+++ b/docs/content/docs/reference/config.mdx
@@ -229,18 +229,30 @@ to run. See [Deploy](/docs/deploy/hosting).
 
 ### logo
 
-Logo with theme-aware variants.
+The mark shown in the sidebar, used as the favicon, and drawn on social cards.
 
 ```yaml
 logo:
-  light: ./logo-light.png
-  dark: ./logo-dark.png
+  light: /logo.svg
+  dark: /logo-dark.svg
 ```
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `light` | `string` | Logo path or URL for light theme |
-| `dark` | `string` | Logo path or URL for dark theme |
+| `light` | `string` | Path or URL used on a light background |
+| `dark` | `string` | Path or URL used on a dark background |
+
+Files live in `public/`, so `public/logo.svg` is written as `/logo.svg`. Setting
+one is enough — the other falls back to it, which is what you want for a mark
+that reads on either background.
+
+Set neither and every theme shows the site's first letter in a tinted box. It is
+deliberately plain, so a site without a logo looks unfinished rather than
+borrowed.
+
+The same image becomes the favicon, replacing `public/favicon.ico` and
+`public/favicon.svg`. Those two are still used when no logo is set, so an
+explicit favicon keeps working.
 
 ### theme
 
diff --git a/docs/content/docs/reference/routes.mdx b/docs/content/docs/reference/routes.mdx
index c2ed9baa..802cc3a5 100644
--- a/docs/content/docs/reference/routes.mdx
+++ b/docs/content/docs/reference/routes.mdx
@@ -89,6 +89,9 @@ directly. It takes what it draws from the query string:
 | `description` | A line under the headline |
 | `authors` | A `By …` line |
 
+The card also carries your `logo`, or the site's first letter when none is set.
+See [`logo`](/docs/reference/config).
+
 Cards are only referenced when `url` is set, because a social network needs an
 absolute URL to fetch the image from.
 
diff --git a/packages/chronicle/src/components/ui/logo.module.css b/packages/chronicle/src/components/ui/logo.module.css
new file mode 100644
index 00000000..166407a8
--- /dev/null
+++ b/packages/chronicle/src/components/ui/logo.module.css
@@ -0,0 +1,17 @@
+/* Explicit tokens rather than `currentColor`: Apsara colours its text
+   components, not their containers, so the inherited colour is black in both
+   themes and a mark drawn from it disappears on a dark ground. */
+.initial {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  border-radius: var(--rs-radius-3);
+  background: var(--rs-color-background-neutral-secondary);
+  color: var(--rs-color-foreground-base-primary);
+  font-weight: 600;
+  line-height: 1;
+  letter-spacing: 0;
+  text-transform: none;
+  user-select: none;
+}
diff --git a/packages/chronicle/src/components/ui/logo.tsx b/packages/chronicle/src/components/ui/logo.tsx
index 4bcf620f..db4f2831 100644
--- a/packages/chronicle/src/components/ui/logo.tsx
+++ b/packages/chronicle/src/components/ui/logo.tsx
@@ -1,38 +1,36 @@
 'use client';
 
 import { useTheme } from '@raystack/apsara';
+import { cx } from 'class-variance-authority';
+import { siteInitial } from '@/lib/site-initial';
 import type { ChronicleConfig } from '@/types';
+import styles from './logo.module.css';
 
-/**
- * The Raystack mark, from `raystack/website` (`public/brand/logo.svg`). Drawn
- * with `currentColor` so it reads on either ground and a theme can tint it.
- */
-export function RaystackMark({
-  width = 28,
-  height = 28,
-  className,
-  label,
-}: {
-  width?: number;
-  height?: number;
+interface SiteInitialProps {
+  title: string;
+  size?: number;
   className?: string;
-  /** Omit to hide the mark from assistive technology. */
+  /** Omit to hide it from assistive technology. */
   label?: string;
-}) {
+}
+
+/** A site's first letter in a tinted box. The mark for a site that sets none. */
+export function SiteInitial({
+  title,
+  size = 28,
+  className,
+  label
+}: SiteInitialProps) {
   return (
-    <svg
-      xmlns='http://www.w3.org/2000/svg'
-      viewBox='0 0 103.923048 116.287187'
-      width={width}
-      height={height}
-      className={className}
+    <span
+      className={cx(styles.initial, className)}
+      style={{ width: size, height: size, fontSize: Math.round(size * 0.46) }}
       role={label ? 'img' : undefined}
       aria-label={label}
       aria-hidden={label ? undefined : true}
-      fill='currentColor'
     >
-      <path d='M1.0995468,30.0536799 L101.718938,88.1466179 C100.73439,89.5383643 99.4491496,90.7266003 97.9230485,91.6076952 L57.9615242,114.679492 C54.2487113,116.823085 49.6743371,116.823085 45.9615242,114.679492 L6,91.6076952 C2.28718708,89.4641016 0,85.5025774 0,81.2153903 L0,35.0717968 C0,33.3095155 0.386462402,31.6022611 1.0995468,30.0536799 Z M18.757,17.313 L103.923,66.483 L103.923048,81.2153903 C103.923048,81.7371223 103.889176,82.2540313 103.822983,82.7634277 L4.70864397,25.540743 C5.11691976,25.2284994 5.54789032,24.9405176 6,24.6794919 L18.757,17.313 Z M35.253,7.789 L103.923,47.435 L103.923,59.885 L24.471,14.014 L35.253,7.789 Z M57.9615242,1.60769515 L97.9230485,24.6794919 C101.635861,26.8230855 103.923048,30.7846097 103.923048,35.0717968 L103.923,40.838 L40.967,4.49 L45.9615242,1.60769515 C49.6743371,-0.535898385 54.2487113,-0.535898385 57.9615242,1.60769515 Z' />
-    </svg>
+      {siteInitial(title)}
+    </span>
   );
 }
 
@@ -42,17 +40,22 @@ interface LogoProps {
   size?: number;
   className?: string;
   /**
-   * Whether assistive technology should announce the logo. Pass `false` where
-   * the site name is already rendered beside it, or it is read out twice.
+   * Whether assistive technology should announce it. Pass `false` where the
+   * site name is already rendered beside it, or it is read out twice.
    */
   labelled?: boolean;
 }
 
 /**
  * A site's logo: whichever of `logo.light` / `logo.dark` suits the active
- * theme, falling back to the Raystack mark when a site sets neither.
+ * theme, falling back to the site's initial when it sets neither.
  */
-export function Logo({ config, size = 28, className, labelled = true }: LogoProps) {
+export function Logo({
+  config,
+  size = 28,
+  className,
+  labelled = true
+}: LogoProps) {
   const { resolvedTheme } = useTheme();
   const logo = config.logo;
 
@@ -73,12 +76,10 @@ export function Logo({ config, size = 28, className, labelled = true }: LogoProp
     );
   }
 
-  // The fallback is Raystack's mark, not the site's, so it never speaks for a
-  // site that is not theirs — it is named only where nothing else names it.
   return (
-    <RaystackMark
-      width={size}
-      height={size}
+    <SiteInitial
+      title={config.site.title}
+      size={size}
       className={className}
       label={labelled ? config.site.title : undefined}
     />
diff --git a/packages/chronicle/src/lib/site-initial.test.ts b/packages/chronicle/src/lib/site-initial.test.ts
new file mode 100644
index 00000000..fbc833e9
--- /dev/null
+++ b/packages/chronicle/src/lib/site-initial.test.ts
@@ -0,0 +1,24 @@
+import { describe, expect, test } from 'bun:test'
+import { siteInitial } from './site-initial'
+
+describe('siteInitial', () => {
+  test('takes the first letter, uppercased', () => {
+    expect(siteInitial('Chronicle')).toBe('C')
+    expect(siteInitial('my documentation')).toBe('M')
+  })
+
+  test('ignores surrounding space', () => {
+    expect(siteInitial('  Chronicle  ')).toBe('C')
+  })
+
+  test('keeps a whole codepoint', () => {
+    // Splitting on UTF-16 units would return half a surrogate pair.
+    expect(siteInitial('🚀 Launch')).toBe('🚀')
+    expect(siteInitial('日本語ドキュメント')).toBe('日')
+  })
+
+  test('falls back when there is nothing to take', () => {
+    expect(siteInitial('')).toBe('?')
+    expect(siteInitial('   ')).toBe('?')
+  })
+})
diff --git a/packages/chronicle/src/lib/site-initial.ts b/packages/chronicle/src/lib/site-initial.ts
new file mode 100644
index 00000000..eb281303
--- /dev/null
+++ b/packages/chronicle/src/lib/site-initial.ts
@@ -0,0 +1,8 @@
+/**
+ * The letter a site is reduced to when it sets no `logo`. Codepoint-safe, so an
+ * emoji or a non-Latin script survives being taken apart.
+ */
+export function siteInitial(title: string): string {
+  const first = Array.from(title.trim())[0]
+  return first ? first.toUpperCase() : '?'
+}
diff --git a/packages/chronicle/src/server/entry-server.tsx b/packages/chronicle/src/server/entry-server.tsx
index 7b35e9f1..d3d14692 100644
--- a/packages/chronicle/src/server/entry-server.tsx
+++ b/packages/chronicle/src/server/entry-server.tsx
@@ -175,6 +175,9 @@ export default {
       : clientAssets.merge(...routeAssets);
 
     const themeColorCss = buildThemeColorCss(config.theme?.colors);
+    // A configured logo doubles as the favicon. Light first: browser chrome is
+    // usually light, and a site that sets only one gets that one either way.
+    const faviconHref = config.logo?.light ?? config.logo?.dark ?? null;
 
     const renderStart = performance.now();
     // prerender (vs renderToReadableStream) waits for all Suspense content;
@@ -186,8 +189,20 @@ export default {
         <head>
           <meta charSet="UTF-8" />
           <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-          <link rel="icon" href="/favicon.ico" />
-          <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
+          {faviconHref ? (
+            <link
+              rel="icon"
+              href={faviconHref}
+              {...(faviconHref.split('?')[0].endsWith('.svg')
+                ? { type: 'image/svg+xml' }
+                : {})}
+            />
+          ) : (
+            <>
+              <link rel="icon" href="/favicon.ico" />
+              <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
+            </>
+          )}
           {assets.css.map((attr: { href: string }) => (
             <link key={attr.href} rel="stylesheet" {...attr} />
           ))}
diff --git a/packages/chronicle/src/server/routes/og.tsx b/packages/chronicle/src/server/routes/og.tsx
index be34729b..c86f74c5 100644
--- a/packages/chronicle/src/server/routes/og.tsx
+++ b/packages/chronicle/src/server/routes/og.tsx
@@ -2,6 +2,7 @@ import { defineHandler } from 'nitro';
 import React from 'react';
 import satori from 'satori';
 import { loadConfig } from '@/lib/config';
+import { siteInitial } from '@/lib/site-initial';
 import { loadFont, loadLogo } from './og-utils';
 
 let fontData: ArrayBuffer | null = null;
@@ -16,8 +17,11 @@ export default defineHandler(async event => {
 
   if (!fontData) fontData = await loadFont(__CHRONICLE_PACKAGE_ROOT__);
   if (cachedLogo === undefined) {
-    cachedLogo = config.logo?.dark
-      ? await loadLogo(__CHRONICLE_PROJECT_ROOT__, config.logo.dark)
+    // The card is dark, so prefer the dark variant — but a site that sets only
+    // one should still get a mark rather than nothing.
+    const logoPath = config.logo?.dark ?? config.logo?.light;
+    cachedLogo = logoPath
+      ? await loadLogo(__CHRONICLE_PROJECT_ROOT__, logoPath)
       : null;
   }
 
@@ -35,13 +39,31 @@ export default defineHandler(async event => {
       }}
     >
       <div style={{ display: 'flex', alignItems: 'center', marginBottom: 16 }}>
-        {cachedLogo && (
+        {cachedLogo ? (
           <img
             src={cachedLogo}
             width={48}
             height={48}
             style={{ marginRight: 16 }}
           />
+        ) : (
+          <div
+            style={{
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              width: 48,
+              height: 48,
+              marginRight: 16,
+              borderRadius: 10,
+              backgroundColor: '#26262a',
+              color: '#fafafa',
+              fontSize: 24,
+              fontWeight: 700,
+            }}
+          >
+            {siteInitial(siteName)}
+          </div>
         )}
         <div style={{ fontSize: 32, color: '#888' }}>
           {siteName}
diff --git a/packages/chronicle/src/themes/fanfold/Layout.module.css b/packages/chronicle/src/themes/fanfold/Layout.module.css
index f1388021..f3dcd86b 100644
--- a/packages/chronicle/src/themes/fanfold/Layout.module.css
+++ b/packages/chronicle/src/themes/fanfold/Layout.module.css
@@ -257,9 +257,10 @@
 /* Above the name, not beside it — the rail is 240px and the display face is
    wide, so sharing a line breaks titles mid-word. */
 .brandLogo {
-  display: block;
+  /* Block-level so the name sits under it, but still a flex box so a letter
+     mark stays centred. */
+  display: flex;
   margin-bottom: 10px;
-  color: var(--fan-ink);
 }
 
 .brandName {
diff --git a/packages/chronicle/src/themes/paper/Layout.module.css b/packages/chronicle/src/themes/paper/Layout.module.css
index 7c28cf7f..e8a0c41b 100644
--- a/packages/chronicle/src/themes/paper/Layout.module.css
+++ b/packages/chronicle/src/themes/paper/Layout.module.css
@@ -41,7 +41,6 @@
 /* Never squeezed by a long site title. */
 .logo {
   flex-shrink: 0;
-  color: var(--rs-color-foreground-accent-primary);
 }
 
 .contentDirTrigger {

From 8ca21c4447c10125925dbccad172fdc20ed1c49f Mon Sep 17 00:00:00 2001
From: Ravi Suhag <suhag.ravi@gmail.com>
Date: Wed, 2 Sep 2026 19:46:06 -0500
Subject: [PATCH 09/10] docs: use the Raystack mark on Chronicle's own site
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Chronicle is a Raystack project, so its docs should carry the Raystack mark —
but through `chronicle.yaml` like any other site would, not baked into a theme.
The themes stay neutral and fall back to the site's initial.

The brand file draws a flat navy through a single-stop gradient, which reads as
near-black on a dark page. Flattened to a plain fill, with a light variant for
`logo.dark`. Same path data either way.

This also becomes the favicon and the mark on social cards, which the config now
covers.
---
 docs/chronicle.yaml       | 4 ++++
 docs/public/logo-dark.svg | 3 +++
 docs/public/logo.svg      | 3 +++
 3 files changed, 10 insertions(+)
 create mode 100644 docs/public/logo-dark.svg
 create mode 100644 docs/public/logo.svg

diff --git a/docs/chronicle.yaml b/docs/chronicle.yaml
index 8199c714..61ca1385 100644
--- a/docs/chronicle.yaml
+++ b/docs/chronicle.yaml
@@ -4,6 +4,10 @@ site:
 
 url: https://chronicle.raystack.org
 
+logo:
+  light: /logo.svg
+  dark: /logo-dark.svg
+
 content:
   - dir: docs
     label: Docs
diff --git a/docs/public/logo-dark.svg b/docs/public/logo-dark.svg
new file mode 100644
index 00000000..a293f1a9
--- /dev/null
+++ b/docs/public/logo-dark.svg
@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 103.923048 116.287187" role="img" aria-label="Raystack">
+  <path fill="#E8ECF7" d="M1.0995468,30.0536799 L101.718938,88.1466179 C100.73439,89.5383643 99.4491496,90.7266003 97.9230485,91.6076952 L57.9615242,114.679492 C54.2487113,116.823085 49.6743371,116.823085 45.9615242,114.679492 L6,91.6076952 C2.28718708,89.4641016 -1.0658141e-14,85.5025774 -3.55271368e-15,81.2153903 L-1.0658141e-14,35.0717968 C-1.0658141e-14,33.3095155 0.386462402,31.6022611 1.0995468,30.0536799 Z M18.757,17.313 L103.923,66.483 L103.923048,81.2153903 C103.923048,81.7371223 103.889176,82.2540313 103.822983,82.7634277 L4.70864397,25.540743 C5.11691976,25.2284994 5.54789032,24.9405176 6,24.6794919 L18.757,17.313 Z M35.253,7.789 L103.923,47.435 L103.923,59.885 L24.471,14.014 L35.253,7.789 Z M57.9615242,1.60769515 L97.9230485,24.6794919 C101.635861,26.8230855 103.923048,30.7846097 103.923048,35.0717968 L103.923,40.838 L40.967,4.49 L45.9615242,1.60769515 C49.6743371,-0.535898385 54.2487113,-0.535898385 57.9615242,1.60769515 Z"/>
+</svg>
diff --git a/docs/public/logo.svg b/docs/public/logo.svg
new file mode 100644
index 00000000..346af062
--- /dev/null
+++ b/docs/public/logo.svg
@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 103.923048 116.287187" role="img" aria-label="Raystack">
+  <path fill="#0A3793" d="M1.0995468,30.0536799 L101.718938,88.1466179 C100.73439,89.5383643 99.4491496,90.7266003 97.9230485,91.6076952 L57.9615242,114.679492 C54.2487113,116.823085 49.6743371,116.823085 45.9615242,114.679492 L6,91.6076952 C2.28718708,89.4641016 -1.0658141e-14,85.5025774 -3.55271368e-15,81.2153903 L-1.0658141e-14,35.0717968 C-1.0658141e-14,33.3095155 0.386462402,31.6022611 1.0995468,30.0536799 Z M18.757,17.313 L103.923,66.483 L103.923048,81.2153903 C103.923048,81.7371223 103.889176,82.2540313 103.822983,82.7634277 L4.70864397,25.540743 C5.11691976,25.2284994 5.54789032,24.9405176 6,24.6794919 L18.757,17.313 Z M35.253,7.789 L103.923,47.435 L103.923,59.885 L24.471,14.014 L35.253,7.789 Z M57.9615242,1.60769515 L97.9230485,24.6794919 C101.635861,26.8230855 103.923048,30.7846097 103.923048,35.0717968 L103.923,40.838 L40.967,4.49 L45.9615242,1.60769515 C49.6743371,-0.535898385 54.2487113,-0.535898385 57.9615242,1.60769515 Z"/>
+</svg>

From 9cc92263d850e8b480997503d82827760fab7a28 Mon Sep 17 00:00:00 2001
From: Ravi Suhag <suhag.ravi@gmail.com>
Date: Wed, 2 Sep 2026 19:53:19 -0500
Subject: [PATCH 10/10] docs: draw the mark in greyscale

Navy pulled the eye to the one thing on the page that is not type. Greyscale
sits with the rest of the sidebar instead.

Matched to the site's own ink rather than picked by eye:
`--rs-color-foreground-base-primary` is oklch(0.2435 0 0) in light and
oklch(0.9491 0 0) in dark, which are #202020 and #EEEEEE.
---
 docs/public/logo-dark.svg | 2 +-
 docs/public/logo.svg      | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/public/logo-dark.svg b/docs/public/logo-dark.svg
index a293f1a9..fcd8483f 100644
--- a/docs/public/logo-dark.svg
+++ b/docs/public/logo-dark.svg
@@ -1,3 +1,3 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 103.923048 116.287187" role="img" aria-label="Raystack">
-  <path fill="#E8ECF7" d="M1.0995468,30.0536799 L101.718938,88.1466179 C100.73439,89.5383643 99.4491496,90.7266003 97.9230485,91.6076952 L57.9615242,114.679492 C54.2487113,116.823085 49.6743371,116.823085 45.9615242,114.679492 L6,91.6076952 C2.28718708,89.4641016 -1.0658141e-14,85.5025774 -3.55271368e-15,81.2153903 L-1.0658141e-14,35.0717968 C-1.0658141e-14,33.3095155 0.386462402,31.6022611 1.0995468,30.0536799 Z M18.757,17.313 L103.923,66.483 L103.923048,81.2153903 C103.923048,81.7371223 103.889176,82.2540313 103.822983,82.7634277 L4.70864397,25.540743 C5.11691976,25.2284994 5.54789032,24.9405176 6,24.6794919 L18.757,17.313 Z M35.253,7.789 L103.923,47.435 L103.923,59.885 L24.471,14.014 L35.253,7.789 Z M57.9615242,1.60769515 L97.9230485,24.6794919 C101.635861,26.8230855 103.923048,30.7846097 103.923048,35.0717968 L103.923,40.838 L40.967,4.49 L45.9615242,1.60769515 C49.6743371,-0.535898385 54.2487113,-0.535898385 57.9615242,1.60769515 Z"/>
+  <path fill="#EEEEEE" d="M1.0995468,30.0536799 L101.718938,88.1466179 C100.73439,89.5383643 99.4491496,90.7266003 97.9230485,91.6076952 L57.9615242,114.679492 C54.2487113,116.823085 49.6743371,116.823085 45.9615242,114.679492 L6,91.6076952 C2.28718708,89.4641016 -1.0658141e-14,85.5025774 -3.55271368e-15,81.2153903 L-1.0658141e-14,35.0717968 C-1.0658141e-14,33.3095155 0.386462402,31.6022611 1.0995468,30.0536799 Z M18.757,17.313 L103.923,66.483 L103.923048,81.2153903 C103.923048,81.7371223 103.889176,82.2540313 103.822983,82.7634277 L4.70864397,25.540743 C5.11691976,25.2284994 5.54789032,24.9405176 6,24.6794919 L18.757,17.313 Z M35.253,7.789 L103.923,47.435 L103.923,59.885 L24.471,14.014 L35.253,7.789 Z M57.9615242,1.60769515 L97.9230485,24.6794919 C101.635861,26.8230855 103.923048,30.7846097 103.923048,35.0717968 L103.923,40.838 L40.967,4.49 L45.9615242,1.60769515 C49.6743371,-0.535898385 54.2487113,-0.535898385 57.9615242,1.60769515 Z"/>
 </svg>
diff --git a/docs/public/logo.svg b/docs/public/logo.svg
index 346af062..623630b1 100644
--- a/docs/public/logo.svg
+++ b/docs/public/logo.svg
@@ -1,3 +1,3 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 103.923048 116.287187" role="img" aria-label="Raystack">
-  <path fill="#0A3793" d="M1.0995468,30.0536799 L101.718938,88.1466179 C100.73439,89.5383643 99.4491496,90.7266003 97.9230485,91.6076952 L57.9615242,114.679492 C54.2487113,116.823085 49.6743371,116.823085 45.9615242,114.679492 L6,91.6076952 C2.28718708,89.4641016 -1.0658141e-14,85.5025774 -3.55271368e-15,81.2153903 L-1.0658141e-14,35.0717968 C-1.0658141e-14,33.3095155 0.386462402,31.6022611 1.0995468,30.0536799 Z M18.757,17.313 L103.923,66.483 L103.923048,81.2153903 C103.923048,81.7371223 103.889176,82.2540313 103.822983,82.7634277 L4.70864397,25.540743 C5.11691976,25.2284994 5.54789032,24.9405176 6,24.6794919 L18.757,17.313 Z M35.253,7.789 L103.923,47.435 L103.923,59.885 L24.471,14.014 L35.253,7.789 Z M57.9615242,1.60769515 L97.9230485,24.6794919 C101.635861,26.8230855 103.923048,30.7846097 103.923048,35.0717968 L103.923,40.838 L40.967,4.49 L45.9615242,1.60769515 C49.6743371,-0.535898385 54.2487113,-0.535898385 57.9615242,1.60769515 Z"/>
+  <path fill="#202020" d="M1.0995468,30.0536799 L101.718938,88.1466179 C100.73439,89.5383643 99.4491496,90.7266003 97.9230485,91.6076952 L57.9615242,114.679492 C54.2487113,116.823085 49.6743371,116.823085 45.9615242,114.679492 L6,91.6076952 C2.28718708,89.4641016 -1.0658141e-14,85.5025774 -3.55271368e-15,81.2153903 L-1.0658141e-14,35.0717968 C-1.0658141e-14,33.3095155 0.386462402,31.6022611 1.0995468,30.0536799 Z M18.757,17.313 L103.923,66.483 L103.923048,81.2153903 C103.923048,81.7371223 103.889176,82.2540313 103.822983,82.7634277 L4.70864397,25.540743 C5.11691976,25.2284994 5.54789032,24.9405176 6,24.6794919 L18.757,17.313 Z M35.253,7.789 L103.923,47.435 L103.923,59.885 L24.471,14.014 L35.253,7.789 Z M57.9615242,1.60769515 L97.9230485,24.6794919 C101.635861,26.8230855 103.923048,30.7846097 103.923048,35.0717968 L103.923,40.838 L40.967,4.49 L45.9615242,1.60769515 C49.6743371,-0.535898385 54.2487113,-0.535898385 57.9615242,1.60769515 Z"/>
 </svg>