From 9e9ecc10c4d973323052f4b8f3e02c0829be7416 Mon Sep 17 00:00:00 2001
From: bordumb <bordumbb@gmail.com>
Date: Fri, 17 Jul 2026 20:18:37 +0100
Subject: [PATCH 1/4] =?UTF-8?q?docs:=20the=20revamp=20foundation=20?=
 =?UTF-8?q?=E2=80=94=20React=20Markdoc,=20one=20route,=20frontmatter=20nav?=
 =?UTF-8?q?,=20the=20ledger?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The four architectural debts are paid: content renders through
Markdoc.renderers.react with a real tag schema (callout, cards, steps,
synced code-tabs, verdict chips — zero dangerouslySetInnerHTML for
content); every page is served by one [...slug] catch-all with metadata
from frontmatter; the nav derives from a validated frontmatter contract
(product/section/order/lastReviewed) so it cannot drift from disk; and
the URL-keyed CodeExamples rail, the hand-written page files, and the
hand-maintained nav array are gone.

Design language is the marketing ledger tuned for reading — paper/ink/
seal tokens with a dark variant, terminal-framed code panes with copy
buttons and verdict-colored transcript lines, Lucide icons (no emoji),
system typeface kept. Identity content is demoted under its own product
switch; the illustrative-only mcp-setup page is deleted ahead of the
real auths-mcp docs.

