Migrate to @btst/stack 3.0.0 (new plugin authoring patterns + example app setup)

[olliethedev]

Context

@btst/stack 3.0.0 is the breaking release landing the Refine-inspired core simplification (upstream: better-stack-ai/better-stack#127, #128, #129, #130, #131, #132, #133, #136, #137).

This migration assumes 3.0.0 is published to npm and all upstream phases are finished. One migration PR against the final API — no 2.x compat.

This repo is the template third-party plugin authors start from, so the bar is higher than "it builds": every file should demonstrate the canonical 3.0.0 pattern, because whatever this template does will be copied. The 2.x boilerplate this template currently teaches (hand-written query keys, error helpers, per-plugin navigation overrides, manual page-handler glue) no longer exists upstream.

Migration checklist

packages/plugin — the todo plugin (the actual teaching material)

• Bump @btst/stack to >=3.0.0 (catalog) and any @btst/yar references to >=1.3.0
• Routes: migrate to defineRoute/defineRoutes; parameterized route pageComponents overrides receive route context ({ params }) as props
• Data layer: replace hand-written query keys / hooks / error helpers with createResource; public hooks (useTodos, etc.) become one-liners over the factory
• Forms: the add-todo page uses the resource useForm (create lifecycle, invalidation, successMessage, redirect), demonstrating field-level StackError mapping with a server-side Zod validation example
• Notifications: useNotify() instead of direct toast imports
• i18n: all UI strings via t("todos.…", "Default") so the template demonstrates translatable plugins
• Auth: demonstrate <CanAccess> and/or a route permission declaration on one route (e.g. gate deleting todos) so plugin authors see the pattern
• List state: todos list filters/pagination (if any) via useListState
• Overrides: overrides.ts contains only genuinely plugin-specific overrides — no Link/navigate/refresh/apiBaseURL fields (removed upstream)

examples/nextjs — the consumer example

• Catch-all page via createNextPage; API route via toNextRouteHandlers (entry factories) — each file ≤5 lines
• Layout uses top-level providers on StackProvider: router={nextRouter()}, api, and (where demonstrated) auth/notify/i18n — no per-plugin navigation wiring
• Remove all usage of deleted 2.x surfaces (onBefore*PageRendered callbacks, manual identity props) — verify by grep

Repo docs

• README / authoring guide rewritten around the new primitives (createResource, defineRoutes, useForm, providers) so new plugin authors never see 2.x patterns
• E2E updated to the new setup

Acceptance criteria

• Builds, type-checks, and E2E passes against published @btst/stack 3.0.0
• Zero references to removed 2.x surfaces (grep-verified)
• The template demonstrates each major 3.0.0 primitive at least once: defineRoutes, createResource, useForm with field errors, useNotify, t(), <CanAccess>, entry factories, top-level providers
• A plugin author following only this template produces an idiomatic 3.0.0 plugin