Move the landing page and docs into one Next.js site, ready for launch

[samkim]

Motivation

The docs site and the new landing page were two Vite entries under showcase/docs/app, with docs on hash routes (/docs/#/<slug>), no shared layout, and no hosting. This moves both into one Next.js app in a top-level site/, deployed on Vercel at openap.org. Docs get real paths, and the two pages share one root layout, which carries the theme and the cookieless analytics.

The landing page is also rewritten to tell the README's story, and the site is readied for a public launch.

Summary of changes

Site migration (site/)

• Next.js 16 App Router with @next/mdx. The 131 guides live at /docs/<slug>, prerendered, and an unknown slug returns 404.
• One root layout: next-themes for light and dark, and PostHog set to cookieless, pageviews only, production only, via i.authzed.com.
• Pagefind search, run after next build, with Cmd+K (Ctrl+K off Apple platforms).
• A prebuild check.ts validates the media manifest, the refs sidecars, every /docs link and anchor, and lede markup.
• showcase/docs and its Vite config are removed.

Go and repo changes that go with it

• clidocs and crddocs emit /docs/oap-* and /docs/crd-* links.
• mage docs:cli writes into site/content/docs. The CLI reference is regenerated.
• The web-bundle diff base and the auditgen default diff base are main, not master. Other master references are updated too.
• oap channel's help text no longer calls webhooks and schedules "future".

Landing page

• It follows the README's order:
  • the hero, with the four trust questions;
  • the credential-scope problem and the comparison table;
  • the six primitives;
  • controls in six areas;
  • Agent Builder;
  • everything else;
  • OWASP coverage;
  • defense in depth.
• Claims are checked against the code. Among the fixes:
  • "Nothing phones home" is replaced, since SpiceDB's default telemetry stays on.
  • ASI07 is re-rated Partial.
  • Revocation is "at the next check".
  • Plan gating is opt-in.
• Includes a shared site footer with the license and the AuthZed credit, and a proper OWASP CC BY-SA 4.0 attribution.

Docs content
Reconciled with the code and the primary message:

• rate limits are opt-in;
• the prompt-injection classifier ships;
• prompt delimiters are an aid, not the boundary;
• oap install examples pass --builder-starters;
• only GKE provisions artifact storage;
• the correct quickstart example path;
• the docs entry page leads with the primary message.

Install prerequisites are listed, each linking to the tool's own install page. README's Desktop line now says it's for trying OAP and demos.

Launch readiness

• Canonical URLs, Open Graph and Twitter tags, a generated share card, robots.txt, a sitemap, a favicon, an apple-touch-icon, and a styled 404 page.
• The docs have a top bar and menu under 900px.
• Accessibility:
  • Links inside running text are underlined.
  • The lightbox gets modal focus handling.
  • The landing page has a <main> landmark.
  • Search results are announced to screen readers.
• Search failures are logged and shown to the reader.
• Security headers, plus a production CSP.

Alternatives considered

• Docs frameworks (Fumadocs, Nextra, Docusaurus, Starlight, hosted options): each would have meant converting the guides' ESM meta exports or fighting a theme. Plain Next.js with @next/mdx reads the metadata natively.
• next-mdx-remote, as authzed/web uses: it is archived and can't read ESM exports.
• Keeping hash routes with a redirect: nothing was deployed, so no external link depends on them.

Provenance

• Author (person, or model and version): Claude Opus 5.5 (1M context), directed by Sam Kim
• Harness or tooling, with version: Claude Code 2.1.285
• Person who read the diff: not yet; the diff needs a human read before merge (see below)

Ship gate

• mage test:unit
• mage test:integration
• mage test:e2e

Results:

mage test:unit         exit 0   554 packages ok, 0 failed   (15:45 to 15:54)
mage test:integration  exit 0   494 packages ok, 0 failed   (15:54 to 16:06)
mage test:e2e          exit 0    64 packages ok, 0 failed   (16:06 to 16:17)
  ok  test/e2e/bronzethread  635.379s
  ok  test/e2e/steelthread    25.761s

The branch is 2 commits behind main (#5, #8). Neither touches a file this branch changes, so the suites ran on the branch as-is.

Regeneration

• Changed a +kubebuilder:rbac marker or a CRD-shaping field in pkg/apis/v1alpha1/*_types.go → ran mage gen:api and mage manifests (not applicable)
• Edited anything under config/** → ran mage manifests (not applicable)
• Changed a cobra command or a CRD schema → ran mage docs:cli / mage docs:crd
• Ran mage fmt:all until mage fmt:check is clean

Coverage

• This adds user-visible behavior, and a bronzethread bundle exercises it, or it does not add user-visible behavior. The user-visible change is the website; no platform or agent behavior changes, so no bundle applies.
• This touches authorization, the SpiceDB schema, or the approver model, and mage test:integration + mage test:e2e are green, or it touches none of those. It touches none of them.

Before requesting review

• The PR holds a single change. If it has several parts, they cannot land independently (explain why below).
• A person has read every line of the diff, or the note below explains how to check the parts they did not.

The parts are coupled: the generators' new link format only resolves on the new site, the landing and docs share one layout and footer, and the launch fixes edit files the migration creates.

Reading the diff: most of the line count is the 131 guides moving from showcase/docs/guides to site/content/docs (history-preserving renames), their #/ links rewritten to /docs/, and the regenerated oap-* and crd-* reference pages. The hand-written code is site/app, site/components, site/lib, site/scripts, site/next.config.mjs, plus the Go files under pkg/gen, magefiles and cmd/oap/internal/channelcmd. The docs prose edits from the launch review are in commits af268a8 and 3b4e74f.

Before deploying (outside this repo)

• Vercel project: root directory site, with "Include files outside the root directory" on (the brand SVGs come from docs/assets/brand). Confirm the install step can run pnpm@12.3.4.
• Set NEXT_PUBLIC_POSTHOG_KEY for Production. Enable cookieless server hash mode in PostHog.
• Point openap.org at the project, and confirm preview deploys send noindex.
• Make the repository public: the GitHub, Source and license links depend on it.

🤖 Generated with Claude Code

[josephschorr]

LGTM