diff --git a/.auths/roots b/.auths/roots
new file mode 100644
index 0000000..42a5528
--- /dev/null
+++ b/.auths/roots
@@ -0,0 +1,2 @@
+# Pinned by auths init — the trusted root for this identity.
+did:keri:EB5cPHY0t-ejNC_rUzPS1dclTvd6kG-R9mQzjozCuGgd
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..1d44441
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+
+      - name: Install
+        run: bun install --frozen-lockfile
+
+      # Markdoc validation + the frontmatter contract run inside the build
+      # (parseDoc throws on critical errors; getAllDocs throws on a missing
+      # field), so a page that would render wrong fails here, not in prod.
+      - name: Build
+        run: bun run build
+
+      - name: Type-check
+        run: bun run type-check
+
+      # Copy lint, verdict lint, and the link check — the drift that bit the
+      # marketing site, encoded as a gate. External links included.
+      - name: Docs check
+        run: bun run check
diff --git a/app/docs/[...slug]/page.tsx b/app/docs/[...slug]/page.tsx
new file mode 100644
index 0000000..cb2c695
--- /dev/null
+++ b/app/docs/[...slug]/page.tsx
@@ -0,0 +1,76 @@
+import fs from 'fs'
+import path from 'path'
+import type { Metadata } from 'next'
+import { notFound } from 'next/navigation'
+import { getAllDocs, getDocBySlug, getPrevNext } from '@/lib/content'
+import { parseDoc } from '@/lib/markdoc'
+import { renderDoc } from '@/lib/markdoc-components'
+import { DocsPrevNext } from '@/components/docs/DocsPrevNext'
+
+/**
+ * The one route for every doc page: content is data (`content/docs/**.md`),
+ * metadata comes from frontmatter, and the nav can never drift from disk.
+ */
+
+type Props = { params: Promise<{ slug: string[] }> }
+
+export function generateStaticParams() {
+  return getAllDocs().map((d) => ({ slug: d.slug }))
+}
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { slug } = await params
+  const doc = getDocBySlug(slug)
+  if (!doc) return { title: 'Not found' }
+  return {
+    title: `${doc.frontmatter.title} — Auths docs`,
+    description: doc.frontmatter.description,
+  }
+}
+
+export default async function DocPage({ params }: Props) {
+  const { slug } = await params
+  const doc = getDocBySlug(slug)
+  if (!doc) notFound()
+
+  const source = fs.readFileSync(doc.filePath, 'utf8')
+  const { content } = parseDoc(source)
+  const { prev, next } = getPrevNext(doc.href)
+
+  const editUrl = `https://github.com/auths-dev/auths-docs/edit/main/${path
+    .relative(process.cwd(), doc.filePath)
+    .split(path.sep)
+    .join('/')}`
+
+  return (
+    <article className="prose max-w-none [counter-reset:step]">
+      <header className="not-prose mb-10">
+        <p className="font-mono text-[11px] font-semibold uppercase tracking-[0.18em] text-seal">
+          {doc.frontmatter.section}
+        </p>
+        <h1 className="mt-3 text-4xl font-bold tracking-tight text-ink">
+          {doc.frontmatter.title}
+        </h1>
+        <p className="mt-3 text-lg leading-8 text-ink-soft">{doc.frontmatter.description}</p>
+      </header>
+
+      {renderDoc(content)}
+
+      <footer className="not-prose mt-14 flex flex-wrap items-baseline justify-between gap-2 border-t border-rule pt-5">
+        <a
+          href={editUrl}
+          target="_blank"
+          rel="noopener noreferrer"
+          className="font-mono text-[12px] text-ink-faint transition-colors hover:text-seal"
+        >
+          Edit this page
+        </a>
+        <span className="font-mono text-[12px] text-ink-faint">
+          Last reviewed {doc.frontmatter.lastReviewed}
+        </span>
+      </footer>
+
+      <DocsPrevNext prev={prev} next={next} />
+    </article>
+  )
+}
diff --git a/app/docs/authentication/page.tsx b/app/docs/authentication/page.tsx
deleted file mode 100644
index 6018faa..0000000
--- a/app/docs/authentication/page.tsx
+++ /dev/null
@@ -1,27 +0,0 @@
-import fs from 'fs'
-import path from 'path'
-import { parseDoc } from '@/lib/markdoc'
-import { DocsPrevNext } from '@/components/docs/DocsPrevNext'
-
-export default async function Page() {
-  const source = fs.readFileSync(path.join(process.cwd(), 'content/docs/authentication.md'), 'utf8')
-  const { html, frontmatter } = parseDoc(source)
-
-  return (
-    <article className="prose prose-gray max-w-none">
-      <div className="mb-8">
-        <h1 className="text-4xl font-bold text-gray-900 mb-4">{frontmatter.title}</h1>
-        <p className="text-lg text-gray-600">{frontmatter.description}</p>
-      </div>
-      <div dangerouslySetInnerHTML={{ __html: html }} />
-      <DocsPrevNext />
-    </article>
-  )
-}
-
-export function generateMetadata() {
-  return {
-    title: 'Authentication - Auths Docs',
-    description: 'Authenticate your API requests with Auths API keys',
-  }
-}
diff --git a/app/docs/build-agents/page.tsx b/app/docs/build-agents/page.tsx
deleted file mode 100644
index 06f6be0..0000000
--- a/app/docs/build-agents/page.tsx
+++ /dev/null
@@ -1,24 +0,0 @@
-import fs from 'fs'
-import path from 'path'
-import { parseDoc } from '@/lib/markdoc'
-import { DocsPrevNext } from '@/components/docs/DocsPrevNext'
-
-export default async function Page() {
-  const source = fs.readFileSync(path.join(process.cwd(), 'content/docs/build-agents.md'), 'utf8')
-  const { html, frontmatter } = parseDoc(source)
-
-  return (
-    <article className="prose prose-gray max-w-none">
-      <div className="mb-8">
-        <h1 className="text-4xl font-bold text-gray-900 mb-4">{frontmatter.title}</h1>
-        <p className="text-lg text-gray-600">{frontmatter.description}</p>
-      </div>
-      <div dangerouslySetInnerHTML={{ __html: html }} />
-      <DocsPrevNext />
-    </article>
-  )
-}
-
-export function generateMetadata() {
-  return { title: 'Build Agents - Auths Docs', description: 'Automate code signing with agents in your CI/CD pipeline' }
-}
diff --git a/app/docs/concepts/[topic]/page.tsx b/app/docs/concepts/[topic]/page.tsx
deleted file mode 100644
index 68f6d52..0000000
--- a/app/docs/concepts/[topic]/page.tsx
+++ /dev/null
@@ -1,49 +0,0 @@
-import fs from 'fs'
-import path from 'path'
-import { parseDoc } from '@/lib/markdoc'
-import { DocsPrevNext } from '@/components/docs/DocsPrevNext'
-
-interface PageProps {
-  params: Promise<{ topic: string }>
-}
-
-export default async function Page(props: PageProps) {
-  const { topic } = await props.params
-  const filePath = path.join(process.cwd(), `content/docs/concepts/${topic}.md`)
-
-  if (!fs.existsSync(filePath)) {
-    return <div>Page not found</div>
-  }
-
-  const source = fs.readFileSync(filePath, 'utf8')
-  const { html, frontmatter } = parseDoc(source)
-
-  return (
-    <article className="prose prose-gray max-w-none">
-      <div className="mb-8">
-        <h1 className="text-4xl font-bold text-gray-900 mb-4">{frontmatter.title}</h1>
-        <p className="text-lg text-gray-600">{frontmatter.description}</p>
-      </div>
-      <div dangerouslySetInnerHTML={{ __html: html }} />
-      <DocsPrevNext />
-    </article>
-  )
-}
-
-export async function generateStaticParams() {
-  const dir = path.join(process.cwd(), 'content/docs/concepts')
-  if (!fs.existsSync(dir)) return []
-  return fs
-    .readdirSync(dir)
-    .filter((f) => f.endsWith('.md'))
-    .map((f) => ({ topic: f.replace(/\.md$/, '') }))
-}
-
-export async function generateMetadata(props: PageProps) {
-  const { topic } = await props.params
-  const filePath = path.join(process.cwd(), `content/docs/concepts/${topic}.md`)
-  if (!fs.existsSync(filePath)) return {}
-  const source = fs.readFileSync(filePath, 'utf8')
-  const { frontmatter } = parseDoc(source)
-  return { title: `${frontmatter.title} - Auths Docs`, description: frontmatter.description }
-}
diff --git a/app/docs/installation/page.tsx b/app/docs/installation/page.tsx
deleted file mode 100644
index 7952bfc..0000000
--- a/app/docs/installation/page.tsx
+++ /dev/null
@@ -1,24 +0,0 @@
-import fs from 'fs'
-import path from 'path'
-import { parseDoc } from '@/lib/markdoc'
-import { DocsPrevNext } from '@/components/docs/DocsPrevNext'
-
-export default async function Page() {
-  const source = fs.readFileSync(path.join(process.cwd(), 'content/docs/installation.md'), 'utf8')
-  const { html, frontmatter } = parseDoc(source)
-
-  return (
-    <article className="prose prose-gray max-w-none">
-      <div className="mb-8">
-        <h1 className="text-4xl font-bold text-gray-900 mb-4">{frontmatter.title}</h1>
-        <p className="text-lg text-gray-600">{frontmatter.description}</p>
-      </div>
-      <div dangerouslySetInnerHTML={{ __html: html }} />
-      <DocsPrevNext />
-    </article>
-  )
-}
-
-export function generateMetadata() {
-  return { title: 'Installation - Auths Docs', description: 'Get the Auths CLI up and running' }
-}
diff --git a/app/docs/layout.tsx b/app/docs/layout.tsx
index 398458a..b2b4a26 100644
--- a/app/docs/layout.tsx
+++ b/app/docs/layout.tsx
@@ -1,39 +1,31 @@
 import { DocsTopBar } from '@/components/docs/DocsTopBar'
 import { DocsSidebar } from '@/components/docs/DocsSidebar'
-import { CodeExamples } from '@/components/docs/CodeExamples'
 import { DocsMobileDrawer } from '@/components/docs/DocsMobileDrawer'
