@strayl/agent 0.1.3 → 0.1.4

package/skills/authentication/SKILL.md

@@ -0,0 +1,294 @@
+---
+name: authentication
+description: Add authentication to a TanStack Start app using Neon Auth (managed Better Auth). Handles sign-in, sign-up, OAuth, email verification, password reset, session management, route protection, and pre-built auth UI. Use when the user needs user accounts, login, or protected routes.
+---
+
+# Authentication (Neon Auth)
+
+## When to Use
+
+- User asks to add authentication, login, sign-up, or user accounts
+- User wants to protect routes (dashboard, settings, profile, etc.)
+- User mentions "auth", "login", "register", "sign up", "sign in", "logout", "session", "password", "OAuth", "Google sign-in"
+- User needs user management or access control in their app
+- User wants OAuth (Google, GitHub) login
+
+## When NOT to Use
+
+- User only needs a public site with no user accounts
+- User wants API key authentication (not session-based)
+- User explicitly wants to build auth from scratch without Neon Auth
+
+## Prerequisites
+
+- A TanStack Start project (scaffolded with `web-application-creation` skill or existing)
+- A database created with `database-management` skill (or will be created in this workflow)
+- `AUTH_BASE_URL` and `VITE_AUTH_BASE_URL` env vars are automatically available after database creation (both set by `create_database`)
+
+## Architecture
+
+Neon Auth is a **managed authentication service** built on Better Auth. It runs as a REST API deployed in the same region as the Neon database.
+
+| Concern | Solution |
+|---------|----------|
+| Auth service | Neon Auth (managed Better Auth) |
+| User storage | `neon_auth` schema in Neon DB (automatic) |
+| UI components | `@neondatabase/neon-js/auth/react/ui` (pre-built) |
+| Session | HTTP-only cookie (`__Secure-neonauth.session_token`), managed by SDK |
+| OAuth | Google works out of the box; GitHub/Vercel need custom credentials |
+
+**No custom user table needed.** Users, sessions, and accounts are stored automatically in the `neon_auth` schema.
+
+## Workflow
+
+### Step 1: Ensure Database Exists
+
+```
+universal({ tool: "list_databases", params: {} })
+```
+
+If no databases exist, create one first:
+```
+universal({ tool: "create_database", params: { name: "main" } })
+```
+
+Auth is automatically provisioned when the database is created. The `AUTH_BASE_URL`, `VITE_AUTH_BASE_URL`, and `AUTH_COOKIE_SECRET` env vars are already set in the sandbox and `.env`.
+
+### Step 2: Install Neon Auth SDK
+
+```bash
+exec({ command: "cd {app-name} && npm install @neondatabase/neon-js", background: true })
+```
+
+### Step 3: Add Auth Styles
+
+**Edit** `src/styles.css` — add the Neon UI import right after the Tailwind import:
+
+```css
+@import 'tailwindcss';
+@import '@neondatabase/neon-js/ui/tailwind';
+```
+
+If the project does NOT use Tailwind, import the pre-built CSS bundle instead. Add to the root layout or entry point:
+```typescript
+import '@neondatabase/neon-js/ui/css';
+```
+
+### Step 4: Create Auth Client
+
+Create `src/auth.ts`. Uses `VITE_AUTH_BASE_URL` which is auto-set by `create_database` — no manual env var setup needed.
+
+```typescript
+import { createAuthClient } from '@neondatabase/neon-js/auth';
+import { BetterAuthReactAdapter } from '@neondatabase/neon-js/auth/react';
+
+export const authClient = createAuthClient(
+  import.meta.env.VITE_AUTH_BASE_URL,
+  { adapter: BetterAuthReactAdapter() }
+);
+```
+
+### Step 5: Add Auth Provider to Root Route
+
+**Edit** `src/routes/__root.tsx` — wrap the app with `NeonAuthUIProvider`:
+
+```typescript
+import { NeonAuthUIProvider } from '@neondatabase/neon-js/auth/react';
+import { authClient } from '../auth';
+```
+
+Wrap the existing `<Outlet />` (or app content) with the provider:
+
+```tsx
+<NeonAuthUIProvider authClient={authClient}>
+  <Outlet />
+</NeonAuthUIProvider>
+```
+
+**Optional props** for `NeonAuthUIProvider`:
+- `social={{ providers: ['google'] }}` — show OAuth buttons (Google works out of the box)
+- `emailOTP` — enable Email OTP sign-in
+- `credentials={{ forgotPassword: true }}` — enable forgot password flow
+- `navigate={navigate}` — for React Router integration
+
+**Do NOT replace** the existing root route — just add the import and wrap the content with the provider.
+
+### Step 6: Create Auth Page Route
+
+Create `src/routes/auth.$pathname.tsx`:
+
+```typescript
+import { createFileRoute } from '@tanstack/react-router';
+import { AuthView } from '@neondatabase/neon-js/auth/react/ui';
+
+export const Route = createFileRoute('/auth/$pathname')({
+  component: Auth,
+});
+
+function Auth() {
+  const { pathname } = Route.useParams();
+  return (
+    <div className="flex min-h-screen items-center justify-center">
+      <AuthView pathname={pathname} />
+    </div>
+  );
+}
+```
+
+This single route handles `/auth/sign-in`, `/auth/sign-up`, `/auth/forgot-password`, etc.
+
+### Step 7: Create Account Page Route
+
+Create `src/routes/account.$pathname.tsx`:
+
+```typescript
+import { createFileRoute } from '@tanstack/react-router';
+import { AccountView } from '@neondatabase/neon-js/auth/react/ui';
+
+export const Route = createFileRoute('/account/$pathname')({
+  component: Account,
+});
+
+function Account() {
+  const { pathname } = Route.useParams();
+  return (
+    <div className="flex min-h-screen items-center justify-center">
+      <AccountView pathname={pathname} />
+    </div>
+  );
+}
+```
+
+This handles `/account/settings`, `/account/profile`, etc.
+
+### Step 8: Protect Routes
+
+**Edit** the main page (e.g., `src/routes/index.tsx`) to require authentication:
+
+```typescript
+import { createFileRoute } from '@tanstack/react-router';
+import { SignedIn, UserButton, RedirectToSignIn } from '@neondatabase/neon-js/auth/react/ui';
+import { authClient } from '../auth';
+
+export const Route = createFileRoute('/')({
+  component: Home,
+});
+
+function Home() {
+  const { data } = authClient.useSession();
+
+  return (
+    <>
+      <SignedIn>
+        <div className="container mx-auto p-6">
+          <div className="flex items-center justify-between">
+            <h1 className="text-2xl font-bold">Welcome, {data?.user?.name}!</h1>
+            <UserButton />
+          </div>
+        </div>
+      </SignedIn>
+      <RedirectToSignIn />
+    </>
+  );
+}
+```
+
+**Key components:**
+- `<SignedIn>` — renders children only when authenticated
+- `<SignedOut>` — renders children only when NOT authenticated
+- `<RedirectToSignIn>` — redirects to `/auth/sign-in` if not authenticated
+- `<UserButton />` — user avatar/menu dropdown with sign-out
+
+### Step 9: Restart and Preview
+
+Restart the dev server to pick up new routes and env vars, then `showPreview`. Tell the user to test `/auth/sign-in` and `/auth/sign-up`.
+
+## File Structure (after completion)
+
+```
+src/
+├── auth.ts                      # Auth client configuration (NEW)
+├── styles.css                   # EDITED: added neon-js/ui/tailwind import
+└── routes/
+    ├── __root.tsx                # EDITED: wrapped with NeonAuthUIProvider
+    ├── auth.$pathname.tsx        # NEW: handles sign-in, sign-up, forgot-password
+    ├── account.$pathname.tsx     # NEW: handles account settings, profile
+    └── index.tsx                 # EDITED: added route protection
+```
+
+## Available UI Components
+
+| Component | Import | Purpose |
+|-----------|--------|---------|
+| `<AuthView>` | `@neondatabase/neon-js/auth/react/ui` | Full auth page (sign-in/sign-up/reset) |
+| `<AccountView>` | `@neondatabase/neon-js/auth/react/ui` | Account management page |
+| `<SignedIn>` | `@neondatabase/neon-js/auth/react/ui` | Render children only when authenticated |
+| `<SignedOut>` | `@neondatabase/neon-js/auth/react/ui` | Render children only when NOT authenticated |
+| `<RedirectToSignIn>` | `@neondatabase/neon-js/auth/react/ui` | Redirect to sign-in if not authenticated |
+| `<RedirectToSignUp>` | `@neondatabase/neon-js/auth/react/ui` | Redirect to sign-up if not authenticated |
+| `<UserButton>` | `@neondatabase/neon-js/auth/react/ui` | User avatar dropdown with sign-out |
+| `<UserAvatar>` | `@neondatabase/neon-js/auth/react/ui` | User profile picture |
+| `<SignInForm>` | `@neondatabase/neon-js/auth/react/ui` | Standalone sign-in form |
+| `<SignUpForm>` | `@neondatabase/neon-js/auth/react/ui` | Standalone sign-up form |
+| `<ForgotPasswordForm>` | `@neondatabase/neon-js/auth/react/ui` | Password recovery form |
+
+## Hooks
+
+| Hook | Import | Returns |
+|------|--------|---------|
+| `authClient.useSession()` | from auth client | `{ data: { session, user }, isPending }` |
+
+## Important Notes
+
+- **No custom user table.** Users are stored automatically in the `neon_auth` schema. Query with `SELECT * FROM neon_auth.user;`
+- **No password hashing.** Neon Auth handles all credential management.
+- **No session management.** Sessions are managed by the SDK via HTTP-only cookies.
+- **Google OAuth works immediately** with shared credentials for development. GitHub/Vercel require custom OAuth app setup.
+- **AUTH_BASE_URL is branch-specific.** Each Neon branch has its own auth environment — dev and prod are isolated.
+- Do NOT import both `@neondatabase/neon-js/ui/css` AND `@neondatabase/neon-js/ui/tailwind` — pick one based on whether the project uses Tailwind.
+- Do NOT install `bcryptjs`, `better-auth`, or other auth libraries — Neon Auth replaces them.
+
+## SDK Methods Reference
+
+For programmatic auth (building custom UI instead of pre-built components):
+
+```typescript
+import { authClient } from './auth';
+
+// Sign up
+await authClient.signUp.email({ email, password, name });
+
+// Sign in with email/password
+await authClient.signIn.email({ email, password });
+
+// Sign in with OAuth
+await authClient.signIn.social({ provider: 'google', callbackURL: '/' });
+
+// Sign out
+await authClient.signOut();
+
+// Get current session
+const { data } = await authClient.getSession();
+// data.session, data.user
+
+// React hook for session
+const { data } = authClient.useSession();
+
+// Update user profile
+await authClient.updateUser({ name: 'New Name' });
+
+// Change password
+await authClient.changePassword({ currentPassword, newPassword });
+
+// Email OTP verification
+await authClient.emailOtp.verifyEmail({ email, otp: code });
+```
+
+## Extending
+
+- **OAuth providers** — add `social={{ providers: ['google', 'github', 'vercel'] }}` to `NeonAuthUIProvider`
+- **Forgot password** — add `credentials={{ forgotPassword: true }}` to `NeonAuthUIProvider`, or use `<ForgotPasswordForm>` and `<ResetPasswordForm>` components
+- **Email verification** — enable in Neon Console (Settings > Auth). Use verification codes (works out of the box) or verification links (requires custom SMTP)
+- **Custom sign-up fields** — use `additionalFields` and `signUp` props on `NeonAuthUIProvider`
+- **Custom localization** — use `localization` prop to change labels (e.g., `{ SIGN_IN: 'Welcome Back' }`)
+- **Protected route layout** — create `src/routes/_authed.tsx` with `<SignedIn>` check for route groups

