docs: make onboarding evaluator-first

[olliethedev]

Summary

• rewrites the documentation landing page around the approved BTST category, audience, plugin payload, incremental adoption, and ownership model
• adds an install-first Blog quickstart for an existing Next.js application, with the generated /pages/blog route as the observable local success condition and the live /p/blog demo kept distinct
• publishes one bounded framework, adapter, shared-runtime, and plugin-exception summary before preserving the existing manual reference
• moves optional AI-agent assistance after human onboarding, removes stale coming-soon inventory, and reorders top-level navigation around evaluator intent

Public stable quickstart provenance

Verified under Node 22 in a fresh shadcn-generated Next.js 16.2.6 application using public stable packages:

• @btst/codegen@0.2.0
• @btst/stack@3.0.0
• @btst/adapter-memory@2.2.3

The verification exposed and now documents two real prerequisites: the generated theme control imports shadcn dropdown-menu, and Codegen warns when the Sonner Toaster is absent. After installing dropdown-menu and Sonner, and supplying trusted local API/site origins, the generated application compiled, completed TypeScript/static generation, and returned HTTP 200 with the Blog title at /pages/blog.

Validation

• docs production build under Node 22.18.0: passed, including TypeScript and 56 static pages
• changed internal documentation links: all returned HTTP 200 from the production docs server
• changed public links, live demo, skill, and playground routes: all returned HTTP 200
• browser verification at desktop and 390px mobile: meaningful content, no framework overlay, no captured console errors
• sidebar quickstart, compatibility, and manual-installation anchors: resolved and scrolled to their targets
• public stable generated Next.js production build: passed
• public stable generated /pages/blog: HTTP 200 with Blog page title
• git diff --check: passed

Scope

The detailed manual framework, migration, auth, SEO, sitemap, API, and edge-case reference remains in place. This PR does not change product APIs, installers, the public /docs route/proxy, or future-domain behavior.

Closes #260

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

2 Skipped Deployments

Project	Deployment	Actions	Updated
better-stack-docs	Ignored		Sep 1, 2026 6:02pm UTC
better-stack-playground	Ignored		Sep 1, 2026 6:02pm UTC

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-01T18:01:39.626588Z	6147a17	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.