+import { OnThisPage } from '@/components/docs/OnThisPage'
+import { LanguageProvider } from '@/components/markdoc/language-context'
+import { getNavigation } from '@/lib/content'
+
+export default function DocsLayout({ children }: { children: React.ReactNode }) {
+  const nav = getNavigation()
 
-export default function DocsLayout({
-  children,
-}: {
-  children: React.ReactNode
-}) {
   return (
-    <>
+    <LanguageProvider>
       <DocsTopBar />
-      <div className="flex-1">
-        <div className="mx-auto">
-          <div className="grid grid-cols-1 lg:grid-cols-[280px_minmax(0,1fr)_320px] gap-0 lg:gap-8">
-            {/* Left Sidebar */}
-            <aside className="hidden lg:block sticky top-14 h-[calc(100vh-3.5rem)] overflow-y-auto px-6 py-8 border-r border-gray-200 bg-gray-50">
-              <DocsSidebar />
-            </aside>
+      <div className="mx-auto max-w-[88rem]">
+        <div className="grid grid-cols-1 gap-0 lg:grid-cols-[270px_minmax(0,1fr)_260px] lg:gap-10">
+          <aside className="sticky top-14 hidden h-[calc(100vh-3.5rem)] overflow-y-auto border-r border-rule bg-paper-deep/40 px-5 py-8 lg:block">
+            <DocsSidebar nav={nav} />
+          </aside>
 
-            {/* Main Content */}
-            <main className="min-w-0 px-6 sm:px-8 lg:px-0 py-8 max-w-2xl">
-              {children}
-            </main>
+          <main className="min-w-0 max-w-[72ch] px-6 py-10 sm:px-8 lg:px-0">{children}</main>
 
-            {/* Right Sidebar (Code Examples) */}
-            <aside className="hidden lg:block sticky top-14 h-[calc(100vh-3.5rem)] overflow-y-auto px-6 py-8 bg-white">
-              <CodeExamples />
-            </aside>
-          </div>
+          <aside className="sticky top-14 hidden h-[calc(100vh-3.5rem)] overflow-y-auto px-4 py-10 lg:block">
+            <OnThisPage />
+          </aside>
         </div>
       </div>
 
-      {/* Mobile drawer */}
-      <DocsMobileDrawer />
-    </>
+      <DocsMobileDrawer nav={nav} />
+    </LanguageProvider>
   )
 }
diff --git a/app/docs/mcp-setup/page.tsx b/app/docs/mcp-setup/page.tsx
deleted file mode 100644
index 9e8f2c2..0000000
--- a/app/docs/mcp-setup/page.tsx
+++ /dev/null
@@ -1,27 +0,0 @@
-import fs from 'fs'
-import path from 'path'
-import { parseDoc } from '@/lib/markdoc'
-import { DocsPrevNext } from '@/components/docs/DocsPrevNext'
-
-export default async function Page() {
-  const source = fs.readFileSync(path.join(process.cwd(), 'content/docs/mcp-setup.md'), 'utf8')
-  const { html, frontmatter } = parseDoc(source)
-
-  return (
-    <article className="prose prose-gray max-w-none">
-      <div className="mb-8">
-        <h1 className="text-4xl font-bold text-gray-900 mb-4">{frontmatter.title}</h1>
-        <p className="text-lg text-gray-600">{frontmatter.description}</p>
-      </div>
-      <div dangerouslySetInnerHTML={{ __html: html }} />
-      <DocsPrevNext />
-    </article>
-  )
-}
-
-export function generateMetadata() {
-  return {
-    title: 'MCP Setup - Auths Docs',
-    description: 'Give a Claude or Cursor agent a scoped, expiring, revocable Auths passport',
-  }
-}
diff --git a/app/docs/page.tsx b/app/docs/page.tsx
index b3ffef9..8422fb5 100644
--- a/app/docs/page.tsx
+++ b/app/docs/page.tsx
@@ -1,68 +1,6 @@
-import Link from 'next/link'
+import { redirect } from 'next/navigation'
 
-export default function DocsPage() {
-  return (
-    <div className="space-y-12">
-      <div>
-        <h1 className="text-4xl font-bold text-gray-900 mb-4">Documentation</h1>
-        <p className="text-xl text-gray-600">
-          Learn how to use Auths to sign commits, manage identities, and prove code provenance.
-        </p>
-      </div>
-
-      <div className="grid grid-cols-1 md:grid-cols-2 gap-8">
-        <Link
-          href="/docs/sign-commits"
-          className="group border border-gray-200 rounded-lg p-6 hover:shadow-md hover:border-gray-300 transition"
-        >
-          <div className="text-2xl mb-3">📝</div>
-          <h3 className="text-lg font-semibold text-gray-900 group-hover:text-blue-600 mb-2 transition">
-            Sign Commits
-          </h3>
-          <p className="text-gray-600 text-sm">
-            Get started with cryptographic commit signing. Learn the basics and best practices.
-          </p>
-        </Link>
-
-        <Link
-          href="/docs/team-identities"
-          className="group border border-gray-200 rounded-lg p-6 hover:shadow-md hover:border-gray-300 transition"
-        >
-          <div className="text-2xl mb-3">👥</div>
-          <h3 className="text-lg font-semibold text-gray-900 group-hover:text-blue-600 mb-2 transition">
-            Team Identities
-          </h3>
-          <p className="text-gray-600 text-sm">
-            Manage multiple identities for your team. Organize and verify contributor keys.
-          </p>
-        </Link>
-
-        <Link
-          href="/docs/build-agents"
-          className="group border border-gray-200 rounded-lg p-6 hover:shadow-md hover:border-gray-300 transition"
-        >
-          <div className="text-2xl mb-3">🤖</div>
-          <h3 className="text-lg font-semibold text-gray-900 group-hover:text-blue-600 mb-2 transition">
-            Build Agents
-          </h3>
-          <p className="text-gray-600 text-sm">
-            Automate code signing with agents. Integrate signing into your CI/CD pipeline.
-          </p>
-        </Link>
-
-        <Link
-          href="/docs/prove-provenance"
-          className="group border border-gray-200 rounded-lg p-6 hover:shadow-md hover:border-gray-300 transition"
-        >
-          <div className="text-2xl mb-3">🔗</div>
-          <h3 className="text-lg font-semibold text-gray-900 group-hover:text-blue-600 mb-2 transition">
-            Prove Provenance
-          </h3>
-          <p className="text-gray-600 text-sm">
-            Verify the origin of code. Prove that commits are authentic and traceable.
-          </p>
-        </Link>
-      </div>
-    </div>
-  )
+/** The docs land on the product that leads: the bounded agent. */
+export default function DocsIndex() {
+  redirect('/docs/mcp')
 }
diff --git a/app/docs/prove-provenance/page.tsx b/app/docs/prove-provenance/page.tsx
deleted file mode 100644
index 0df2b8e..0000000
--- a/app/docs/prove-provenance/page.tsx
+++ /dev/null
@@ -1,24 +0,0 @@
-import fs from 'fs'
-import path from 'path'
-import { parseDoc } from '@/lib/markdoc'
-import { DocsPrevNext } from '@/components/docs/DocsPrevNext'
-
-export default async function Page() {
-  const source = fs.readFileSync(path.join(process.cwd(), 'content/docs/prove-provenance.md'), 'utf8')
-  const { html, frontmatter } = parseDoc(source)
-
-  return (
-    <article className="prose prose-gray max-w-none">
-      <div className="mb-8">
-        <h1 className="text-4xl font-bold text-gray-900 mb-4">{frontmatter.title}</h1>
-        <p className="text-lg text-gray-600">{frontmatter.description}</p>
-      </div>
-      <div dangerouslySetInnerHTML={{ __html: html }} />
-      <DocsPrevNext />
-    </article>
-  )
-}
-
-export function generateMetadata() {
-  return { title: 'Prove Provenance - Auths Docs', description: 'Verify the authenticity and origin of code commits' }
-}
diff --git a/app/docs/quickstart/page.tsx b/app/docs/quickstart/page.tsx
deleted file mode 100644
index 2bdc57e..0000000
--- a/app/docs/quickstart/page.tsx
+++ /dev/null
@@ -1,27 +0,0 @@
-import fs from 'fs'
-import path from 'path'
-import { parseDoc } from '@/lib/markdoc'
-import { DocsPrevNext } from '@/components/docs/DocsPrevNext'
-
-export default async function Page() {
-  const source = fs.readFileSync(path.join(process.cwd(), 'content/docs/quickstart.md'), 'utf8')
-  const { html, frontmatter } = parseDoc(source)
-
-  return (
-    <article className="prose prose-gray max-w-none">
-      <div className="mb-8">
-        <h1 className="text-4xl font-bold text-gray-900 mb-4">{frontmatter.title}</h1>
-        <p className="text-lg text-gray-600">{frontmatter.description}</p>
-      </div>
-      <div dangerouslySetInnerHTML={{ __html: html }} />
-      <DocsPrevNext />
-    </article>
-  )
-}
-
-export function generateMetadata() {
-  return {
-    title: 'Quickstart - Auths Docs',
-    description: 'Install Auths, create an identity, and verify your first signed commit in five minutes',
-  }
-}
diff --git a/app/docs/reference/[topic]/page.tsx b/app/docs/reference/[topic]/page.tsx
deleted file mode 100644
index b7c01b2..0000000
--- a/app/docs/reference/[topic]/page.tsx
+++ /dev/null
@@ -1,49 +0,0 @@
-import fs from 'fs'
-import path from 'path'
-import { parseDoc } from '@/lib/markdoc'
-import { DocsPrevNext } from '@/components/docs/DocsPrevNext'
-
-interface PageProps {
-  params: Promise<{ topic: string }>
-}
-
-export default async function Page(props: PageProps) {
-  const { topic } = await props.params
-  const filePath = path.join(process.cwd(), `content/docs/reference/${topic}.md`)
-
-  if (!fs.existsSync(filePath)) {
-    return <div>Page not found</div>
-  }
-
-  const source = fs.readFileSync(filePath, 'utf8')
-  const { html, frontmatter } = parseDoc(source)
-
-  return (
-    <article className="prose prose-gray max-w-none">
-      <div className="mb-8">
-        <h1 className="text-4xl font-bold text-gray-900 mb-4">{frontmatter.title}</h1>
-        <p className="text-lg text-gray-600">{frontmatter.description}</p>
-      </div>
-      <div dangerouslySetInnerHTML={{ __html: html }} />
-      <DocsPrevNext />
-    </article>
-  )
-}
-
-export async function generateStaticParams() {
-  const dir = path.join(process.cwd(), 'content/docs/reference')
-  if (!fs.existsSync(dir)) return []
-  return fs
-    .readdirSync(dir)
-    .filter((f) => f.endsWith('.md'))
-    .map((f) => ({ topic: f.replace(/\.md$/, '') }))
-}
-
-export async function generateMetadata(props: PageProps) {
-  const { topic } = await props.params
-  const filePath = path.join(process.cwd(), `content/docs/reference/${topic}.md`)
-  if (!fs.existsSync(filePath)) return {}
-  const source = fs.readFileSync(filePath, 'utf8')
-  const { frontmatter } = parseDoc(source)
-  return { title: `${frontmatter.title} - Auths Docs`, description: frontmatter.description }
-}
diff --git a/app/docs/sign-commits/page.tsx b/app/docs/sign-commits/page.tsx
deleted file mode 100644
index 7cc1f32..0000000
--- a/app/docs/sign-commits/page.tsx
+++ /dev/null
@@ -1,34 +0,0 @@
-import fs from 'fs'
-import path from 'path'
-import { parseDoc } from '@/lib/markdoc'
-import { DocsPrevNext } from '@/components/docs/DocsPrevNext'
-
-export default async function Page() {
-  const source = fs.readFileSync(
-    path.join(process.cwd(), 'content/docs/sign-commits.md'),
-    'utf8'
-  )
-  const { html, frontmatter } = parseDoc(source)
-
-  return (
-    <article className="prose prose-gray max-w-none">
-      <div className="mb-8">
-        <h1 className="text-4xl font-bold text-gray-900 mb-4">
-          {frontmatter.title as string}
-        </h1>
-        <p className="text-lg text-gray-600">
-          {frontmatter.description as string}
-        </p>
-      </div>
-      <div dangerouslySetInnerHTML={{ __html: html }} />
-      <DocsPrevNext />
-    </article>
-  )
-}
-
-export function generateMetadata() {
-  return {
-    title: 'Sign Commits - Auths Docs',
-    description: 'Learn how to cryptographically sign your commits with Auths',
-  }
-}
diff --git a/app/docs/team-identities/page.tsx b/app/docs/team-identities/page.tsx
deleted file mode 100644
index d55fbf9..0000000
--- a/app/docs/team-identities/page.tsx
+++ /dev/null
@@ -1,24 +0,0 @@
-import fs from 'fs'
-import path from 'path'
-import { parseDoc } from '@/lib/markdoc'
-import { DocsPrevNext } from '@/components/docs/DocsPrevNext'
-
-export default async function Page() {
-  const source = fs.readFileSync(path.join(process.cwd(), 'content/docs/team-identities.md'), 'utf8')
-  const { html, frontmatter } = parseDoc(source)
-
-  return (
-    <article className="prose prose-gray max-w-none">
-      <div className="mb-8">
-        <h1 className="text-4xl font-bold text-gray-900 mb-4">{frontmatter.title}</h1>
-        <p className="text-lg text-gray-600">{frontmatter.description}</p>
-      </div>
-      <div dangerouslySetInnerHTML={{ __html: html }} />
-      <DocsPrevNext />
-    </article>
-  )
-}
-
-export function generateMetadata() {
-  return { title: 'Team Identities - Auths Docs', description: 'Manage multiple identities and signing keys for your team' }
-}
diff --git a/app/globals.css b/app/globals.css
index 7806d96..8da13a5 100644
--- a/app/globals.css
+++ b/app/globals.css
@@ -1,96 +1,198 @@
 @import "tailwindcss";
 
+/* ---------------------------------------------------------------------------
+ * The ledger, for reading: the marketing site's paper-and-ink palette tuned
+ * for long-form docs. One accent (the seal); the reserved red means exactly
+ * one thing — a denial. Terminals and code panes are the only dark objects
+ * in light mode. Typeface: the system stack (unchanged).
+ * ------------------------------------------------------------------------ */
+
+:root {
+  --paper: #f6f3ec;
+  --paper-deep: #ece7db;
+  --ink: #1c1814;
+  --ink-soft: #5b5448;
+  --ink-faint: #726c5e;
+  --rule: rgba(28, 24, 20, 0.16);
+  --seal: #c2401b;
+  --seal-deep: #9c3214;
+  --deny: #c0442e;
+  --terminal: #15130f;
+}
+
+.dark {
+  --paper: #141210;
+  --paper-deep: #1d1a16;
+  --ink: #eae5db;
+  --ink-soft: #b3aa9b;
+  --ink-faint: #948b7c;
+  --rule: rgba(234, 229, 219, 0.14);
+  --seal: #e8845c;
+  --seal-deep: #f09b78;
+  --deny: #e2664a;
+  --terminal: #100e0b;
+}
+
+@theme inline {
+  --color-paper: var(--paper);
+  --color-paper-deep: var(--paper-deep);
+  --color-ink: var(--ink);
+  --color-ink-soft: var(--ink-soft);
+  --color-ink-faint: var(--ink-faint);
+  --color-rule: var(--rule);
+  --color-seal: var(--seal);
+  --color-seal-deep: var(--seal-deep);
+  --color-deny: var(--deny);
+  --color-terminal: var(--terminal);
+}
+
 html {
   scroll-behavior: smooth;
+  scroll-padding-top: 5rem;
+}
+
+body {
+  background: var(--paper);
+  color: var(--ink);
 }
 
-/* Prose typography */
+/* ---------------------------------------------------------------------------
+ * Prose — one comfortable measure, generous rhythm, hairline rules.
+ * Code fences render through the CodeBlock component, not prose styles.
+ * ------------------------------------------------------------------------ */
+
 article.prose {
-  color: theme(colors.gray.900);
-  line-height: 1.75;
+  color: var(--ink-soft);
+  line-height: 1.7;
+  font-size: 1rem;
 }
 
 .prose h2 {
-  margin-top: 2rem;
+  margin-top: 3rem;
   margin-bottom: 1rem;
-  font-size: 1.875rem;
+  padding-top: 1.25rem;
+  border-top: 1px solid var(--rule);
+  font-size: 1.5rem;
   font-weight: 700;
+  letter-spacing: -0.015em;
+  color: var(--ink);
+  scroll-margin-top: 6rem;
 }
 
 .prose h3 {
-  margin-top: 1.5rem;
+  margin-top: 2rem;
   margin-bottom: 0.75rem;
-  font-size: 1.25rem;
+  font-size: 1.125rem;
   font-weight: 600;
+  color: var(--ink);
+  scroll-margin-top: 6rem;
 }
 
 .prose p {
   margin-bottom: 1rem;
 }
 
-.prose ul,
-.prose ol {
+.prose strong {
+  color: var(--ink);
+  font-weight: 600;
+}
+
+.prose ul:not(:where(.not-prose, .not-prose *)),
+.prose ol:not(:where(.not-prose, .not-prose *)) {
   margin-bottom: 1rem;
-  margin-left: 1.5rem;
-  padding-left: 1rem;
+  padding-left: 1.5rem;
 }
 
-.prose li {
-  margin-bottom: 0.5rem;
+.prose li:not(:where(.not-prose, .not-prose *)) {
+  margin-bottom: 0.4rem;
 }
 
-.prose ul li {
+.prose ul li:not(:where(.not-prose, .not-prose *)) {
   list-style-type: disc;
 }
 
-.prose ol li {
+.prose ol li:not(:where(.not-prose, .not-prose *)) {
   list-style-type: decimal;
 }
 
-/* Code blocks */
-.prose pre {
-  background-color: #1f2937;
-  color: #f3f4f6;
-  padding: 1rem;
-  border-radius: 0.5rem;
-  overflow-x: auto;
-  margin-bottom: 1rem;
-}
-
-.prose pre code {
-  background-color: transparent;
-  color: inherit;
-  padding: 0;
-  font-size: 0.875rem;
-  line-height: 1.5;
+.prose li:not(:where(.not-prose, .not-prose *))::marker {
+  color: var(--ink-faint);
 }
 
-/* Inline code */
+/* Inline code — an ink chip, never a color of its own. */
 .prose :not(pre) > code {
-  background-color: #f3f4f6;
-  color: #dc2626;
+  background: color-mix(in srgb, var(--ink) 6%, transparent);
+  color: var(--ink);
   padding: 0.125rem 0.375rem;
   border-radius: 0.25rem;
-  font-family: ui-monospace, monospace;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
   font-size: 0.875em;
-  font-weight: 600;
+  font-weight: 500;
 }
 
-/* Links */
 .prose a {
-  color: #2563eb;
+  color: var(--seal);
   text-decoration: none;
+  border-bottom: 1px solid color-mix(in srgb, var(--seal) 40%, transparent);
+  transition: border-color 150ms ease;
 }
 
 .prose a:hover {
-  text-decoration: underline;
+  border-bottom-color: var(--seal);
+}
+
+.prose a:has(code) {
+  border-bottom: none;
 }
 
-/* Blockquotes */
 .prose blockquote {
-  border-left: 4px solid #e5e7eb;
+  border-left: 2px solid color-mix(in srgb, var(--seal) 50%, transparent);
   padding-left: 1rem;
   font-style: italic;
-  color: #6b7280;
+  color: var(--ink);
   margin: 1.5rem 0;
 }
+
+/* Tables — hairlines, mono heads, no zebra. */
+.prose table {
+  width: 100%;
+  margin: 1.5rem 0;
+  border-collapse: collapse;
+  font-size: 0.9rem;
+}
+
+.prose thead th {
+  text-align: left;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 0.72rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--ink-faint);
+  border-bottom: 1px solid var(--rule);
+  padding: 0.5rem 0.75rem 0.5rem 0;
+}
+
+.prose tbody td {
+  border-bottom: 1px solid var(--rule);
+  padding: 0.6rem 0.75rem 0.6rem 0;
+  vertical-align: top;
+}
+
+.prose tbody tr:last-child td {
+  border-bottom: none;
+}
+
+.prose hr {
+  border: none;
+  border-top: 1px solid var(--rule);
+  margin: 2.5rem 0;
+}
+
+/* Anchored headings: hover reveals a link affordance. */
+.prose h2:hover::after,
+.prose h3:hover::after {
+  content: " #";
+  color: var(--ink-faint);
+  font-weight: 400;
+}
diff --git a/app/layout.tsx b/app/layout.tsx
index 3c8ca43..36eeff3 100644
--- a/app/layout.tsx
+++ b/app/layout.tsx
@@ -1,21 +1,32 @@
 import type { Metadata } from 'next'
 import './globals.css'
 
+const SEAL_FAVICON =
+  'data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><circle cx="50" cy="50" r="38" fill="%23c2401b"/></svg>'
+
 export const metadata: Metadata = {
-  title: 'Auths Docs',
-  description: 'Documentation for Auths - proof of provenance for code.',
-  icons: {
-    icon: 'data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><text y=".9em" font-size="90">🔐</text></svg>',
-  },
+  title: 'Auths docs',
+  description:
+    'Bound an AI agent to a scope, a budget, and an expiry — and prove it with receipts anyone can verify.',
+  icons: { icon: SEAL_FAVICON },
 }
 
-export default function RootLayout({
-  children,
-}: {
-  children: React.ReactNode
-}) {
+/** Applies the stored (or system) theme before paint — no flash. */
+const THEME_SCRIPT = `
+try {
+  var t = localStorage.getItem('auths.docs.theme');
+  if (t === 'dark' || (!t && window.matchMedia('(prefers-color-scheme: dark)').matches)) {
+    document.documentElement.classList.add('dark');
+  }
+} catch (e) {}
+`
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
   return (
-    <html lang="en">
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <script dangerouslySetInnerHTML={{ __html: THEME_SCRIPT }} />
+      </head>
       <body>{children}</body>
     </html>
   )
diff --git a/app/page.tsx b/app/page.tsx
index e6412da..d855f2a 100644
--- a/app/page.tsx
+++ b/app/page.tsx
@@ -1,150 +1,5 @@
-export default function Home() {
-  return (
-    <main className="min-h-screen bg-white">
-      {/* Header */}
-      <header className="border-b border-gray-200">
-        <div className="max-w-7xl mx-auto px-6 sm:px-8 lg:px-12 h-16 flex items-center justify-between">
-          <div className="flex items-center gap-2">
-            <span className="text-2xl">🔐</span>
-            <span className="font-semibold text-gray-900 text-lg">Auths</span>
-          </div>
-          <a
-            href="https://github.com/auths-dev/auths"
-            className="text-sm text-gray-600 hover:text-gray-900 transition"
-            target="_blank"
-            rel="noopener noreferrer"
-          >
-            GitHub
-          </a>
-        </div>
-      </header>
-
-      {/* Hero Section */}
-      <section className="border-b border-gray-200">
-        <div className="max-w-7xl mx-auto px-6 sm:px-8 lg:px-12 py-20 sm:py-32">
-          <div className="max-w-3xl">
-            <h1 className="text-5xl sm:text-6xl font-bold text-gray-900 mb-6 leading-tight">
-              Cryptographically verify code provenance
-            </h1>
-            <p className="text-xl text-gray-600 mb-8 leading-relaxed">
-              Sign commits, manage team identities, and prove the origin of your code with Auths. Production-ready tooling for secure software supply chains.
-            </p>
-            <div className="flex flex-col sm:flex-row gap-4">
-              <a
-                href="/docs/quickstart"
-                className="inline-flex items-center justify-center px-6 py-3 bg-gray-900 text-white font-medium rounded-lg hover:bg-gray-800 transition"
-              >
-                Get Started
-              </a>
-              <a
-                href="/docs/sign-commits"
-                className="inline-flex items-center justify-center px-6 py-3 border border-gray-300 text-gray-900 font-medium rounded-lg hover:border-gray-400 hover:bg-gray-50 transition"
-              >
-                Read the Guide
-              </a>
-            </div>
-          </div>
-        </div>
-      </section>
-
-      {/* Quick Links Section */}
-      <section>
-        <div className="max-w-7xl mx-auto px-6 sm:px-8 lg:px-12 py-16 sm:py-24">
-          <h2 className="text-3xl font-bold text-gray-900 mb-12">Documentation</h2>
-
-          <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-8">
-            {/* Guides */}
-            <div className="group cursor-pointer">
-              <a href="/docs/sign-commits" className="block">
-                <div className="mb-4">
-                  <span className="text-3xl">📖</span>
-                </div>
-                <h3 className="text-xl font-semibold text-gray-900 mb-2 group-hover:text-blue-600 transition">
-                  Guides
-                </h3>
-                <p className="text-gray-600 mb-4 leading-relaxed">
-                  Learn how to sign commits, manage team identities, build agents, and prove code provenance.
-                </p>
-                <div className="flex items-center gap-2 text-blue-600 font-medium">
-                  Explore
-                  <span className="transition group-hover:translate-x-1">→</span>
-                </div>
-              </a>
-            </div>
+import { redirect } from 'next/navigation'
 
-            {/* Concepts */}
-            <div className="group cursor-pointer">
-              <a href="/docs/concepts/identity-model" className="block">
-                <div className="mb-4">
-                  <span className="text-3xl">💡</span>
-                </div>
-                <h3 className="text-xl font-semibold text-gray-900 mb-2 group-hover:text-blue-600 transition">
-                  Concepts
-                </h3>
-                <p className="text-gray-600 mb-4 leading-relaxed">
-                  Understand the identity model, key rotation, delegation mechanisms, and cryptographic foundations.
-                </p>
-                <div className="flex items-center gap-2 text-blue-600 font-medium">
-                  Learn
-                  <span className="transition group-hover:translate-x-1">→</span>
-                </div>
-              </a>
-            </div>
-
-            {/* Reference */}
-            <div className="group cursor-pointer">
-              <a href="/docs/reference/cli" className="block">
-                <div className="mb-4">
-                  <span className="text-3xl">⚙️</span>
-                </div>
-                <h3 className="text-xl font-semibold text-gray-900 mb-2 group-hover:text-blue-600 transition">
-                  Reference
-                </h3>
-                <p className="text-gray-600 mb-4 leading-relaxed">
-                  Complete CLI reference, API documentation, and GitHub Actions integration details.
-                </p>
-                <div className="flex items-center gap-2 text-blue-600 font-medium">
-                  Reference
-                  <span className="transition group-hover:translate-x-1">→</span>
-                </div>
-              </a>
-            </div>
-          </div>
-        </div>
-      </section>
-
-      {/* Footer */}
-      <footer className="border-t border-gray-200 bg-gray-50">
-        <div className="max-w-7xl mx-auto px-6 sm:px-8 lg:px-12 py-8 sm:py-12">
-          <div className="flex flex-col sm:flex-row justify-between items-start sm:items-center gap-8">
-            <div className="flex items-center gap-2">
-              <span className="text-xl">🔐</span>
-              <span className="font-semibold text-gray-900">Auths</span>
-            </div>
-            <div className="flex gap-8">
-              <a
-                href="https://github.com/auths-dev/auths"
-                className="text-sm text-gray-600 hover:text-gray-900 transition"
-                target="_blank"
-                rel="noopener noreferrer"
-              >
-                GitHub
-              </a>
-              <a
-                href="https://auths.dev"
-                className="text-sm text-gray-600 hover:text-gray-900 transition"
-                target="_blank"
-                rel="noopener noreferrer"
-              >
-                auths.dev
-              </a>
-            </div>
-          </div>
-          <p className="text-sm text-gray-500 mt-8">
-            © 2026 auths-dev. Auths is open source and available on GitHub.
-          </p>
-        </div>
-      </footer>
-    </main>
-  )
+export default function Home() {
+  redirect('/docs')
 }
diff --git a/bun.lock b/bun.lock
index 9d10885..2c05683 100644
--- a/bun.lock
+++ b/bun.lock
@@ -8,8 +8,10 @@
         "@markdoc/markdoc": "^0.5.7",
         "github-slugger": "^2.0.0",
         "js-yaml": "^4.1.1",
+        "lucide-react": "^1.25.0",
         "next": "latest",
         "prism-react-renderer": "^2.4.1",
+        "prismjs": "^1.30.0",
         "react": "^19.0.0",
         "react-dom": "^19.0.0",
       },
@@ -667,6 +669,8 @@
 
     "lru-cache": ["lru-cache@5.1.1", "", { "dependencies": { "yallist": "^3.0.2" } }, "sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w=="],
 
+    "lucide-react": ["lucide-react@1.25.0", "", { "peerDependencies": { "react": "^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0" } }, "sha512-/mdJTRbiwcLOQ1NZZK1amZF9rIZyvO18D6r9TngE6TG1NmqHgFuT4eE7Xrkm9UsXMbBJD1NlfwHVltCDWHrOTw=="],
+
     "magic-string": ["magic-string@0.30.21", "", { "dependencies": { "@jridgewell/sourcemap-codec": "^1.5.5" } }, "sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ=="],
 
     "math-intrinsics": ["math-intrinsics@1.1.0", "", {}, "sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g=="],
@@ -745,6 +749,8 @@
 
     "prism-react-renderer": ["prism-react-renderer@2.4.1", "", { "dependencies": { "@types/prismjs": "^1.26.0", "clsx": "^2.0.0" }, "peerDependencies": { "react": ">=16.0.0" } }, "sha512-ey8Ls/+Di31eqzUxC46h8MksNuGx/n0AAC8uKpwFau4RPDYLuE3EXTp8N8G2vX2N7UC/+IXeNUnlWBGGcAG+Ig=="],
 
+    "prismjs": ["prismjs@1.30.0", "", {}, "sha512-DEvV2ZF2r2/63V+tK8hQvrR2ZGn10srHbXviTlcv7Kpzw8jWiNTqbVgjO3IY8RxrrOUF8VPMQQFysYYYv0YZxw=="],
+
     "prop-types": ["prop-types@15.8.1", "", { "dependencies": { "loose-envify": "^1.4.0", "object-assign": "^4.1.1", "react-is": "^16.13.1" } }, "sha512-oj87CgZICdulUohogVAR7AjlC0327U4el4L6eAvOqCeudMDVU0NThNaV+b9Df4dXgSP1gXMTnPdhfe/2qDH5cg=="],
 
     "punycode": ["punycode@2.3.1", "", {}, "sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg=="],
diff --git a/components/CodeBlock.tsx b/components/CodeBlock.tsx
deleted file mode 100644
index b025119..0000000
--- a/components/CodeBlock.tsx
+++ /dev/null
@@ -1,26 +0,0 @@
-'use client'
-
-import { Highlight, themes } from 'prism-react-renderer'
-
-interface CodeBlockProps {
-  language?: string
-  content: string
-}
-
-export function CodeBlock({ language = 'bash', content }: CodeBlockProps) {
-  return (
-    <Highlight theme={themes.oneDark} code={content} language={language as any}>
-      {({ className, style, tokens, getLineProps, getTokenProps }) => (
-        <pre className={className} style={style}>
-          {tokens.map((line, i) => (
-            <div key={i} {...getLineProps({ line, key: i })}>
-              {line.map((token, key) => (
-                <span key={key} {...getTokenProps({ token, key })} />
-              ))}
-            </div>
-          ))}
-        </pre>
-      )}
-    </Highlight>
-  )
-}
diff --git a/components/docs/CodeExamples.tsx b/components/docs/CodeExamples.tsx
deleted file mode 100644
index b0af0c9..0000000
--- a/components/docs/CodeExamples.tsx
+++ /dev/null
@@ -1,153 +0,0 @@
-'use client'
-
-import { usePathname } from 'next/navigation'
-
-interface CodeExample {
-  label: string
-  language: string
-  code: string
-}
-
-const codeExamples: Record<string, CodeExample[]> = {
-  '/docs/sign-commits': [
-    {
-      label: 'Sign a commit (automatic after init)',
-      language: 'bash',
-      code: `git commit -m "Add new feature"`,
-    },
-    {
-      label: 'Verify the latest commit',
-      language: 'bash',
-      code: `auths verify HEAD`,
-    },
-    {
-      label: 'Verify any commit or range',
-      language: 'bash',
-      code: `auths verify abc1234
-auths verify main..HEAD`,
-    },
-  ],
-  '/docs/team-identities': [
-    {
-      label: 'Share your identity',
-      language: 'bash',
-      code: `auths whoami`,
-    },
-    {
-      label: 'Pin a teammate',
-      language: 'bash',
-      code: `auths trust pin \\
-  --did did:keri:E... \\
-  --key <pubkey-hex>`,
-    },
-    {
-      label: 'Export a CI bundle',
-      language: 'bash',
-      code: `auths id export-bundle --alias main \\
-  --output .auths/ci-bundle.json \\
-  --max-age-secs 31536000`,
-    },
-  ],
-  '/docs/build-agents': [
-    {
-      label: 'Delegate an agent',
-      language: 'bash',
-      code: `auths id agent add \\
-  --label ci-bot --key main \\
-  --scope sign_commit`,
-    },
-    {
-      label: 'Sign in CI',
-      language: 'yaml',
-      code: `- uses: auths-dev/sign@v1
-  with:
-    files: 'dist/*'
-    auths-version: '0.1.2'`,
-    },
-    {
-      label: 'Verify in CI',
-      language: 'yaml',
-      code: `- uses: auths-dev/verify@v1
-  with:
-    auths-version: '0.1.2'
-    identity-bundle: .auths/ci-bundle.json`,
-    },
-  ],
-  '/docs/prove-provenance': [
-    {
-      label: 'Verify a commit range',
-      language: 'bash',
-      code: `auths verify main..HEAD`,
-    },
-    {
-      label: 'Sign an artifact',
-      language: 'bash',
-      code: `auths artifact sign release.tar.gz`,
-    },
-    {
-      label: 'Stateless verification (CI)',
-      language: 'bash',
-      code: `auths verify HEAD \\
-  --identity-bundle .auths/ci-bundle.json`,
-    },
-  ],
-  '/docs/installation': [
-    {
-      label: 'Install via Homebrew',
-      language: 'bash',
-      code: `brew install auths-dev/auths-cli/auths`,
-    },
-    {
-      label: 'Install via Cargo',
-      language: 'bash',
-      code: `cargo install auths-cli`,
-    },
-    {
-      label: 'Verify installation',
-      language: 'bash',
-      code: `auths --version
-auths doctor`,
-    },
-  ],
-}
-
-export function CodeExamples() {
-  const pathname = usePathname()
-  const examples = codeExamples[pathname] || []
-
-  if (examples.length === 0) {
-    return null
-  }
-
-  return (
-    <div className="space-y-8">
-      <div className="sticky top-14 bg-white pt-2 pb-4">
-        <h3 className="text-xs font-semibold text-gray-900 uppercase tracking-wide">
-          Examples
-        </h3>
-      </div>
-
-      {examples.map((example, idx) => (
-        <div key={idx} className="space-y-2">
-          <p className="text-xs font-medium text-gray-600">{example.label}</p>
-          <div className="relative group">
-            <pre className="bg-gray-950 text-gray-100 p-3 rounded text-xs leading-relaxed overflow-x-auto border border-gray-800">
-              <code className="font-mono">{example.code}</code>
-            </pre>
-          </div>
-        </div>
-      ))}
-
-      <div className="text-center pt-4">
-        <a
-          href="https://github.com/auths-dev/auths"
-          target="_blank"
-          rel="noopener noreferrer"
-          className="text-xs text-blue-600 hover:text-blue-700 font-medium"
-        >
-          View on GitHub →
-        </a>
-      </div>
-    </div>
-  )
-}
diff --git a/components/docs/DocWrapper.tsx b/components/docs/DocWrapper.tsx
deleted file mode 100644
index 332458d..0000000
--- a/components/docs/DocWrapper.tsx
+++ /dev/null
@@ -1,17 +0,0 @@
-import { DocsPrevNext } from './DocsPrevNext'
-
-interface DocWrapperProps {
-  children: React.ReactNode
-}
-
-export function DocWrapper({ children }: DocWrapperProps) {
-  return (
-    <article className="prose prose-gray max-w-none">
-      {/* Main content */}
-      <div className="space-y-6">{children}</div>
-
-      {/* Prev/Next navigation */}
-      <DocsPrevNext />
-    </article>
-  )
-}
diff --git a/components/docs/DocsLayout.tsx b/components/docs/DocsLayout.tsx
deleted file mode 100644
index 3dc6562..0000000
--- a/components/docs/DocsLayout.tsx
+++ /dev/null
@@ -1 +0,0 @@
-// This component is no longer needed - the app/docs/layout.tsx handles layout
diff --git a/components/docs/DocsMobileDrawer.tsx b/components/docs/DocsMobileDrawer.tsx
index f01de84..ab6b825 100644
--- a/components/docs/DocsMobileDrawer.tsx
+++ b/components/docs/DocsMobileDrawer.tsx
@@ -1,78 +1,52 @@
 'use client'
 
+import { useEffect, useState } from 'react'
 import { usePathname } from 'next/navigation'
-import { useState, useEffect } from 'react'
+import { Menu, X } from 'lucide-react'
 import { DocsSidebar } from './DocsSidebar'
+import type { ProductNav } from '@/lib/content'
 
-export function DocsMobileDrawer() {
+export function DocsMobileDrawer({ nav }: { nav: ProductNav[] }) {
   const [isOpen, setIsOpen] = useState(false)
   const pathname = usePathname()
 
-  // Close drawer when pathname changes
   useEffect(() => {
     setIsOpen(false)
   }, [pathname])
 
   return (
     <>
-      {/* Hamburger button */}
       <button
         onClick={() => setIsOpen(true)}
-        className="lg:hidden fixed bottom-6 right-6 z-30 w-12 h-12 bg-blue-600 text-white rounded-full flex items-center justify-center hover:bg-blue-700 transition shadow-lg"
+        className="fixed bottom-6 right-6 z-30 flex h-12 w-12 items-center justify-center rounded-full bg-seal text-paper shadow-lg transition-colors hover:bg-seal-deep lg:hidden"
         aria-label="Open menu"
       >
-        <svg
-          className="w-6 h-6"
-          fill="none"
-          stroke="currentColor"
-          viewBox="0 0 24 24"
-        >
-          <path
-            strokeLinecap="round"
-            strokeLinejoin="round"
-            strokeWidth={2}
-            d="M4 6h16M4 12h16M4 18h16"
-          />
-        </svg>
+        <Menu size={20} />
       </button>
 
-      {/* Backdrop */}
       {isOpen && (
         <div
-          className="fixed inset-0 bg-black/50 z-40 lg:hidden"
+          className="fixed inset-0 z-40 bg-black/50 lg:hidden"
           onClick={() => setIsOpen(false)}
         />
       )}
 
-      {/* Drawer */}
       <div
-        className={`fixed top-0 left-0 bottom-0 w-64 bg-white z-50 transform transition lg:hidden ${
+        className={`fixed bottom-0 left-0 top-0 z-50 w-72 transform bg-paper transition lg:hidden ${
           isOpen ? 'translate-x-0' : '-translate-x-full'
         }`}
       >
-        <div className="h-14 border-b border-gray-200 flex items-center px-4">
+        <div className="flex h-14 items-center border-b border-rule px-4">
           <button
             onClick={() => setIsOpen(false)}
-            className="ml-auto text-gray-500 hover:text-gray-900"
+            className="ml-auto text-ink-faint hover:text-ink"
             aria-label="Close menu"
           >
-            <svg
-              className="w-6 h-6"
-              fill="none"
-              stroke="currentColor"
-              viewBox="0 0 24 24"
-            >
-              <path
-                strokeLinecap="round"
-                strokeLinejoin="round"
-                strokeWidth={2}
-                d="M6 18L18 6M6 6l12 12"
-              />
-            </svg>
+            <X size={20} />
           </button>
         </div>
-        <div className="overflow-y-auto h-[calc(100vh-3.5rem)] p-4">
-          <DocsSidebar />
+        <div className="h-[calc(100vh-3.5rem)] overflow-y-auto p-4">
+          <DocsSidebar nav={nav} />
         </div>
       </div>
     </>
diff --git a/components/docs/DocsPrevNext.tsx b/components/docs/DocsPrevNext.tsx
index d08afdc..b8f6633 100644
--- a/components/docs/DocsPrevNext.tsx
+++ b/components/docs/DocsPrevNext.tsx
@@ -1,38 +1,33 @@
-'use client'
-
-import { usePathname } from 'next/navigation'
-import { getPrevNext } from '@/lib/docs-navigation'
-
-export function DocsPrevNext() {
-  const pathname = usePathname()
-  const { prev, next } = getPrevNext(pathname)
+import Link from 'next/link'
+import type { NavItem } from '@/lib/content'
 
+export function DocsPrevNext({ prev, next }: { prev: NavItem | null; next: NavItem | null }) {
+  if (!prev && !next) return null
   return (
-    <div className="border-t border-gray-200 mt-12 pt-8 grid grid-cols-2 gap-4">
+    <div className="mt-14 grid grid-cols-2 gap-4 border-t border-rule pt-8">
       {prev ? (
-        <a
+        <Link
           href={prev.href}
-          className="group flex flex-col gap-2 p-4 border border-gray-200 rounded-lg hover:border-gray-300 hover:bg-gray-50 transition"
+          className="group flex flex-col gap-1.5 rounded-lg border border-rule p-4 transition-colors hover:border-seal/50"
         >
-          <span className="text-xs text-gray-500 group-hover:text-gray-700">← Previous</span>
-          <span className="font-semibold text-gray-900 group-hover:text-blue-600 transition">
+          <span className="font-mono text-[11px] text-ink-faint">← Previous</span>
+          <span className="font-semibold text-ink transition-colors group-hover:text-seal-deep">
             {prev.label}
           </span>
-        </a>
+        </Link>
       ) : (
         <div />
       )}
-
       {next ? (
-        <a
+        <Link
           href={next.href}
-          className="group flex flex-col gap-2 p-4 border border-gray-200 rounded-lg hover:border-gray-300 hover:bg-gray-50 transition text-right"
+          className="group flex flex-col gap-1.5 rounded-lg border border-rule p-4 text-right transition-colors hover:border-seal/50"
         >
-          <span className="text-xs text-gray-500 group-hover:text-gray-700">Next →</span>
-          <span className="font-semibold text-gray-900 group-hover:text-blue-600 transition">
+          <span className="font-mono text-[11px] text-ink-faint">Next →</span>
+          <span className="font-semibold text-ink transition-colors group-hover:text-seal-deep">
             {next.label}
           </span>
-        </a>
+        </Link>
       ) : (
         <div />
       )}
diff --git a/components/docs/DocsSidebar.tsx b/components/docs/DocsSidebar.tsx
index 1170081..2f749db 100644
--- a/components/docs/DocsSidebar.tsx
+++ b/components/docs/DocsSidebar.tsx
@@ -1,44 +1,90 @@
 'use client'
 
+import { useState } from 'react'
+import Link from 'next/link'
 import { usePathname } from 'next/navigation'
-import { docsNavigation, isPlaceholder } from '@/lib/docs-navigation'
+import type { ProductNav } from '@/lib/content'
 
-export function DocsSidebar() {
+/**
+ * Frontmatter-derived nav with the product switch on top: auths-mcp and
+ * Identity & signing are separate worlds that never intermix.
+ */
+
+function productForPath(nav: ProductNav[], pathname: string): ProductNav['product'] {
+  for (const p of nav) {
+    if (p.sections.some((s) => s.items.some((i) => i.href === pathname))) return p.product
+  }
+  return 'mcp'
+}
+
+export function DocsSidebar({ nav }: { nav: ProductNav[] }) {
   const pathname = usePathname()
+  const currentProduct = productForPath(nav, pathname)
+  const [product, setProduct] = useState<ProductNav['product']>(currentProduct)
+  const active = nav.find((p) => p.product === product) ?? nav[0]
 
   return (
     <nav className="space-y-8">
-      {docsNavigation.map((section) => (
+      <div
+        role="tablist"
+        aria-label="Product"
+        className="flex rounded-lg border border-rule bg-paper p-1"
+      >
+        {nav.map((p) => (
+          <button
+            key={p.product}
+            role="tab"
+            type="button"
+            aria-selected={p.product === product}
+            onClick={() => setProduct(p.product)}
+            className={`flex-1 rounded-md px-2 py-1.5 font-mono text-[12px] transition-colors ${
+              p.product === product
+                ? 'bg-paper-deep font-semibold text-ink'
+                : 'text-ink-faint hover:text-ink'
+            }`}
+          >
+            {p.label}
+          </button>
+        ))}
+      </div>
+
+      {active.sections.map((section) => (
         <div key={section.title}>
-          <h3 className="text-xs font-semibold text-gray-500 uppercase tracking-widest mb-4 px-2">
+          <h3 className="mb-3 px-2 font-mono text-[11px] font-semibold uppercase tracking-[0.15em] text-ink-faint">
             {section.title}
           </h3>
-          <ul className="space-y-1">
+          <ul className="space-y-0.5">
             {section.items.map((item) => {
               const isActive = pathname === item.href
-              const isPlaceholderItem = isPlaceholder(item)
-
-              return (
-                <li key={item.href}>
-                  {isPlaceholderItem ? (
-                    <div className="flex items-center justify-between px-3 py-2 text-sm text-gray-400 cursor-not-allowed">
+              if (item.badge === 'soon') {
+                return (
+                  <li key={item.href}>
+                    <div className="flex cursor-default items-center justify-between px-3 py-1.5 text-sm text-ink-faint/70">
                       <span>{item.label}</span>
-                      <span className="text-xs bg-gray-200 text-gray-600 px-2 py-0.5 rounded text-xs">
+                      <span className="rounded-sm border border-rule px-1.5 py-0.5 font-mono text-[10px] text-ink-faint">
                         soon
                       </span>
                     </div>
-                  ) : (
-                    <a
-                      href={item.href}
-                      className={`block px-3 py-2 text-sm rounded transition ${
-                        isActive
-                          ? 'bg-blue-50 text-blue-900 font-semibold border-l-2 border-blue-600'
-                          : 'text-gray-700 hover:text-gray-900 hover:bg-gray-100'
-                      }`}
-                    >
-                      {item.label}
-                    </a>
-                  )}
+                  </li>
+                )
+              }
+              return (
+                <li key={item.href}>
+                  <Link
+                    href={item.href}
+                    className={`flex items-center justify-between border-l-2 px-3 py-1.5 text-sm transition-colors ${
+                      isActive
+                        ? 'border-seal font-semibold text-ink'
+                        : 'border-transparent text-ink-soft hover:border-rule hover:text-ink'
+                    }`}
+                  >
+                    <span>{item.label}</span>
+                    {item.badge === 'new' ? (
+                      <span className="rounded-sm bg-seal/10 px-1.5 py-0.5 font-mono text-[10px] font-semibold text-seal">
+                        new
+                      </span>
+                    ) : null}
+                  </Link>
                 </li>
               )
             })}
diff --git a/components/docs/DocsTopBar.tsx b/components/docs/DocsTopBar.tsx
index afff207..232aca7 100644
--- a/components/docs/DocsTopBar.tsx
+++ b/components/docs/DocsTopBar.tsx
@@ -1,48 +1,36 @@
-'use client'
-
-import { usePathname } from 'next/navigation'
-import { docsNavigation } from '@/lib/docs-navigation'
+import Link from 'next/link'
+import { ThemeToggle } from './ThemeToggle'
 
 export function DocsTopBar() {
-  const pathname = usePathname()
-
-  // Find the current section
-  let currentSection = ''
-  for (const section of docsNavigation) {
-    for (const item of section.items) {
-      if (item.href === pathname) {
-        currentSection = section.title
-        break
-      }
-      if (item.items?.some((i) => i.href === pathname)) {
-        currentSection = section.title
-        break
-      }
-    }
-    if (currentSection) break
-  }
-
   return (
-    <nav className="border-b border-gray-200 sticky top-0 z-40 bg-white">
-      <div className="max-w-7xl mx-auto px-6 sm:px-8 lg:px-12 h-14 flex items-center justify-between">
-        <a href="/docs" className="flex items-center gap-2 font-semibold text-gray-900 hover:text-gray-700">
-          ← Auths
-        </a>
-
-        {currentSection && (
-          <div className="flex-1 text-center text-sm text-gray-600 hidden sm:block">
-            {currentSection}
-          </div>
-        )}
+    <nav className="sticky top-0 z-40 border-b border-rule bg-paper/90 backdrop-blur-sm">
+      <div className="mx-auto flex h-14 max-w-[88rem] items-center justify-between px-6">
+        <div className="flex items-baseline gap-2.5">
+          <Link href="/docs" className="font-semibold tracking-tight text-ink transition-opacity hover:opacity-80">
+            Auths
+          </Link>
+          <span className="font-mono text-[12px] uppercase tracking-[0.15em] text-ink-faint">
+            docs
+          </span>
+        </div>
 
-        <a
-          href="https://github.com/auths-dev/auths"
-          className="text-sm text-gray-600 hover:text-gray-900 transition"
-          target="_blank"
-          rel="noopener noreferrer"
-        >
-          GitHub
-        </a>
+        <div className="flex items-center gap-5">
+          <a
+            href="https://auths.dev"
+            className="font-mono text-[13px] text-ink-faint transition-colors hover:text-ink"
+          >
+            auths.dev
+          </a>
+          <a
+            href="https://github.com/auths-dev/auths"
+            target="_blank"
+            rel="noopener noreferrer"
+            className="font-mono text-[13px] text-ink-faint transition-colors hover:text-ink"
+          >
+            GitHub
+          </a>
+          <ThemeToggle />
+        </div>
       </div>
     </nav>
   )
diff --git a/components/docs/OnThisPage.tsx b/components/docs/OnThisPage.tsx
index 4079a3a..f64f668 100644
--- a/components/docs/OnThisPage.tsx
+++ b/components/docs/OnThisPage.tsx
@@ -111,8 +111,8 @@ export function OnThisPage() {
               href={`#${item.id}`}
               className={`block py-1 transition ${
                 activeId === item.id
-                  ? 'text-blue-600 font-medium'
-                  : 'text-gray-600 hover:text-gray-900'
+                  ? 'text-seal font-medium'
+                  : 'text-ink-faint hover:text-ink'
               }`}
             >
               {item.text}
diff --git a/components/docs/ThemeToggle.tsx b/components/docs/ThemeToggle.tsx
new file mode 100644
index 0000000..4a3a2db
--- /dev/null
+++ b/components/docs/ThemeToggle.tsx
@@ -0,0 +1,38 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+import { Moon, Sun } from 'lucide-react'
+
+/**
+ * Light/dark toggle. The root layout's inline script applies the stored (or
+ * system) theme before hydration, so there is no flash.
+ */
+export function ThemeToggle() {
+  const [dark, setDark] = useState<boolean | null>(null)
+
+  useEffect(() => {
+    setDark(document.documentElement.classList.contains('dark'))
+  }, [])
+
+  const toggle = () => {
+    const next = !document.documentElement.classList.contains('dark')
+    document.documentElement.classList.toggle('dark', next)
+    try {
+      window.localStorage.setItem('auths.docs.theme', next ? 'dark' : 'light')
+    } catch {
+      // Private mode: applies for this visit only.
+    }
+    setDark(next)
+  }
+
+  return (
+    <button
+      type="button"
+      onClick={toggle}
+      aria-label={dark ? 'Switch to light theme' : 'Switch to dark theme'}
+      className="rounded-md p-1.5 text-ink-faint transition-colors hover:text-ink focus-visible:outline focus-visible:outline-1 focus-visible:outline-seal"
+    >
+      {dark ? <Sun size={16} /> : <Moon size={16} />}
+    </button>
+  )
+}
diff --git a/components/markdoc/Callout.tsx b/components/markdoc/Callout.tsx
index 3348ae1..1d97253 100644
--- a/components/markdoc/Callout.tsx
+++ b/components/markdoc/Callout.tsx
@@ -1,45 +1,63 @@
-interface CalloutProps {
-  type?: 'info' | 'warning' | 'error'
-  title?: string
-  children: React.ReactNode
-}
+import { Info, TriangleAlert, OctagonAlert, Check, type LucideIcon } from 'lucide-react'
+
+/**
+ * The ledger's callouts: hairline frame, one icon, no emoji. `danger` is for
+ * real money and destructive actions — loud by design.
+ */
 
-export function Callout({ type = 'info', title, children }: CalloutProps) {
-  const styles = {
-    info: {
-      bg: 'bg-blue-50',
-      border: 'border-blue-200',
-      icon: '💡',
-      textColor: 'text-blue-900',
-      titleColor: 'text-blue-900',
-    },
-    warning: {
-      bg: 'bg-amber-50',
-      border: 'border-amber-200',
-      icon: '⚠️',
-      textColor: 'text-amber-900',
-      titleColor: 'text-amber-900',
-    },
-    error: {
-      bg: 'bg-red-50',
-      border: 'border-red-200',
-      icon: '❌',
-      textColor: 'text-red-900',
-      titleColor: 'text-red-900',
-    },
-  }
+type CalloutType = 'info' | 'warning' | 'danger' | 'success'
 
-  const style = styles[type]
+const STYLES: Record<
+  CalloutType,
+  { icon: LucideIcon; frame: string; iconColor: string; titleColor: string }
+> = {
+  info: {
+    icon: Info,
+    frame: 'border-rule bg-paper-deep/50',
+    iconColor: 'text-ink-soft',
+    titleColor: 'text-ink',
+  },
+  warning: {
+    icon: TriangleAlert,
+    frame: 'border-seal/40 bg-seal/[0.06]',
+    iconColor: 'text-seal',
+    titleColor: 'text-ink',
+  },
+  danger: {
+    icon: OctagonAlert,
+    frame: 'border-deny/50 bg-deny/[0.06]',
+    iconColor: 'text-deny',
+    titleColor: 'text-deny',
+  },
+  success: {
+    icon: Check,
+    frame: 'border-seal/40 bg-paper-deep/50',
+    iconColor: 'text-seal',
+    titleColor: 'text-ink',
+  },
+}
+
+export function Callout({
+  type = 'info',
+  title,
+  children,
+}: {
+  type?: CalloutType
+  title?: string
+  children: React.ReactNode
+}) {
+  const style = STYLES[type] ?? STYLES.info
+  const Icon = style.icon
 
   return (
-    <div className={`${style.bg} ${style.border} border-l-4 rounded-md p-4 my-4`}>
-      {title && (
-        <div className={`flex items-center gap-2 font-semibold ${style.titleColor} mb-2`}>
-          <span>{style.icon}</span>
-          {title}
+    <div className={`not-prose my-6 rounded-lg border p-4 ${style.frame}`}>
+      <div className="flex gap-3">
+        <Icon size={18} className={`mt-0.5 shrink-0 ${style.iconColor}`} aria-hidden="true" />
+        <div className="min-w-0 text-[15px] leading-7 text-ink-soft [&_a]:text-seal [&_code]:rounded-sm [&_code]:bg-ink/[0.06] [&_code]:px-1 [&_code]:py-0.5 [&_code]:font-mono [&_code]:text-[0.9em] [&_p+p]:mt-2">
+          {title ? <p className={`mb-1 font-semibold ${style.titleColor}`}>{title}</p> : null}
+          {children}
         </div>
-      )}
-      <div className={`${style.textColor} text-sm`}>{children}</div>
+      </div>
     </div>
   )
 }
diff --git a/components/markdoc/Cards.tsx b/components/markdoc/Cards.tsx
new file mode 100644
index 0000000..93dde36
--- /dev/null
+++ b/components/markdoc/Cards.tsx
@@ -0,0 +1,63 @@
+import Link from 'next/link'
+import {
+  ArrowUpRight,
+  Ban,
+  KeyRound,
+  ReceiptText,
+  SquareTerminal,
+  Wallet,
+  ShieldCheck,
+  type LucideIcon,
+} from 'lucide-react'
+
+const ICONS: Record<string, LucideIcon> = {
+  terminal: SquareTerminal,
+  receipt: ReceiptText,
+  key: KeyRound,
+  wallet: Wallet,
+  shield: ShieldCheck,
+  refusal: Ban,
+}
+
+export function CardGroup({ children }: { children: React.ReactNode }) {
+  return <div className="not-prose my-6 grid gap-4 sm:grid-cols-2">{children}</div>
+}
+
+export function Card({
+  title,
+  href,
+  icon,
+  children,
+}: {
+  title: string
+  href?: string
+  icon?: string
+  children?: React.ReactNode
+}) {
+  const Icon = icon ? ICONS[icon] : undefined
+  const body = (
+    <>
+      <div className="flex items-center gap-2.5">
+        {Icon ? <Icon size={17} className="shrink-0 text-seal" aria-hidden="true" /> : null}
+        <span className="font-semibold text-ink">{title}</span>
+        {href ? (
+          <ArrowUpRight
+            size={14}
+            className="ml-auto shrink-0 text-ink-faint transition-colors group-hover:text-seal"
+            aria-hidden="true"
+          />
+        ) : null}
+      </div>
+      <div className="mt-2 text-sm leading-6 text-ink-soft">{children}</div>
+    </>
+  )
+
+  const frame = 'rounded-lg border border-rule bg-paper p-4 transition-colors'
+  return href ? (
+    <Link href={href} className={`group block ${frame} hover:border-seal/50`}>
+      {body}
+    </Link>
+  ) : (
+    <div className={frame}>{body}</div>
+  )
+}
diff --git a/components/markdoc/CodeBlock.tsx b/components/markdoc/CodeBlock.tsx
new file mode 100644
index 0000000..e8e58f7
--- /dev/null
+++ b/components/markdoc/CodeBlock.tsx
@@ -0,0 +1,172 @@
+'use client'
+
+import { useCallback, useState } from 'react'
+import { Highlight, themes, type PrismTheme } from 'prism-react-renderer'
+import '@/components/markdoc/prism'
+
+/**
+ * The code surface of the docs, in the ledger's artifact frame: a dark pane
+ * (#15130f) that reads like a photograph tipped into the page. Every block
+ * has a one-click copy; `language="output"` (or "terminal") renders a
+ * session transcript with verdict-colored lines instead of syntax highlight.
+ */
+
+const OK = '#e8845c'
+const DENY = '#e2664a'
+const DIM = '#9a948c'
+const BODY = '#d6d3d1'
+
+/**
+ * Base highlight theme with comments pushed firmly into the background. The eye
+ * has to separate "run this" from "read this" at a glance, so comments — whole
+ * line or trailing annotation — render dim and italic while the command stays
+ * bright. Without this the base theme's comment hue sits too close to the code.
+ */
+const CODE_THEME: PrismTheme = {
+  ...themes.gruvboxMaterialDark,
+  styles: [
+    ...themes.gruvboxMaterialDark.styles,
+    { types: ['comment', 'prolog', 'cdata', 'shebang'], style: { color: '#736e64', fontStyle: 'italic' } },
+  ],
+}
+
+/**
+ * Fence-language normalization. Aliases collapse onto the grammar that is
+ * actually registered, and a fence with NO language renders as plain text —
+ * previously it defaulted to "bash", which mislabeled ASCII diagrams and,
+ * now that the bash grammar is real, would half-highlight them.
+ */
+const LANGUAGE_ALIASES: Record<string, string> = {
+  sh: 'bash',
+  shell: 'bash',
+  zsh: 'bash',
+  console: 'bash',
+}
+
+/** Transcript copy: only the runnable `$ ` lines, prompt stripped. */
+function commandsOnly(code: string): string {
+  const commands = code
+    .split('\n')
+    .filter((line) => line.startsWith('$ '))
+    .map((line) => line.slice(2))
+  return commands.length > 0 ? commands.join('\n') : code
+}
+
+function parseHighlight(spec?: string): Set<number> {
+  const lines = new Set<number>()
+  if (!spec) return lines
+  for (const part of spec.split(',')) {
+    const [a, b] = part.split('-').map((n) => parseInt(n.trim(), 10))
+    if (Number.isNaN(a)) continue
+    const end = Number.isNaN(b as number) || b === undefined ? a : b
+    for (let i = a; i <= end; i++) lines.add(i)
+  }
+  return lines
+}
+
+function CopyButton({ text }: { text: string }) {
+  const [copied, setCopied] = useState(false)
+  const copy = useCallback(async () => {
+    try {
+      await navigator.clipboard.writeText(text)
+      setCopied(true)
+      setTimeout(() => setCopied(false), 2000)
+    } catch {
+      // Clipboard unavailable — the text stays selectable.
+    }
+  }, [text])
+
+  return (
+    <button
+      type="button"
+      onClick={copy}
+      aria-label="Copy code"
+      className="rounded-sm px-1.5 py-0.5 font-mono text-[11px] transition-colors focus-visible:outline focus-visible:outline-1 focus-visible:outline-stone-400"
+      style={{ color: copied ? OK : DIM }}
+    >
+      {copied ? 'copied' : 'copy'}
+    </button>
+  )
+}
+
+/** A transcript line: verdicts and prompts colored like the real terminal. */
+function TerminalLine({ line }: { line: string }) {
+  if (line.startsWith('✓')) return <div style={{ color: OK }}>{line}</div>
+  if (line.startsWith('✗')) return <div style={{ color: DENY }}>{line}</div>
+  if (line.startsWith('#')) return <div style={{ color: DIM }}>{line}</div>
+  if (line.startsWith('$ ')) {
+    return (
+      <div>
+        <span className="select-none" style={{ color: DIM }}>
+          $&nbsp;
+        </span>
+        <span style={{ color: BODY }}>{line.slice(2)}</span>
+      </div>
+    )
+  }
+  return <div style={{ color: BODY }}>{line}</div>
+}
+
+export interface CodeBlockProps {
+  content: string
+  language?: string
+  filename?: string
+  label?: string
+  highlight?: string
+}
+
+export function CodeBlock({ content, language, filename, label, highlight }: CodeBlockProps) {
+  const code = content.replace(/\n$/, '')
+  const lang = LANGUAGE_ALIASES[language ?? ''] ?? language ?? 'text'
+  const isTerminal = lang === 'output' || lang === 'terminal'
+  const header = filename ?? label
+  const highlighted = parseHighlight(highlight)
+
+  return (
+    <div className="not-prose group my-6 overflow-hidden rounded-lg bg-[#15130f] shadow-[0_18px_45px_-14px_rgba(28,24,20,0.4)] ring-1 ring-black/20">
+      <div className="flex items-center justify-between border-b border-white/5 px-4 py-2">
+        <span className="font-mono text-[11px] tracking-wider" style={{ color: DIM }}>
+          {header ?? (isTerminal ? 'terminal' : lang)}
+        </span>
+        <span className="flex items-center gap-3">
+          {header && !isTerminal ? (
+            <span className="font-mono text-[11px]" style={{ color: '#6e6960' }}>
+              {lang}
+            </span>
+          ) : null}
+          <CopyButton text={isTerminal ? commandsOnly(code) : code} />
+        </span>
+      </div>
+
+      {isTerminal ? (
+        <div className="space-y-1 overflow-x-auto px-4 py-3.5 font-mono text-[13px] leading-relaxed">
+          {code.split('\n').map((line, i) => (
+            <TerminalLine key={i} line={line} />
+          ))}
+        </div>
+      ) : (
+        <Highlight theme={CODE_THEME} code={code} language={lang}>
+          {({ tokens, getLineProps, getTokenProps }) => (
+            <pre className="overflow-x-auto px-4 py-3.5 font-mono text-[13px] leading-relaxed">
+              {tokens.map((line, i) => {
+                const lineProps = getLineProps({ line })
+                const isHot = highlighted.has(i + 1)
+                return (
+                  <div
+                    key={i}
+                    {...lineProps}
+                    className={`${lineProps.className ?? ''} ${isHot ? '-mx-4 border-l-2 border-[#e8845c] bg-white/[0.045] px-4 pl-[14px]' : ''}`}
+                  >
+                    {line.map((token, key) => (
+                      <span key={key} {...getTokenProps({ token })} />
+                    ))}
+                  </div>
+                )
+              })}
+            </pre>
+          )}
+        </Highlight>
+      )}
+    </div>
+  )
+}
diff --git a/components/markdoc/CodeFence.tsx b/components/markdoc/CodeFence.tsx
deleted file mode 100644
index fc403b3..0000000
--- a/components/markdoc/CodeFence.tsx
+++ /dev/null
@@ -1,12 +0,0 @@
-'use client'
-
-import { CodeBlock } from '@/components/CodeBlock'
-
-interface CodeFenceProps {
-  language?: string
-  content: string
-}
-
-export function CodeFence({ language = 'bash', content }: CodeFenceProps) {
-  return <CodeBlock language={language} content={content} />
-}
diff --git a/components/markdoc/CodeTabs.tsx b/components/markdoc/CodeTabs.tsx
new file mode 100644
index 0000000..085b734
--- /dev/null
+++ b/components/markdoc/CodeTabs.tsx
@@ -0,0 +1,115 @@
+'use client'
+
+import {
+  Children,
+  isValidElement,
+  useEffect,
+  useId,
+  useRef,
+  useState,
+  type ReactElement,
+  type ReactNode,
+} from 'react'
+import { useLanguage } from './language-context'
+
+/**
+ * Synchronized multi-language code tabs. Every `CodeTabs` on the site
+ * subscribes to the shared language context: switching one switches all,
+ * the choice persists (localStorage) and deep-links (`?lang=`).
+ *
+ * SSR renders the first tab; if a block lacks the chosen language it falls
+ * back to its first tab with a quiet note instead of breaking the set.
+ */
+
+interface CodeTabProps {
+  lang: string
+  label?: string
+  children: ReactNode
+}
+
+export function CodeTab({ children }: CodeTabProps) {
+  return <>{children}</>
+}
+
+export function CodeTabs({ children }: { children: ReactNode }) {
+  const { lang, setLang } = useLanguage()
+  const baseId = useId()
+  const tabRefs = useRef<(HTMLButtonElement | null)[]>([])
+  const [hydrated, setHydrated] = useState(false)
+  useEffect(() => setHydrated(true), [])
+
+  const tabs = Children.toArray(children).filter(
+    (c): c is ReactElement<CodeTabProps> => isValidElement(c) && 'lang' in ((c.props as object) ?? {})
+  )
+  if (tabs.length === 0) return null
+
+  const langs = tabs.map((t) => t.props.lang)
+  // Until hydration, and whenever the chosen language is absent, show the
+  // block's own first tab.
+  const chosen = hydrated && lang && langs.includes(lang) ? lang : langs[0]
+  const activeIndex = langs.indexOf(chosen)
+  const fellBack = hydrated && lang !== null && !langs.includes(lang)
+
+  const onKeyDown = (e: React.KeyboardEvent) => {
+    if (e.key !== 'ArrowRight' && e.key !== 'ArrowLeft') return
+    e.preventDefault()
+    const delta = e.key === 'ArrowRight' ? 1 : -1
+    const next = (activeIndex + delta + tabs.length) % tabs.length
+    setLang(langs[next])
+    tabRefs.current[next]?.focus()
+  }
+
+  return (
+    <div className="not-prose my-6">
+      <div
+        role="tablist"
+        aria-label="Code language"
+        onKeyDown={onKeyDown}
+        className="flex items-center gap-1 border-b border-rule"
+      >
+        {tabs.map((tab, i) => {
+          const active = i === activeIndex
+          return (
+            <button
+              key={tab.props.lang}
+              ref={(el) => {
+                tabRefs.current[i] = el
+              }}
+              role="tab"
+              type="button"
+              id={`${baseId}-tab-${i}`}
+              aria-selected={active}
+              aria-controls={`${baseId}-panel-${i}`}
+              tabIndex={active ? 0 : -1}
+              onClick={() => setLang(tab.props.lang)}
+              className={`-mb-px rounded-t-sm border-b-2 px-3 py-1.5 font-mono text-[13px] transition-colors focus-visible:outline focus-visible:outline-1 focus-visible:outline-seal ${
+                active
+                  ? 'border-seal text-ink'
+                  : 'border-transparent text-ink-faint hover:text-ink'
+              }`}
+            >
+              {tab.props.label ?? tab.props.lang}
+            </button>
+          )
+        })}
+        {fellBack ? (
+          <span className="ml-auto pb-1 font-mono text-[11px] text-ink-faint">
+            not available in {lang} — showing {tabs[activeIndex].props.label ?? chosen}
+          </span>
+        ) : null}
+      </div>
+      {tabs.map((tab, i) => (
+        <div
+          key={tab.props.lang}
+          role="tabpanel"
+          id={`${baseId}-panel-${i}`}
+          aria-labelledby={`${baseId}-tab-${i}`}
+          hidden={i !== activeIndex}
+          className="[&_.not-prose]:my-0 [&_.not-prose]:rounded-t-none"
+        >
+          {tab}
+        </div>
+      ))}
+    </div>
+  )
+}
diff --git a/components/markdoc/Steps.tsx b/components/markdoc/Steps.tsx
new file mode 100644
index 0000000..c12bd2b
--- /dev/null
+++ b/components/markdoc/Steps.tsx
@@ -0,0 +1,23 @@
+/**
+ * Numbered steps with the ledger's hairline spine — the walk-through
+ * skeleton for quickstarts and guides.
+ */
+
+export function Steps({ children }: { children: React.ReactNode }) {
+  return <ol className="not-prose my-6 space-y-0">{children}</ol>
+}
+
+export function Step({ title, children }: { title: string; children: React.ReactNode }) {
+  return (
+    <li className="relative border-l border-rule pb-8 pl-8 last:border-transparent last:pb-0 [counter-increment:step]">
+      <span
+        aria-hidden="true"
+        className="absolute -left-[13px] top-0 flex h-[26px] w-[26px] items-center justify-center rounded-full border border-rule bg-paper font-mono text-[12px] font-semibold text-seal before:content-[counter(step)]"
+      />
+      <p className="pt-0.5 font-semibold text-ink">{title}</p>
+      <div className="mt-2 text-[15px] leading-7 text-ink-soft [&_a]:text-seal [&_code]:rounded-sm [&_code]:bg-ink/[0.06] [&_code]:px-1 [&_code]:py-0.5 [&_code]:font-mono [&_code]:text-[0.9em] [&_p+p]:mt-2 [&_ul]:mt-2 [&_ul]:list-disc [&_ul]:space-y-1 [&_ul]:pl-5">
+        {children}
+      </div>
+    </li>
+  )
+}
diff --git a/components/markdoc/VerdictChip.tsx b/components/markdoc/VerdictChip.tsx
new file mode 100644
index 0000000..c64b496
--- /dev/null
+++ b/components/markdoc/VerdictChip.tsx
@@ -0,0 +1,22 @@
+/**
+ * A verdict as it reads on the wire — exact strings only. `allowed` and
+ * `consistent` carry the warm accent; every refusal carries the reserved
+ * red, which means exactly one thing on this site: a denial.
+ */
+
+const POSITIVE = new Set(['allowed', 'consistent'])
+
+export function VerdictChip({ code }: { code: string }) {
+  const positive = POSITIVE.has(code)
+  return (
+    <code
+      className={`whitespace-nowrap rounded-sm border px-1.5 py-0.5 font-mono text-[0.85em] font-medium ${
+        positive
+          ? 'border-seal/40 bg-seal/[0.07] text-seal-deep'
+          : 'border-deny/40 bg-deny/[0.06] text-deny'
+      }`}
+    >
+      {code}
+    </code>
+  )
+}
diff --git a/components/markdoc/language-context.tsx b/components/markdoc/language-context.tsx
new file mode 100644
index 0000000..ebfad74
--- /dev/null
+++ b/components/markdoc/language-context.tsx
@@ -0,0 +1,49 @@
+'use client'
+
+import { createContext, useContext, useEffect, useState } from 'react'
+
+/**
+ * The shared code-tab language: pick a language once and every code-tabs
+ * block on the site follows. Hydrated from `?lang=` (deep link) then
+ * localStorage; SSR renders each block's first tab so there is no flash.
+ */
+
+const STORAGE_KEY = 'auths.docs.lang'
+
+interface LanguageContextValue {
+  lang: string | null
+  setLang: (lang: string) => void
+}
+
+const LanguageContext = createContext<LanguageContextValue>({
+  lang: null,
+  setLang: () => {},
+})
+
+export function LanguageProvider({ children }: { children: React.ReactNode }) {
+  const [lang, setLangState] = useState<string | null>(null)
+
+  useEffect(() => {
+    const fromUrl = new URLSearchParams(window.location.search).get('lang')
+    const fromStorage = window.localStorage.getItem(STORAGE_KEY)
+    const initial = fromUrl ?? fromStorage
+    if (initial) setLangState(initial)
+  }, [])
+
+  const setLang = (next: string) => {
+    setLangState(next)
+    try {
+      window.localStorage.setItem(STORAGE_KEY, next)
+    } catch {
+      // Private mode: the choice still applies for this visit.
+    }
+  }
+
+  return (
+    <LanguageContext.Provider value={{ lang, setLang }}>{children}</LanguageContext.Provider>
+  )
+}
+
+export function useLanguage(): LanguageContextValue {
+  return useContext(LanguageContext)
+}
diff --git a/components/markdoc/prism.ts b/components/markdoc/prism.ts
new file mode 100644
index 0000000..75f50ef
--- /dev/null
+++ b/components/markdoc/prism.ts
@@ -0,0 +1,29 @@
+import { Prism } from 'prism-react-renderer'
+
+/**
+ * Registers Prism grammars that prism-react-renderer does not bundle.
+ *
+ * prism-react-renderer vendors only a subset of Prism languages. Any fence
+ * whose grammar is missing silently falls back to a single plain token, so
+ * the whole block — comments included — renders in one color. Bash is the
+ * heaviest-used language in this content and is NOT in the vendored set,
+ * which is why `# comment` lines used to read exactly like commands.
+ *
+ * This module is the single, site-wide fix: it uses the library's documented
+ * extension point (expose the Prism instance on the global, then load the
+ * grammar module, which mutates `Prism.languages`). Import it once from any
+ * component that renders code; every fence on every page picks it up.
+ *
+ * To support a new fence language later, check `Prism.languages` first (many
+ * grammars ARE vendored — json, yaml, rust, python, ts, go, …) and only add
+ * a `require('prismjs/components/prism-<lang>')` line here if it is missing.
+ */
+;(globalThis as typeof globalThis & { Prism?: unknown }).Prism = Prism
+
+// Grammar modules attach to the global Prism as a side effect, so they must
+// load AFTER the assignment above — hoisted `import` statements would run
+// first, hence `require`.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+require('prismjs/components/prism-bash')
+
+export { Prism }
diff --git a/content/docs/authentication.md b/content/docs/authentication.md
index 3ad89ff..235ea40 100644
--- a/content/docs/authentication.md
+++ b/content/docs/authentication.md
@@ -1,6 +1,10 @@
 ---
 title: Authentication
 description: How Auths authenticates — cryptographic identities, not API keys
+product: identity
+section: Guides
+order: 3
+lastReviewed: "2026-07-17"
 ---
 
 ## No API keys
@@ -9,11 +13,11 @@ Auths does **not** use API keys, secret tokens, or a dashboard. There is no `sk_
 
 ## Your identity
 
-Running `auths init` creates a KERI identity (KERI: Key Event Receipt Infrastructure — identity as a verifiable log of key events rather than an account) — a `did:keri:…` backed by a key stored on your machine (under `~/.auths`, protected by a passphrase):
+Running `auths init` creates your identity — not an account, but a verifiable **key event log (KEL)**, backed by a key stored on your machine (under `~/.auths`, protected by a passphrase):
 
 ```bash
 auths init
-auths whoami      # your identity (did:keri:…)
+auths whoami      # your identity
 auths status      # identity + signing overview
 ```
 
@@ -24,7 +28,7 @@ You **prove** your identity by signing (`auths sign`); others **authenticate** y
 There's no central account to log into. Verifiers decide whom to trust by **pinning** identities:
 
 ```bash
-auths trust pin --did did:keri:E... --key <pubkey-hex>   # trust an identity
+auths trust pin --did <their-identity> --key <pubkey-hex>   # trust an identity
 auths trust list
 ```
 
@@ -38,17 +42,17 @@ For AI agents, CI, and services, Auths issues a **scoped passport** — a delega
 - **Expiring** — set a lifetime so a leaked credential dies on its own.
 - **Revocable** — revocation is a logged fact, effective immediately.
 
-See the [MCP setup guide](/docs/mcp-setup) and the [agent demo](https://github.com/auths-dev/auths-agent-demo).
+See the [bounded-agent gateway](/docs/mcp).
 
 ## Security
 
 - Keep your **private key** safe — it never leaves your machine and is passphrase-protected.
-- Share only your **public identity** (`did:keri:…`); it carries no secret.
+- Share only your **public identity**; it carries no secret.
 - Prefer **scoped, expiring** delegation for automation over reusing a human key.
 
 ## Related
 
 - [Quickstart](/docs/quickstart)
 - [Team Identities](/docs/team-identities)
-- [MCP Setup](/docs/mcp-setup)
+- [The bounded agent](/docs/mcp)
 - [Identity Model](/docs/concepts/identity-model)
diff --git a/content/docs/build-agents.md b/content/docs/build-agents.md
index 4a4b0b4..3a9624a 100644
--- a/content/docs/build-agents.md
+++ b/content/docs/build-agents.md
@@ -1,6 +1,10 @@
 ---
 title: Build Agents
 description: Sign and verify in CI/CD with the Auths GitHub Actions — no secrets
+product: identity
+section: Guides
+order: 6
+lastReviewed: "2026-07-17"
 ---
 
 ## Overview
@@ -58,7 +62,7 @@ The sign action emits `signed-files`, `attestation-files` (the `.auths.json` sid
 
 ## Stateless verification with an identity bundle
 
-By default the verify action uses KEL-native verification. For stateless verification against a specific identity, export a bundle and pass it in:
+By default the verify action verifies against each signer's key event log (KEL). For stateless verification against a specific identity, export a bundle and pass it in:
 
 ```bash
 auths id export-bundle    # advanced (auths --help-all); commit to .auths/ci-bundle.json
@@ -73,7 +77,7 @@ auths id export-bundle    # advanced (auths --help-all); commit to .auths/ci-bun
 
 ## Scoped agent credentials
 
-For an autonomous agent (not a CI step) that needs to act on its own, delegate a **scoped, expiring** passport rather than reuse a human key — see the [MCP setup guide](/docs/mcp-setup) and the [agent demo](https://github.com/auths-dev/auths-agent-demo).
+For an autonomous agent (not a CI step) that needs to act on its own, delegate a **scoped, expiring** passport rather than reuse a human key — see the [bounded-agent gateway](/docs/mcp).
 
 ## Security considerations
 
@@ -87,4 +91,4 @@ For an autonomous agent (not a CI step) that needs to act on its own, delegate a
 - [Sign Commits](/docs/sign-commits)
 - [Prove Provenance](/docs/prove-provenance)
 - [GitHub Actions reference](/docs/reference/github-actions)
-- [MCP Setup](/docs/mcp-setup)
+- [The bounded agent](/docs/mcp)
diff --git a/content/docs/concepts/delegation.md b/content/docs/concepts/delegation.md
index 77f9ed0..0f2576e 100644
--- a/content/docs/concepts/delegation.md
+++ b/content/docs/concepts/delegation.md
@@ -1,11 +1,16 @@
 ---
 title: Delegation
 description: Allow others to sign on your behalf
+product: identity
+section: Concepts
+order: 3
+lastReviewed: "2026-07-17"
+badge: soon
 ---
 
 > 🚧 **Stub** — this page hasn't been written yet. The links below are the current sources of truth.
 
-Delegation in Auths uses KERI delegated identifiers: a root identity anchors a scoped, expiring, revocable identity for an agent or device — no key sharing.
+Delegation in Auths uses delegated identifiers: a root identity anchors a scoped, expiring, revocable identity for an agent or device — no key sharing.
 
 For what exists today:
 
diff --git a/content/docs/concepts/identity-model.md b/content/docs/concepts/identity-model.md
index 3a932a1..6b9eee7 100644
--- a/content/docs/concepts/identity-model.md
+++ b/content/docs/concepts/identity-model.md
@@ -1,11 +1,16 @@
 ---
 title: Identity Model
 description: Understanding Auths' identity and signing model
+product: identity
+section: Concepts
+order: 1
+lastReviewed: "2026-07-17"
+badge: soon
 ---
 
 > 🚧 **Stub** — this page hasn't been written yet. The links below are the current sources of truth.
 
-In short: your identity is a `did:keri:…` — a self-certifying identifier backed by a key event log (KEL), a signed, append-only history of your keys. Devices and agents get their own delegated identifiers anchored by your root. There is no account and no server; everything verifies locally from the log.
+In short: your identity is a self-certifying identifier backed by a key event log (KEL) — a signed, append-only history of your keys. Devices and agents get their own delegated identifiers anchored by your root. There is no account and no server; everything verifies locally from the log.
 
 For what exists today:
 
diff --git a/content/docs/concepts/key-rotation.md b/content/docs/concepts/key-rotation.md
index 1f4023d..646b5ba 100644
--- a/content/docs/concepts/key-rotation.md
+++ b/content/docs/concepts/key-rotation.md
@@ -1,11 +1,16 @@
 ---
 title: Key Rotation
 description: Best practices for rotating signing keys
+product: identity
+section: Concepts
+order: 2
+lastReviewed: "2026-07-17"
+badge: soon
 ---
 
 > 🚧 **Stub** — this page hasn't been written yet. The links below are the current sources of truth.
 
-Auths uses KERI pre-rotation: each key event commits to the *next* key in advance, so rotating to a new key (`auths id rotate`) extends the same identity — old signatures remain valid because verification replays the key event log at the time of signing.
+Auths uses pre-rotation: each key event commits to the *next* key in advance, so rotating to a new key (`auths id rotate`) extends the same identity — old signatures remain valid because verification replays the key event log at the time of signing.
 
 For what exists today:
 
diff --git a/content/docs/installation.md b/content/docs/installation.md
index af3e7a0..12ab9b8 100644
--- a/content/docs/installation.md
+++ b/content/docs/installation.md
@@ -1,6 +1,10 @@
 ---
 title: Installation
 description: Get the Auths CLI up and running
+product: identity
+section: Guides
+order: 2
+lastReviewed: "2026-07-17"
 ---
 
 ## System Requirements
diff --git a/content/docs/mcp-setup.md b/content/docs/mcp-setup.md
deleted file mode 100644
index 33d6629..0000000
--- a/content/docs/mcp-setup.md
+++ /dev/null
@@ -1,103 +0,0 @@
----
-title: MCP Setup
-description: Give a Claude or Cursor agent a scoped, expiring, revocable Auths passport
----
-
-This guide explains how Auths secures an **MCP (Model Context Protocol) agent** — a Claude Desktop, Cursor, or Claude Code agent — with a **scoped passport** instead of a long-lived API key.
-
-> **Preview — tooling not yet shipped.** The streamlined, copy-paste setup (a one-command `auths passport present` helper and ready-made client configs) lands with the MCP tooling work (roadmap **G2.4**). This page describes the model and the current building blocks so you can understand it now; the snippets below are **illustrative**, not yet copy-paste-runnable. It will be upgraded to a working walkthrough when G2.4 ships.
-
-## What is an agent passport?
-
-An Auths agent is a **KERI delegated identity** — its own `did:keri:…` incepted under (and anchored by) a human or org identity, carrying a **scope seal** that grants specific capabilities (for example `sign_commit`) with an optional expiry. There are **no bearer tokens**: authority is provable by replaying the key event log, and it's **revocable** at any time.
-
-That makes it a good fit for an AI agent's credential:
-
-- **Scoped** — the agent can only do what its scope seal allows.
-- **Expiring** — grant `--expires-in` so a leaked credential dies on its own.
-- **Revocable** — revocation is a logged fact; signatures after it stop verifying.
-
-## How the MCP server authorizes a tool call
-
-Auths ships an MCP server (`auths-mcp-server`) that runs as a local HTTP service (default `:8080`). Each tool is mapped to a required capability, so a passport scoped to one capability can't invoke another:
-
-| MCP tool | Required capability |
-|----------|---------------------|
-| `read_file` | `fs:read` |
-| `write_file` | `fs:write` |
-| `deploy` | `deploy:staging` |
-
-When the agent calls a protected tool (`POST /mcp/tools/{tool}`), it presents its passport in the HTTP **`Authorization`** header. The server replays the passport's KEL, checks the capability against the table above, and confirms the credential hasn't expired or been revoked before running the tool. (`GET /mcp/tools` and `/health` are public.)
-
-## Least-privilege checklist
-
-Scoping is the whole point — keep it tight:
-
-- **Start from the minimal scope** the agent actually needs (e.g. `sign_commit` only). Add capabilities when a task first requires one, not preemptively.
-- **Never grant wildcard/omnibus scopes** ("all", "full-access"). Broad grants enlarge the blast radius and make revocation disruptive.
-- **Always set an expiry** (`--expires-in`) for agent credentials.
-- **Bind to one audience.** A credential minted for the auths MCP server should not be accepted elsewhere.
-- **Review before approving.** A local MCP server runs with your privileges — read the exact command and the requested scope before you approve it in your client.
-- **Never paste secrets into a checked-in config.** Use your client's `env`/secret mechanism, and don't commit a project `.mcp.json` containing a credential.
-
-## Where the client config lives
-
-All three clients use the same top-level `mcpServers` object; only the file location differs:
-
-- **Claude Desktop** — `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) / `%APPDATA%\Claude\claude_desktop_config.json` (Windows). **Restart Claude Desktop** after editing.
-- **Cursor** — `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` global). Picks up changes automatically.
-- **Claude Code** — a project `.mcp.json`, or `claude mcp add`.
-
-## What the config will look like
-
-Because the auths MCP server speaks HTTP, the client entry will use the remote (`url` + `headers`) form, presenting the passport in the `Authorization` header:
-
-```jsonc
-// ILLUSTRATIVE — pending the G2.4 header helper; not yet copy-paste-runnable
-{
-  "mcpServers": {
-    "auths": {
-      "type": "http",
-      "url": "http://localhost:8080/mcp",
-      "headers": {
-        "Authorization": "Bearer <agent-passport-presentation>"
-      }
-    }
-  }
-}
-```
-
-The missing piece today is a one-command way to mint `<agent-passport-presentation>` for the header — that helper is what G2.4 delivers.
-
-## Provisioning a scoped agent today (advanced)
-
-The underlying delegation already works via the advanced identity commands. To delegate a `sign_commit`-scoped agent that expires in a day:
-
-```bash
-auths id agent add \
-  --label mcp-agent \
-  --key my-key \
-  --scope sign_commit \
-  --expires-in 86400
-```
-
-Revoke it at any time:
-
-```bash
-auths id agent revoke did:keri:EAgent… --key my-key
-```
-
-> These `auths id agent …` commands are advanced/in-flux. G2.4 promotes this into a streamlined `auths passport` workflow plus the header helper and the ready-made client configs above.
-
-## What changes when G2.4 ships
-
-- A one-command `auths passport present --header` (or equivalent) that prints the exact `Authorization` value to paste.
-- Copy-paste, validated configs for Claude Desktop, Cursor, and Claude Code.
-- A scoped-passport `create / list / revoke` workflow that persists the agent DID for you.
-
-This page becomes the working, copy-paste walkthrough at that point.
-
-## Next steps
-
-- **[Quickstart](/docs/quickstart)** — get an identity and verify a signed commit first.
-- **[Delegation](/docs/concepts/delegation)** — how scoped, revocable delegation works under the hood.
diff --git a/content/docs/mcp/concepts/budgets.md b/content/docs/mcp/concepts/budgets.md
new file mode 100644
index 0000000..1d0c448
--- /dev/null
+++ b/content/docs/mcp/concepts/budgets.md
@@ -0,0 +1,70 @@
+---
+title: Budgets
+description: One durable cap across every rail, reserved before the rail is touched — real money by default, test mode the single opt-in.
+product: mcp
+section: Core ideas
+order: 2
+lastReviewed: "2026-07-17"
+---
+
+{% callout type="danger" title="Real money is the default" %}
+With no `--test-mode` flag, a wrapped payment rail spends real money — live Stripe
+(an `sk_live_…` key) and x402 on base mainnet (real USDC). The `--budget` cap is the
+hard ceiling and it is mandatory. Prove the cap in test mode before you point a live
+key or a funded wallet at a rail.
+{% /callout %}
+
+The budget is a seatbelt, not a setting. With a `$5` cap the agent cannot spend
+`$5.01` — the gateway **reserves** each charge against the cap *before* the rail is
+touched, settles the actual amount from the rail's own response after, and refuses
+the call that would cross the cap with {% verdict code="usage-cap-exceeded" /%}.
+The rail is never charged past the budget.
+
+## One cap, every rail
+
+The cap is a **durable, cross-rail counter**, not an in-memory per-session tally.
+Stripe spend and x402 spend meter into the same counter:
+
+```output
+# one $5 cap, two rails
+✓ stripe charge  $4.99 → allowed · spent $4.99 / $5.00
+✗ x402 settle    $4.99 → usage-cap-exceeded · refused
+```
+
+An agent at `$4.99` on Stripe cannot move to a second rail for fresh headroom —
+`$4.99 + $4.99` is `$9.98` of a `$5` cap, so the next call on **either** rail is
+refused. Two siloed per-rail budgets would each wave that call through; the one
+cross-rail counter refuses it. The counter survives the session: it is held by the
+verifier and re-derived by the [offline audit](/docs/mcp/concepts/receipts), so an
+operator cannot quietly reset it.
+
+## The cap is mandatory
+
+A payment rail wrapped with no `--budget` is refused —
+{% verdict code="budget-required" /%}, fail-closed, before anything is served or
+charged, in **both** modes. Real-money-by-default with a skippable cap would be a
+foot-gun aimed at a live card; that shape is simply not allowed.
+
+## Modes
+
+| Mode | Trigger | Rails |
+| --- | --- | --- |
+| Real *(default)* | no flag | live Stripe (`sk_live_…` at `api.stripe.com`) + x402 base mainnet — real money |
+| Test | `--test-mode` (or `AUTHS_MCP_TEST_MODE=1`) | Stripe `sk_test_…` + x402 base-sepolia — no real money |
+
+The mode is always disclosed: every payment-rail wrap prints a `mode=real|test`
+banner at startup, so a live rail is never silent.
+
+## The habit: disclose before you wrap
+
+`--show-mode` resolves and discloses the mode — and enforces the mandatory cap —
+then exits without serving the proxy or touching a rail:
+
+```bash
+auths-mcp wrap --show-mode --scope paid.call --budget '$5' -- <downstream server>
+```
+
+Run it before every live wrap. When the output says `mode=real`, you know exactly
+which world goes live — and when you don't mean real money, `--test-mode` is the
+single opt-in. The full live path is the
+[walkthrough](/docs/mcp/guides/spend-real-money).
diff --git a/content/docs/mcp/concepts/custody.md b/content/docs/mcp/concepts/custody.md
new file mode 100644
index 0000000..03986a6
--- /dev/null
+++ b/content/docs/mcp/concepts/custody.md
@@ -0,0 +1,47 @@
+---
+title: Credential custody
+description: The gateway holds the provider secret; the agent holds only its delegation. Bypassing the gateway leaves the agent with no credential at all.
+product: mcp
+section: Core ideas
+order: 3
+lastReviewed: "2026-07-17"
+---
+
+The gateway is a **credential-custody broker**, not just a proxy. It holds the
+downstream provider's secret — a Stripe key, a wallet, an API token — and injects it
+into the wrapped server's process. The agent holds only its scoped, budget-bound
+delegation. It never sees the secret.
+
+That makes the boundary unbypassable by construction: an agent that goes around the
+gateway reaches the raw downstream with **no credential**, so the call fails. There
+is no configuration in which the bypass path works.
+
+## Handing the gateway a secret
+
+`--custody-credential` takes the secret in one of two shapes:
+
+```bash
+# bare NAME — the gateway ADOPTS the value from its own environment;
+# the secret never appears on the agent-visible command line
+export STRIPE_API_KEY=sk_test_...
+auths-mcp wrap --custody-credential STRIPE_API_KEY -- <downstream server>
+
+# NAME=VALUE — inject an explicit value
+auths-mcp wrap --custody-credential SOME_TOKEN=abc123 -- <downstream server>
+```
+
+Repeat the flag for each secret the downstream needs (the x402 rail, for example,
+custodies both a wallet key and a facilitator URL).
+
+## Where the secret never goes
+
+The value is injected into the **downstream process only**. It never touches the MCP
+wire, never appears in receipts, and is never logged or echoed — a malformed
+`--custody-credential` is reported by NAME alone. The agent-side surface carries
+exactly one thing: the delegation, whose scope, budget, and expiry the
+[gate](/docs/mcp/concepts/how-it-works) checks on every call.
+
+Replacing a leaked long-lived key with a bounded delegation is the point: if the
+agent's delegation leaks, it is scoped, capped, expiring, and
+[revocable in one step](/docs/mcp/concepts/receipts) — none of which is true of the
+provider secret it replaced.
diff --git a/content/docs/mcp/concepts/how-it-works.md b/content/docs/mcp/concepts/how-it-works.md
new file mode 100644
index 0000000..11206cd
--- /dev/null
+++ b/content/docs/mcp/concepts/how-it-works.md
@@ -0,0 +1,59 @@
+---
+title: How the gate works
+description: Stock MCP in, stock MCP out — and one gate on every tools/call that checks five bounds and fails closed.
+product: mcp
+section: Core ideas
+order: 1
+lastReviewed: "2026-07-17"
+---
+
+The gateway speaks ordinary MCP up to your agent and down to the wrapped server,
+proxying `tools/list` and `tools/call`. Nothing about your client or your server
+changes. What changes is that **every `tools/call` runs one gate** before it is
+forwarded.
+
+```
+agent ──tools/call──▶ gateway ──tools/call──▶ downstream server
+                         │
+                         │  scope ⊆ parent · budget · expiry · revocation · authenticity
+                         │  forwards ONLY on allowed; fails closed on anything else
+                         ▼
+                      one signed receipt per call
+```
+
+## The five bounds
+
+| Bound | Refusal | When |
+| --- | --- | --- |
+| scope ⊆ parent | `outside-agent-scope` | a call for a capability the grant never gave |
+| budget | `usage-cap-exceeded` | the reservation would cross the cap — refused before the rail is charged |
+| expiry | `agent-expired` | the delegation has a TTL; past it, nothing signs |
+| revocation | `revoked` | you recorded a revocation; every verifier honors it on the next call |
+| authenticity | `proof-unauthentic` | the signature does not verify against the agent's key |
+
+Two properties hold everywhere:
+
+- **Fail closed.** On any verdict but {% verdict code="allowed" /%}, the downstream
+  tool is never invoked. There is no "log and forward" mode.
+- **Scope only narrows.** The agent's delegation is issued by your root identity, and
+  its scope can only ever narrow what the parent granted — never widen it.
+
+## What makes it stick
+
+Three mechanisms carry those bounds, each with its own page:
+
+- **A delegation, not a token.** The agent holds a delegated identity with its scope,
+  budget, and expiry fixed at issue time — not a bearer token that anyone who copies
+  it can replay. The key material stays on the machine that created it.
+- **One durable budget across every rail** — the [cross-rail cap](/docs/mcp/concepts/budgets).
+- **A signed receipt per call**, re-checkable by anyone — [receipts](/docs/mcp/concepts/receipts).
+
+And because the gateway [custodies the downstream credential](/docs/mcp/concepts/custody),
+an agent that bypasses the gateway reaches the raw server with no credential at all —
+the boundary is unbypassable for credentialed resources.
+
+## A non-auths client still works
+
+A client that knows nothing about auths can still call the wrapped server:
+unauthenticated calls pass through the same scope gate without a receipt, so adoption
+is incremental — you can wrap first and roll out signing after.
diff --git a/content/docs/mcp/concepts/receipts.md b/content/docs/mcp/concepts/receipts.md
new file mode 100644
index 0000000..c1397aa
--- /dev/null
+++ b/content/docs/mcp/concepts/receipts.md
@@ -0,0 +1,76 @@
+---
+title: Receipts
+description: Every gated call is signed and logged; anyone can re-derive the spend offline — and tampering with the log is caught, byte for byte.
+product: mcp
+section: Core ideas
+order: 4
+lastReviewed: "2026-07-17"
+---
+
+A log is a claim the operator makes about themselves. A receipt is a claim you can
+check **against** them. Every gated call — allowed or refused — is canonicalized,
+signed by the agent's delegated key, and appended to a spend log. From those
+receipts alone, a party who never ran the agent can re-derive exactly what it did.
+
+## Prove it yourself
+
+{% steps %}
+{% step title="Re-derive the spend, offline" %}
+`verify-spend` re-verifies every signed proof through the same verifier the live
+gate uses and re-derives the spend — no account, no server, no trust in the operator
+that produced the log:
+
+```bash
+auths-mcp verify-spend --log spend.jsonl --registry ./registry \
+  --agent <agent> --root <root>
+```
+
+```output
+✓ verify-spend: consistent — 2 call(s), $12.00 re-derived from signed costs
+```
+
+It exits non-zero on any verdict but {% verdict code="consistent" /%}.
+{% /step %}
+
+{% step title="Tamper with it and watch the audit catch it" %}
+Flip one byte of a signed proof and re-run — the altered record fails verification:
+
+```output
+✗ verify-spend: tampered-proof — 51017ad1… failed verification (exit 1)
+```
+
+A doctored log cannot audit clean.
+{% /step %}
+{% /steps %}
+
+## What the audit catches
+
+The verdicts on the live gate and in the offline audit are exact strings — these,
+and no others:
+
+| Verdict | Meaning |
+| --- | --- |
+| `allowed` | in bounds; forwarded, receipt written |
+| `usage-cap-exceeded` | would cross the budget cap — refused before the rail is touched |
+| `outside-agent-scope` | a capability the grant never gave |
+| `agent-expired` | past the delegation TTL |
+| `revoked` | a revocation is recorded; honored on the next call, every rail |
+| `budget-required` | a payment rail wrapped with no `--budget` — fail-closed, both modes |
+| `proof-unauthentic` | the signature does not verify against the agent's key |
+| `consistent` | the clean audit: every proof verifies, the spend re-derives |
+| `tampered-proof` | a signed proof was altered — caught offline |
+| `dropped-call` | a record was removed from the log — each receipt back-links to the prior one |
+| `budget-mismatch` | the durable cross-rail counter disagrees with the log (e.g. a truncated tail) |
+
+The last three are why handing you the log is not an act of trust: an **edited**
+record breaks its signature, a **removed** record breaks the back-link chain, and a
+**truncated** log disagrees with the durable counter. Each forgery has a distinct
+verdict, and the audit fails loudly on all of them.
+
+## Revocation
+
+If anything looks wrong, revoke the agent's delegation. The revocation is a signed
+event in your identity's history — the agent's **next call fails on every rail at
+once** with {% verdict code="revoked" /%}, no propagation window, and the other
+agents keep working. Keep the revoke step ready whenever real money is live; the
+[walkthrough](/docs/mcp/guides/spend-real-money) treats it as the kill switch.
diff --git a/content/docs/mcp/guides/spend-real-money.md b/content/docs/mcp/guides/spend-real-money.md
new file mode 100644
index 0000000..30daf49
--- /dev/null
+++ b/content/docs/mcp/guides/spend-real-money.md
@@ -0,0 +1,146 @@
+---
+title: "Walkthrough: real money"
+description: "Wrap live Stripe and x402 rails behind one hard budget cap, then watch a real agent get refused the charge that would cross it."
+product: mcp
+section: Spend real money
+order: 1
+lastReviewed: "2026-07-17"
+---
+
+This is the product's whole reason to exist: let an autonomous agent spend real money, and make it provably impossible for it to spend past a cap. This page walks the live path end-to-end — real Stripe, real USDC over x402 (on-chain USDC settlement), and a real Claude agent that tries to overspend and gets refused at the boundary.
+
+{% callout type="danger" title="Real money is the default" %}
+The gateway resolves a wrapped payment rail to **real money by default**: with no `--test-mode` flag, a Stripe wrap uses a live `sk_live_…` key and an x402 wrap settles on **base mainnet** with real USDC. **Test mode is the single, deliberate opt-in.** The **budget cap is the hard ceiling** — an agent provably cannot spend past it, on any rail, even if the model is buggy, prompt-injected, or adversarial — and it is **mandatory**. Start with a tiny cap. **Live charges and on-chain transfers are irreversible.**
+{% /callout %}
+
+## The seatbelt: the cap is what makes this sane
+
+Do not think of the [cap](/docs/mcp/concepts/budgets) as a setting — think of it as a **seatbelt**. With a `$5` delegation, the agent cannot spend `$5.01`. Not "shouldn't" — **cannot**: the gateway reserves each charge against the cap *before* the rail is touched and refuses the call that would cross it, across **all** rails at once. The cap bounds your **downside**, not the probability of a bad decision. And it is not optional: a payment rail wrapped with no `--budget` is refused {% verdict code="budget-required" /%}, fail-closed, in **both** modes. So the discipline is simple: **start with the smallest cap that proves the point, and prove the cap in test mode first.**
+
+Adapter paths in the commands below are relative to a checkout of [github.com/auths-dev/auths-mcp](https://github.com/auths-dev/auths-mcp).
+
+{% steps %}
+
+{% step title="Disclose the mode — test is the opt-in" %}
+Real money is the default, so there is no "switch on live money" gate to flip — the gate runs the other way: **`--test-mode` is the opt-in to sandbox rails.** Two guardrails make real-by-default safe, and both are enforced at the `wrap` boundary:
+
+- **The mode is disclosed.** Every payment-rail wrap prints a `mode=real|test` banner and a machine-readable `mode=… stripe.… x402.…` line at startup — a live rail is never silent.
+- **The cap is mandatory.** A payment-rail wrap with no `--budget` is refused {% verdict code="budget-required" /%} before anything is served or charged, in real **and** test mode.
+
+Before wrapping a live rail, **dry-run the disclosure** to confirm exactly which world will go live — it resolves and discloses the mode, then exits **without** serving the proxy or touching a rail:
+
+{% code-tabs %}
+{% code-tab lang="test" label="Test mode (start here)" %}
+```output
+$ auths-mcp wrap --show-mode --test-mode --scope paid.call --budget '$5' -- node …/server.mjs
+mode=test … stripe.key_expected=sk_test_ … x402.network=base-sepolia …
+```
+{% /code-tab %}
+{% code-tab lang="live" label="Live (real money)" %}
+```output
+$ auths-mcp wrap --show-mode --scope paid.call --budget '$5' -- node …/server.mjs
+mode=real stripe.endpoint=api.stripe.com stripe.key_expected=sk_live_ … x402.network=base …
+```
+{% /code-tab %}
+{% /code-tabs %}
+{% /step %}
+
+{% step title="Wrap real Stripe (the default)" %}
+In the [Stripe dashboard](https://dashboard.stripe.com/apikeys), switch **off** Test mode and copy a **live** secret key (`sk_live_…`) — or, for the test tab, an `sk_test_…` key from the dashboard's Test mode toggle.
+
+{% callout type="danger" title="No undo on a live charge" %}
+A `sk_live_…` key charges **real cards / real money**. There is no undo on a live charge beyond a refund.
+{% /callout %}
+
+Custody it on the gateway (the agent never sees it) and wrap the Stripe adapter with a **small** cap. No live-money flag is needed — real is the default:
+
+{% code-tabs %}
+{% code-tab lang="test" label="Test mode (start here)" %}
+```bash
+export STRIPE_API_KEY=sk_test_...
+auths-mcp wrap \
+  --test-mode \
+  --scope paid.call --budget '$5' --ttl 30m \
+  --custody-credential STRIPE_API_KEY \
+  -- node examples/payments/adapters/stripe-adapter/server.mjs
+```
+{% /code-tab %}
+{% code-tab lang="live" label="Live (real money)" %}
+```bash
+export STRIPE_API_KEY=sk_live_...
+auths-mcp wrap \
+  --scope paid.call --budget '$5' --ttl 30m \
+  --custody-credential STRIPE_API_KEY \
+  -- node examples/payments/adapters/stripe-adapter/server.mjs
+```
+{% /code-tab %}
+{% /code-tabs %}
+
+The gateway discloses `mode=real`, then extracts `amount_captured` from each real Charge, meters it against the cap, and refuses any charge that would cross `$5` — {% verdict code="usage-cap-exceeded" /%}, **before** Stripe is called, so the card is never charged past the cap. The [receipt](/docs/mcp/concepts/receipts) names the real `ch_…`. Full rail details: [Stripe rail](/docs/mcp/providers/stripe).
+{% /step %}
+
+{% step title="Wrap real USDC over x402 — same cap" %}
+Fund a **base mainnet** wallet with **real USDC** (and a little ETH for gas), and obtain a **mainnet** x402 facilitator URL. For the test tab, fund a **base-sepolia** testnet wallet and use a base-sepolia facilitator instead.
+
+{% callout type="danger" title="No chargeback" %}
+On-chain USDC transfers are **irreversible**. There is no chargeback.
+{% /callout %}
+
+Custody both and wrap the x402 adapter (same `$5` cap — it's the **same** cross-rail counter as Stripe):
+
+{% code-tabs %}
+{% code-tab lang="test" label="Test mode (start here)" %}
+```bash
+export X402_WALLET_PRIVATE_KEY=0x...
+export X402_FACILITATOR_URL=https://...
+auths-mcp wrap \
+  --test-mode \
+  --scope paid.call --budget '$5' --ttl 30m \
+  --custody-credential X402_WALLET_PRIVATE_KEY \
+  --custody-credential X402_FACILITATOR_URL \
+  -- node examples/payments/adapters/x402-adapter/server.mjs
+```
+{% /code-tab %}
+{% code-tab lang="live" label="Live (real money)" %}
+```bash
+export X402_WALLET_PRIVATE_KEY=0x...
+export X402_FACILITATOR_URL=https://...
+auths-mcp wrap \
+  --scope paid.call --budget '$5' --ttl 30m \
+  --custody-credential X402_WALLET_PRIVATE_KEY \
+  --custody-credential X402_FACILITATOR_URL \
+  -- node examples/payments/adapters/x402-adapter/server.mjs
+```
+{% /code-tab %}
+{% /code-tabs %}
+
+Stripe spend **and** x402 spend share the one `$5` cap. An agent at `$4.99` on Stripe and `$4.99` on x402 has spent `$9.98` of `$5` — the next call on **either** rail is refused. Full rail details: [x402 / USDC rail](/docs/mcp/providers/x402).
+{% /step %}
+
+{% step title="Ask an agent to spend real money" %}
+Now put a real model behind the gateway and give it a task that tempts it to overspend:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+python3 examples/live/record.py --out spend.recorded.json
+```
+
+A real `claude-opus-4-8` tool-loop runs behind the gateway, making real charges as it works. When its cumulative spend reaches the cap, the **very next** charge — the one that would cross `$5` — is refused {% verdict code="usage-cap-exceeded" /%} at the boundary. The model can decide whatever it likes; **the money stops at `$5`.** The receipts (real `ch_…` / `0x…` tx) are the verifiable record of exactly what was spent and what was refused.
+{% /step %}
+
+{% /steps %}
+
+## Kill it instantly
+
+If anything looks wrong, revoke the agent's delegation — its **next call fails on every rail at once**, with no propagation window. That's the "stop spending now" button, and it actually works: [revocation](/docs/mcp/concepts/receipts) is proved by the suite.
+
+## Safety checklist
+
+- **Prove the cap in test mode first** — add `--test-mode` (or `AUTHS_MCP_TEST_MODE=1`) and watch the cap refuse the over-cap call before you ever point a live key/wallet at the rail.
+- **Confirm the mode before you wrap** — `auths-mcp wrap --show-mode …` prints `mode=real|test` and the resolved rails, and exits without charging.
+- **Start with the smallest cap** that demonstrates the point (e.g. `--budget '$1'`).
+- **Never omit `--budget`** — a payment rail with no cap is refused {% verdict code="budget-required" /%}, fail-closed, in both modes; the seatbelt is mandatory.
+- The gateway **custodies** the live key/wallet — the agent never holds it; a bypass leaves it with no credential.
+- Live charges and on-chain transfers are **irreversible** — the cap bounds the downside, not the probability of a bad call.
+- Keep the **revoke** command ready, and a short `--ttl`.
+- Real money is the **default** — there is no silent live rail (the mode is disclosed), but there is also no extra flag protecting you from real spend. Reach for `--test-mode` whenever you don't mean real money.
diff --git a/content/docs/mcp/index.md b/content/docs/mcp/index.md
new file mode 100644
index 0000000..0d5c921
--- /dev/null
+++ b/content/docs/mcp/index.md
@@ -0,0 +1,52 @@
+---
+title: The bounded agent
+description: Put a gateway in front of any MCP server and your agent cannot exceed its scope, its budget, or its lifetime — and you can prove what it did.
+product: mcp
+section: Get started
+order: 1
+lastReviewed: "2026-07-17"
+---
+
+**auths-mcp** is the bounded-agent MCP gateway. It sits between an agent and its tools,
+holds a scoped, budget-bound, instantly-revocable delegation for that agent, and refuses
+any `tools/call` that exceeds it — at the protocol boundary, before the tool runs.
+
+The cap is a seatbelt, not a setting. With a `$20` budget the agent cannot spend `$20.01`.
+Not shouldn't — **cannot**: the gateway reserves each charge against the cap before the
+rail is touched and refuses the call that would cross it.
+
+```output
+$ auths-mcp wrap --budget '$20' --ttl 30m -- my-mcp-server
+✓ payments.charge $12.00 → allowed · spent $12.00 / $20.00 · rcpt_1a2b
+✗ payments.charge $940.00 → usage-cap-exceeded · refused · rcpt_8f2a
+```
+
+The refusal is the product. Every call — allowed or refused — leaves a signed receipt,
+and anyone can re-derive the spend from the receipts alone, offline, without trusting
+you or us. See [receipts](/docs/mcp/concepts/receipts).
+
+## Where to start
+
+{% card-group %}
+{% card title="Quickstart — no money" href="/docs/mcp/quickstart" icon="terminal" %}
+Wrap a filesystem server and watch a refusal in five minutes. No card, no wallet,
+nothing at risk.
+{% /card %}
+{% card title="Spend real money" href="/docs/mcp/guides/spend-real-money" icon="wallet" %}
+Put a real model on real rails — Stripe and on-chain USDC — behind one cap it provably
+cannot cross.
+{% /card %}
+{% /card-group %}
+
+## What the gate refuses
+
+Every `tools/call` runs one gate and fails closed. A call outside the granted scope is
+{% verdict code="outside-agent-scope" /%}. A call that would cross the budget is
+{% verdict code="usage-cap-exceeded" /%}. A call after the delegation expires is
+{% verdict code="agent-expired" /%}. A call after you revoke is
+{% verdict code="revoked" /%}. On any of them, the downstream tool is never invoked.
+
+How each bound works — and why you can check the receipts yourself — is four short
+pages: [the gate](/docs/mcp/concepts/how-it-works),
+[budgets](/docs/mcp/concepts/budgets), [custody](/docs/mcp/concepts/custody), and
+[receipts](/docs/mcp/concepts/receipts).
diff --git a/content/docs/mcp/install.md b/content/docs/mcp/install.md
new file mode 100644
index 0000000..90f89df
--- /dev/null
+++ b/content/docs/mcp/install.md
@@ -0,0 +1,78 @@
+---
+title: Install
+description: One line in front of any MCP server — npx today, brew and uvx as fast-follows.
+product: mcp
+section: Get started
+order: 2
+lastReviewed: "2026-07-17"
+---
+
+The gateway ships as a launcher that resolves a prebuilt binary for your platform.
+There is no toolchain to install and nothing to build.
+
+## Prerequisites
+
+- Node 18 or newer.
+- A downstream MCP server to wrap (any stock MCP server works — the gateway speaks
+  ordinary MCP up to your agent and down to the server).
+
+## The one line
+
+{% code-tabs %}
+{% code-tab lang="npx" label="npx" %}
+```bash
+npx -y @auths-dev/mcp wrap --scope fs.read --budget '$5' --ttl 30m -- <downstream server>
+```
+{% /code-tab %}
+{% code-tab lang="brew" label="brew" %}
+```bash
+# fast-follow — not yet published
+brew install auths-mcp
+```
+{% /code-tab %}
+{% code-tab lang="uvx" label="uvx" %}
+```bash
+# fast-follow — not yet published
+uvx auths-mcp
+```
+{% /code-tab %}
+{% /code-tabs %}
+
+{% callout type="warning" title="Availability" %}
+`@auths-dev/mcp` is publishing now; prebuilt binaries ship for linux-x64, linux-arm64,
+and darwin-arm64. If `npx` cannot resolve the package yet, build the gateway from
+source ([github.com/auths-dev/auths](https://github.com/auths-dev/auths)) and point
+`GATEWAY_BIN` at `target/release/auths-mcp-gateway`. The `brew` and `uvx` forms are
+fast-follows.
+{% /callout %}
+
+In these docs, commands use `auths-mcp` — the installed binary name. The no-install
+form is the same command through `npx`: `npx -y @auths-dev/mcp wrap …`.
+
+## The wrap shape
+
+One shape for every downstream — everything after `--` is the untouched server
+command you already had:
+
+| Flag | Value | Meaning |
+| --- | --- | --- |
+| `--scope` | `CAP` (repeatable) | a capability granted to the agent, e.g. `fs.read`, `paid.call` |
+| `--budget` | `$5` or `20calls` | the cross-rail spend cap — mandatory when the scope grants `paid.call` |
+| `--ttl` | `30m` | the delegation lifetime |
+| `--rail` | `stripe` or `x402` | the payment rail the wrapped downstream settles on; when set, every call is metered on this rail from the rail's own response |
+| `--test-mode` | flag | opt into sandbox rails; real money is the default. Env twin: `AUTHS_MCP_TEST_MODE=1` |
+| `--show-mode` | flag | resolve and disclose the payment mode, then exit — no proxy, no charge |
+| `--custody-credential` | `NAME[=VALUE]` (repeatable) | a downstream secret the gateway holds; bare `NAME` adopts it from the gateway's environment |
+| `-- <DOWNSTREAM>` | required | the wrapped MCP server command |
+
+## Verify without touching anything
+
+`--show-mode` resolves what a wrap *would* do — the payment mode and the rails it
+names — then exits without serving the proxy or touching a rail:
+
+```bash
+auths-mcp wrap --show-mode --scope fs.read --budget '$5' -- <downstream server>
+```
+
+That's the whole install. Next: [wrap your first server](/docs/mcp/quickstart) —
+no money, five minutes.
diff --git a/content/docs/mcp/providers/stripe.md b/content/docs/mcp/providers/stripe.md
new file mode 100644
index 0000000..d2edd2e
--- /dev/null
+++ b/content/docs/mcp/providers/stripe.md
@@ -0,0 +1,90 @@
+---
+title: "Stripe rail"
+description: "Wrap the Stripe rail: live charges by default, a mandatory budget cap, gateway-custodied keys, and test mode to prove the cap first."
+product: mcp
+section: Spend real money
+order: 2
+lastReviewed: "2026-07-17"
+---
+
+The Stripe rail issues a **real, live charge** and returns the **Charge object** the gateway extracts the metered cost from (`charge.amount_captured`, cents). **Real money is the default**: with no `--test-mode` flag the rail resolves to live Stripe — an `sk_live_…` key talking to `api.stripe.com` — and the charge moves real money on a real card.
+
+{% callout type="danger" title="Real money is the default" %}
+With no `--test-mode`, this rail makes a **live `sk_live_…` charge**. There is no undo on a live charge beyond a refund. The `--budget` cap is the hard ceiling — an agent provably cannot spend past it — and it is **mandatory**. Start with the smallest cap that proves the point, and prove the cap in [test mode](#test-mode) first.
+{% /callout %}
+
+## Prerequisites
+
+- A Stripe **live** secret key (`sk_live_…`) from the [Stripe dashboard](https://dashboard.stripe.com/apikeys) (Test mode **off**).
+- For test mode, an `sk_test_…` key from the dashboard's Test mode toggle.
+
+Adapter paths in the commands below are relative to a checkout of [github.com/auths-dev/auths-mcp](https://github.com/auths-dev/auths-mcp).
+
+## Setup
+
+{% code-tabs %}
+{% code-tab lang="test" label="Test mode (start here)" %}
+```bash
+export STRIPE_API_KEY=sk_test_...
+auths-mcp wrap \
+  --test-mode \
+  --scope paid.call --budget '$5' --ttl 30m \
+  --custody-credential STRIPE_API_KEY \
+  -- node examples/payments/adapters/stripe-adapter/server.mjs
+```
+{% /code-tab %}
+{% code-tab lang="live" label="Live (real money)" %}
+```bash
+export STRIPE_API_KEY=sk_live_...
+auths-mcp wrap \
+  --scope paid.call --budget '$5' --ttl 30m \
+  --custody-credential STRIPE_API_KEY \
+  -- node examples/payments/adapters/stripe-adapter/server.mjs
+```
+{% /code-tab %}
+{% /code-tabs %}
+
+In real mode the adapter POSTs a **live** charge to `api.stripe.com/v1/charges` and returns Stripe's real Charge object. Two things are non-negotiable here:
+
+- **The cap is mandatory.** Omit `--budget` and the gateway refuses to wrap the rail at all — {% verdict code="budget-required" /%}, fail-closed, before any rail is touched. Real money with a skippable cap is not an allowed shape. See [budgets](/docs/mcp/concepts/budgets).
+- **The mode is disclosed.** Every payment-rail wrap prints a `mode=real` banner and a `mode=real …` machine line at startup, so a live rail is never silent. Run `auths-mcp wrap --show-mode …` to resolve and disclose the mode **without** serving the proxy or making a charge.
+
+## Custody — the agent never holds the key
+
+The live `sk_live_…` key lives in the gateway's [custody vault](/docs/mcp/concepts/custody) (`--custody-credential`), never with the agent. The agent holds only its scoped, budget-bound delegation. An agent that tries to reach Stripe without going through the gateway has **no credential** — so the boundary is unbypassable.
+
+## How it works
+
+```
+agent ──tools/call──▶ gateway ──tools/call──▶ stripe-adapter ──▶ Stripe live API
+                         │  reserve ceiling BEFORE the rail        ◀── Charge object
+                         │  extract charge.amount_captured (cents, USD-only)
+                         │  settle the EXTRACTED amount; release slack
+                         ▼
+                      receipt: rail=stripe, mode=real, charge=ch_…, cross-rail total
+```
+
+- The gateway meters `charge.amount_captured` (cents). A **non-USD** charge is refused, not mis-metered.
+- An **over-cap** charge is refused {% verdict code="usage-cap-exceeded" /%} on its extracted ceiling **before** the adapter settles — Stripe is never charged past the cap.
+- The settle amount comes from the **response**, never an agent-declared number — so an agent cannot under-report a charge to slip the cap.
+- Spend on this rail and the [x402 rail](/docs/mcp/providers/x402) meters into one cross-rail cap; the [receipt](/docs/mcp/concepts/receipts) names the real `ch_…` and the cross-rail total.
+
+## The "small reconcile"
+
+The adapter is built against Stripe's documented Charge object and verified against a recorded fixture (`node examples/payments/adapters/stripe-adapter/test.mjs`). When you point it at a real key, a live charge may surface minor response-shape differences from the doc fixture — reconcile those (typically a field path) and you're live. The gateway's own extractor (`auths-mcp-core::rail::extract_stripe`) is the authority; the adapter's `extractCost` is a parity check against it.
+
+## Troubleshooting
+
+| Symptom | Cause |
+| --- | --- |
+| gateway refuses to wrap (`budget-required`) | no `--budget` — the cap is mandatory for a payment rail (both modes) |
+| adapter runs but never calls Stripe | no `STRIPE_API_KEY` set → it falls back to the recorded fixture shape |
+| charge refused before any Stripe call | the extracted amount would cross the `--budget` cap (expected) |
+| live charge metered differently than the fixture | the "small reconcile" — align the adapter to the real response field path |
+| unsure which mode is live | run `auths-mcp wrap --show-mode …` — it prints `mode=real|test` and exits without charging |
+
+## Test mode
+
+To exercise the rail **without real money**, opt into sandbox rails with `--test-mode` (or `AUTHS_MCP_TEST_MODE=1` for the adapter) — the test tab under [Setup](#setup) shows the full command. Test mode resolves the Stripe rail to an `sk_test_…` key (still `api.stripe.com`, but a test-mode charge — no real money). The cap is **still mandatory**, and the mode is disclosed as `mode=test`.
+
+Use test mode to prove the cap refuses the over-cap call before you ever point a live `sk_live_…` key at the rail. Then walk the full live path: [Walkthrough: real money](/docs/mcp/guides/spend-real-money).
diff --git a/content/docs/mcp/providers/x402.md b/content/docs/mcp/providers/x402.md
new file mode 100644
index 0000000..b19b3f6
--- /dev/null
+++ b/content/docs/mcp/providers/x402.md
@@ -0,0 +1,109 @@
+---
+title: "x402 / USDC rail"
+description: "Wrap the x402 rail: on-chain USDC settlement on base mainnet by default, metered into the same cross-rail cap as Stripe."
+product: mcp
+section: Spend real money
+order: 3
+lastReviewed: "2026-07-17"
+---
+
+The [x402](https://github.com/0xKoda/x402-wallet/blob/main/wallet.md) rail settles a **real USDC payment on base mainnet** — on-chain USDC settlement — and returns the `SettlementResponse` + `PaymentRequirements` the gateway extracts the metered cost from, metering into the **same cross-rail cap as [Stripe](/docs/mcp/providers/stripe)**. This is the second rail and the moat. **Real money is the default**: with no `--test-mode` flag the rail resolves to **base mainnet** and moves **real USDC** on-chain.
+
+{% callout type="danger" title="Real money is the default" %}
+With no `--test-mode`, this rail settles **real USDC on base mainnet**. On-chain USDC transfers are **irreversible** — there is no chargeback. The `--budget` cap is the hard ceiling — an agent provably cannot spend past it — and it is **mandatory**. Start with the smallest cap that proves the point, and prove the cap in [testnet mode](#testnet-mode) first.
+{% /callout %}
+
+{% callout type="warning" title="x402 needs a funded wallet + facilitator — not just a key" %}
+Unlike Stripe, x402's on-chain settle needs **a funded base-mainnet USDC wallet *and* an x402 facilitator URL**. A key alone does **not** fund the transfer. This is real setup; budget for it.
+{% /callout %}
+
+## Prerequisites
+
+- A **base mainnet** wallet **funded with real USDC** (private key, `0x…`), plus a little ETH on base mainnet for gas.
+- A **mainnet** x402 facilitator URL (the service that brokers the settle).
+
+Adapter paths in the commands below are relative to a checkout of [github.com/auths-dev/auths-mcp](https://github.com/auths-dev/auths-mcp).
+
+## Setup
+
+The live tab expects the funded **mainnet** wallet and facilitator from the prerequisites; the test tab expects a funded **base-sepolia** testnet wallet and a base-sepolia facilitator (see [testnet mode](#testnet-mode)).
+
+{% code-tabs %}
+{% code-tab lang="test" label="Test mode (start here)" %}
+```bash
+export X402_WALLET_PRIVATE_KEY=0x...
+export X402_FACILITATOR_URL=https://...
+auths-mcp wrap \
+  --test-mode \
+  --scope paid.call --budget '$5' --ttl 30m \
+  --custody-credential X402_WALLET_PRIVATE_KEY \
+  --custody-credential X402_FACILITATOR_URL \
+  -- node examples/payments/adapters/x402-adapter/server.mjs
+```
+{% /code-tab %}
+{% code-tab lang="live" label="Live (real money)" %}
+```bash
+export X402_WALLET_PRIVATE_KEY=0x...
+export X402_FACILITATOR_URL=https://...
+auths-mcp wrap \
+  --scope paid.call --budget '$5' --ttl 30m \
+  --custody-credential X402_WALLET_PRIVATE_KEY \
+  --custody-credential X402_FACILITATOR_URL \
+  -- node examples/payments/adapters/x402-adapter/server.mjs
+```
+{% /code-tab %}
+{% /code-tabs %}
+
+Two things are non-negotiable here:
+
+- **The cap is mandatory.** Omit `--budget` and the gateway refuses to wrap the rail at all — {% verdict code="budget-required" /%}, fail-closed, before any rail is touched. Real money with a skippable cap is not an allowed shape. See [budgets](/docs/mcp/concepts/budgets).
+- **The mode is disclosed.** Every payment-rail wrap prints a `mode=real` banner and a `mode=real …` machine line at startup, so a live rail is never silent. Run `auths-mcp wrap --show-mode …` to resolve and disclose the mode **without** serving the proxy or settling on-chain.
+
+## Custody — the agent never holds the wallet
+
+The wallet private key and facilitator URL live in the gateway's [custody vault](/docs/mcp/concepts/custody) (`--custody-credential`), never with the agent. The agent holds only its scoped, budget-bound delegation. An agent that tries to settle without going through the gateway has **no wallet** — so the boundary is unbypassable.
+
+## How it works
+
+```
+agent ──tools/call (x402)──▶ gateway ──tools/call──▶ x402-adapter ──▶ facilitator (base mainnet)
+                                │  reserve ceiling BEFORE the rail, ACROSS rails  ◀── SettlementResponse
+                                │  extract requirements.maxAmountRequired (atomic USDC → cents)
+                                │  settle into the SAME cap the Stripe rail meters into
+                                ▼
+                             receipt: rail=x402, mode=real, tx=0x…, cross-rail total
+```
+
+### Atomic USDC → cents
+
+USDC has **6 decimals**, so x402 amounts are **atomic**: `1500000` atomic = `1.50` USDC = **150 cents**. The conversion is `atomic / 10000`, **exact only** — a sub-cent residue is refused, not truncated, so the metered cost equals the settled amount exactly. The [receipt](/docs/mcp/concepts/receipts) names the on-chain settlement **tx** (`0x…`).
+
+### The cross-rail moat
+
+A `$1.50` Stripe charge **+** a `$1.50` x402 settle = `$3.00` of one `$5` cap. A later **`$0.60`** x402 settle is tiny in a per-rail x402 silo (x402-alone is only `$2.10`) — but summed cross-rail onto `$4.50` it would reserve to `$5.10 > $5`, so the gateway refuses it {% verdict code="usage-cap-exceeded" /%} **before** the adapter settles. Two siloed per-rail budgets would each wave it through; the one cross-rail counter refuses it.
+
+## Never faked
+
+With no wallet + facilitator the adapter runs against the recorded settlement shape (not a fabricated on-chain settle), so it stays runnable and self-checkable (`node examples/payments/adapters/x402-adapter/test.mjs`). If the live path is reached without a reachable facilitator it **throws** rather than inventing a transaction.
+
+## Troubleshooting
+
+| Symptom | Cause |
+| --- | --- |
+| gateway refuses to wrap (`budget-required`) | no `--budget` — the cap is mandatory for a payment rail (both modes) |
+| adapter runs but never settles on-chain | no wallet + facilitator → it returns the recorded settlement shape |
+| live path throws instead of settling | facilitator URL unset/unreachable — by design, it never fabricates a tx |
+| `usage-cap-exceeded` on a tiny x402 call | the cross-rail moat — the shared cap is already spent (expected) |
+| sub-cent amount refused | x402 atomic→cents is exact-only; align the amount to whole cents |
+| unsure which network is live | run `auths-mcp wrap --show-mode …` — it prints `mode=real|test` (base vs base-sepolia) and exits |
+
+## Testnet mode
+
+To exercise the rail **without real money**, opt into sandbox rails with `--test-mode` (or `AUTHS_MCP_TEST_MODE=1` for the adapter) — the test tab under [Setup](#setup) shows the full command. Testnet mode resolves the x402 rail to **base-sepolia** with **testnet USDC** — no real money. The cap is **still mandatory**, and the mode is disclosed as `mode=test`.
+
+Fund the base-sepolia wallet from a base-sepolia ETH faucet (for gas) and a testnet USDC faucet. Use testnet mode to prove the cap refuses the over-cap call before you ever point a funded mainnet wallet at the rail. Then walk the full live path: [Walkthrough: real money](/docs/mcp/guides/spend-real-money).
+
+## Useful links
+
+- Testnet USDC faucet: https://cloud.google.com/application/web3/faucet/ethereum/sepolia
+- x402 wallet reference: https://github.com/0xKoda/x402-wallet/blob/main/wallet.md
diff --git a/content/docs/mcp/quickstart.md b/content/docs/mcp/quickstart.md
new file mode 100644
index 0000000..9357324
--- /dev/null
+++ b/content/docs/mcp/quickstart.md
@@ -0,0 +1,69 @@
+---
+title: Quickstart
+description: Wrap a filesystem MCP server, ask for something out of scope, and watch the gateway refuse it — five minutes, zero money at risk.
+product: mcp
+section: Get started
+order: 3
+badge: new
+lastReviewed: "2026-07-17"
+---
+
+The fastest way to trust the gate is to watch it say no. You'll wrap a filesystem
+MCP server with a read-only scope, then ask the agent to write — and the gateway
+will refuse the call before the server ever sees it. No card, no wallet.
+
+{% steps %}
+{% step title="Prepend one wrap line to a server you already have" %}
+In your MCP client config (Claude Desktop, Claude Code, or Cursor's `mcp.json`),
+wrap the filesystem server line by prepending the gateway:
+
+```json {% filename="mcp.json" %}
+"filesystem": {
+  "command": "npx",
+  "args": ["-y", "@auths-dev/mcp", "wrap", "--scope", "fs.read", "--budget", "$5", "--ttl", "30m",
+           "--", "npx", "-y", "@modelcontextprotocol/server-filesystem", "/Users/me/proj"]
+}
+```
+
+Everything after `--` is the untouched server line you already had. The agent keeps
+working — now bounded to `fs.read`, a `$5` budget, and a 30-minute lifetime.
+{% /step %}
+
+{% step title="Make an in-scope call" %}
+Ask the agent to read a file. The call is inside the granted scope, so the gate
+forwards it and writes a receipt:
+
+```output
+✓ read_file → allowed
+```
+{% /step %}
+
+{% step title="Cause the refusal" %}
+Now ask the agent to write a file. `fs.read` never granted that capability, so the
+gate refuses the call — the downstream server is never invoked:
+
+```output
+✗ write_file → outside-agent-scope · refused
+```
+
+The model can decide whatever it likes; the boundary holds. That refusal — with its
+receipt — is the product working.
+{% /step %}
+
+{% step title="Let it expire" %}
+After the 30-minute TTL, nothing the agent signs passes: every call is
+{% verdict code="agent-expired" /%} until you wrap again with a fresh delegation.
+Short lifetimes are cheap; use them.
+{% /step %}
+{% /steps %}
+
+## What you just proved
+
+The agent held a delegation with three bounds — scope, budget, expiry — and the
+gateway refused the call that exceeded one of them, at the protocol boundary,
+fail-closed. How the gate decides is one short page:
+[how it works](/docs/mcp/concepts/how-it-works).
+
+When you're ready to bound something that spends, go to
+[spend real money](/docs/mcp/guides/spend-real-money) — same gate, real rails,
+`--test-mode` first.
diff --git a/content/docs/prove-provenance.md b/content/docs/prove-provenance.md
index e3f7f4e..6d56b9a 100644
--- a/content/docs/prove-provenance.md
+++ b/content/docs/prove-provenance.md
@@ -1,6 +1,10 @@
 ---
 title: Prove Provenance
 description: Verify the authenticity and origin of commits and build artifacts
+product: identity
+section: Guides
+order: 7
+lastReviewed: "2026-07-17"
 ---
 
 ## What is code provenance?
@@ -17,7 +21,7 @@ auths verify <commit-sha>
 auths verify HEAD~10..HEAD
 ```
 
-`auths verify` confirms each signature resolves to a trusted identity and that the commit is unmodified. To trust a signer first, pin them with `auths trust pin --did did:keri:E... --key <pubkey-hex>` (see [Sign Commits](/docs/sign-commits)).
+`auths verify` confirms each signature resolves to a trusted identity and that the commit is unmodified. To trust a signer first, pin them with `auths trust pin --did <their-identity> --key <pubkey-hex>` (see [Sign Commits](/docs/sign-commits)).
 
 ## Verify build artifacts
 
@@ -31,7 +35,7 @@ Attestations are the same mechanism the [verify widget](https://github.com/auths
 
 ## Enforce verification in CI
 
-Use the **verify** GitHub Action to fail a pull request when commits (or artifacts) aren't properly signed. It uses ephemeral, KEL-native verification — no secrets to manage:
+Use the **verify** GitHub Action to fail a pull request when commits (or artifacts) aren't properly signed. It uses ephemeral verification against the signer's key event log (KEL) — no secrets to manage:
 
 ```yaml
 name: Verify provenance
diff --git a/content/docs/quickstart.md b/content/docs/quickstart.md
index 59d93c8..638d3a9 100644
--- a/content/docs/quickstart.md
+++ b/content/docs/quickstart.md
@@ -1,6 +1,11 @@
 ---
 title: Quickstart
 description: Install Auths, create an identity, and verify your first signed commit in five minutes
+product: identity
+section: Guides
+order: 1
+lastReviewed: "2026-07-17"
+badge: new
 ---
 
 Go from zero to a **verified, signed commit** in about five minutes — entirely offline, no account or server required.
@@ -44,7 +49,7 @@ Check who you are:
 auths whoami
 ```
 
-You should see your new identity — a `did:keri:…` identifier: a decentralized ID backed by a *key event log* (KEL), a tamper-evident history of your keys. No account, no server.
+You should see your new identity — a self-certifying identifier backed by a *key event log* (KEL), a tamper-evident history of your keys that travels with you. No account, no server.
 
 ## 3. Sign a commit
 
@@ -73,7 +78,7 @@ A successful verification is the **payoff** — it confirms the commit's signatu
 
 ```text
 ✔ Verified: HEAD
-  Signer: did:keri:…
+  Signer: <root>
   Signature valid.
 ```
 
@@ -87,7 +92,6 @@ Auths can render a **"Verified" badge** for a repository's releases using the em
 
 ## Next steps
 
-- **[Give an AI agent a scoped passport](/docs/mcp-setup)** — set up Auths for a Claude or Cursor MCP agent.
-- **[Agent hello-world (`auths-agent-demo`)](https://github.com/auths-dev/auths-agent-demo)** — the canonical agent/SDK demo: an operator delegates scoped, time-bounded authority to AI agents, and a server verifies it (Python SDK; install from source with `pip install -e .`).
+- **[Bound an AI agent](/docs/mcp)** — put a Claude or Cursor MCP agent behind a scope, a budget, and an expiry.
 - **[Sign commits in depth](/docs/sign-commits)** — signing ranges, CI, and team workflows.
 - **[Concepts](/docs/concepts/identity-model)** — how identities, keys, and verification work under the hood.
diff --git a/content/docs/reference/cli.md b/content/docs/reference/cli.md
index 5bb4f36..153af48 100644
--- a/content/docs/reference/cli.md
+++ b/content/docs/reference/cli.md
@@ -1,6 +1,11 @@
 ---
 title: CLI Reference
 description: Complete reference for Auths CLI commands
+product: identity
+section: Reference
+order: 1
+lastReviewed: "2026-07-17"
+badge: soon
 ---
 
 > 🚧 **Stub** — a full per-command reference hasn't been published here yet. The CLI's own help is the source of truth:
@@ -16,7 +21,7 @@ auths <command> --help
 | Command | Purpose |
 |---------|---------|
 | `auths init` | Create your identity and set up Git signing (`--non-interactive` skips prompts) |
-| `auths whoami` | Show your identity (`did:keri:…`) |
+| `auths whoami` | Show your identity |
 | `auths status` | Identity + signing overview |
 | `auths sign <ref-or-range>` | Sign a commit or range |
 | `auths verify <ref/range/file>` | Verify commits or artifacts |
diff --git a/content/docs/reference/github-actions.md b/content/docs/reference/github-actions.md
index 0a2f8cb..e421155 100644
--- a/content/docs/reference/github-actions.md
+++ b/content/docs/reference/github-actions.md
@@ -1,6 +1,11 @@
 ---
 title: GitHub Actions
 description: Integrate Auths with GitHub Actions
+product: identity
+section: Reference
+order: 2
+lastReviewed: "2026-07-17"
+badge: soon
 ---
 
 > 🚧 **Stub** — a full input/output reference hasn't been written yet. The action repos below are the current sources of truth.
diff --git a/content/docs/sign-commits.md b/content/docs/sign-commits.md
index ae42222..a493d46 100644
--- a/content/docs/sign-commits.md
+++ b/content/docs/sign-commits.md
@@ -1,6 +1,10 @@
 ---
 title: Sign Commits
 description: Cryptographically sign and verify your Git commits with Auths
+product: identity
+section: Guides
+order: 4
+lastReviewed: "2026-07-17"
 ---
 
 Signing a commit proves that **you** authored it — provably, offline, with no central server or API key. This guide assumes you've already installed Auths and run `auths init` (see the [quickstart](/docs/quickstart)).
@@ -48,9 +52,9 @@ A successful verification confirms the signature resolves to a trusted identity
 Verification checks signatures against your **trusted identity roots**. Pin a teammate's identity (they share their DID and public key, e.g. from `auths whoami` and `auths id show`) so their commits verify on your machine:
 
 ```bash
-auths trust pin --did did:keri:E... --key <pubkey-hex>   # pin an identity as trusted
-auths trust list                                         # show pinned identities
-auths trust show did:keri:E...                           # details for one identity
+auths trust pin --did <their-identity> --key <pubkey-hex>   # pin an identity as trusted
+auths trust list                                            # show pinned identities
+auths trust show <their-identity>                           # details for one identity
 ```
 
 See [Team Identities](/docs/team-identities) for sharing identities across a team.
diff --git a/content/docs/team-identities.md b/content/docs/team-identities.md
index bda9fdc..bd2056e 100644
--- a/content/docs/team-identities.md
+++ b/content/docs/team-identities.md
@@ -1,11 +1,15 @@
 ---
 title: Team Identities
 description: Share and trust identities across a team, and delegate to agents
+product: identity
+section: Guides
+order: 5
+lastReviewed: "2026-07-17"
 ---
 
 ## Overview
 
-Each developer and machine has its own Auths identity (a `did:keri:…`). Working as a team means **establishing trust** between those identities and, where needed, **delegating** scoped authority to CI and agents. Auths has no central account system — trust is pinned locally and proven cryptographically.
+Each developer and machine has its own Auths identity. Working as a team means **establishing trust** between those identities and, where needed, **delegating** scoped authority to CI and agents. Auths has no central account system — trust is pinned locally and proven cryptographically.
 
 ## Your identity
 
@@ -13,19 +17,19 @@ Every member creates their own identity once:
 
 ```bash
 auths init
-auths whoami      # show your identity (did:keri:…)
+auths whoami      # show your identity
 auths status      # identity + signing overview
 ```
 
 ## Trusting teammates
 
-To verify a teammate's commits, pin their identity as a trusted root. They share their `did:keri:…` (from `auths whoami`) and their public key (from `auths id show`), then:
+To verify a teammate's commits, pin their identity as a trusted root. They share their DID (from `auths whoami`) and their public key (from `auths id show`), then:
 
 ```bash
-auths trust pin --did did:keri:E... --key <pubkey-hex>   # pin a teammate as trusted
-auths trust list                                         # all pinned identities
-auths trust show did:keri:E...                           # details
-auths trust remove did:keri:E...                         # unpin
+auths trust pin --did <their-identity> --key <pubkey-hex>   # pin a teammate as trusted
+auths trust list                                            # all pinned identities
+auths trust show <their-identity>                           # details
+auths trust remove <their-identity>                         # unpin
 ```
 
 Once pinned, `auths verify` accepts that identity's signatures. Commit a checked-in trust root (e.g. under `.auths/`) so the whole team and CI share the same trusted set.
@@ -42,7 +46,7 @@ Pass the result to `auths-dev/verify` via its `identity-bundle` input — see [B
 
 ## Delegating to agents
 
-Rather than share a human's key, delegate **scoped, expiring, revocable** authority to an agent or CI bot. This uses the same KERI delegation that powers agent passports:
+Rather than share a human's key, delegate **scoped, expiring, revocable** authority to an agent or CI bot. This uses the same delegation mechanism that powers agent passports:
 
 ```bash
 auths id agent add \
@@ -52,7 +56,7 @@ auths id agent add \
   --expires-in 86400
 ```
 
-See the [MCP setup guide](/docs/mcp-setup) and the [agent demo](https://github.com/auths-dev/auths-agent-demo) for the full delegation, scoping, and revocation workflow.
+See the [bounded-agent gateway](/docs/mcp) for the full delegation, scoping, and revocation workflow.
 
 ## Best practices
 
@@ -74,6 +78,6 @@ See the [MCP setup guide](/docs/mcp-setup) and the [agent demo](https://github.c
 ## Related topics
 
 - [Sign Commits](/docs/sign-commits)
-- [MCP Setup](/docs/mcp-setup)
+- [The bounded agent](/docs/mcp)
 - [Delegation](/docs/concepts/delegation)
 - [Key Rotation](/docs/concepts/key-rotation)
diff --git a/docs/prompts/build.md b/docs/prompts/build.md
new file mode 100644
index 0000000..69f8b43
--- /dev/null
+++ b/docs/prompts/build.md
@@ -0,0 +1,473 @@
+# Build plan — auths docs revamp on Markdoc (Stripe's OSS stack, no lock-in)
+
+**Goal:** rebuild the auths documentation as a small, beautiful, Stripe-grade site that
+takes a developer from *"what is auths-mcp"* to *"I bounded a real agent to a budget and
+verified the receipt myself"* — on a stack **we own**, with a design and architecture that
+stay clean as the product grows. Ship ~10 pages of `auths-mcp` first; push the deeper auths
+(signing, verify, identity) docs further down; make everything else cheap to add later.
+
+**Why this repo, not Mintlify.** This site (`auths-docs-stripe`) is **Next.js 15 +
+Markdoc**. Markdoc is Stripe's open-source authoring framework (MIT) — the same engine
+behind Stripe's own docs. We render it ourselves in our own Next app, so there is **no
+vendor lock-in**: no proprietary `docs.json`, no hosted-only components, no platform we
+can't leave. The tradeoff is we build the chrome (layout, code tabs, search) — which is
+exactly what this plan specifies, and most of the bones already exist here.
+
+- **Repo:** `/Users/bordumb/workspace/repositories/auths-base/auths-docs-stripe`
+- **Run:** `bun dev` (or `npm run dev`) → `http://localhost:3000/docs`
+- **Stack today:** Next 15 (App Router) · `@markdoc/markdoc ^0.5.7` · Tailwind v4 ·
+  `prism-react-renderer` · content in `content/docs/*.md`.
+- **Scope this pass:** `auths-mcp` (the bounded-agent gateway) leads. The existing
+  signing/identity content is **demoted, not deleted**.
+
+---
+
+## 0. Ground truth — read before writing a line
+
+Every command, flag, verdict, and provider detail must come from real source. Invent
+nothing. Priority order:
+
+1. **`auths-mcp` repo docs** — `../auths-mcp/docs/` (`index.md`, `walkthrough.md`,
+   `ai-providers/*`, `payment-providers/*`) and `clients/README.md`. ~90% of the content;
+   this pass is **port + tighten + redesign**, not net-new writing.
+2. **Gateway source** — `../auths/crates/auths-mcp-gateway/src/main.rs` (the clap CLI is the
+   authority on `wrap` flags/subcommands) and `../auths/crates/auths-mcp-core` (verdicts,
+   rail extractors). **When prose and source disagree, source wins** (§10).
+3. **Positioning / voice** — the marketing site (`../auths-site`,
+   `apps/web/src/components/landing-ledger.tsx`, `/verify`, `/trust`). The docs must feel
+   like the same product: the promise is *"your agent can't exceed its budget, and you can
+   prove it,"* and the recurring beat is a **refusal with a receipt**.
+
+The verified surface is pinned in **Appendix A** — canonical; reconcile every code block
+against it and `auths-mcp-gateway wrap --help`.
+
+---
+
+## 1. Current state — what's here, and the debt a "complete revamp" must clear
+
+The repo already has a Stripe-shaped skeleton (3-pane layout, sidebar, on-this-page,
+prev/next). Good bones. But four architectural problems block the design and scale goals,
+and all four must be fixed as part of the revamp:
+
+| # | Problem (today) | Why it blocks us | Fix (this plan) |
+|---|---|---|---|
+| **D1** | `lib/markdoc.ts` renders to an **HTML string** via `Markdoc.renderers.html` + `dangerouslySetInnerHTML`. | Custom Markdoc tags can never become **interactive React** — so synchronized code tabs, copy buttons, live verdict chips are impossible from content. `markdoc/tags` and `markdoc/nodes` are **empty**. | Render with `Markdoc.renderers.react`; populate the tag/node schema. **The keystone fix** — nothing else interactive works without it. (§6) |
+| **D2** | Every page is a **hand-written** `app/docs/<slug>/page.tsx` that hardcodes the content path **and** duplicates title/description in `generateMetadata`. | Adding a page = writing React + duplicating frontmatter. Doesn't scale; drifts. | One `app/docs/[...slug]/page.tsx` catch-all; metadata from frontmatter; `generateStaticParams` from the content tree. (§6) |
+| **D3** | `components/docs/CodeExamples.tsx` is a hardcoded `Record<pathname, …>` in a **right rail keyed by URL**, divorced from the prose. | Code samples live apart from the content that explains them; can't be authored inline; no language sync. | Content-authored `{% code-tabs %}` with a **global synced language** (§5). Retire the URL-keyed map. |
+| **D4** | `lib/docs-navigation.ts` is a hand-maintained array that **leads with "Sign Commits / Team Identities"** (the old product) and drifts from the files. | Wrong product first; nav and content can disagree silently. | Derive nav from content **frontmatter** (`section`, `order`, `badge`); **auths-mcp leads**, signing demoted. (§7–8) |
+
+Also flagged for the revamp: `components/markdoc/Callout.tsx` uses **emoji** (💡 ⚠️ ❌) —
+replaced by a real icon set (§4); design tokens are stock gray/blue Tailwind — replaced by
+a brand system (§4).
+
+---
+
+## 2. Honesty / dependency callouts (resolve before "Install" ships)
+
+The gateway is real and passes its full suite (`run.sh --check`: wrap, scope/budget gating,
+signed receipts, tamper + drop detection, metered Stripe/x402 settlement, a live MCP wire).
+But *distribution* is mid-flight — the docs must not promise an install that 404s:
+
+- **npm publish pending.** `@auths-dev/mcp` is not yet on npm (`package.json` → `"private":
+  true`, `0.0.0`). Until published, `npx @auths-dev/mcp wrap …` will 404. Gate the Install
+  page's runnable lines behind an availability note, or ship after publish.
+- **Per-platform binary vendoring pending.** The launcher resolves a prebuilt gateway from
+  `vendor/<platform>/`, populated by a release CI that doesn't exist in `auths-mcp` yet.
+  Headline the one-line `npx` path; mark `brew`/`uvx` "fast-follow."
+- **Package name is `@auths-dev/mcp` / `auths-mcp`.** Sweep for stray `@auths/mcp` (it
+  survives in some source comments and the marketing hero — being corrected; don't copy).
+
+---
+
+## 3. Principles (the spine — every page, every component)
+
+1. **One quick win, fast, with zero money at risk.** A reader wraps a *filesystem* server
+   and watches a refusal inside five minutes — trust earned before we ask for a live key.
+2. **Lead with the refusal.** Every page's payoff is the gateway saying *no*
+   (`usage-cap-exceeded`, `outside-agent-scope`, `revoked`) with a receipt.
+3. **Every command is real and runnable.** Real strings, real verdicts (Appendix A).
+4. **Danger is loud.** Payment rails are **real money by default**; every page that can
+   touch a live rail opens with a danger callout and shows `--test-mode` *first*.
+5. **Teach each idea once.** The cap, custody, receipts each get exactly one home page;
+   everything links there.
+6. **Ten pages, not a hundred.** Off the critical path → deferred (§11), not built now.
+7. **Content is data, not code.** After the D1/D2 fixes, a page is a `.md` file — an agent
+   or a non-engineer can add one. Protect that property; never regress to per-page React.
+
+---
+
+## 4. Design — Stripe-grade ease of use, unmistakably auths
+
+The bar: a developer lands and immediately feels *"this is going to be easy."* That feeling
+is made of layout discipline, restraint, real typography, and code blocks that do exactly
+what you expect. Concretely:
+
+### 4a. Layout — the Stripe three-pane, used well
+Keep the scaffolded grid `[sidebar | content | right-rail]` (`app/docs/layout.tsx`), refined:
+
+- **Left rail (nav):** sections as small-caps eyebrows; the current page marked with the
+  accent and a hairline indicator; collapsible groups; a persistent product switch at the
+  top (**auths-mcp** vs **Identity & signing**) so the two product areas never tangle.
+- **Center (prose):** one comfortable measure (~72ch), generous line-height (1.7), clear
+  h2/h3 rhythm, hairline section rules. This is a reading column, not a wall.
+- **Right rail:** **"On this page"** TOC (already built, keep) — and, on guide pages that
+  earn it, Stripe's signature **sticky code panel**: the runnable commands for the current
+  section pin on the right and swap as you scroll. This replaces the hardcoded
+  `CodeExamples` (D3) with content-authored, section-anchored code.
+- **Mobile:** the drawer (already built) closes on navigate; the sticky code panel collapses
+  into inline blocks. No horizontal scroll; tables and wide code scroll inside their own box.
+
+### 4b. Icons — a real set, never emoji
+Remove every emoji (starting with `Callout.tsx`'s 💡⚠️❌). Adopt **Lucide** (`lucide-react`,
+MIT, tree-shakeable) — the marketing site already uses it, so icons match across properties.
+Map meaning to icon, consistently: info → `Info`, warning → `TriangleAlert`, danger →
+`OctagonAlert`, success/allowed → `Check`, refusal/denied → `Ban`, receipt → `ReceiptText`,
+key/custody → `KeyRound`, terminal → `SquareTerminal`. Icons are line-weight, currentColor,
+sized to the text — decoration never carries meaning alone (pair with a label for a11y).
+
+### 4c. Brand — clean like Stripe, warm like auths
+There's a real tension to resolve (flag in §12): the marketing "ledger" is warm paper
+(`#f6f3ec`) / ink (`#1c1814`) / seal (`#c2401b`); Stripe docs are cool white / indigo. For
+**docs specifically** (long reading + dense code needs crisp contrast), the recommended
+synthesis:
+
+- **Canvas:** a clean, high-contrast near-white (not the warm paper) for the reading column;
+  the warm paper can tint the nav rail for identity.
+- **One accent:** the **seal `#c2401b`** — links, active nav, focus rings, primary buttons.
+  Exactly one accent, like Stripe's single indigo.
+- **Keep the receipt/terminal motif:** code and verdict blocks use the marketing site's dark
+  terminal (`#15130f`) — the only dark objects on the page, reading like photographs tipped
+  into a document. The reserved red `#c0442e` is used for **one meaning only: a denial /
+  `refused` verdict** — never decorative.
+- **Type:** a refined sans for prose (Geist, matching marketing), true monospace in code, a
+  display face (Fraunces) reserved for page titles if we want the editorial signature. Small
+  caps for section eyebrows.
+- Full **light/dark** support; both themes styled, respecting `prefers-color-scheme` with a
+  manual toggle.
+
+### 4d. Code blocks — the thing developers actually touch
+Code is the product surface of docs; make it excellent:
+
+- **Copy button** on every block (none today). One-click, with copied-state feedback.
+- **Filename / label header** and language pill.
+- **Syntax highlighting** worthy of Stripe — `prism-react-renderer` is fine to start;
+  consider **Shiki** (VS Code grammars, exact fidelity) as an upgrade (flag §12).
+- **Line highlighting / focus** for step-by-step (`{% code highlight="2-3" %}`).
+- **Verdict chips:** inline `allowed` (seal) / `refused` (reserved red) tokens so a receipt
+  reads like the real terminal output, not gray text.
+- No layout shift on hydration; blocks render server-side and stay put.
+
+### 4e. Synchronized multi-language code tabs (the headline request)
+When a tool exists in several languages (the **verifier/SDK**: Rust crate, WASM/npm, Python
+& Go & Swift via FFI — and even within auths-mcp: `npx` vs `brew` vs `uvx`, or CLI vs the
+Python recorder), the reader picks a language **once** and **every** code block on the page
+follows. Build it now, even though auths-mcp v0 is CLI-heavy — it's the foundation SDK docs
+will lean on.
+
+Design:
+
+- **`LanguageProvider`** (React context) holds the active language, hydrated from
+  `localStorage('auths.docs.lang')` and restored on load; SSR renders a stable default (no
+  flash, no layout shift).
+- A Markdoc tag **`{% code-tabs %}`** wraps N `{% code-tab lang="python" file="verify.py" %}`
+  children. Every `CodeTabs` instance **subscribes to the shared context** — switching the
+  tab in one block sets the global language, and all blocks re-render to it. This is the
+  "anchored across all code blocks" behavior.
+- **Graceful fallback:** if a block lacks the chosen language, it shows its default and a
+  quiet note (*"Not available in Python — showing Bash"*) rather than breaking the set.
+- **Keyboard + a11y:** tabs are a real ARIA tablist, arrow-key navigable, focus-visible.
+- **Deep-linkable:** honor `?lang=python` on load so shared links land in the right language.
+
+Retire `components/docs/CodeExamples.tsx` (the URL-keyed map) in favor of this — code lives
+inline with the prose that explains it.
+
+### 4f. Small touches that read as "easy"
+Persistent, working **search** (flag scope in §11); a **"Copy page as Markdown / Open in
+ChatGPT/Claude"** affordance (cheap, on-brand for a "check it yourself" product); **"Edit
+this page"** + **"Last reviewed"** on every page (§11); breadcrumbs; anchored headings with
+hover-to-link; a real 404 that routes back into the nav.
+
+---
+
+## 5. Content information architecture — the 10 pages (auths-mcp leads)
+
+Three groups, ten pages — the shortest path from *what is it* to *I bounded a real agent and
+verified it*. Each spec: **purpose · the one thing it lands · real commands/verdicts ·
+components · what to leave out.** Routes are `/docs/<slug>`; content is `content/docs/<slug>.md`.
+
+### Group A — Get started (zero → first refusal)
+**A1 `mcp/index.md` — The bounded agent.** *What/why in 30s.* Lands: the gateway holds a
+scoped, budget-bound, revocable delegation and **refuses any `tools/call` that exceeds it**;
+the cap is a seatbelt (**cannot**, not shouldn't). A 4-line terminal: `allowed` → then
+`usage-cap-exceeded` with a receipt id. Two cards: **Quickstart (no money)** /
+**Spend real money**. *Components:* card group, terminal block, verdict chips. *Leave out:*
+architecture, crypto internals.
+
+**A2 `mcp/install.md` — Install.** Shortest page. Lands: the one-line `npx` form is the
+headline; `brew`/`uvx` fast-follow. Prereqs (Node 18+, a downstream MCP server); verify with
+`auths-mcp wrap --show-mode …` (touches nothing). *Components:* synced code-tabs
+(npx/brew/uvx), availability warning (§2). *Leave out:* a platform-binary matrix.
+
+**A3 `mcp/quickstart.md` — Wrap your first server (no money, 5 min).** The quick win. Lands:
+prepend one `wrap` line to a filesystem MCP server with `--scope fs.read --budget '$1'
+--ttl 30m`; an in-scope call is `allowed`, an out-of-scope `write_file` is
+`outside-agent-scope` — **no card, no wallet.** *Components:* steps, the `mcp.json` snippet
+(from `clients/README.md`), verdict chips. *Leave out:* payments, custody, revocation.
+
+### Group B — Core ideas (the read-once mental model)
+**B1 `mcp/concepts/how-it-works.md` — The gate.** Lands: stock MCP up and down; **every
+`tools/call`** runs one gate — scope ⊆ parent · budget · expiry · revocation · authenticity
+— forwards **only** on `allowed`, **fails closed**. One receipt per call. *Components:* the
+data-flow diagram (adapt `payment-providers/stripe.md`), five bounds each with its verdict.
+
+**B2 `mcp/concepts/budgets.md` — The seatbelt & the cross-rail moat.** Lands: a durable
+cross-rail counter, pre-authorized (reserve before the rail, settle after) — `$4.99` Stripe
++ `$4.99` x402 = `$9.98` of a `$5` cap → next call on **either** rail refused. Real money is
+default; `--test-mode` is the single opt-in; the cap is **mandatory** (`budget-required`,
+both modes). *Components:* danger callout, mode table, `--show-mode` habit.
+
+**B3 `mcp/concepts/custody.md` — The agent never holds the key.** Lands: gateway is a
+credential-custody broker (`--custody-credential NAME` adopts from its env; `NAME=VALUE`
+injects); bypass → no credential → unbypassable. Secret never touches wire, receipts, logs.
+
+**B4 `mcp/concepts/receipts.md` — Prove it yourself.** Lands: every gated call is signed +
+logged; anyone re-derives spend **offline** with `verify-spend`; tampering is caught. The
+verdict table lives here (Appendix A); one paragraph on **revocation** (next call fails on
+every rail at once). *Components:* steps (verify → tamper), verdict table.
+
+### Group C — Do the real thing (bound real money)
+**C1 `mcp/guides/spend-real-money.md` — Walkthrough (flagship).** Port
+`auths-mcp/docs/walkthrough.md`: Step 0 disclose mode (`--show-mode`), Step 1 Stripe, Step 2
+x402 (same cap), Step 3 a real `claude-opus-4-8` loop hitting the wall, "kill it instantly"
+(revoke), safety checklist. **Open with the real-money danger callout; `--test-mode` first.**
+This page earns the **sticky right-hand code panel** (§4a). *Components:* steps, danger,
+checklist, synced tabs, sticky code.
+
+**C2 `mcp/providers/stripe.md` — Stripe rail.** Port `payment-providers/stripe.md`: live
+`sk_live_…` default; meters `charge.amount_captured` from Stripe's own response; over-cap
+refused **before** Stripe is called; `--test-mode` → `sk_test_…`; the "small reconcile";
+troubleshooting. *Components:* danger, synced tabs (test/live), troubleshooting accordion.
+
+**C3 `mcp/providers/x402.md` — x402 / USDC rail.** Port `payment-providers/x402.md`: base
+**mainnet** default; needs a **funded wallet + facilitator** (warn loudly — not a key
+drop-in); atomic-USDC→cents exact-only; meters into the **same** cap (the moat); `--test-mode`
+→ base-sepolia; faucet link. *Components:* warning + danger, synced tabs.
+
+> **Demoted, not deleted — "Identity & signing" (secondary top-level section).** The existing
+> `content/docs/*.md` (sign-commits, team-identities, build-agents, prove-provenance,
+> installation, authentication, concepts/*, reference/*) move **below** the auths-mcp
+> section, clearly secondary. Keep them reachable; do not lead with them. No page linked from
+> the auths-mcp section leads with commit signing.
+
+---
+
+## 6. Architecture revamp (the foundation for §4 and §11)
+
+Do these first — the design and scale goals depend on them.
+
+1. **Render to React (fixes D1).** Rewrite `lib/markdoc.ts` to use `Markdoc.renderers.react`
+   with a `components` map, not `renderers.html` + `dangerouslySetInnerHTML`. Custom tags now
+   become interactive components. *Everything interactive depends on this.*
+2. **Populate the Markdoc schema.** `markdoc/nodes/`: `heading` (auto-id + `scroll-mt`, keep
+   the slugger), `fence` (→ the new copy-enabled `CodeBlock`). `markdoc/tags/`: `callout`,
+   `code-tabs` + `code-tab`, `card`/`card-group`, `steps`/`step`, `verdict`, `receipt`,
+   `snippet` (§11). Each tag = a schema file + a React component in `components/markdoc/`.
+3. **One catch-all route (fixes D2).** Replace the per-page files with
+   `app/docs/[...slug]/page.tsx`: resolve slug → `content/docs/**.md`, parse, render; derive
+   `<title>`/description/OG from **frontmatter**; `generateStaticParams` walks the content
+   tree. Delete the hand-written page files as they're migrated.
+4. **Filesystem-driven nav (fixes D4).** Generate `docsNavigation` from content frontmatter
+   (`section`, `order`, `badge`) so nav can't drift from files. **auths-mcp is the first
+   section;** identity/signing follow.
+5. **Keep the good bones:** `OnThisPage`, `DocsPrevNext`, the drawer, the 3-pane grid — reuse
+   as-is (restyled per §4).
+
+---
+
+## 7. Navigation config (target shape)
+
+Frontmatter-driven; the array below is the *result*, not a hand-maintained source:
+
+```
+auths-mcp (LEAD)
+  Get started      → mcp/index, mcp/install, mcp/quickstart
+  Core ideas       → mcp/concepts/how-it-works, .../budgets, .../custody, .../receipts
+  Spend real money → mcp/guides/spend-real-money, mcp/providers/stripe, mcp/providers/x402
+Identity & signing (SECONDARY, demoted)
+  → installation, sign-commits, team-identities, build-agents, prove-provenance, authentication
+Concepts   → identity-model, key-rotation, delegation        (badge: soon, as today)
+Reference  → cli, github-actions                              (badge: soon)
+```
+
+Top-of-sidebar **product switch** toggles the two product worlds so they never intermix.
+
+---
+
+## 8. Voice & copy rules (from the marketing site)
+
+- **Say** can't / refused / proved / bounded / cannot. **Avoid** enables / empowers /
+  leverages / seamless / robust; avoid hedges (just / simply / should / might) unless
+  deliberate.
+- **Never** put `KERI` / `CESR` / `DID` / `did:keri:…` in docs; mechanism words
+  ("delegation", "key event log", "device-bound key") only inside how-it-works. Use
+  `<agent>` / `<root>` placeholders.
+- **Never** say "blockchain" / "decentralized" / "self-sovereign." x402 is "on-chain USDC
+  settlement" (a mechanism), not a category.
+- **Don't** lead with "offline verification" as the differentiator (everyone ships
+  `--offline`). The edge: *the receipt re-derives against the key that signed it, checkable
+  by anyone.*
+- House style: active voice, second person, sentence-case headings, one idea per sentence,
+  code formatting for commands/paths/verdicts. Real-money danger stated plainly, every time.
+
+---
+
+## 9. Grounding & anti-drift
+
+- **Reconcile every command against the binary** before publishing. Known drift: prose docs
+  wrap payment rails with `--scope paid.call` and **no** `--rail`, but the clap surface
+  defines `--rail stripe|x402`. Run `auths-mcp-gateway wrap --help` and match it.
+- **Verdict strings are exact** — only the ten in Appendix A. No paraphrase.
+- **No fabricated output** — every terminal line reproducible via the documented command
+  (`run.sh --check`, `examples/live/` are the real output shapes).
+- **Package name** `@auths-dev/mcp` / `auths-mcp` everywhere; sweep stray `@auths/mcp`.
+
+---
+
+## 10. Scalability & anti-staleness — keep the docs true as the product moves
+
+The failure mode we've already hit on the marketing site (links and commands drifting from
+reality) is the thing to engineer against here. Build these guardrails as part of the revamp:
+
+1. **Snippet transclusion (the big one).** A `{% snippet file="…" region="…" %}` tag pulls
+   command/code blocks from **real, CI-run example files** in the `auths-mcp` repo instead of
+   hand-copied strings. If the example changes, the doc changes; if the example breaks CI,
+   we know before the doc lies. Use it for every command-bearing block that has a source of
+   truth.
+2. **Generated reference.** The CLI reference and the verdict table are **generated** from
+   source — a script runs `auths-mcp-gateway wrap --help` → `content/docs/mcp/reference/cli.md`,
+   and reads the verdict enum from `auths-mcp-core` → the verdict table. Never hand-maintained,
+   never drifts. Wire it as a `bun run gen:reference` step + a CI check that fails if the
+   committed output is stale.
+3. **CI guardrails (cheap, high-value):**
+   - **Link check** — internal + external; fail the build on any 404 (the marketing-site
+     lesson, encoded).
+   - **Verdict/name lint** — fail on any code block using a verdict string not in the enum,
+     or any stray `@auths/mcp`.
+   - **Frontmatter contract** — required fields (`title`, `description`, `section`, `order`,
+     `lastReviewed`); build-time validation.
+   - **Markdoc validation** — `Markdoc.validate()` in CI catches unknown tags/attrs before
+     they render as nothing.
+4. **Freshness surfaced, not hidden.** Every page shows **"Last reviewed <date>"** (from
+   `lastReviewed` frontmatter) and an **"Edit this page"** link to its `.md` on GitHub. A
+   scheduled job (weekly) opens an issue listing pages past a freshness threshold, so stale
+   pages get triaged instead of rotting.
+5. **Content-is-data compounding.** Because pages are `.md` + one catch-all route (§6), a new
+   page needs **no React** — an engineer, a writer, or an agent adds a file. Protect this: no
+   feature should reintroduce per-page components.
+6. **Search at scale** — a build-time static index (e.g. a generated JSON + client search, or
+   Pagefind) when the page count crosses ~20. Not v0; noted so the architecture leaves room.
+7. **Design tokens, one source.** All color/spacing/type as CSS variables (mirroring the
+   marketing `globals.css`), so a brand change is one file, not a hunt through components.
+
+---
+
+## 11. Deliberately NOT in this pass (the next ten)
+
+Listed so we don't build them now and nothing secretly depends on them: per-client config
+pages (Claude Desktop/Code/Cursor/Codex); the AI-provider / live-evidence recorder page
+(`providers/anthropic`); the full generated CLI reference (infra in §10.2, page later);
+a standalone revocation guide; a scopes reference; the multi-language **SDK** docs (they'll
+lean hard on §4e — build the tabs now, the pages later); errors index; self-hosting the
+binary; CI-usage guide; architecture deep-dive. If a v0 reader needs one, link GitHub or mark
+"coming" — never stub a hollow page.
+
+---
+
+## 12. Open decisions (flag; don't block)
+
+1. **Docs canvas** — clean near-white (recommended, for reading + code contrast) vs. the
+   warm marketing paper. Accent = seal `#c2401b` either way.
+2. **Highlighter** — keep `prism-react-renderer` (installed) or upgrade to **Shiki**
+   (VS Code-grade). Recommend Shiki once tabs land.
+3. **Install timing** — publish `@auths-dev/mcp` before docs go live, or ship with the
+   availability callout (§2).
+4. **`--rail` vs `--scope paid.call`** — confirm the current binary's required payment-wrap
+   shape and standardize (§9).
+5. **Fate of the Mintlify clone** (`../auths-docs`) — this plan supersedes it; decide whether
+   to archive/delete that repo.
+
+---
+
+## 13. Definition of done (v0)
+
+- [ ] `lib/markdoc.ts` renders **React** (not an HTML string); `markdoc/tags` + `markdoc/nodes`
+      populated; **zero `dangerouslySetInnerHTML`** for content.
+- [ ] One `app/docs/[...slug]` catch-all; per-page `page.tsx` files removed; metadata comes
+      from frontmatter.
+- [ ] Nav is frontmatter-driven; **auths-mcp is the first section**; identity/signing demoted
+      below it; no auths-mcp page leads with commit signing.
+- [ ] All 10 auths-mcp pages exist at the §5 slugs with real, reconciled commands.
+- [ ] **No emoji anywhere**; Lucide icon set wired; `Callout.tsx` reworked.
+- [ ] **Synchronized language tabs** work: switching one block switches all, persists across
+      reloads, deep-links via `?lang=`, falls back gracefully, is keyboard/ARIA-correct.
+- [ ] Every code block has a **copy button**; verdict chips styled; terminal/receipt motif +
+      single seal accent; light/dark both styled.
+- [ ] Every page that can touch a live rail opens with a real-money danger callout and shows
+      `--test-mode` first.
+- [ ] At least the CI **link check** + **verdict/name lint** + **frontmatter contract** are
+      wired; **"Last reviewed" + "Edit this page"** render on every page.
+- [ ] Copy audit passes: zero `blockchain|decentraliz|self-sovereign`, zero
+      `KERI|CESR|did:keri` outside how-it-works, zero stray `@auths/mcp`.
+- [ ] `bun dev` clean, no broken links; `bun run build` + `type-check` green.
+- [ ] New reader can go index → quickstart and get a refusal with **no money at risk**, then
+      index → walkthrough for the real-money payoff.
+- [ ] Committed to a branch + PR; not force-published.
+
+---
+
+## Appendix A — Verified command & verdict surface (canonical)
+
+Pinned from `auths/crates/auths-mcp-gateway/src/main.rs` and `auths-mcp-core`. Reconcile all
+docs against this and `--help`; **source wins over prose.**
+
+**Invocation:** installed `auths-mcp`; no-install `npx -y @auths-dev/mcp …`. Fast-follows:
+`brew install auths-mcp`, `uvx auths-mcp` (pending, §2).
+**Subcommands:** `wrap` · `replay` (hermetic `--check` gate) · `verify-spend` (offline re-audit).
+
+**`wrap` flags:**
+
+| Flag | Value | Meaning |
+| --- | --- | --- |
+| `--scope` | `CAP` (repeatable) | capability granted, e.g. `fs.read`, `paid.call` |
+| `--budget` | `$5` / `20calls` | cross-rail cap; **mandatory** for payment rails |
+| `--ttl` | `30m` | delegation lifetime |
+| `--rail` | `stripe` \| `x402` | designates the payment rail (§9: reconcile vs prose) |
+| `--test-mode` | flag | opt into SANDBOX rails (Stripe `sk_test_…`, x402 `base-sepolia`); env twin `AUTHS_MCP_TEST_MODE=1` |
+| `--show-mode` | flag | resolve + disclose mode, then exit — dry run, no rail touched, no charge |
+| `--custody-credential` | `NAME[=VALUE]` (repeatable) | secret the gateway custodies; bare `NAME` adopts from gateway env, `NAME=VALUE` injects |
+| `-- <DOWNSTREAM>` | required | the wrapped MCP server command (everything after `--`) |
+
+**`verify-spend`:** `auths-mcp-gateway verify-spend --log spend.jsonl --registry ./registry
+--agent <agent> --root <root>` → prints `verify-spend: <hash> — <verdict>`.
+
+**The ten verdicts (exact strings — the only ones that exist):**
+
+| Verdict | Meaning |
+| --- | --- |
+| `allowed` | in bounds; forwarded, receipt written |
+| `usage-cap-exceeded` | would cross the budget cap (refused before the rail is touched) |
+| `outside-agent-scope` | capability the grant never gave |
+| `agent-expired` | past the delegation TTL |
+| `revoked` | root recorded a revocation; honored next call, every rail |
+| `budget-required` | payment rail wrapped with no `--budget` (fail-closed, both modes) |
+| `proof-unauthentic` | signature doesn't verify against the agent's key |
+| `tampered-proof` | a signed proof was altered (caught offline) |
+| `dropped-call` | a record removed from the log (caught by the back-link cross-check) |
+| `budget-mismatch` | durable cross-rail counter disagrees with the log (e.g. tail truncation) |
+
+**Modes:** REAL default (live Stripe `sk_live_…` @ `api.stripe.com`; x402 base **mainnet**,
+real USDC). `--test-mode` → sandbox (Stripe `sk_test_…`; x402 `base-sepolia`). Mode always
+disclosed at startup; live rails are never silent.
+
+**Providers (v0 scope):** Stripe (key drop-in) · x402/USDC (funded wallet + facilitator).
+Anthropic/`claude-opus-4-8` live recording is deferred (§11).
diff --git a/lib/content.ts b/lib/content.ts
new file mode 100644
index 0000000..4d9da64
--- /dev/null
+++ b/lib/content.ts
@@ -0,0 +1,183 @@
+import fs from 'fs'
+import path from 'path'
+import Markdoc from '@markdoc/markdoc'
+import * as yaml from 'js-yaml'
+
+/**
+ * The content layer: walks `content/docs/**.md`, enforces the frontmatter
+ * contract, and derives the navigation from it — the nav can never disagree
+ * with the files on disk.
+ */
+
+const CONTENT_DIR = path.join(process.cwd(), 'content/docs')
+
+export interface DocFrontmatter {
+  title: string
+  description: string
+  /** Which product world the page belongs to. */
+  product: 'mcp' | 'identity'
+  /** The sidebar section (eyebrow) the page lives under. */
+  section: string
+  /** Sort order within its section. */
+  order: number
+  badge?: 'new' | 'soon'
+  /** ISO date the page was last reviewed against the product. */
+  lastReviewed: string
+}
+
+export interface DocEntry {
+  /** Slug segments relative to /docs, e.g. ['mcp', 'quickstart']. */
+  slug: string[]
+  href: string
+  filePath: string
+  frontmatter: DocFrontmatter
+}
+
+export interface NavItem {
+  label: string
+  href: string
+  badge?: 'new' | 'soon'
+}
+
+export interface NavSection {
+  title: string
+  items: NavItem[]
+}
+
+export interface ProductNav {
+  product: 'mcp' | 'identity'
+  label: string
+  sections: NavSection[]
+}
+
+/** Section display order per product — the only hand-maintained nav input. */
+const SECTION_ORDER: Record<'mcp' | 'identity', string[]> = {
+  mcp: ['Get started', 'Core ideas', 'Spend real money'],
+  identity: ['Guides', 'Concepts', 'Reference'],
+}
+
+const PRODUCT_LABEL: Record<'mcp' | 'identity', string> = {
+  mcp: 'auths-mcp',
+  identity: 'Identity & signing',
+}
+
+const REQUIRED_FIELDS = [
+  'title',
+  'description',
+  'product',
+  'section',
+  'order',
+  'lastReviewed',
+] as const
+
+function walk(dir: string): string[] {
+  return fs.readdirSync(dir, { withFileTypes: true }).flatMap((e) => {
+    const p = path.join(dir, e.name)
+    if (e.isDirectory()) return walk(p)
+    return e.name.endsWith('.md') ? [p] : []
+  })
+}
+
+/**
+ * Parses and validates a doc file's frontmatter against the contract.
+ * Throws (build-time) with the file path on any missing field — a page
+ * without its contract never ships silently.
+ */
+function readFrontmatter(filePath: string): DocFrontmatter {
+  const source = fs.readFileSync(filePath, 'utf8')
+  const ast = Markdoc.parse(source)
+  const fm = ast.attributes.frontmatter
+    ? (yaml.load(ast.attributes.frontmatter) as Record<string, unknown>)
+    : {}
+
+  const missing = REQUIRED_FIELDS.filter((f) => fm[f] === undefined || fm[f] === '')
+  if (missing.length > 0) {
+    throw new Error(
+      `frontmatter contract: ${path.relative(process.cwd(), filePath)} is missing [${missing.join(', ')}]`
+    )
+  }
+  if (fm.product !== 'mcp' && fm.product !== 'identity') {
+    throw new Error(
+      `frontmatter contract: ${path.relative(process.cwd(), filePath)} has product="${String(fm.product)}" (must be "mcp" or "identity")`
+    )
+  }
+  return fm as unknown as DocFrontmatter
+}
+
+function toSlug(filePath: string): string[] {
+  const rel = path.relative(CONTENT_DIR, filePath).replace(/\.md$/, '')
+  const segments = rel.split(path.sep)
+  // index files collapse onto their directory: mcp/index.md → /docs/mcp
+  if (segments[segments.length - 1] === 'index') segments.pop()
+  return segments
+}
+
+/** Every doc on disk, contract-validated. Cached per server process. */
+let cachedEntries: DocEntry[] | null = null
+
+export function getAllDocs(): DocEntry[] {
+  if (cachedEntries) return cachedEntries
+  const entries = walk(CONTENT_DIR).map((filePath) => {
+    const slug = toSlug(filePath)
+    return {
+      slug,
+      href: `/docs/${slug.join('/')}`,
+      filePath,
+      frontmatter: readFrontmatter(filePath),
+    }
+  })
+  cachedEntries = entries
+  return entries
+}
+
+/** Resolve slug segments to a doc file, honoring index collapsing. */
+export function getDocBySlug(slug: string[]): DocEntry | null {
+  return getAllDocs().find((d) => d.slug.join('/') === slug.join('/')) ?? null
+}
+
+/**
+ * The navigation, derived from frontmatter. auths-mcp leads; identity &
+ * signing follows, demoted. Sections appear in SECTION_ORDER; pages sort by
+ * `order` within a section.
+ */
+export function getNavigation(): ProductNav[] {
+  const docs = getAllDocs()
+  return (['mcp', 'identity'] as const).map((product) => {
+    const inProduct = docs.filter((d) => d.frontmatter.product === product)
+    const sectionNames = [
+      ...SECTION_ORDER[product].filter((s) => inProduct.some((d) => d.frontmatter.section === s)),
+      // any section not in the configured order still renders, at the end
+      ...[...new Set(inProduct.map((d) => d.frontmatter.section))].filter(
+        (s) => !SECTION_ORDER[product].includes(s)
+      ),
+    ]
+    return {
+      product,
+      label: PRODUCT_LABEL[product],
+      sections: sectionNames.map((title) => ({
+        title,
+        items: inProduct
+          .filter((d) => d.frontmatter.section === title)
+          .sort((a, b) => a.frontmatter.order - b.frontmatter.order)
+          .map((d) => ({
+            label: d.frontmatter.title,
+            href: d.href,
+            badge: d.frontmatter.badge,
+          })),
+      })),
+    }
+  })
+}
+
+/** The flattened reading order (mcp first), for prev/next. */
+export function getPrevNext(href: string): { prev: NavItem | null; next: NavItem | null } {
+  const flat = getNavigation().flatMap((p) =>
+    p.sections.flatMap((s) => s.items.filter((i) => i.badge !== 'soon'))
+  )
+  const i = flat.findIndex((item) => item.href === href)
+  if (i === -1) return { prev: null, next: null }
+  return {
+    prev: i > 0 ? flat[i - 1] : null,
+    next: i < flat.length - 1 ? flat[i + 1] : null,
+  }
+}
diff --git a/lib/docs-navigation.ts b/lib/docs-navigation.ts
deleted file mode 100644
index 84b54fe..0000000
--- a/lib/docs-navigation.ts
+++ /dev/null
@@ -1,114 +0,0 @@
-/**
- * Docs navigation structure and utilities for the sidebar and prev/next nav.
- */
-
-export interface NavItem {
-  label: string
-  href: string
-  badge?: 'soon' | 'new'
-  items?: NavItem[]
-}
-
-export interface NavSection {
-  title: string
-  items: NavItem[]
-}
-
-/**
- * Navigation hierarchy for the docs site.
- * Used by DocsSidebar and DocsTopBar.
- */
-export const docsNavigation: NavSection[] = [
-  {
-    title: 'Getting Started',
-    items: [
-      { label: 'Overview', href: '/docs' },
-      { label: 'Quickstart', href: '/docs/quickstart', badge: 'new' },
-      { label: 'Installation', href: '/docs/installation' },
-      { label: 'Authentication', href: '/docs/authentication' },
-    ],
-  },
-  {
-    title: 'Guides',
-    items: [
-      { label: 'Sign Commits', href: '/docs/sign-commits' },
-      { label: 'Team Identities', href: '/docs/team-identities' },
-      { label: 'Build Agents', href: '/docs/build-agents' },
-      { label: 'MCP Setup', href: '/docs/mcp-setup', badge: 'new' },
-      { label: 'Prove Provenance', href: '/docs/prove-provenance' },
-    ],
-  },
-  {
-    title: 'Concepts',
-    items: [
-      { label: 'Identity Model', href: '/docs/concepts/identity-model', badge: 'soon' },
-      { label: 'Key Rotation', href: '/docs/concepts/key-rotation', badge: 'soon' },
-      { label: 'Delegation', href: '/docs/concepts/delegation', badge: 'soon' },
-    ],
-  },
-  {
-    title: 'Reference',
-    items: [
-      { label: 'CLI Reference', href: '/docs/reference/cli', badge: 'soon' },
-      { label: 'GitHub Actions', href: '/docs/reference/github-actions', badge: 'soon' },
-    ],
-  },
-]
-
-/**
- * Flattened navigation for prev/next computation.
- * Computed once at module level for efficient lookups.
- * @internal
- */
-const FLATTENED_NAV = docsNavigation.flatMap((section) =>
-  section.items.flatMap((item) => [item, ...(item.items ?? [])])
-)
-
-/**
- * Get the previous and next pages in the flattened nav sequence.
- * @param currentPath - The current page's URL path (e.g., '/docs/sign-commits')
- * @returns Object with `prev` and `next` NavItem or null if at boundaries
- * @example
- * const { prev, next } = getPrevNext('/docs/sign-commits')
- * // prev: { label: 'Installation', href: '/docs/installation' }
- * // next: { label: 'Team Identities', href: '/docs/team-identities' }
- */
-export function getPrevNext(currentPath: string): {
-  prev: NavItem | null
-  next: NavItem | null
-} {
-  const currentIndex = FLATTENED_NAV.findIndex((item) => item.href === currentPath)
-
-  if (currentIndex === -1) {
-    return { prev: null, next: null }
-  }
-
-  return {
-    prev: currentIndex > 0 ? FLATTENED_NAV[currentIndex - 1] : null,
-    next: currentIndex < FLATTENED_NAV.length - 1 ? FLATTENED_NAV[currentIndex + 1] : null,
-  }
-}
-
-/**
- * Check if a nav item is a placeholder (coming soon).
- * @param item - The nav item to check
- * @returns True if the item has badge 'soon'
- * @example
- * if (isPlaceholder(item)) {
- *   // Render as gray non-link with badge
- * }
- */
-export function isPlaceholder(item: NavItem): boolean {
-  return item.badge === 'soon'
-}
-
-/**
- * Get all nav items as a flat list (for static param generation, etc).
- * @returns Array of all nav items in the hierarchy
- * @example
- * const allItems = getAllNavItems()
- * const paths = allItems.map(item => item.href)
- */
-export function getAllNavItems(): NavItem[] {
-  return FLATTENED_NAV
-}
diff --git a/lib/markdoc-components.tsx b/lib/markdoc-components.tsx
new file mode 100644
index 0000000..712ad56
--- /dev/null
+++ b/lib/markdoc-components.tsx
@@ -0,0 +1,26 @@
+import React from 'react'
+import Markdoc, { type RenderableTreeNode } from '@markdoc/markdoc'
+import { CodeBlock } from '@/components/markdoc/CodeBlock'
+import { Callout } from '@/components/markdoc/Callout'
+import { Card, CardGroup } from '@/components/markdoc/Cards'
+import { Steps, Step } from '@/components/markdoc/Steps'
+import { CodeTabs, CodeTab } from '@/components/markdoc/CodeTabs'
+import { VerdictChip } from '@/components/markdoc/VerdictChip'
+
+/** The single map from Markdoc tag names to React components. */
+const components = {
+  CodeBlock,
+  Callout,
+  Card,
+  CardGroup,
+  Steps,
+  Step,
+  CodeTabs,
+  CodeTab,
+  VerdictChip,
+}
+
+/** Renders a transformed Markdoc tree to React — no HTML strings, ever. */
+export function renderDoc(content: RenderableTreeNode): React.ReactNode {
+  return Markdoc.renderers.react(content, React, { components })
+}
diff --git a/lib/markdoc.ts b/lib/markdoc.ts
index 4d515b9..3aa2c88 100644
--- a/lib/markdoc.ts
+++ b/lib/markdoc.ts
@@ -1,6 +1,7 @@
-import Markdoc, { RenderableTreeNode } from '@markdoc/markdoc'
+import Markdoc, { type RenderableTreeNode } from '@markdoc/markdoc'
 import * as yaml from 'js-yaml'
 import GithubSlugger from 'github-slugger'
+import { buildConfig } from '@/markdoc/schema'
 
 export interface TocItem {
   id: string
@@ -8,65 +9,45 @@ export interface TocItem {
   level: 2 | 3
 }
 
-export interface DocFrontmatter {
-  title?: string
-  description?: string
-  [key: string]: unknown
-}
-
 export interface ParsedDoc {
   content: RenderableTreeNode
-  frontmatter: DocFrontmatter
+  frontmatter: Record<string, unknown>
   toc: TocItem[]
 }
 
-const config = {}
-
 /**
- * Add IDs to headings in HTML
- * @param html - Raw HTML string from Markdoc renderer
- * @returns HTML with IDs added to h2 and h3 tags
+ * Parses a Markdoc source string into a renderable tree (for
+ * `Markdoc.renderers.react`), frontmatter, and TOC. Validation errors throw
+ * at build time — an unknown tag never silently renders as nothing.
  */
-function addHeadingIds(html: string): string {
-  const slugger = new GithubSlugger()
-  return html.replace(/<(h[2-3])([^>]*)>/g, (match, tag, attrs) => {
-    // Extract text content from the next closing tag
-    const closeTag = `</${tag}>`
-    const closeIndex = html.indexOf(closeTag, html.indexOf(match) + match.length)
-    const content = html.substring(html.indexOf(match) + match.length, closeIndex)
-    const text = content.replace(/<[^>]*>/g, '') // Strip any nested tags
-    const id = slugger.slug(text)
-
-    // Check if id attr already exists
-    if (attrs.includes('id=')) {
-      return match
-    }
-
-    return `<${tag}${attrs} id="${id}">`
-  })
-}
-
-/**
- * Parses a Markdoc source string into HTML, frontmatter, and TOC.
- * @param source - Raw markdown string from the .md file
- * @returns { html, frontmatter, toc }
- */
-export function parseDoc(
-  source: string
-): { html: string; frontmatter: DocFrontmatter; toc: TocItem[] } {
+export function parseDoc(source: string): ParsedDoc {
   const ast = Markdoc.parse(source)
-  const frontmatter: DocFrontmatter = ast.attributes.frontmatter
-    ? (yaml.load(ast.attributes.frontmatter) as DocFrontmatter)
+  const frontmatter = ast.attributes.frontmatter
+    ? (yaml.load(ast.attributes.frontmatter) as Record<string, unknown>)
     : {}
 
-  // Extract TOC from AST
+  const config = buildConfig()
+
+  const errors = Markdoc.validate(ast, config).filter((e) => e.error.level === 'critical')
+  if (errors.length > 0) {
+    const detail = errors
+      .map((e) => `${e.error.id ?? 'error'} at line ${e.lines?.[0] ?? '?'}: ${e.error.message}`)
+      .join('\n  ')
+    throw new Error(`Markdoc validation failed:\n  ${detail}`)
+  }
+
+  // TOC from the AST with its own slugger — same algorithm as the heading
+  // node transform, so ids always match.
   const slugger = new GithubSlugger()
   const toc: TocItem[] = ast.children
     .filter((node) => node.type === 'heading' && [2, 3].includes(node.attributes.level))
     .map((node) => {
-      const text = node.children
-        .map((c: any) => (typeof c === 'string' ? c : c.attributes?.content ?? ''))
-        .join('')
+      let text = ''
+      for (const child of node.walk()) {
+        if (child.type === 'text' || child.type === 'code') {
+          text += String(child.attributes.content ?? '')
+        }
+      }
       return {
         id: slugger.slug(text),
         text,
@@ -75,8 +56,6 @@ export function parseDoc(
     })
 
   const content = Markdoc.transform(ast, config)
-  let html = Markdoc.renderers.html(content) || ''
-  html = addHeadingIds(html)
 
-  return { html, frontmatter, toc }
+  return { content, frontmatter, toc }
 }
diff --git a/lib/toc-context.tsx b/lib/toc-context.tsx
deleted file mode 100644
index a047659..0000000
--- a/lib/toc-context.tsx
+++ /dev/null
@@ -1,46 +0,0 @@
-'use client'
-
-import React, { createContext, useContext, useState } from 'react'
-
-export interface TocItem {
-  id: string
-  text: string
-  level: 2 | 3
-}
-
-interface TocContextType {
-  toc: TocItem[]
-  setToc: (toc: TocItem[]) => void
-}
-
-const TocContext = createContext<TocContextType | undefined>(undefined)
-
-export function TocProvider({ children }: { children: React.ReactNode }) {
-  const [toc, setToc] = useState<TocItem[]>([])
-
-  return (
-    <TocContext.Provider value={{ toc, setToc }}>
-      {children}
-    </TocContext.Provider>
-  )
-}
-
-export function useToc() {
-  const context = useContext(TocContext)
-  if (!context) {
-    throw new Error('useToc must be used within TocProvider')
-  }
-  return context
-}
-
-/**
- * Tiny client component that sets the TOC when the page mounts.
- * Called by Server Components that have extracted the TOC from Markdoc.
- */
-export function TocSetter({ toc }: { toc: TocItem[] }) {
-  const { setToc } = useToc()
-  React.useEffect(() => {
-    setToc(toc)
-  }, [toc, setToc])
-  return null
-}
diff --git a/markdoc/schema.ts b/markdoc/schema.ts
new file mode 100644
index 0000000..2d92b9d
--- /dev/null
+++ b/markdoc/schema.ts
@@ -0,0 +1,120 @@
+import { Tag, type Config, type Node } from '@markdoc/markdoc'
+import GithubSlugger from 'github-slugger'
+
+/**
+ * The Markdoc schema: nodes and tags transform into named components that
+ * `Markdoc.renderers.react` resolves through the components map in
+ * `lib/markdoc-components.tsx`. Content stays data; interactivity lives in
+ * the components.
+ */
+
+function headingText(node: Node): string {
+  let text = ''
+  for (const child of node.walk()) {
+    if (child.type === 'text' || child.type === 'code') {
+      text += String(child.attributes.content ?? '')
+    }
+  }
+  return text
+}
+
+/**
+ * Builds a per-document config: the heading slugger is stateful, so each
+ * document gets a fresh one (ids match the TOC extraction in lib/markdoc.ts).
+ */
+export function buildConfig(): Config {
+  const slugger = new GithubSlugger()
+
+  return {
+    nodes: {
+      heading: {
+        children: ['inline'],
+        attributes: {
+          id: { type: String },
+          level: { type: Number, required: true },
+        },
+        transform(node, config) {
+          const attributes = node.transformAttributes(config)
+          const children = node.transformChildren(config)
+          const id = attributes.id ?? slugger.slug(headingText(node))
+          return new Tag(`h${node.attributes.level}`, { ...attributes, id }, children)
+        },
+      },
+      fence: {
+        render: 'CodeBlock',
+        attributes: {
+          content: { type: String },
+          language: { type: String },
+          filename: { type: String },
+          label: { type: String },
+          highlight: { type: String },
+        },
+        transform(node, config) {
+          const attributes = node.transformAttributes(config)
+          return new Tag('CodeBlock', {
+            ...attributes,
+            content: node.attributes.content,
+            language: node.attributes.language,
+          })
+        },
+      },
+    },
+    tags: {
+      callout: {
+        render: 'Callout',
+        children: ['paragraph', 'list', 'fence'],
+        attributes: {
+          type: {
+            type: String,
+            default: 'info',
+            matches: ['info', 'warning', 'danger', 'success'],
+          },
+          title: { type: String },
+        },
+      },
+      'card-group': {
+        render: 'CardGroup',
+        children: ['tag'],
+      },
+      card: {
+        render: 'Card',
+        children: ['paragraph', 'inline'],
+        attributes: {
+          title: { type: String, required: true },
+          href: { type: String },
+          icon: { type: String },
+        },
+      },
+      steps: {
+        render: 'Steps',
+        children: ['tag'],
+      },
+      step: {
+        render: 'Step',
+        children: ['paragraph', 'list', 'fence', 'tag', 'heading'],
+        attributes: {
+          title: { type: String, required: true },
+        },
+      },
+      'code-tabs': {
+        render: 'CodeTabs',
+        children: ['tag'],
+      },
+      'code-tab': {
+        render: 'CodeTab',
+        children: ['fence', 'paragraph'],
+        attributes: {
+          lang: { type: String, required: true },
+          label: { type: String },
+        },
+      },
+      verdict: {
+        render: 'VerdictChip',
+        selfClosing: true,
+        attributes: {
+          code: { type: String, required: true },
+        },
+      },
+    },
+  }
+}
diff --git a/package.json b/package.json
index 065bcd8..9b41c7f 100644
--- a/package.json
+++ b/package.json
@@ -7,14 +7,18 @@
     "build": "next build",
     "start": "next start",
     "lint": "next lint",
-    "type-check": "tsc --noEmit"
+    "type-check": "tsc --noEmit",
+    "check": "node scripts/check-docs.mjs",
+    "check:offline": "node scripts/check-docs.mjs --no-external"
   },
   "dependencies": {
     "@markdoc/markdoc": "^0.5.7",
     "github-slugger": "^2.0.0",
     "js-yaml": "^4.1.1",
+    "lucide-react": "^1.25.0",
     "next": "latest",
     "prism-react-renderer": "^2.4.1",
+    "prismjs": "^1.30.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
diff --git a/scripts/check-docs.mjs b/scripts/check-docs.mjs
new file mode 100644
index 0000000..a4987af
--- /dev/null
+++ b/scripts/check-docs.mjs
@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+/**
+ * The docs guardrails, encoded (the marketing-site lesson):
+ *   1. copy lint      — banned vocabulary and the stray old package name
+ *   2. verdict lint   — every verdict-shaped string must be one the source defines
+ *   3. link check     — every internal link resolves to a page; external links
+ *                       must not 404 (bot-blocks 403/429 are warnings)
+ *   4. frontmatter    — the required contract on every page
+ *
+ * Run: node scripts/check-docs.mjs [--no-external]
+ * Exits non-zero on any failure.
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+
+const ROOT = path.resolve(path.dirname(new URL(import.meta.url).pathname), '..')
+const CONTENT = path.join(ROOT, 'content/docs')
+const checkExternal = !process.argv.includes('--no-external')
+
+/** The exact verdict strings the gateway source defines — nothing else may appear. */
+const VERDICTS = new Set([
+  'allowed',
+  'outside-agent-scope',
+  'usage-cap-exceeded',
+  'metered-amount-required',
+  'usage-counter-rolled-back',
+  'agent-expired',
+  'revoked',
+  'stale',
+  'budget-required',
+  'proof-unauthentic',
+  'consistent',
+  'tampered-proof',
+  'cost-mismatch',
+  'budget-mismatch',
+  'dropped-call',
+])
+
+const BANNED = [
+  { re: /blockchain|decentraliz|self-sovereign/i, why: 'category vocabulary' },
+  { re: /\bKERI\b|\bCESR\b|did:keri/, why: 'protocol jargon' },
+  { re: /\bseamless|\bleverag|\bempower|\brobust\b/i, why: 'hype vocabulary' },
+  { re: /@auths\/mcp/, why: 'stray old package name (now @auths-dev/mcp)' },
+]
+
+const REQUIRED_FM = ['title', 'description', 'product', 'section', 'order', 'lastReviewed']
+
+function walk(dir) {
+  return fs.readdirSync(dir, { withFileTypes: true }).flatMap((e) => {
+    const p = path.join(dir, e.name)
+    return e.isDirectory() ? walk(p) : e.name.endsWith('.md') ? [p] : []
+  })
+}
+
+const files = walk(CONTENT)
+const slugs = new Set(
+  files.map((f) => {
+    const rel = path.relative(CONTENT, f).replace(/\.md$/, '')
+    const segs = rel.split(path.sep)
+    if (segs[segs.length - 1] === 'index') segs.pop()
+    return '/docs/' + segs.join('/')
+  })
+)
+slugs.add('/docs')
+
+const failures = []
+const warnings = []
+const externalLinks = new Map()
+
+for (const file of files) {
+  const rel = path.relative(ROOT, file)
+  const source = fs.readFileSync(file, 'utf8')
+
+  // 4. frontmatter contract
+  const fm = source.match(/^---\n([\s\S]*?)\n---/)
+  const fmText = fm ? fm[1] : ''
+  for (const field of REQUIRED_FM) {
+    if (!new RegExp(`^${field}:`, 'm').test(fmText)) {
+      failures.push(`${rel}: frontmatter missing "${field}"`)
+    }
+  }
+
+  // 1. copy lint
+  source.split('\n').forEach((line, i) => {
+    for (const { re, why } of BANNED) {
+      if (re.test(line)) failures.push(`${rel}:${i + 1}: ${why}: ${line.trim().slice(0, 80)}`)
+    }
+  })
+
+  // 2. verdict lint — verdict tags, and verdict-position tokens in output fences
+  for (const m of source.matchAll(/\{%\s*verdict\s+code="([^"]+)"/g)) {
+    if (!VERDICTS.has(m[1])) failures.push(`${rel}: unknown verdict "${m[1]}" in verdict tag`)
+  }
+  for (const m of source.matchAll(/→\s+([a-z][a-z-]+[a-z])/g)) {
+    const token = m[1]
+    if (/-/.test(token) && !VERDICTS.has(token)) {
+      failures.push(`${rel}: "${token}" reads as a verdict but the source defines no such string`)
+    }
+  }
+
+  // 3. links
+  for (const m of source.matchAll(/\[[^\]]*\]\(([^)\s]+)\)/g)) {
+    const href = m[1]
+    if (href.startsWith('#')) continue
+    if (href.startsWith('/')) {
+      const target = href.split('#')[0]
+      if (!slugs.has(target)) failures.push(`${rel}: internal link ${target} resolves to no page`)
+    } else if (href.startsWith('http')) {
+      if (!externalLinks.has(href)) externalLinks.set(href, [])
+      externalLinks.get(href).push(rel)
+    } else {
+      failures.push(`${rel}: relative link "${href}" — use root-relative /docs/... paths`)
+    }
+  }
+}
+
+if (checkExternal) {
+  for (const [href, where] of externalLinks) {
+    try {
+      let res = await fetch(href, { method: 'HEAD', redirect: 'follow' })
+      if (res.status === 405 || res.status === 403) {
+        res = await fetch(href, { method: 'GET', redirect: 'follow' })
+      }
+      if (res.status === 403 || res.status === 429) {
+        warnings.push(`external ${res.status} (bot-block?) ${href} (${where[0]})`)
+      } else if (!res.ok) {
+        failures.push(`external ${res.status} ${href} (${where[0]})`)
+      }
+    } catch (e) {
+      failures.push(`external unreachable ${href} (${where[0]}): ${e.message}`)
+    }
+  }
+}
+
+for (const w of warnings) console.log(`warn  ${w}`)
+if (failures.length > 0) {
+  for (const f of failures) console.error(`FAIL  ${f}`)
+  console.error(`\n${failures.length} failure(s) across ${files.length} pages`)
+  process.exit(1)
+}
+console.log(`docs check clean — ${files.length} pages, ${externalLinks.size} external links`)