[Epic] Migrate ARCP website from Nuxt → Astro + Markdoc

[nficano]

Migrate the ARCP website from Nuxt → Astro + Markdoc

Rebuild agentruntimecontrolprotocol/www
(Nuxt 4) as an Astro + Markdoc site in this repo, preserving the "Inkwell" design
system, fonts, dark/light themes, and all URLs. Built in parallel with www; the
domain cuts over after visual + route parity.

Canonical spec: docs/markdoc-migration.md
— every phase issue is derived from it.

Target stack

Astro 5 (output: 'static') · @astrojs/markdoc · Tailwind v4 (@tailwindcss/vite) ·
Shiki (arcp-light / arcp-dark) · @astrojs/sitemap · Fontsource (IBM Plex Mono +
Newsreader) · Vercel Git integration.

Phases

• Step 0 — Scaffold the Astro + Markdoc project #2 — Step 0 · Scaffold the Astro + Markdoc project
• Step 1 — Port the Inkwell design system (palette, fonts, dark/light) #3 — Step 1 · Port the Inkwell design system (palette, fonts, dark/light)
• Step 2 — Markdoc + Shiki + content collections #4 — Step 2 · Markdoc + Shiki + content collections
• Step 3 — Routing, sidebar nav & TOC #5 — Step 3 · Routing, sidebar nav & TOC
• Step 4 — Port the docs-sync pipeline #6 — Step 4 · Port the docs-sync pipeline
• Step 5 — Diagram <img> HTML passthrough (Markdoc tag) #7 — Step 5 · Diagram <img> HTML passthrough (Markdoc tag)
• Step 6 — Rebuild the app shell + home page #8 — Step 6 · Rebuild the app shell + home page
• Step 7 — SEO, OG images, sitemap & redirects #9 — Step 7 · SEO, OG images, sitemap & redirects
• Step 8 — Deploy on Vercel (Git integration) #10 — Step 8 · Deploy on Vercel (Git integration)
• Step 9 — Verify: regression gate before cutover #11 — Step 9 · Verify: regression gate before cutover

Rough order: #2 (scaffold) then #3 (design tokens) unblock everything. #6 (sync)
can run in parallel and feeds #4/#5 (content/routing) and #7 (diagrams). #8 (shell/home),
#9 (SEO/OG), #10 (deploy) follow; #11 (verify) is the final gate before cutover.

Hard constraints (apply to every phase)

1. Inkwell design system is sacred — palette, fonts, weights, dark/light values, and
   Shiki token colors must match www exactly.
2. Preserve all URLs — /<lang>/<page> (no trailing slash), /spec/..., /. Thousands
   of synced internal links are pre-rewritten to these paths.
3. Preserve the sync-docs.mjs link + diagram rewriting — load-bearing and error-prone.
4. Drop FontAwesome (installed but 100% unused; also removes the FA-Pro npm token).
5. No search (out of scope; future Pagefind follow-up).

Reference

• Source of truth for look/behavior/sync: ../www (agentruntimecontrolprotocol/www).
• Docs are synced at build from the sibling *-sdk + spec repos (~2,286 files).