feat: playground

.agents/skills/btst-build-config/SKILL.md

@@ -59,27 +59,27 @@ The `postbuild.cjs` script auto-discovers and copies them — no manual registra
 }
 ```
 
-## Updating all three example apps
+## Updating all three codegen projects
 
 When adding a new plugin or changing plugin config, update ALL three:
 
-**Next.js** (`examples/nextjs/`)
-- `lib/stack.tsx` — backend plugin registration
+**Next.js** (`codegen-projects/nextjs/`)
+- `lib/stack.ts` — backend plugin registration
 - `lib/stack-client.tsx` — client plugin registration
-- `app/pages/[[...all]]/layout.tsx` — override configuration
+- `app/pages/layout.tsx` — override configuration
 - `app/globals.css` — `@import "@btst/stack/plugins/{name}/css";`
 
-**React Router** (`examples/react-router/`)
-- `app/lib/stack.tsx`
+**React Router** (`codegen-projects/react-router/`)
+- `app/lib/stack.ts`
 - `app/lib/stack-client.tsx`
 - `app/routes/pages/_layout.tsx`
 - `app/app.css`
 
-**TanStack** (`examples/tanstack/`)
-- `src/lib/stack.tsx`
+**TanStack** (`codegen-projects/tanstack/`)
+- `src/lib/stack.ts`
 - `src/lib/stack-client.tsx`
 - `src/routes/pages/route.tsx`
-- `src/styles/app.css`
+- `src/styles.css`
 
 ### Override type registration (in each layout)
 
@@ -119,6 +119,6 @@ pnpm turbo clean && pnpm build
 ## Gotchas
 
 - **Missing `typesVersions`** — always add alongside `exports`; TypeScript won't resolve the new path otherwise.
-- **Build cache** — run `pnpm turbo clean` if changes aren't reflected in examples after `pnpm build`.
+- **Build cache** — run `pnpm turbo clean` if changes aren't reflected in codegen projects after `pnpm build`.
 - **CSS not loading** — ensure `"./plugins/{name}/css"` entry exists in `package.json` exports; `postbuild.cjs` handles the rest automatically.
 - **`@workspace/ui` sub-path components** — if a new component imports from a directory (not a single file), add it to `EXTERNAL_REGISTRY_COMPONENTS` in `build-registry.ts`.

.agents/skills/btst-client-plugin-dev/SKILL.md

@@ -11,13 +11,30 @@ description: Patterns for writing BTST client plugins inside the monorepo, inclu
 src/plugins/{name}/
   client/
     plugin.tsx           ← defineClientPlugin entry
+    hooks.ts             ← "use client" React hooks only
     components/
       pages/
         my-page.tsx      ← wrapper: ComposedRoute + lazy import
         my-page.internal.tsx  ← actual UI: useSuspenseQuery
   query-keys.ts          ← React Query key factory
 ```
 
+## Server/client module boundary
+
+`client/plugin.tsx` must stay import-safe on the server. Next.js (including SSG build)
+can execute `createStackClient()` on the server, which calls each `*ClientPlugin()`
+factory. If that module is marked `"use client"` or imports a client-only module, build
+can fail with "Attempted to call ... from the server".
+
+Rules:
+
+- Do **not** add `"use client"` to `client/plugin.tsx`.
+- Keep `client/plugin.tsx` free of React hooks (`useState`, `useEffect`, etc.).
+- Put hook utilities in a separate client-only module (`client/hooks.ts`) with
+  `"use client"`, and re-export them from `client/index.ts`.
+- UI components can remain client components as needed; only the plugin factory entry
+  must stay server-import-safe.
+
 ## Route anatomy
 
 Each route returns exactly three things:
