docs(site): promote the docs site restructure to main

.github/workflows/docs.yml

@@ -45,6 +45,7 @@ jobs:
         run: npm run build
         env:
           DOCS_BASE_PATH: /donkey-development-kit
+          GITHUB_TOKEN: ${{ github.token }}
       - name: Disable Jekyll so Pages serves Next's _next/ directory
         run: touch out/.nojekyll
       - uses: actions/configure-pages@v6

website/README.md

@@ -80,17 +80,43 @@ future custom domain serve at the root without the sub-path.
 
 ## Structure
 
+The sidebar is grouped into capability pillars by separators in
+`content/_meta.js`; page URLs are flat, so moving a page between pillars never
+breaks a link.
+
 ```
 content/
-  index.mdx                 Introduction — what the SDK is
-  quickstart.mdx            First governed request
-  feature-overview.mdx      The three pillars at a glance
-  frameworks/               Model access — one page per framework (Pillar 1)
-  tool-access.mdx           Pillar 2 (roadmap)
-  provisioning.mdx          Pillar 3 (roadmap)
-  concepts/                 Verification policy, governance, attribution
-  errors.mdx                Governed error taxonomy
-  reference/                Configuration, unsupported boundary
+  index.mdx, quickstart.mdx,
+  feature-overview.mdx               Get started
+  frameworks/                         Model access — one page per framework
+  errors, budget, identity,
+  hitl, policies                      Governance
+  telemetry                           Observability
+  simulator, testing, cli,
+  use-with-your-agent                 Developer tooling
+  tool-access/, a2a, publishing       Registry & catalog
+  scenarios/                          Scenarios
+  examples/                           Examples (from donkey-development-kit-demos)
+  roadmap.mdx                         Roadmap — rendered from data/roadmap.json
+  community/                          Team, Contribute
+  reference/                          Configuration, unsupported boundary
+```
+
+Capability status uses one vocabulary: `<Badge tone="live">Live</Badge>` for
+what is available now and `<Badge tone="roadmap">Roadmap</Badge>` for what is
+planned. Delivery detail (phases, milestones, issues) belongs on the Roadmap
+page only.
+
+## Roadmap data
+
+`data/roadmap.json` is a snapshot of the phase milestones and their issues,
+written by [`scripts/generate-roadmap.mjs`](scripts/generate-roadmap.mjs) from
+the GitHub API. `npm run build` refreshes it first (via `prebuild`); if the API
+is unreachable the committed snapshot is kept, so builds never depend on the
+network. Set `GITHUB_TOKEN` to avoid the unauthenticated rate limit.
+
+```bash
+npm run generate:roadmap
 ```
 
 ## Editing rules (inherited from the SDK — verification discipline)

website/app/layout.tsx

@@ -1,5 +1,5 @@
 import type { Metadata } from 'next'
-import { Inter } from 'next/font/google'
+import { Play } from 'next/font/google'
 import { Footer, Layout, Navbar } from 'nextra-theme-docs'
 import { Head } from 'nextra/components'
 import { getPageMap } from 'nextra/page-map'
@@ -8,17 +8,18 @@ import '../styles/globals.css'
 
 const SITE_NAME = 'Donkey Development Kit'
 const SITE_DESCRIPTION =
-  'An SDK for Agent Fabric — governed model access from your own agent framework, with budget, refusals, telemetry and simulation on one skeleton.'
+  'Governed by the gateway, understood by your code. An open-source SDK that brings Agent Fabric and Omni Gateway awareness into your agent framework.'
 
 // next/image's unoptimized loader does not prefix basePath for /public assets,
 // so reference the served copy under website/public/img/ with the base path
 // applied manually — same convention as components/index.tsx.
 const BASE_PATH = process.env.NEXT_PUBLIC_BASE_PATH ?? ''
 
