@strayl/agent 0.1.9 → 0.1.10

package/skills/reference/SKILL.md

@@ -1,149 +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.
+---
+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.