Auths-Id: did:keri:EB5cPHY0t-ejNC_rUzPS1dclTvd6kG-R9mQzjozCuGgd
Auths-Device: did:keri:EB5cPHY0t-ejNC_rUzPS1dclTvd6kG-R9mQzjozCuGgd
Auths-Anchor-Seq: 1
---
 app/docs/[...slug]/page.tsx              |  76 ++++
 app/docs/authentication/page.tsx         |  27 --
 app/docs/build-agents/page.tsx           |  24 --
 app/docs/concepts/[topic]/page.tsx       |  49 ---
 app/docs/installation/page.tsx           |  24 --
 app/docs/layout.tsx                      |  44 +--
 app/docs/mcp-setup/page.tsx              |  27 --
 app/docs/page.tsx                        |  70 +---
 app/docs/prove-provenance/page.tsx       |  24 --
 app/docs/quickstart/page.tsx             |  27 --
 app/docs/reference/[topic]/page.tsx      |  49 ---
 app/docs/sign-commits/page.tsx           |  34 --
 app/docs/team-identities/page.tsx        |  24 --
 app/globals.css                          | 176 +++++++--
 app/layout.tsx                           |  33 +-
 app/page.tsx                             | 151 +-------
 bun.lock                                 |   3 +
 components/CodeBlock.tsx                 |  26 --
 components/docs/CodeExamples.tsx         | 153 --------
 components/docs/DocWrapper.tsx           |  17 -
 components/docs/DocsLayout.tsx           |   1 -
 components/docs/DocsMobileDrawer.tsx     |  52 +--
 components/docs/DocsPrevNext.tsx         |  35 +-
 components/docs/DocsSidebar.tsx          |  94 +++--
 components/docs/DocsTopBar.tsx           |  70 ++--
 components/docs/OnThisPage.tsx           |   4 +-
 components/docs/ThemeToggle.tsx          |  38 ++
 components/markdoc/Callout.tsx           |  92 +++--
 components/markdoc/Cards.tsx             |  63 +++
 components/markdoc/CodeBlock.tsx         | 134 +++++++
 components/markdoc/CodeFence.tsx         |  12 -
 components/markdoc/CodeTabs.tsx          | 115 ++++++
 components/markdoc/Steps.tsx             |  23 ++
 components/markdoc/VerdictChip.tsx       |  22 ++
 components/markdoc/language-context.tsx  |  49 +++
 content/docs/authentication.md           |   4 +
 content/docs/build-agents.md             |   4 +
 content/docs/concepts/delegation.md      |   5 +
 content/docs/concepts/identity-model.md  |   5 +
 content/docs/concepts/key-rotation.md    |   5 +
 content/docs/installation.md             |   4 +
 content/docs/mcp-setup.md                | 103 -----
 content/docs/prove-provenance.md         |   4 +
 content/docs/quickstart.md               |   5 +
 content/docs/reference/cli.md            |   5 +
 content/docs/reference/github-actions.md |   5 +
 content/docs/sign-commits.md             |   4 +
 content/docs/team-identities.md          |   4 +
 docs/prompts/build.md                    | 473 +++++++++++++++++++++++
 lib/content.ts                           | 183 +++++++++
 lib/docs-navigation.ts                   | 114 ------
 lib/markdoc-components.tsx               |  26 ++
 lib/markdoc.ts                           |  77 ++--
 lib/toc-context.tsx                      |  46 ---
 markdoc/schema.ts                        | 120 ++++++
 package.json                             |   1 +
 56 files changed, 1778 insertions(+), 1281 deletions(-)
 create mode 100644 app/docs/[...slug]/page.tsx
 delete mode 100644 app/docs/authentication/page.tsx
 delete mode 100644 app/docs/build-agents/page.tsx
 delete mode 100644 app/docs/concepts/[topic]/page.tsx
 delete mode 100644 app/docs/installation/page.tsx
 delete mode 100644 app/docs/mcp-setup/page.tsx
 delete mode 100644 app/docs/prove-provenance/page.tsx
 delete mode 100644 app/docs/quickstart/page.tsx
 delete mode 100644 app/docs/reference/[topic]/page.tsx
 delete mode 100644 app/docs/sign-commits/page.tsx
 delete mode 100644 app/docs/team-identities/page.tsx
 delete mode 100644 components/CodeBlock.tsx
 delete mode 100644 components/docs/CodeExamples.tsx
 delete mode 100644 components/docs/DocWrapper.tsx
 delete mode 100644 components/docs/DocsLayout.tsx
 create mode 100644 components/docs/ThemeToggle.tsx
 create mode 100644 components/markdoc/Cards.tsx
 create mode 100644 components/markdoc/CodeBlock.tsx
 delete mode 100644 components/markdoc/CodeFence.tsx
 create mode 100644 components/markdoc/CodeTabs.tsx
 create mode 100644 components/markdoc/Steps.tsx
 create mode 100644 components/markdoc/VerdictChip.tsx
 create mode 100644 components/markdoc/language-context.tsx
 delete mode 100644 content/docs/mcp-setup.md
 create mode 100644 docs/prompts/build.md
 create mode 100644 lib/content.ts
 delete mode 100644 lib/docs-navigation.ts
 create mode 100644 lib/markdoc-components.tsx
 delete mode 100644 lib/toc-context.tsx
 create mode 100644 markdoc/schema.ts

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..c59e6a6 100644
--- a/app/globals.css
+++ b/app/globals.css
@@ -1,42 +1,110 @@
 @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 strong {
+  color: var(--ink);
+  font-weight: 600;
+}
+
 .prose ul,
 .prose ol {
   margin-bottom: 1rem;
-  margin-left: 1.5rem;
-  padding-left: 1rem;
+  padding-left: 1.5rem;
 }
 
 .prose li {
-  margin-bottom: 0.5rem;
+  margin-bottom: 0.4rem;
 }
 
 .prose ul li {
@@ -47,50 +115,84 @@ article.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::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..f65314c 100644
--- a/bun.lock
+++ b/bun.lock
@@ -8,6 +8,7 @@
         "@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",
         "react": "^19.0.0",
@@ -667,6 +668,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=="],
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..1ba1060
--- /dev/null
+++ b/components/markdoc/CodeBlock.tsx
@@ -0,0 +1,134 @@
+'use client'
+
+import { useCallback, useState } from 'react'
+import { Highlight, themes } from 'prism-react-renderer'
+
+/**
+ * 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'
+
+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 = 'bash', filename, label, highlight }: CodeBlockProps) {
+  const code = content.replace(/\n$/, '')
+  const isTerminal = language === 'output' || language === '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' : language)}
+        </span>
+        <span className="flex items-center gap-3">
+          {header && !isTerminal ? (
+            <span className="font-mono text-[11px]" style={{ color: '#6e6960' }}>
+              {language}
+            </span>
+          ) : null}
+          <CopyButton text={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={themes.gruvboxMaterialDark} code={code} language={language}>
+          {({ 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/content/docs/authentication.md b/content/docs/authentication.md
index 3ad89ff..ad2d053 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
diff --git a/content/docs/build-agents.md b/content/docs/build-agents.md
index 4a4b0b4..f84e960 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
diff --git a/content/docs/concepts/delegation.md b/content/docs/concepts/delegation.md
index 77f9ed0..0cfa548 100644
--- a/content/docs/concepts/delegation.md
+++ b/content/docs/concepts/delegation.md
@@ -1,6 +1,11 @@
 ---
 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.
diff --git a/content/docs/concepts/identity-model.md b/content/docs/concepts/identity-model.md
index 3a932a1..9da2eab 100644
--- a/content/docs/concepts/identity-model.md
+++ b/content/docs/concepts/identity-model.md
@@ -1,6 +1,11 @@
 ---
 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.
diff --git a/content/docs/concepts/key-rotation.md b/content/docs/concepts/key-rotation.md
index 1f4023d..3603395 100644
--- a/content/docs/concepts/key-rotation.md
+++ b/content/docs/concepts/key-rotation.md
@@ -1,6 +1,11 @@
 ---
 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.
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/prove-provenance.md b/content/docs/prove-provenance.md
index e3f7f4e..9258ced 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?
diff --git a/content/docs/quickstart.md b/content/docs/quickstart.md
index 59d93c8..17503fb 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.
diff --git a/content/docs/reference/cli.md b/content/docs/reference/cli.md
index 5bb4f36..7c4b863 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:
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..b525958 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)).
diff --git a/content/docs/team-identities.md b/content/docs/team-identities.md
index bda9fdc..d8da4b3 100644
--- a/content/docs/team-identities.md
+++ b/content/docs/team-identities.md
@@ -1,6 +1,10 @@
 ---
 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
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..f46de70 100644
--- a/package.json
+++ b/package.json
@@ -13,6 +13,7 @@
     "@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",
     "react": "^19.0.0",

From ead5cb9bfda26e19a4cb47f9b9b00fe0a215d17f Mon Sep 17 00:00:00 2001
From: bordumb <bordumbb@gmail.com>
Date: Fri, 17 Jul 2026 20:31:10 +0100
Subject: [PATCH 2/4] =?UTF-8?q?docs:=20the=20revamp=20=E2=80=94=20auths-mc?=
 =?UTF-8?q?p=20leads,=20on=20the=20ledger,=20with=20guardrails?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Ten auths-mcp pages take a reader from 'what is this' to a refusal they
caused themselves to real money behind a cap — every command reconciled
against the gateway's clap surface (the --rail/paid.call question is
resolved from source: the seatbelt keys off the paid.call scope), every
verdict string exact, danger callouts and --test-mode-first tabs on
every page that can touch a live rail. The demoted identity docs are
scrubbed to the same copy rules and their dead links fixed.

Guardrails wired as CI: copy lint, verdict lint against the
source-derived string set, internal + external link check (it already
caught a dead repo link), and the frontmatter contract — plus build-time
Markdoc validation. bun run check runs the lot.

Auths-Id: did:keri:EB5cPHY0t-ejNC_rUzPS1dclTvd6kG-R9mQzjozCuGgd
Auths-Device: did:keri:EB5cPHY0t-ejNC_rUzPS1dclTvd6kG-R9mQzjozCuGgd
Auths-Anchor-Seq: 1
---
 .auths/roots                                |   2 +
 .github/workflows/ci.yml                    |  34 +++++
 app/globals.css                             |  12 +-
 content/docs/authentication.md              |  12 +-
 content/docs/build-agents.md                |   6 +-
 content/docs/concepts/delegation.md         |   2 +-
 content/docs/concepts/identity-model.md     |   2 +-
 content/docs/concepts/key-rotation.md       |   2 +-
 content/docs/mcp/concepts/budgets.md        |  70 +++++++++
 content/docs/mcp/concepts/custody.md        |  47 +++++++
 content/docs/mcp/concepts/how-it-works.md   |  59 ++++++++
 content/docs/mcp/concepts/receipts.md       |  76 ++++++++++
 content/docs/mcp/guides/spend-real-money.md | 148 ++++++++++++++++++++
 content/docs/mcp/index.md                   |  52 +++++++
 content/docs/mcp/install.md                 |  78 +++++++++++
 content/docs/mcp/providers/stripe.md        |  91 ++++++++++++
 content/docs/mcp/providers/x402.md          | 108 ++++++++++++++
 content/docs/mcp/quickstart.md              |  69 +++++++++
 content/docs/prove-provenance.md            |   4 +-
 content/docs/quickstart.md                  |   7 +-
 content/docs/reference/cli.md               |   2 +-
 content/docs/sign-commits.md                |   6 +-
 content/docs/team-identities.md             |  20 +--
 package.json                                |   4 +-
 scripts/check-docs.mjs                      | 142 +++++++++++++++++++
 25 files changed, 1016 insertions(+), 39 deletions(-)
 create mode 100644 .auths/roots
 create mode 100644 .github/workflows/ci.yml
 create mode 100644 content/docs/mcp/concepts/budgets.md
 create mode 100644 content/docs/mcp/concepts/custody.md
 create mode 100644 content/docs/mcp/concepts/how-it-works.md
 create mode 100644 content/docs/mcp/concepts/receipts.md
 create mode 100644 content/docs/mcp/guides/spend-real-money.md
 create mode 100644 content/docs/mcp/index.md
 create mode 100644 content/docs/mcp/install.md
 create mode 100644 content/docs/mcp/providers/stripe.md
 create mode 100644 content/docs/mcp/providers/x402.md
 create mode 100644 content/docs/mcp/quickstart.md
 create mode 100644 scripts/check-docs.mjs

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/globals.css b/app/globals.css
index c59e6a6..8da13a5 100644
--- a/app/globals.css
+++ b/app/globals.css
@@ -97,25 +97,25 @@ article.prose {
   font-weight: 600;
 }
 
-.prose ul,
-.prose ol {
+.prose ul:not(:where(.not-prose, .not-prose *)),
+.prose ol:not(:where(.not-prose, .not-prose *)) {
   margin-bottom: 1rem;
   padding-left: 1.5rem;
 }
 
-.prose li {
+.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;
 }
 
-.prose li::marker {
+.prose li:not(:where(.not-prose, .not-prose *))::marker {
   color: var(--ink-faint);
 }
 
diff --git a/content/docs/authentication.md b/content/docs/authentication.md
index ad2d053..235ea40 100644
--- a/content/docs/authentication.md
+++ b/content/docs/authentication.md
@@ -13,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
 ```
 
@@ -28,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
 ```
 
@@ -42,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 f84e960..3a9624a 100644
--- a/content/docs/build-agents.md
+++ b/content/docs/build-agents.md
@@ -62,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
@@ -77,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
 
@@ -91,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 0cfa548..0f2576e 100644
--- a/content/docs/concepts/delegation.md
+++ b/content/docs/concepts/delegation.md
@@ -10,7 +10,7 @@ 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 9da2eab..6b9eee7 100644
--- a/content/docs/concepts/identity-model.md
+++ b/content/docs/concepts/identity-model.md
@@ -10,7 +10,7 @@ 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 3603395..646b5ba 100644
--- a/content/docs/concepts/key-rotation.md
+++ b/content/docs/concepts/key-rotation.md
@@ -10,7 +10,7 @@ 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/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..b1bd941
--- /dev/null
+++ b/content/docs/mcp/guides/spend-real-money.md
@@ -0,0 +1,148 @@
+---
+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)" %}
+```bash
+# to prove the cap WITHOUT real money first, opt into sandbox rails:
+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)" %}
+```bash
+# resolve + disclose the mode and the rails it names, then exit (no proxy, no charge)
+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_...     # a TEST-mode key from the dashboard's Test mode toggle
+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.
+
+{% 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...        # a FUNDED base-sepolia USDC testnet wallet
+export X402_FACILITATOR_URL=https://...     # a base-sepolia x402 facilitator
+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...      # a funded base MAINNET USDC wallet
+export X402_FACILITATOR_URL=https://...   # a mainnet facilitator
+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..7eb9c0f
--- /dev/null
+++ b/content/docs/mcp/providers/stripe.md
@@ -0,0 +1,91 @@
+---
+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_...     # a TEST-mode key from the dashboard's Test mode toggle
+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
+# run live, with the live key custodied by the gateway (the agent never sees it)
+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..806fe55
--- /dev/null
+++ b/content/docs/mcp/providers/x402.md
@@ -0,0 +1,108 @@
+---
+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
+
+{% code-tabs %}
+{% code-tab lang="test" label="Test mode (start here)" %}
+```bash
+export X402_WALLET_PRIVATE_KEY=0x...        # a FUNDED base-sepolia USDC testnet wallet
+export X402_FACILITATOR_URL=https://...     # a base-sepolia x402 facilitator
+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
+# settle live on base mainnet, with the wallet + facilitator custodied by the gateway
+export X402_WALLET_PRIVATE_KEY=0x...        # a FUNDED base MAINNET USDC wallet
+export X402_FACILITATOR_URL=https://...     # a mainnet x402 facilitator
+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 9258ced..6d56b9a 100644
--- a/content/docs/prove-provenance.md
+++ b/content/docs/prove-provenance.md
@@ -21,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
 
@@ -35,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 17503fb..638d3a9 100644
--- a/content/docs/quickstart.md
+++ b/content/docs/quickstart.md
@@ -49,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
 
@@ -78,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.
 ```
 
@@ -92,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 7c4b863..153af48 100644
--- a/content/docs/reference/cli.md
+++ b/content/docs/reference/cli.md
@@ -21,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/sign-commits.md b/content/docs/sign-commits.md
index b525958..a493d46 100644
--- a/content/docs/sign-commits.md
+++ b/content/docs/sign-commits.md
@@ -52,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 d8da4b3..bd2056e 100644
--- a/content/docs/team-identities.md
+++ b/content/docs/team-identities.md
@@ -9,7 +9,7 @@ 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
 
@@ -17,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.
@@ -46,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 \
@@ -56,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
 
@@ -78,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/package.json b/package.json
index f46de70..4a1f4d8 100644
--- a/package.json
+++ b/package.json
@@ -7,7 +7,9 @@
     "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",
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`)

From 161e8a6cbfe5094b316871d7851cb0d42a7376f3 Mon Sep 17 00:00:00 2001
From: bordumb <bordumbb@gmail.com>
Date: Fri, 17 Jul 2026 20:41:26 +0100
Subject: [PATCH 3/4] docs: runnable and readable are now structurally distinct
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

--show-mode transcripts render as output fences (the $-prefixed line is
the command, the disclosure is what it prints); every bash fence is
pure runnable lines, with the wallet/key guidance moved into the prose
above it — what you copy is exactly what you run.

Auths-Id: did:keri:EB5cPHY0t-ejNC_rUzPS1dclTvd6kG-R9mQzjozCuGgd
Auths-Device: did:keri:EB5cPHY0t-ejNC_rUzPS1dclTvd6kG-R9mQzjozCuGgd
Auths-Anchor-Seq: 1
---
 content/docs/mcp/guides/spend-real-money.md | 26 ++++++++++-----------
 content/docs/mcp/providers/stripe.md        |  3 +--
 content/docs/mcp/providers/x402.md          | 11 +++++----
 3 files changed, 19 insertions(+), 21 deletions(-)

diff --git a/content/docs/mcp/guides/spend-real-money.md b/content/docs/mcp/guides/spend-real-money.md
index b1bd941..30daf49 100644
--- a/content/docs/mcp/guides/spend-real-money.md
+++ b/content/docs/mcp/guides/spend-real-money.md
@@ -31,17 +31,15 @@ Before wrapping a live rail, **dry-run the disclosure** to confirm exactly which
 
 {% code-tabs %}
 {% code-tab lang="test" label="Test mode (start here)" %}
-```bash
-# to prove the cap WITHOUT real money first, opt into sandbox rails:
-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 …
+```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)" %}
-```bash
-# resolve + disclose the mode and the rails it names, then exit (no proxy, no charge)
-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 …
+```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 %}
@@ -59,7 +57,7 @@ Custody it on the gateway (the agent never sees it) and wrap the Stripe adapter
 {% code-tabs %}
 {% code-tab lang="test" label="Test mode (start here)" %}
 ```bash
-export STRIPE_API_KEY=sk_test_...     # a TEST-mode key from the dashboard's Test mode toggle
+export STRIPE_API_KEY=sk_test_...
 auths-mcp wrap \
   --test-mode \
   --scope paid.call --budget '$5' --ttl 30m \
@@ -82,7 +80,7 @@ The gateway discloses `mode=real`, then extracts `amount_captured` from each rea
 {% /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.
+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.
@@ -93,8 +91,8 @@ Custody both and wrap the x402 adapter (same `$5` cap — it's the **same** cros
 {% code-tabs %}
 {% code-tab lang="test" label="Test mode (start here)" %}
 ```bash
-export X402_WALLET_PRIVATE_KEY=0x...        # a FUNDED base-sepolia USDC testnet wallet
-export X402_FACILITATOR_URL=https://...     # a base-sepolia x402 facilitator
+export X402_WALLET_PRIVATE_KEY=0x...
+export X402_FACILITATOR_URL=https://...
 auths-mcp wrap \
   --test-mode \
   --scope paid.call --budget '$5' --ttl 30m \
@@ -105,8 +103,8 @@ auths-mcp wrap \
 {% /code-tab %}
 {% code-tab lang="live" label="Live (real money)" %}
 ```bash
-export X402_WALLET_PRIVATE_KEY=0x...      # a funded base MAINNET USDC wallet
-export X402_FACILITATOR_URL=https://...   # a mainnet facilitator
+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 \
diff --git a/content/docs/mcp/providers/stripe.md b/content/docs/mcp/providers/stripe.md
index 7eb9c0f..d2edd2e 100644
--- a/content/docs/mcp/providers/stripe.md
+++ b/content/docs/mcp/providers/stripe.md
@@ -25,7 +25,7 @@ Adapter paths in the commands below are relative to a checkout of [github.com/au
 {% code-tabs %}
 {% code-tab lang="test" label="Test mode (start here)" %}
 ```bash
-export STRIPE_API_KEY=sk_test_...     # a TEST-mode key from the dashboard's Test mode toggle
+export STRIPE_API_KEY=sk_test_...
 auths-mcp wrap \
   --test-mode \
   --scope paid.call --budget '$5' --ttl 30m \
@@ -35,7 +35,6 @@ auths-mcp wrap \
 {% /code-tab %}
 {% code-tab lang="live" label="Live (real money)" %}
 ```bash
-# run live, with the live key custodied by the gateway (the agent never sees it)
 export STRIPE_API_KEY=sk_live_...
 auths-mcp wrap \
   --scope paid.call --budget '$5' --ttl 30m \
diff --git a/content/docs/mcp/providers/x402.md b/content/docs/mcp/providers/x402.md
index 806fe55..b19b3f6 100644
--- a/content/docs/mcp/providers/x402.md
+++ b/content/docs/mcp/providers/x402.md
@@ -26,11 +26,13 @@ Adapter paths in the commands below are relative to a checkout of [github.com/au
 
 ## 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...        # a FUNDED base-sepolia USDC testnet wallet
-export X402_FACILITATOR_URL=https://...     # a base-sepolia x402 facilitator
+export X402_WALLET_PRIVATE_KEY=0x...
+export X402_FACILITATOR_URL=https://...
 auths-mcp wrap \
   --test-mode \
   --scope paid.call --budget '$5' --ttl 30m \
@@ -41,9 +43,8 @@ auths-mcp wrap \
 {% /code-tab %}
 {% code-tab lang="live" label="Live (real money)" %}
 ```bash
-# settle live on base mainnet, with the wallet + facilitator custodied by the gateway
-export X402_WALLET_PRIVATE_KEY=0x...        # a FUNDED base MAINNET USDC wallet
-export X402_FACILITATOR_URL=https://...     # a mainnet x402 facilitator
+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 \

From e9e63c9f204dd8d9e1d4dacc5e65304022f35535 Mon Sep 17 00:00:00 2001
From: bordumb <bordumbb@gmail.com>
Date: Fri, 17 Jul 2026 20:47:57 +0100
Subject: [PATCH 4/4] =?UTF-8?q?docs:=20real=20bash=20highlighting=20?=
 =?UTF-8?q?=E2=80=94=20the=20grammar=20was=20never=20registered?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

prism-react-renderer bundles no bash grammar, so every bash fence on
the site tokenized as one plain blob and the theme's comment color was
dead code. Register the grammar once (prismjs, via the library's
documented extension point), push comments firmly into the background
(dim italic vs bright commands), stop defaulting bare fences to bash
(ASCII diagrams are text), alias sh/shell/zsh/console onto bash, and
make transcript copy lift only the runnable $ lines, prompt stripped —
copy always equals what you run.

Auths-Id: did:keri:EB5cPHY0t-ejNC_rUzPS1dclTvd6kG-R9mQzjozCuGgd
Auths-Device: did:keri:EB5cPHY0t-ejNC_rUzPS1dclTvd6kG-R9mQzjozCuGgd
Auths-Anchor-Seq: 1
---
 bun.lock                         |  3 ++
 components/markdoc/CodeBlock.tsx | 52 +++++++++++++++++++++++++++-----
 components/markdoc/prism.ts      | 29 ++++++++++++++++++
 package.json                     |  1 +
 4 files changed, 78 insertions(+), 7 deletions(-)
 create mode 100644 components/markdoc/prism.ts

diff --git a/bun.lock b/bun.lock
index f65314c..2c05683 100644
--- a/bun.lock
+++ b/bun.lock
@@ -11,6 +11,7 @@
         "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",
       },
@@ -748,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/markdoc/CodeBlock.tsx b/components/markdoc/CodeBlock.tsx
index 1ba1060..e8e58f7 100644
--- a/components/markdoc/CodeBlock.tsx
+++ b/components/markdoc/CodeBlock.tsx
@@ -1,7 +1,8 @@
 'use client'
 
 import { useCallback, useState } from 'react'
-import { Highlight, themes } from 'prism-react-renderer'
+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
@@ -15,6 +16,42 @@ 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
@@ -78,9 +115,10 @@ export interface CodeBlockProps {
   highlight?: string
 }
 
-export function CodeBlock({ content, language = 'bash', filename, label, highlight }: CodeBlockProps) {
+export function CodeBlock({ content, language, filename, label, highlight }: CodeBlockProps) {
   const code = content.replace(/\n$/, '')
-  const isTerminal = language === 'output' || language === 'terminal'
+  const lang = LANGUAGE_ALIASES[language ?? ''] ?? language ?? 'text'
+  const isTerminal = lang === 'output' || lang === 'terminal'
   const header = filename ?? label
   const highlighted = parseHighlight(highlight)
 
@@ -88,15 +126,15 @@ export function CodeBlock({ content, language = 'bash', filename, label, highlig
     <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' : language)}
+          {header ?? (isTerminal ? 'terminal' : lang)}
         </span>
         <span className="flex items-center gap-3">
           {header && !isTerminal ? (
             <span className="font-mono text-[11px]" style={{ color: '#6e6960' }}>
-              {language}
+              {lang}
             </span>
           ) : null}
-          <CopyButton text={code} />
+          <CopyButton text={isTerminal ? commandsOnly(code) : code} />
         </span>
       </div>
 
@@ -107,7 +145,7 @@ export function CodeBlock({ content, language = 'bash', filename, label, highlig
           ))}
         </div>
       ) : (
-        <Highlight theme={themes.gruvboxMaterialDark} code={code} language={language}>
+        <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) => {
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/package.json b/package.json
index 4a1f4d8..9b41c7f 100644
--- a/package.json
+++ b/package.json
@@ -18,6 +18,7 @@
     "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"
   },