-const inter = Inter({
+const play = Play({
   subsets: ['latin'],
+  weight: ['400', '700'],
   display: 'swap',
-  variable: '--font-inter',
+  variable: '--font-play',
 })
 
 // Replaces theme.config.tsx `head()`: the Metadata API builds the same
@@ -61,15 +62,38 @@ const navbar = (
       </span>
     }
     projectLink="https://github.com/Donkey-Development-Kit/donkey-development-kit"
-  />
+  >
+    <a
+      href="https://www.mulesoft.com/"
+      target="_blank"
+      rel="noreferrer"
+      className="af-nav-link"
+      aria-label="MuleSoft"
+      title="MuleSoft"
+    >
+      <img
+        src={`${BASE_PATH}/img/mulesoft-logo.png`}
+        alt="MuleSoft"
+        width={24}
+        height={24}
+        className="af-nav-logo"
+      />
+    </a>
+  </Navbar>
 )
 
 const footer = (
   <Footer>
     <span>
-      Donkey Development Kit — an SDK <em>for</em> Agent Fabric. “Agent Fabric”,
-      “Anypoint”, and “Omni Gateway” are Salesforce trademarks; this project is
-      descriptive (the trademark/support boundary).
+      Donkey Development Kit is an open-source, community-driven project
+      (Apache-2.0). It is not an official Salesforce or MuleSoft product and is
+      not supported by Salesforce. “Agent Fabric”, “Anypoint”, “MuleSoft” and
+      “Omni Gateway” are trademarks of Salesforce, Inc., used here only to
+      describe the platform DDK connects to. Learn more about the platform at{' '}
+      <a href="https://www.mulesoft.com/" target="_blank" rel="noreferrer">
+        mulesoft.com
+      </a>
+      .
     </span>
   </Footer>
 )
@@ -85,16 +109,16 @@ export default async function RootLayout({
       lang="en"
       dir="ltr"
       suppressHydrationWarning
-      className={`${inter.variable} ${inter.className}`}
+      className={`${play.variable} ${play.className}`}
     >
-      {/* Violet accent, close to the reference docs look (was theme.config `color`). */}
-      <Head color={{ hue: 262, saturation: 90 }} />
+      {/* #00B4FF accent, matching --af-accent in styles/globals.css. */}
+      <Head color={{ hue: 198, saturation: 100, lightness: { light: 50, dark: 50 } }} />
       <body>
         <Layout
           navbar={navbar}
           footer={footer}
           pageMap={pageMap}
-          docsRepositoryBase="https://github.com/Donkey-Development-Kit/donkey-development-kit/tree/main/website/content"
+          docsRepositoryBase="https://github.com/Donkey-Development-Kit/donkey-development-kit/tree/develop/website/content"
           sidebar={{ defaultMenuCollapseLevel: 1, toggleButton: true }}
           toc={{ backToTop: 'Scroll to top' }}
         >

website/components/adapter-error-taxonomy-note.mdx

@@ -8,10 +8,10 @@
 
   Intentional overrides that keep their own inline wording (documented, not silent):
     • langgraph        — prefixes a proxy-surface caveat before this sentence.
-    • adk, crewai      — "surface through LiteLLM's error path" (LiteLLM owns transport).
+    • adk, crewai      — "surface through ADK's `LiteLlm` model" / "CrewAI's LiteLLM layer".
     • agent-framework  — references the PolicyViolation hierarchy / middleware shape.
 */}
 
 See the [error taxonomy](/errors) for how proxy rejections surface as typed
-exceptions, and the [verification policy](/concepts/verification) page for
+exceptions, and the [verification ledger](https://github.com/Donkey-Development-Kit/donkey-development-kit/blob/develop/docs/verified-apis.md) for
 the current status of every constructor signature this adapter depends on.

website/components/index.tsx

@@ -1,6 +1,7 @@
 import React from 'react'
 import Link from 'next/link'
 import NextImage from 'next/image'
+import roadmap from '../data/roadmap.json'
 
 /* Presentation components for the docs pages.
  *
@@ -117,6 +118,23 @@ export function Card({
   )
 }
 
+export function Output({
+  children,
+  label = 'Expected output',
+  wrap = false,
+}: {
+  children: React.ReactNode
+  label?: string
+  wrap?: boolean
+}) {
+  return (
+    <div className={wrap ? 'af-output af-output-wrap' : 'af-output'}>
+      <div className="af-output-label">{label}</div>
+      {children}
+    </div>
+  )
+}
+
 export function Figure({
   src,
   alt,
@@ -147,3 +165,141 @@ export function Figure({
     </figure>
   )
 }
+
+/* ---------------------------------------------------------------- roadmap */
+
+type RoadmapIssue = {
+  number: number
+  title: string
+  state: string
+  url: string
+  epic: boolean
+}
+
+function IssueList({ issues }: { issues: RoadmapIssue[] }) {
+  return (
+    <ul className="af-issue-list">
+      {issues.map(issue => (
+        <li key={issue.number} data-state={issue.state}>
+          <span className="af-issue-state" aria-label={issue.state === 'open' ? 'Open' : 'Done'}>
+            {issue.state === 'open' ? '○' : '●'}
+          </span>
+          <a href={issue.url} target="_blank" rel="noopener noreferrer">
+            #{issue.number}
+          </a>{' '}
+          {issue.title}
+        </li>
+      ))}
+    </ul>
+  )
+}
+
+// Renders one milestone from data/roadmap.json (see scripts/generate-roadmap.mjs):
+// a status pill, a progress bar, and its issues split into open and done.
+export function RoadmapPhase({
+  milestone,
+  children,
+}: {
+  milestone: string
+  children?: React.ReactNode
+}) {
+  const m = roadmap.milestones.find(x => x.title.startsWith(milestone))
+  if (!m) return null
+  const total = m.open + m.closed
+  const pct = total ? Math.round((m.closed / total) * 100) : 0
+  const status =
+    m.open === 0 && total > 0
+      ? { label: 'Complete', tone: 'live' as Tone }
+      : m.closed > 0
+        ? { label: 'In progress', tone: 'accent' as Tone }
+        : { label: 'Planned', tone: 'roadmap' as Tone }
+  const open = m.issues.filter(i => i.state === 'open')
+  const done = m.issues.filter(i => i.state !== 'open')
+  return (
+    <section className="af-phase">
+      <div className="af-phase-head">
+        <a className="af-phase-title" href={m.url} target="_blank" rel="noopener noreferrer">
+          {m.title}
+        </a>
+        <Badge tone={status.tone}>{status.label}</Badge>
+      </div>
+      {children ? <div className="af-phase-body">{children}</div> : null}
+      <div className="af-progress" role="img" aria-label={`${pct}% complete`}>
+        <span style={{ width: `${pct}%` }} />
+      </div>
+      <p className="af-phase-stats">
+        {pct}% complete · {m.closed} done · {m.open} open
+      </p>
+      {open.length ? (
+        <details className="af-phase-issues">
+          <summary>Open issues ({open.length})</summary>
+          <IssueList issues={open} />
+        </details>
+      ) : null}
+      {done.length ? (
+        <details className="af-phase-issues">
+          <summary>Done ({done.length})</summary>
+          <IssueList issues={done} />
+        </details>
+      ) : null}
+    </section>
+  )
+}
+
+export function RoadmapUpdated() {
+  const date = new Date(roadmap.generatedAt)
+  return (
+    <span className="af-roadmap-updated">
+      Status synced from GitHub milestones on{' '}
+      {date.toLocaleDateString('en-GB', { day: 'numeric', month: 'long', year: 'numeric' })}.
+    </span>
+  )
+}
+
+/* ------------------------------------------------------------------- team */
+
+export function TeamGrid({ children }: { children: React.ReactNode }) {
+  return <div className="af-team-grid">{children}</div>
+}
+
+export function TeamMember({
+  name,
+  role,
+  linkedin,
+  photo,
+}: {
+  name: string
+  role: 'Creator' | 'Contributor'
+  linkedin: string
+  photo?: string
+}) {
+  const initials = name
+    .split(/[\s-]+/)
+    .filter(Boolean)
+    .slice(0, 2)
+    .map(part => part[0])
+    .join('')
+  return (
+    <a className="af-card af-team-member" href={linkedin} target="_blank" rel="noopener noreferrer">
+      {photo ? (
+        <img
+          className="af-team-avatar af-team-photo"
+          src={photo.startsWith('/') ? `${BASE_PATH}${photo}` : photo}
+          alt=""
+          width={64}
+          height={64}
+          loading="lazy"
+        />
+      ) : (
+        <span className="af-team-avatar" aria-hidden="true">
+          {initials}
+        </span>
+      )}
+      <span className="af-card-title">{name}</span>
+      <span className="af-card-badges">
+        <Badge tone={role === 'Creator' ? 'accent' : 'neutral'}>{role}</Badge>
+        <span className="af-team-link">LinkedIn</span>
+      </span>
+    </a>
+  )
+}