docs: rebuild README evaluator journey

[olliethedev]

Closes #261

Why

The previous README led with implementation detail before a first-time visitor could tell what BTST is, what a plugin installs, where it fits, or what they keep. This rewrite turns the README into an evaluator journey while keeping detailed setup in canonical docs.

What changed

• leads with the approved BTST category, audience, payload, ownership contract, and Blog-first CTA order
• uses the product-proof banner, ownership diagram, Blog result, and code-to-result assets from [visuals] Create the reusable BTST product-proof asset kit #259 without changing their manifest or source files
• adds a factual UI kit / starter application / hosted feature service comparison
• provides one public, version-pinned Blog quickstart with /pages/blog as the visible success condition
• pairs stable-v3 backend and client Blog registration with the resulting route
• lists only released capabilities with honest full-stack, one-sided, dependency, and companion topology
• qualifies the maintained framework matrix, published adapter limits, memory-adapter scope, and shadcn ejection paths
• replaces the broken Examples destination with canonical docs, playground, development, API, and migration links

Clean-project provenance

Verified on Node.js 22.23.2 in a fresh Next.js 16.2.6 App Router project using public packages:

pnpm dlx shadcn@4.19.1 init --base radix --preset nova --css-variables
pnpm dlx shadcn@4.19.1 add button dropdown-menu sonner --yes
pnpm dlx @btst/codegen@0.2.0 init \
  --framework nextjs \
  --adapter memory \
  --plugins blog
pnpm build
pnpm start

Observed result: the generated production app loaded /pages/blog, rendered the Blog Posts heading and empty-state UI, had no horizontal overflow, and produced no browser console/page errors.

Two clean-room checks narrowed the documented path:

• npm's resolver selected a Zod 3 path through @hookform/resolvers and rejected better-call's Zod 4 peer requirement; this README therefore documents the verified pnpm path rather than claiming npm parity.
• shadcn 4's default Base UI configuration failed the generated DropdownMenuTrigger asChild build contract; the README now gives the exact pinned Radix initialization used by the passing build.

These findings do not change package or generator behavior in this PR.

Verification

• pnpm check:product-proof — 8 assets, 206,291 bytes
• pnpm test:product-proof — 10/10 passing
• pnpm lint — canonical DX guard and Biome pass (Node.js 22.23.2)
• git diff --check
• local file/image targets checked; canonical website/docs/demo/playground links returned HTTP 200; npm package/version existence checked from the registry
• GitHub GFM API render checked: all four proof assets and all three tables render; no raw fence leakage
• published GitHub branch inspected at 1440×1000 and 390×844 in light and dark modes: no horizontal overflow, no broken images, CTA links remain legible, and all proof assets resolve at their intended responsive width
• independent Standards review: pass after clarifying Radix setup and ejection variants
• independent Spec review: pass against every [github] Rebuild the README as a first-time evaluator journey #261 acceptance criterion and the approved positioning contract

Scope and future context

• README-only: no product, docs-site, package, lockfile, manifest, or asset changes
• keeps this PR free of ROI, roadmap, maturity, universal-support, unsupported framework, and hosted Better Stack product claims
• detailed production setup remains canonical in the installation, adapter, architecture, API, and migration docs
• the npm resolver and Base UI incompatibilities above may merit separate engineering investigation; they are recorded here so future maintainers do not broaden the quickstart without re-verifying it

[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 8:00pm UTC
better-stack-playground	Ignored		Sep 1, 2026 8:00pm 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-01T20:09:10.610115Z	33eac35	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.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 33eac3587c

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Include next-themes in the quickstart prerequisites

For a clean existing Next.js app where shadcn/ui was not previously configured, these commands do not install next-themes, but the generator always emits components/mode-toggle.tsx, which imports useTheme from that package (packages/cli/src/templates/shared/components/mode-toggle.tsx:4). The generator's dependency installer also omits it (packages/cli/src/utils/package-installer.ts:46-53), so following the advertised path leaves the generated project failing typechecking/production builds with Cannot find module 'next-themes'; add it to this prerequisite install sequence or have codegen install it.

Useful? React with 👍 / 👎.