docs: add evaluator-first Blog, Form Builder, and OpenAPI pages

[olliethedev]

Closes #262

Why

First-time readers need to decide whether a plugin fits before they reach installation and API detail. This tracer slice turns Blog, Form Builder, and OpenAPI into evaluator-first examples for a complete feature, a workflow-heavy feature, and a backend-only feature.

What changed

• Adds a versioned PluginDecisionMeta contract for technical plugin truth: topology, separate relationship, Preview maturity, concrete payload, adopter prerequisites, dependencies/external services, maintained framework paths, and canonical docs/demo/source identifiers.
• Keeps the source of truth focused in plugin-decision.ts, then composes it into the existing PluginMeta inventory by key.
• Keeps audience, ownership prose, workflow wording, CTA composition, imagery, and presentation in the docs-owned representativeCopy seam.
• Adds reusable accessible evaluator headers, catalog cards, topology/status badges, fact blocks, and semantic workflow strips.
• Applies the pattern only to the plugin catalog and the Blog, Form Builder, and OpenAPI intros; existing installation and API reference detail remains intact.
• Uses the checked-in product-proof manifest for exact alt text and captions.
• Gives every detail page exactly two actions. Blog uses the real /p/blog result; Form and OpenAPI do not invent demos.
• Documents the intentional public metadata contract with AutoTypeTable.

Factual boundaries

• Blog: full-stack backend/client/routes/data/SSR/SEO proof; auth policy is conditional when protected authoring is enabled.
• Form Builder: editor → stored JSON Schema → adopter-owned FormRenderer route → validated/stored submission; isolated transactions are required and public read/submission policy is explicit when auth is enabled.
• OpenAPI: backend-only OpenAPI 3.1 generation; /open-api/schema is the fixed suffix beneath the configured API base path; title/version/reference path are optional overrides with documented defaults; Scalar remains optional and loads from jsDelivr only when used.
• Maintained integrations: Next.js 15+ App Router, React Router v7, and TanStack Start.

Validation

• pnpm --filter @btst/codegen test — 12 files / 176 tests passed
• pnpm --filter @btst/codegen typecheck
• pnpm --filter @btst/codegen build
• pnpm --filter btst-docs build — 56 static pages generated
• pnpm --filter btst-playground typecheck
• pnpm --filter btst-playground build
• pnpm check:product-proof — 8 assets / 206,291 bytes
• pnpm test:product-proof — 10 tests passed
• pnpm lint
• Full package pipeline pnpm test — codegen 176 tests and stack 1,043 tests passed
• Frozen lockfile install passed

Browser evidence

Verified catalog plus all three detail pages at 1440×900 and 390×844 in light and dark modes:

• proof images load with manifest-specific alt text and captions
• heading hierarchy and semantic workflow lists are correct
• exactly two evaluator/detail CTAs per representative page
• catalog actions resolve to detail pages; workflow/install anchors resolve with the /docs base path
• Blog live result returns HTTP 200
• all three canonical source URLs return HTTP 200
• no page errors; only the expected local Vercel Analytics log appears
• new evaluator sections have no horizontal overflow; the Blog page's existing 6px mobile overflow matches production and comes from unchanged downstream code blocks
• axe recheck cleared the new classification grouping; remaining findings are pre-existing docs chrome/code-theme issues

Review gate

Independent Standards and Spec reviews ran in parallel before commit. Initial findings were corrected, then the same reviewers performed focused re-reviews; both axes passed with no remaining findings.

Downstream manifest seam

The PR now checks in packages/cli/plugin-decisions.json so downstream marketing can consume core technical facts immediately after merge without waiting for an @btst/codegen release or making a runtime cross-site request.

• Schema: schemaVersion: 1, with Blog, Form Builder, and OpenAPI under plugins
• Source of truth: generated directly from PLUGIN_DECISIONS
• Stable raw path: https://raw.githubusercontent.com/better-stack-ai/better-stack/main/packages/cli/plugin-decisions.json (commit pinning documented)
• Future package path: @btst/codegen/plugin-decisions.json; confirmed present via npm pack --dry-run
• Regenerate: pnpm --filter @btst/codegen plugin-decisions:generate
• Drift check: pnpm --filter @btst/codegen plugin-decisions:check
• Test: semantic equality plus the real byte-level check command; CLI suite now passes 178 tests

The same independent Standards and Spec reviewers performed a focused read-only re-review of this addition and both passed with no findings.

[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 9:09pm UTC
better-stack-playground	Ignored		Sep 1, 2026 9:09pm 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-01T21:13:35.153254Z	7fa4b68	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: a521368cee

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