package/skills/frontend-design/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: frontend-design
+description: Design and implement distinctive frontend UI for landing pages and web applications. Use when users ask for visual direction, layout, styling, component composition, or UX polish.
+---
+
+# Frontend Design
+
+## When to Use
+
+- After scaffolding with `landing-creation` or `web-application-creation`
+- User asks to design, style, polish, or redesign UI
+- User wants new screens/sections (hero, pricing, dashboard, settings, auth pages, etc.)
+- User asks for a specific aesthetic direction (minimal, bold, editorial, brutalist, retro, corporate)
+
+## Workflow
+
+1. **Clarify intent quickly**
+   - Product/site goal and audience
+   - Required screens/sections
+   - Preferred visual direction and color constraints
+
+2. **Define the visual system first**
+   - Typography pair (display + body) — see **Font Guidelines** below
+   - Color tokens via CSS variables
+   - Spacing, radius, shadow, and motion rules
+
+3. **Compose the layout**
+   - For landing pages: nav, hero, proof, features, CTA, footer
+   - For apps: app shell, primary user flow, settings/forms, data states
+   - Add meaningful empty/loading/error states where relevant
+
+4. **Implement pragmatically**
+   - Reuse existing project components before adding new dependencies
+   - Add new UI components only when the current set cannot cover the requirement
+   - Run install commands in background mode and confirm via logs
+
+5. **Validate before handoff**
+   - Check mobile/tablet/desktop behavior
+   - Verify contrast and focus states
+   - Show preview, gather feedback, iterate
+
+## Core Principles
+
+### 1. Universal Frontend Scope
+This skill is not only for landing pages. Apply it to marketing sites, product pages, dashboards, and full web app screens.
+
+### 2. Distinct Visual Direction
+Avoid generic template outputs. Make deliberate choices in typography, spacing rhythm, and layout structure.
+
+### 3. No Forced Component Catalog
+Do not rely on a single external component catalog as a default workflow. Use the project's own design language first.
+
+### 4. Reuse Before Reinventing
+Prefer existing components and tokens; extend them only where needed to keep UI consistent.
+
+### 5. Responsive by Default
+Design for small screens first, then scale up without breaking hierarchy and readability.
+
+## Font Guidelines
+
+**NEVER use the Bitcount font** — it is a Strayl branding font and must not be used in user projects.
+
+**Avoid generic defaults** — Do NOT default to System UI, Inter, Arial, Helvetica, or other overused fonts. Every project deserves a distinctive typographic identity.
+
+**Be creative and intentional** — Pick fonts that match the project's personality and aesthetic direction. Experiment with interesting pairings. Examples of strong choices:
+- **Editorial / luxury**: Playfair Display, Cormorant, Fraunces, Libre Baskerville
+- **Modern / clean**: Space Grotesk, General Sans, Outfit, Plus Jakarta Sans, Sora
+- **Bold / statement**: Clash Display, Cabinet Grotesk, Unbounded, Familjen Grotesk
+- **Geometric**: DM Sans, Manrope, Satoshi, Urbanist
+- **Playful / warm**: Bricolage Grotesque, Instrument Sans, Lora, Crimson Pro
+- **Monospace accent**: JetBrains Mono, Fira Code, IBM Plex Mono, Space Mono
+
+Use Google Fonts CDN or fontsource for font loading. Always pick a display + body pair that complement each other.
+
+## Technical Guidelines
+
+- For simple sites, start with `src/routes/index.tsx`.
+- For app features, edit the route/component relevant to the request.
+- Extract reusable UI into `src/components/`.
+- Keep style tokens centralized in `src/styles.css` and route shell files.
+
+## Image Generation
+
+**Proactively generate images** when the design calls for visual content (hero images, backgrounds, illustrations, icons, product shots). Do NOT use placeholder boxes or Lorem-style image URLs — generate real images instead.
+
+**When to generate:**
+- The user asks to build a page/section that naturally needs imagery (hero, about, features, gallery) and has NOT provided their own images or URLs
+- The design would look incomplete or broken without visual content
+- The user explicitly asks for images or illustrations
+
+**When NOT to generate:**
+- The user provided their own images, URLs, or assets
+- The section works well with icons, gradients, or pure typography (no image needed)
+- The user explicitly said to skip images or use placeholders
+
+**How:**
+- Use `generate_image` — up to 10 images per call, with descriptive prompts and appropriate aspect ratios
+- Write detailed prompts: describe style, mood, colors, subject — not just "hero image"
+- Match aspect ratios to layout: `16:9` for hero banners, `1:1` for cards/avatars, `3:4` for portraits
+- Use `analyze_image` to understand user-provided mockups or screenshots before designing
+
+## Workflow Checklist
+
+- [ ] Confirmed goal, screens, and visual direction
+- [ ] Defined typography and color/token system
+- [ ] Implemented responsive layout and key states
+- [ ] Reused existing components where possible
+- [ ] Previewed and iterated with user feedback

