bryant22 · Oct 10, 2026 · Oct 9, 2026 · Oct 9, 2026
diff --git a/apps/docs/.source/browser.ts b/apps/docs/.source/browser.ts
diff --git a/apps/docs/.source/server.ts b/apps/docs/.source/server.ts
diff --git a/apps/docs/app/apple-icon.png b/apps/docs/app/apple-icon.png
diff --git a/apps/docs/app/docs/[[...slug]]/page.tsx b/apps/docs/app/docs/[[...slug]]/page.tsx
@@ -12,7 +12,7 @@ export default async function Page(props: { params: Promise<{ slug?: string[] }>
 
   return (
     <DocsPage toc={page.data.toc} full={page.data.full}>
-      <DocsTitle>{page.data.title}</DocsTitle>
+      <DocsTitle className="fd-title">{page.data.title}</DocsTitle>
       <DocsDescription>{page.data.description}</DocsDescription>
       <DocsBody>
         <MDX components={{ ...defaultMdxComponents }} />

diff --git a/apps/docs/app/docs/layout.tsx b/apps/docs/app/docs/layout.tsx
@@ -1,15 +1,16 @@
 import { DocsLayout } from 'fumadocs-ui/layouts/docs'
 import { source } from '@/lib/source'
-import Image from 'next/image'
+import { OrgAiMark } from '@/lib/org-ai-mark'
 
 export default function Layout({ children }: { children: React.ReactNode }) {
   return (
     <DocsLayout
       tree={source.pageTree}
+      disableThemeSwitch
       nav={{
         title: (
           <>
-            <Image src="/org-ai.svg" alt="" width={24} height={24} />
+            <OrgAiMark />
             <span>MDX.org.ai</span>
           </>
         ),

diff --git a/apps/docs/app/favicon.ico b/apps/docs/app/favicon.ico
diff --git a/apps/docs/app/fonts/publicsans-OFL.txt b/apps/docs/app/fonts/publicsans-OFL.txt
@@ -0,0 +1,93 @@
+Copyright 2015 The Public Sans Project Authors (https://github.com/uswds/public-sans) PublicSans-Italic[wght].ttf: Copyright 2015 The Public Sans Project Authors (https://github.com/uswds/public-sans)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
diff --git a/apps/docs/app/fonts/publicsans-latin.woff2 b/apps/docs/app/fonts/publicsans-latin.woff2
diff --git a/apps/docs/app/global.css b/apps/docs/app/global.css
@@ -3,3 +3,35 @@
 @tailwind base;
 @tailwind components;
 @tailwind utilities;
+
+/* The Org.AI Foundation's palette, as foundation.org.ai defines it, in the form Fumadocs 14 takes its colours:
+   hue, saturation and lightness, converted from the Foundation's oklch tokens (named on the right), each exact to
+   the 8-bit colour the Foundation's own pages render. The docs are dark, as every Foundation site is, so the light and
+   dark sets are the same. */
+:root,
+.dark {
+  --fd-background: 35.90 13.33% 6.44%; /* ground */
+  --fd-foreground: 40.98 17.86% 94.35%; /* ink */
+  --fd-muted: 35.90 10.31% 10.26%; /* raise */
+  --fd-muted-foreground: 38.31 2.74% 58.05%; /* ink-3 */
+  --fd-popover: 35.90 10.31% 10.26%; /* raise */
+  --fd-popover-foreground: 40.98 17.86% 94.35%; /* ink */
+  --fd-card: 35.90 10.31% 10.26%; /* raise */
+  --fd-card-foreground: 40.98 17.86% 94.35%; /* ink */
+  --fd-border: 35.88 7.98% 13.76%; /* rule-faint */
+  --fd-primary: 31.77 82.03% 66.98%; /* now, the amber */
+  --fd-primary-foreground: 28.39 57.39% 8.52%; /* now-ink */
+  --fd-secondary: 35.90 10.31% 10.26%; /* raise */
+  --fd-secondary-foreground: 40.98 17.86% 94.35%; /* ink */
+  --fd-accent: 35.89 8.65% 14.65%; /* raise-hi */
+  --fd-accent-foreground: 40.98 17.86% 94.35%; /* ink */
+  --fd-ring: 31.77 82.03% 66.98%; /* now */
+  color-scheme: dark;
+}
+
+/* the Foundation's type: headings set light, with tight tracking, as on foundation.org.ai */
+.fd-title { font-weight: 360; letter-spacing: -0.025em; }
+.prose h1 { font-weight: 340; letter-spacing: -0.03em; }
+.prose h2 { font-weight: 400; letter-spacing: -0.02em; }
+.prose h3 { font-weight: 500; letter-spacing: -0.012em; }
+.prose h4 { font-weight: 600; }
diff --git a/apps/docs/app/icon.svg b/apps/docs/app/icon.svg
diff --git a/apps/docs/app/layout.tsx b/apps/docs/app/layout.tsx
@@ -1,5 +1,9 @@
 import './global.css'
 import { RootProvider } from 'fumadocs-ui/provider'
+import localFont from 'next/font/local'
+
+// Public Sans, the Org.AI Foundation's typeface, served from this site
+const publicSans = localFont({ src: './fonts/publicsans-latin.woff2', weight: '100 900', display: 'swap' })
 
 export const metadata = {
   title: 'MDX.org.ai Documentation',
@@ -8,9 +12,10 @@ export const metadata = {
 
 export default function RootLayout({ children }: { children: React.ReactNode }) {
   return (
-    <html lang="en" suppressHydrationWarning>
+    <html lang="en" className={publicSans.className} suppressHydrationWarning>
       <body>
-        <RootProvider>{children}</RootProvider>
+        {/* dark, as every Org.AI Foundation site is */}
+        <RootProvider theme={{ forcedTheme: 'dark', defaultTheme: 'dark', enableSystem: false }}>{children}</RootProvider>
       </body>
     </html>
   )

diff --git a/apps/docs/lib/org-ai-mark.tsx b/apps/docs/lib/org-ai-mark.tsx
@@ -0,0 +1,13 @@
+/** The Org.AI Foundation's mark: six ovals turning, the last one amber. The five take the text colour, so the mark follows the theme. */
+export function OrgAiMark({ size = 24 }: { size?: number }) {
+  return (
+    <svg viewBox="0 0 48 48" width={size} height={size} aria-hidden="true" focusable="false">
+      <ellipse cx="20.32" cy="37.72" rx="6.8" ry="3.9" transform="rotate(129 20.32 37.72)" fill="currentColor" />
+      <ellipse cx="10.28" cy="27.68" rx="6.8" ry="3.9" transform="rotate(189 10.28 27.68)" fill="currentColor" />
+      <ellipse cx="13.96" cy="13.96" rx="6.8" ry="3.9" transform="rotate(249 13.96 13.96)" fill="currentColor" />
+      <ellipse cx="27.68" cy="10.28" rx="6.8" ry="3.9" transform="rotate(309 27.68 10.28)" fill="currentColor" />
+      <ellipse cx="37.72" cy="20.32" rx="6.8" ry="3.9" transform="rotate(369 37.72 20.32)" fill="currentColor" />
+      <ellipse cx="34.04" cy="34.04" rx="6.8" ry="3.9" transform="rotate(429 34.04 34.04)" fill="#f0af66" />
+    </svg>
+  )
+}
diff --git a/apps/docs/public/org-ai.svg b/apps/docs/public/org-ai.svg
diff --git a/docs/(Executable Code)/executable-code.mdx b/docs/(Executable Code)/executable-code.mdx
@@ -9,7 +9,7 @@ The **Executable Code** layer brings MDX documents to life with TypeScript funct
 
 ## Core Concepts
 
-### [Function](/Function)
+### Function
 
 AI function definitions with four variants:
 
@@ -18,7 +18,9 @@ AI function definitions with four variants:
 - **AgenticFunction** - Multi-step AI reasoning
 - **HumanFunction** - Human-in-the-loop approval
 
-### [Agent](/Agent)
+See the [Function overview](/docs/Function).
+
+### Agent
 
 Autonomous AI entities with roles, goals, and team coordination.
 
@@ -31,7 +33,9 @@ const writer = await createAgent({
 })
 ```
 
-### [Workflow](/Workflow)
+See the [Agent overview](/docs/Agent).
+
+### Workflow
 
 Event-driven business logic using the `$` context:
 
@@ -46,20 +50,26 @@ $.every.day.at('9:00')(async () => {
 })
 ```
 
+See the [Workflow overview](/docs/Workflow).
+
 ## Packages
 
-### [mdxe](/mdxe)
+### mdxe
 
 Execute MDX in various runtimes:
 
 - **@mdxe/workers** - Cloudflare Workers (and local dev under Miniflare)
 - **@mdxe/hono** - Hono web framework
 - **@mdxe/ink** - Terminal UI
 
-### [mdxai](/mdxai)
+See the [mdxe overview](/docs/mdxe).
+
+### mdxai
 
 AI integrations:
 
 - **@mdxai/claude** - Claude AI with MCP tools
 - **@mdxai/mastra** - Mastra agent framework
 - **@mdxai/vapi** - Voice AI
+
+See the [mdxai overview](/docs/mdxai).
diff --git a/docs/(Executable Code)/mdxe/styling/backgrounds.mdx b/docs/(Executable Code)/mdxe/styling/backgrounds.mdx
@@ -37,7 +37,7 @@ $style:
 
 ## Full Documentation
 
-See the [BuilderCSS backgrounds documentation](/packages/buildercss/docs/backgrounds.md) for:
+See the BuilderCSS backgrounds documentation for:
 - CSS implementation details
 - Color integration
 - Best use cases for each effect

diff --git a/docs/(Executable Code)/mdxe/styling/index.mdx b/docs/(Executable Code)/mdxe/styling/index.mdx
@@ -53,8 +53,8 @@ $style:
 
 For comprehensive documentation, see the [BuilderCSS docs](https://github.com/your-org/buildercss):
 
-- [URL Conventions](/packages/buildercss/docs/url-conventions.md) - URL patterns and parameters
-- [Document Types](/packages/buildercss/docs/types.md) - Available types and HTML structures
-- [Backgrounds](/packages/buildercss/docs/backgrounds.md) - Background effects
-- [Colors](/packages/buildercss/docs/colors.md) - Color system
-- [CSS Variables](/packages/buildercss/docs/variables.md) - shadcn/ui compatible variables
+- URL Conventions - URL patterns and parameters
+- Document Types - Available types and HTML structures
+- Backgrounds - Background effects
+- Colors - Color system
+- CSS Variables - shadcn/ui compatible variables
diff --git a/docs/(Executable Code)/mdxe/styling/types.mdx b/docs/(Executable Code)/mdxe/styling/types.mdx
@@ -34,7 +34,7 @@ title: My Product
 
 ## Full Documentation
 
-See the [BuilderCSS types documentation](/packages/buildercss/docs/types.md) for:
+See the BuilderCSS types documentation for:
 - Complete HTML structures for each type
 - All frontmatter properties
 - CSS class references

diff --git a/docs/(Executable Code)/meta.json b/docs/(Executable Code)/meta.json
@@ -0,0 +1,8 @@
+{
+  "title": "Executable Code",
+  "pages": [
+    "executable-code",
+    "..."
+  ],
+  "defaultOpen": true
+}
diff --git a/docs/(Structured Data)/mdxld/formats/diff.mdx b/docs/(Structured Data)/mdxld/formats/diff.mdx
@@ -449,5 +449,5 @@ template-based round trip; `@mdxld/markdown` exports no diff of its own.
 | Package | Description |
 |---------|-------------|
 | [`@mdxld/markdown`](/docs/mdxld/formats/markdown) | Markdown conversion with diff support |
-| [`@mdxld/extract`](/docs/mdxld/extract) | Template-based extraction |
+| `@mdxld/extract` | Template-based extraction |
 | [`mdxdb`](/docs/mdxdb) | Document storage |
diff --git a/docs/(Structured Data)/mdxld/formats/html.mdx b/docs/(Structured Data)/mdxld/formats/html.mdx
@@ -336,4 +336,4 @@ const html = toHTML(data, { theme: 'modern' })  // Styled HTML
 | [`@mdxld/markdown`](/docs/mdxld/formats/markdown) | Object ↔ Markdown |
 | [`@mdxld/json`](/docs/mdxld/formats/json) | JSON-LD and JSON Schema |
 | [`@mdxui/html`](/docs/mdxui/renderers/html) | Styled HTML output |
-| [`@mdxld/jsx`](/docs/mdxld/jsx) | JSX runtime for HTML |
+| `@mdxld/jsx` | JSX runtime for HTML |
diff --git a/docs/(Structured Data)/mdxld/formats/index.mdx b/docs/(Structured Data)/mdxld/formats/index.mdx
@@ -195,6 +195,6 @@ if (changes.hasChanges) {
 
 ## Related
 
-- [Template-based Extraction](/docs/mdxld/extract) - For explicit MDX templates
-- [JSX Primitives](/docs/mdxld/jsx) - Universal JSX runtime
+- Template-based Extraction - For explicit MDX templates
+- JSX Primitives - Universal JSX runtime
 - [mdxdb Storage](/docs/mdxdb) - Document storage
diff --git a/docs/(Structured Data)/mdxld/formats/json.mdx b/docs/(Structured Data)/mdxld/formats/json.mdx
@@ -421,6 +421,6 @@ server.setRequestHandler('tools/list', () => tools)
 
 | Package | Description |
 |---------|-------------|
-| [`@mdxld/jsonld`](/docs/mdxld/jsonld) | Full JSON-LD processing (expand, compact, frame) |
+| `@mdxld/jsonld` | Full JSON-LD processing (expand, compact, frame) |
 | [`@mdxld/typescript`](/docs/mdxld/formats/typescript) | TypeScript types and Zod schemas |
 | [`@mdxui/json`](/docs/mdxui/renderers/json) | Styled JSON output |