Docs revamp: auths-mcp leads, on the ledger, with guardrails

.auths/roots

@@ -0,0 +1,2 @@
+# Pinned by auths init — the trusted root for this identity.
+did:keri:EB5cPHY0t-ejNC_rUzPS1dclTvd6kG-R9mQzjozCuGgd

.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

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>
+  )
+}

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>
   )
 }