package/skills/landing-creation/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: landing-creation
+description: Initialize a new landing page from the Strayl landing template using npx create-strayl-landing. Use when the user wants a single-page site, landing page, or marketing page — NOT a full web application with multiple routes and complex state.
+---
+
+# Landing Page Creation
+
+## When to Use
+
+- User asks to create a landing page, marketing page, or single-page site
+- User says something like "create a site", "make me a landing page", "build a website", "create a homepage"
+- User wants a simple promotional or presentation page (not a multi-page app with forms, auth, dashboards)
+- The workspace repository is empty and the user's request implies a simple site rather than a full application
+
+## When NOT to Use (use `web-application-creation` instead)
+
+- User explicitly asks for a "web app", "application", "dashboard", "admin panel"
+- User needs multiple routes, forms, data handling, state management, i18n
+- User describes features like authentication, CRUD, API integration, database
+- User wants 50+ UI components out of the box
+
+## Workflow
+
+1. **Ask the user for the site name** before running any commands. The name will be used as the project directory name.
+2. **Run the scaffolding command** in the repository root:
+   ```
+   npx -y create-strayl-landing@latest --name {site-name}
+   ```
+3. **Install dependencies:**
+   ```
+   cd {site-name} && npm install
+   ```
+4. **Start the dev server** in background mode:
+   ```
+   cd {site-name} && npm run dev
+   ```
+5. **Check logs** to confirm the server started successfully (look for "ready" or "listening on port").
+6. **Show preview** to the user with `showPreview`.
+
+7. **🔴 REQUIRED: Read and follow the design skill** — After showing preview, you MUST immediately:
+   ```
+   read_file("/skills/frontend-design/SKILL.md")
+   ```
+   Then follow the design skill's workflow to build out the landing page content. Do NOT stop after showing the preview — the scaffolding is just the starting point.
+
+## After Scaffolding
+
+**IMPORTANT:** Scaffolding creates an empty template. Your job is not done after `showPreview`. You MUST continue to the `frontend-design` skill to actually build the landing page content (hero, features, sections, etc.) based on the user's request.
+
+## Template Stack
+
+| Layer | Technology |
+|-------|------------|
+| Framework | React 19.2 + TanStack Start |
+| Bundler | Vite 7.1 |
+| Language | TypeScript 5.7 (strict mode) |
+| Routing | TanStack Router (file-based) |
+| Styling | Tailwind CSS 4.0 + CSS custom properties |
+| UI Components | shadcn/ui (install as needed) |
+| Icons | Lucide React |
+| Theming | next-themes (light/dark + system default) |
+| Fonts | Geist, Geist Mono (Google CDN) |
+| Server | Nitro |
+
+## Project Structure
+
+```
+{site-name}/
+├── public/
+│   ├── favicon.ico
+│   ├── logo-dark.webp
+│   └── logo-light.webp
+├── src/
+│   ├── components/
+│   │   ├── ui/
+│   │   │   └── button.tsx            # Button component (7 variants, 6 sizes)
+│   │   ├── theme-provider.tsx        # Theme provider (light/dark/system)
+│   │   └── themed-logo.tsx           # Theme-aware logo
+│   ├── lib/
+│   │   └── utils.ts                  # cn() — class merging utility
+│   ├── routes/
+│   │   ├── __root.tsx                # Root layout (fonts, meta, ThemeProvider)
+│   │   ├── index.tsx                 # Home page (single landing page)
+│   │   └── routeTree.gen.ts          # Auto-generated route tree
+│   ├── router.tsx                    # Router configuration
+│   └── styles.css                    # Global styles + CSS custom properties
+├── package.json
+├── tsconfig.json
+├── vite.config.ts
+└── components.json                   # shadcn/ui configuration
+```
+
+## Key Features
+
+- **Theming** — Light/dark mode via CSS custom properties. Semantic tokens: `primary`, `secondary`, `accent`, `destructive`, `muted`, `info`, `success`, `warning`. Light background `#f5f5f5`, dark background `#171717`.
+- **Button component** — Simple button with CVA variants (`default`, `destructive`, `outline`, `ghost`, `secondary`, `link`) and sizes (`sm`, `default`, `lg`, `icon`).
+- **Hydration safety** — Components check `mounted` state before rendering theme-dependent UI, preventing SSR mismatches.
+- **Minimal footprint** — Only 3 components (Button, ThemeProvider, ThemedLogo) and a single page. No bloat.
+- **Extensible** — Add new components via `npx shadcn@latest add <component>`. Add pages by creating files in `src/routes/`.
+
+## Default Page Content
+
+The template ships with a single page (`/`) containing:
+- "STRAYL" heading (responsive sizing)
+- "Landing page template" subheading
+- "Get Started" CTA button with themed logo
+- Full-height centered layout
+
+## Architecture
+
+- **Root layout** (`__root.tsx`) — Uses `shellComponent` for HTML shell. Geist fonts via Google Fonts CDN, ThemeProvider wrapper. Same pattern as `web-application-creation` template.
+- **Routing** — File-based via TanStack Router. Files in `src/routes/` become routes automatically.
+- **SSR** — Supported via TanStack React Start + Nitro.
+- **Path alias** — `@/*` maps to `./src/*`.
+- **`cn()`** — Utility combining clsx + tailwind-merge for conflict-free class merging.
+- **Button** — Standard React button component. For link buttons, wrap with an anchor or use Tailwind classes directly.
+
+## Best Practices
+
+- **Do NOT** use `npm create`, `npx create-vite`, or other scaffolding tools. Always use `npx -y create-strayl-landing@latest`.
+- Always use the `--name` flag to specify the site name.
+- After creation, work inside the `{site-name}/` directory for all file edits.
+- Start editing from `src/routes/index.tsx` (the landing page).
+- Add new UI components via `npx shadcn@latest add <component>` rather than installing separate UI libraries.
+- This is a landing page template — keep it simple. For complex multi-page apps, use the `web-application-creation` skill instead.

