Phase 1b: Build new mcpaql.com homepage in staging (homepage redesign)

[mickdarling]

Part of #32 (Epic: MCPAQL 2026 product launch). Phase 1b deliverable.

What

Build the new mcpaql.com homepage and supporting pages in a staging deployment of this repo. Production mcpaql.com continues to redirect to .org throughout this phase; the new .com site doesn't go live to users until Phase 1c.

Applies the strategy brief's five fixes plus the cross-link discipline rules from the epic.

The five fixes

• Fix 1 — Code above the fold. Side-by-side before/after JSON: discrete-tools (~30 tools, ~30k tokens) on the left, CRUDE (5 endpoints, ~2.6k tokens) on the right. Reference layout: graphql.org hero.
• Fix 2 — Install line in hero. Copyable npx @mcpaql/adapter-generator <your-mcp-server> (or hosted-demo curl, whichever is shippable first). Reference: trpc.io quickstart block.
• Fix 3 — Architecture diagram. Lift the graph LR Mermaid from MCPAQL/ORG-README.md — don't redraw. Reference: modelcontextprotocol.io architecture page.
• Fix 4 — Token bar chart. Visualize 29,600 → 4,500 → 1,100. Mermaid xychart-beta or static SVG. Reference: bun.sh benchmarks, fastify.dev/benchmarks/.
• Fix 5 — Playground CTA. "Try the Studio →" button linking to studio.mcpaql.com (lands in Phase 2a). Until the studio is live, the button can route to a /studio-coming-soon placeholder page.

Cross-link discipline (mandatory, per epic)

• Topbar cross-link chip — top-right of nav on every page: "← Read the Spec" linking to mcpaql.org. Visually distinct (border + accent). One click, direct destination.
• Sub-hero clarifier band on the homepage: one paragraph explaining the .com / .org split for first-time visitors
• Footer cross-link — third safety net to .org

Mirror this on .org once the homepage launches (tracked separately under Phase 1c).

Voice / framing

• Drop all RFC-2119 normative framing from .com pages (it stays on .org where it belongs)
• Confident developer-product voice (upper-right quadrant per the strategy framework). Models: graphql.org for content shape, trpc.io for visual aesthetic, grpc.io for staffing realism.
• Cite the GitHub MCP case study at mcpaql.org/research/github-mcp-case-study/ (lands in Phase 1a — blocking dependency)

CI gates

• Lighthouse green
• HTMLHint clean
• markdownlint clean
• lychee link-check passes
• No regressions in npm run generate:repo-docs:check

Phase

1b (weeks 2-3). All work happens in staging. Production .com continues redirecting to .org until Phase 1c lifts the root redirect.