@@ -110,6 +127,7 @@ type PluginOverrides = {
 - **Next.js Link href undefined** — use `href={href || "#"}` pattern.
 - **Suspense errors not caught** — add `if (error && !isFetching) throw error` in every suspense hook.
 - **Missing ComposedRoute wrapper** — without it, errors crash the entire app instead of hitting ErrorBoundary.
+- **Client directive on `client/plugin.tsx`** — can break SSG/SSR when plugin factories are invoked server-side.
 
 ## Full code patterns
 

.agents/skills/btst-testing/SKILL.md

@@ -67,41 +67,76 @@ Use `vi.mock` for external modules that don't exist in the test environment (e.g
 
 ## E2E tests (Playwright)
 
+### E2E setup
+
+Playwright configuration lives in `e2e/playwright.codegen.config.ts`, command `pnpm codegen:e2e`. It starts the `codegen-projects/` apps (ports 3006–3008) and tests the CLI codegen output — accurately reflecting what a real `btst init` user gets.
+
+The codegen projects are built from scratch via `scripts/codegen/setup-*.sh`.
+
 ### Location and naming
 
 Tests live in `e2e/tests/`. Naming convention: `smoke.{feature}.spec.ts`
 
 Examples: `smoke.chat.spec.ts`, `smoke.blog.spec.ts`
 
+### Setting up codegen projects (required before running codegen E2E)
+
+The `codegen-projects/` directory is **not committed** — build it from scratch:
+
+```bash
+# Set up a specific framework
+bash scripts/codegen/setup-nextjs.sh
+bash scripts/codegen/setup-react-router.sh
+bash scripts/codegen/setup-tanstack.sh
+
+# Or set up all frameworks at once
+bash scripts/codegen/setup.sh
+
+# Cleanup when you want a fresh start
+bash scripts/codegen/cleanup.sh nextjs
+bash scripts/codegen/cleanup.sh react-router
+bash scripts/codegen/cleanup.sh tanstack
+```
+
+See `scripts/codegen/README.md` for full details on the E2E overlay file system and update workflow.
+
 ### Run commands
 
 ```bash
-# All frameworks (starts all 3 servers)
 cd e2e
-export $(cat ../examples/nextjs/.env | xargs)
-pnpm e2e:smoke
 
-# Single framework only
-pnpm e2e:smoke:nextjs
-pnpm e2e:smoke:tanstack
-pnpm e2e:smoke:react-router
+# Run all codegen E2E tests
+pnpm codegen:e2e
 
-# Specific test file
-pnpm e2e:smoke -- tests/smoke.chat.spec.ts
+# Target a specific framework
+pnpm codegen:e2e:nextjs
+pnpm codegen:e2e:tanstack
+pnpm codegen:e2e:react-router
 
-# Specific Playwright project
-pnpm e2e:smoke -- --project="nextjs:memory"
+# Specific test file
+pnpm codegen:e2e:nextjs -- tests/smoke.blog.spec.ts
 ```
 
 ### Playwright projects and ports
 
 | Project | Port |
 |---|---|
-| `nextjs:memory` | 3003 |
-| `tanstack:memory` | 3004 |
-| `react-router:memory` | 3005 |
+| `nextjs:codegen` | 3006 |
+| `tanstack:codegen` | 3007 |
+| `react-router:codegen` | 3008 |
+
+Set `BTST_FRAMEWORK=nextjs|tanstack|react-router` to start only one server.
+
+### In-memory state between test runs
 
-Defined in `playwright.config.ts`. By default all three servers start. Set `BTST_FRAMEWORK=nextjs|tanstack|react-router` to start only one — or use the per-framework scripts above. CI uses a matrix to run each in a separate parallel job.
+The in-memory adapter keeps data alive for the lifetime of the server process. If you re-run tests against an already-running server, earlier test data will still be present and can cause failures.
+
+To reset: kill the server and let `reuseExistingServer: true` restart it, or rebuild with `start:e2e`:
+
+```bash
+kill $(lsof -ti:3006)
+pnpm -F nextjs run start:e2e   # rebuilds .next and starts fresh
+```
 
 ### API key guard pattern
 
@@ -122,7 +157,7 @@ test.beforeEach(async () => {
 ### Environment variables
 
 ```bash
-export $(cat ../examples/nextjs/.env | xargs)
+# Env is loaded from codegen-projects/nextjs/.env automatically by playwright.codegen.config.ts
 ```
 
-For CI, the workflow uses a matrix — each framework job sets `BTST_FRAMEWORK` and only starts its own server.
+For CI, the codegen workflow (`.github/workflows/codegen-e2e.yml`) builds the codegen project from scratch and passes `OPENAI_API_KEY` from secrets.