package/skills/reference/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: reference
+description: Essential reference for stack versions, APIs, common errors, and patterns. Read this BEFORE writing any code in a TanStack Start project to avoid wrong imports, deprecated APIs, and build errors.
+---
+
+# Reference — Stack Versions & Patterns
+
+## When to Read This Skill
+
+- **ALWAYS** before writing code that uses TanStack Start, Tailwind CSS, or shadcn/ui
+- Before debugging build or runtime errors
+- Before setting up a dev server
+- When unsure about correct import paths or API syntax
+
+## Stack Versions
+
+| Package | Version | Key Changes |
+|---------|---------|-------------|
+| React | 19.x | `use()`, `useActionState()`, `useOptimistic()`, ref as prop (no forwardRef) |
+| TanStack Start | 1.x | `createServerFn()` with fluent API, Nitro server, config in `vite.config.ts` |
+| TanStack Router | 1.x | `createFileRoute()`, `Link`, `useNavigate()`, `useParams()`, `useSearch()` |
+| Vite | 7.x | `@tailwindcss/vite` plugin, `@tanstack/react-start/plugin/vite` |
+| Tailwind CSS | 4.x | CSS-based config via `@theme {}` — **NO `tailwind.config.js`** |
+| shadcn/ui | latest | OKLCH colors, `tw-animate-css` (NOT `tailwindcss-animate`), `@custom-variant dark` |
+| TypeScript | 5.7+ | strict mode |
+
+## Tailwind CSS 4 — Critical Differences from v3
+
+- Config lives in `src/styles.css` using `@import "tailwindcss"` and `@theme {}` blocks
+- **NO `tailwind.config.js`** — delete it if it exists
+- Colors use OKLCH format, not HSL
+- Custom properties: `--color-primary`, `--color-background`, etc. inside `@theme inline {}`
+- Plugins loaded via CSS: `@plugin "..."` — NOT via JS config
+- No `content` array needed — auto-detection
+- Animation: use `tw-animate-css`, NOT `tailwindcss-animate`
+
+## TanStack Start API
+
+### Config
+Config is in `vite.config.ts` with `tanstackStart()` plugin. **NOT** old `app.config.ts` with `defineConfig`.
+
+### Server Functions
+```typescript
+import { createServerFn } from '@tanstack/react-start'
+import { z } from 'zod'
+
+const mySchema = z.object({ id: z.string() })
+
+export const getData = createServerFn({ method: 'GET' })
+  .inputValidator((d: unknown) => mySchema.parse(d))
+  .handler(async ({ data }) => {
+    // data is typed as { id: string }
+    return { result: data.id }
+  })
+```
+
+**IMPORTANT:** `.inputValidator()` takes a **FUNCTION**, not a schema directly. Always wrap zod: `.inputValidator((d: unknown) => mySchema.parse(d))`
+
+### File-Based Routing
+- `$param` for dynamic segments
+- `_layout` prefix for pathless layouts
+- `__root.tsx` for root layout
+- Loaders: defined on route via `loader` option in `createFileRoute()`
+
+## Common Errors & Recovery
+
+### Build / Compile Errors
+| Error | Fix |
+|-------|-----|
+| `Cannot find module 'X'` | Run `npm install` first, then retry |
+| `Type error: ...` | Read the file, fix the type, rebuild |
+| `ENOENT: no such file or directory` | Check the path — likely wrong relative path |
+
+### Dev Server Errors
+| Error | Fix |
+|-------|-----|
+| Port already in use | Kill the background process, restart on a different port |
+| `MODULE_NOT_FOUND` after install | `rm -rf node_modules && npm install` |
+
+### Package Install Errors
+| Error | Fix |
+|-------|-----|
+| `ERESOLVE: peer dependency conflict` | Use `npm install --legacy-peer-deps` |
+| `ETARGET: no matching version` | Check the actual package name/version with `web_search` |
+
+### Recovery Pattern
+1. Read the **FULL** error message (don't guess from partial output)
+2. Check `getLogs` if it was a background command
+3. Fix the root cause (don't retry the same failing command)
+4. **NEVER repeat the same edit or command twice** — if your fix didn't work, try a DIFFERENT approach
+5. If stuck after 2 attempts, use `web_search` to find the solution
+6. If still stuck, use `askUser` to explain the problem and ask for guidance
+
+### Do NOT Loop
+If you edited a file and it still errors:
+- Read the error message carefully — it may be a different issue
+- Use `web_search` or `task(web-researcher)` to understand the correct API
+- Try a fundamentally different approach, not a variation of the same one
+
+## Dev Server
+
+When starting a dev server:
+1. Run `exec({ command: "npm install", cwd: "web-application" })` if `node_modules` is missing
+2. Use `exec({ command: "npm run dev", cwd: "web-application", background: true })` to start in background
+3. Use `getLogs({ sessionId, commandId })` to check output and wait for ready
+4. Extract the actual port from logs (e.g., "localhost:5173", "127.0.0.1:3001")
+5. Use that detected port in `showPreview({ port: DETECTED_PORT, title: "Dev Server" })`
+6. Only if no port found in logs, fallback to `showPreview({ port: 3000, title: "Dev Server" })`
+
+## Database — Neon PostgreSQL
+
+- **ALWAYS use `@neondatabase/serverless`** — it uses HTTP/WebSocket, compatible with Workers
+- API: `import { neon } from '@neondatabase/serverless'`
+- For simple queries: `const sql = neon(process.env.DATABASE_URL); const rows = await sql`SELECT * FROM users`;`
+- For ORM: use `drizzle-orm` + `drizzle-orm/neon-http`
+
+### Database Provisioning
+1. First check if `DATABASE_URL` already exists via `list_env_vars`
+2. If not — use `create_database` tool to provision a Neon DB (it auto-sets `DATABASE_URL`)
+3. **NEVER ask the user to provide DATABASE_URL** — the platform provisions databases automatically
+4. Only use `requestEnvVar` for DATABASE_URL if the user explicitly wants their own external database
+
+### Critical: Lazy Initialization
+`neon()` must **NEVER** be called at module top level. In Cloudflare Workers, `process.env` is only populated inside the `fetch()` handler. Module-level `neon(process.env.DATABASE_URL)` will crash with `undefined`. Always use a lazy singleton — see the `db()` pattern in `api-creation` and `authentication` skills.
+
+## Packages Compatible with Workers
+
+| Package | Purpose |
+|---------|---------|
+| `@neondatabase/serverless` | PostgreSQL via HTTP (Neon) |
+| `drizzle-orm` + `drizzle-orm/neon-http` | ORM for Neon (~7kb) |
+| `kysely` | Lightweight query builder (pure TS) |
+| `@planetscale/database` | MySQL via HTTP |
+| `@upstash/redis` | Redis via HTTP |
+| `@libsql/client/web` | Turso/libSQL via HTTP |
+| `jose` | JWT/JWE/JWS (WebCrypto native) |
+| `bcryptjs` | Password hashing (pure JS) |
+| `zod` | Schema validation |
+| `fetch` | Built-in, no import needed |
+
+## Background Commands
+
+Use `background: true` for long-running commands:
+- `npx -y shadcn@latest add ...` → wait 20-40 seconds
+- `npm install` with many deps → wait 20-30 seconds
+- `npm run build` → wait 15-45 seconds
+- `npm run dev` (server startup) → wait 5-10 seconds
+
+After starting in background, call `wait({ seconds: N })`, then `getLogs` to check. If still running, wait again (5-10s) and re-check. Do NOT call `getLogs` repeatedly without waiting.