@strayl/agent 0.1.8 → 0.1.10

package/skills/web-application-creation/SKILL.md

@@ -1,231 +1,231 @@
----
-name: web-application-creation
-description: Initialize a new web application from the Strayl template using npx create-strayl-app. Handles project scaffolding, dependency installation, and dev server startup. Use when the user wants a full-featured app with multiple routes, forms, auth, database, or any complex logic.
----
-
-# Web Application Creation
-
-## When to Use
-
-- User asks to create, start, or scaffold a new web application
-- User wants to build a new project from scratch
-- The workspace repository is empty and needs a project initialized
-- User says "create an app", "start a new project", "build me an app"
-- User needs multiple routes, forms, auth, database, dashboards, CRUD
-
-## When NOT to Use (use `landing-creation` instead)
-
-- User wants a single-page landing, marketing page, or promotional site
-- User says "make me a website", "create a homepage", "build a landing page"
-- User's request implies a simple static site without complex backend logic
-
-## Workflow
-
-1. **Ask the user for the app 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-app@latest --name {app-name}
-   ```
-3. **Install dependencies:**
-   ```
-   cd {app-name} && npm install
-   ```
-4. **Start the dev server** in background mode:
-   ```
-   cd {app-name} && npm run dev
-   ```
-5. **Check logs** to confirm the server started successfully (look for "ready" or "listening on port 3000").
-6. **Show preview** to the user with `showPreview`.
-7. **Continue building** based on user's request. Common next steps:
-   - Need user accounts? → Read `/skills/authentication/SKILL.md`
-   - Need a database? → Read `/skills/database-management/SKILL.md`
-   - Need API endpoints / server logic? → Read `/skills/api-creation/SKILL.md`
-   - Need UI/UX design, styling, or visual polish? → Read `/skills/frontend-design/SKILL.md`
-
-## Template Stack
-
-| Layer | Technology | Version |
-|-------|------------|---------|
-| Framework | React + TanStack Start | React 19, Start 1.x |
-| Bundler | Vite | 7.x |
-| Language | TypeScript (strict) | 5.7+ |
-| Routing | TanStack Router (file-based) | 1.x |
-| Styling | Tailwind CSS + CSS custom properties | 4.x |
-| UI Components | shadcn/ui (install as needed) | latest |
-| Icons | Lucide React | 0.475+ |
-| Theming | next-themes (light/dark + system) | 0.4.x |
-| Font | Geist (fontsource) | — |
-| Server | Nitro (SSR + server functions) | nightly |
-
-## Project Structure
-
-```
-{app-name}/
-├── public/
-│   └── favicon.ico
-├── src/
-│   ├── components/
-│   │   ├── theme-provider.tsx       # next-themes wrapper
-│   │   └── ui/                      # Minimal starter components (button, input, label, textarea)
-│   ├── hooks/
-│   │   └── use-mobile.ts           # useIsMobile() — viewport < 768px
-│   ├── lib/
-│   │   └── utils.ts                 # cn() — clsx + tailwind-merge
-│   ├── routes/
-│   │   ├── __root.tsx               # Root layout (HTML shell, Geist font, ThemeProvider)
-│   │   ├── index.tsx                # Home page ("STRAYL" + theme toggle)
-│   │   └── routeTree.gen.ts         # Auto-generated route tree (DO NOT EDIT)
-│   ├── router.tsx                   # Router config (empty context, scroll restoration)
-│   └── styles.css                   # Tailwind 4 theme (colors, fonts, radius)
-├── components.json                  # shadcn/ui config (style: new-york)
-├── package.json
-├── tsconfig.json
-└── vite.config.ts                   # Vite + Nitro + TanStack Start + Tailwind plugins
-```
-
-## Critical Files — Know Before Editing
-
-### `src/routes/__root.tsx` — App Shell
-
-Uses `shellComponent` (NOT `component`) to define the HTML document structure:
-
-```typescript
-import { HeadContent, Scripts, createRootRoute } from '@tanstack/react-router'
-import '@fontsource-variable/geist'
-import { ThemeProvider } from '../components/theme-provider'
-import appCss from '../styles.css?url'
-
-export const Route = createRootRoute({
-  head: () => ({
-    meta: [
-      { charSet: 'utf-8' },
-      { name: 'viewport', content: 'width=device-width, initial-scale=1' },
-      { title: 'Strayl' },
-    ],
-    links: [
-      { rel: 'stylesheet', href: appCss },
-      { rel: 'icon', href: '/favicon.ico' },
-    ],
-  }),
-  shellComponent: RootDocument,
-})
-
-function RootDocument({ children }: { children: React.ReactNode }) {
-  return (
-    <html lang="en" suppressHydrationWarning>
-      <head><HeadContent /></head>
-      <body>
-        <ThemeProvider>{children}</ThemeProvider>
-        <Scripts />
-      </body>
-    </html>
-  )
-}
-```
-
-**To add auth context**, add `beforeLoad` — it works alongside `shellComponent`:
-```typescript
-export const Route = createRootRoute({
-  beforeLoad: async () => {
-    const user = await getUser();
-    return { user };
-  },
-  head: () => ({ ... }),
-  shellComponent: RootDocument,
-})
-```
-
-### `src/router.tsx` — Router Instance
-
-```typescript
-export const getRouter = () => {
-  const router = createRouter({
-    routeTree,
-    context: {},           // ← empty by default; auth adds user here
-    scrollRestoration: true,
-    defaultPreloadStaleTime: 0,
-  })
-  return router
-}
-```
-
-### `vite.config.ts` — Plugin Order Matters
-
-```typescript
-plugins: [
-  nitro(),                 // SSR / server functions
-  viteTsConfigPaths(),     // @/* path aliases
-  tailwindcss(),           // Tailwind CSS 4
-  tanstackStart(),         // TanStack Start framework
-  viteReact(),             // React Fast Refresh
-]
-```
-
-**Do NOT rewrite this file.** Use `edit_file` to add plugins if needed.
-
-### `src/styles.css` — Tailwind CSS 4 Theme
-
-Uses `@theme inline {}` directive (NOT `tailwind.config.js`):
-
-```css
-@import "tailwindcss";
-@import "tw-animate-css";
-
-@custom-variant dark (&:is(.dark *));
-@variant dark (&:where(.dark, .dark *));
-
-@theme inline {
-  --color-background: var(--background);
-  --color-primary: var(--primary);
-  --font-sans: "Geist Variable", ui-sans-serif, system-ui, sans-serif;
-  /* ... radius, animations */
-}
-
-:root { /* light theme colors */ }
-.dark { /* dark theme colors */ }
-```
-
-**To add custom colors**, edit the `:root` and `.dark` blocks. To add font families, add `@theme inline {}` entries.
-
-## UI Components
-
-The template ships with only **4 minimal starter components** in `src/components/ui/`: `button`, `input`, `label`, `textarea`. These are simple, unstyled wrappers — just enough to get started.
-
-### Adding More Components
-
-Use **shadcn/ui** to add any components you need:
-
-```bash
-npx shadcn@latest add card dialog sheet select badge separator scroll-area tabs accordion dropdown-menu
-```
-
-You can add any shadcn/ui component this way. Always install components as needed rather than building custom ones from scratch.
-
-### Important
-
-- **Do NOT hardcode a fixed set of UI components into every app.** Each app should have components appropriate for its purpose.
-- **Design each app's UI uniquely** — use different layouts, color schemes, and component combinations. Avoid repeating the same card/dialog/sheet pattern everywhere.
-- Use Tailwind CSS utility classes directly for custom layouts. Not everything needs a component wrapper.
-- For complex components (data tables, charts, calendars, etc.), install them via shadcn: `npx shadcn@latest add table chart calendar`
-
-## Protected Files — Edit Only, Never Rewrite
-
-- `package.json` — use `npm install <pkg>`, use `edit_file` for scripts
-- `tsconfig.json` — edit specific fields only
-- `vite.config.ts` — edit, don't rewrite (plugin order matters)
-- `src/styles.css` — append or edit (Tailwind @theme config)
-- `src/routes/__root.tsx` — edit carefully (fonts, providers, beforeLoad)
-- `src/routeTree.gen.ts` — NEVER edit (auto-generated by TanStack Router)
-
-## Best Practices
-
-- **Do NOT** use `npm create`, `npx create-vite`, or other scaffolding tools
-- Always use the `--name` flag to specify the project name
-- After creation, work inside the `{app-name}/` directory for all file edits
-- Start editing from `src/routes/index.tsx` and create new routes as files in `src/routes/`
-- Add UI components via `npx shadcn@latest add <component>` as needed — do NOT install alternative UI libraries (no MUI, Chakra, Ant Design, etc.)
-- New routes auto-register via TanStack Router file-based routing (the `routeTree.gen.ts` regenerates on dev server restart)
-- For protected routes, use the `_authed.tsx` layout pattern (see `authentication` skill)
-- For server-side logic, use `createServerFn` (see `api-creation` skill)
-- **Run `npm run build` after your first server function + route are written.** Build errors surface immediately when the codebase is small and easy to fix. Catching import/bundling errors early prevents hours of debugging later.
-- **NEVER use `await import()` for server functions in components.** Always static imports + `useServerFn()` for mutations. See `api-creation` skill for correct patterns.
+---
+name: web-application-creation
+description: Initialize a new web application from the Strayl template using npx create-strayl-app. Handles project scaffolding, dependency installation, and dev server startup. Use when the user wants a full-featured app with multiple routes, forms, auth, database, or any complex logic.
+---
+
+# Web Application Creation
+
+## When to Use
+
+- User asks to create, start, or scaffold a new web application
+- User wants to build a new project from scratch
+- The workspace repository is empty and needs a project initialized
+- User says "create an app", "start a new project", "build me an app"
+- User needs multiple routes, forms, auth, database, dashboards, CRUD
+
+## When NOT to Use (use `landing-creation` instead)
+
+- User wants a single-page landing, marketing page, or promotional site
+- User says "make me a website", "create a homepage", "build a landing page"
+- User's request implies a simple static site without complex backend logic
+
+## Workflow
+
+1. **Ask the user for the app 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-app@latest --name {app-name}
+   ```
+3. **Install dependencies:**
+   ```
+   cd {app-name} && npm install
+   ```
+4. **Start the dev server** in background mode:
+   ```
+   cd {app-name} && npm run dev
+   ```
+5. **Check logs** to confirm the server started successfully (look for "ready" or "listening on port 3000").
+6. **Show preview** to the user with `showPreview`.
+7. **Continue building** based on user's request. Common next steps:
+   - Need user accounts? → Read `/skills/authentication/SKILL.md`
+   - Need a database? → Read `/skills/database-management/SKILL.md`
+   - Need API endpoints / server logic? → Read `/skills/api-creation/SKILL.md`
+   - Need UI/UX design, styling, or visual polish? → Read `/skills/frontend-design/SKILL.md`
+
+## Template Stack
+
+| Layer | Technology | Version |
+|-------|------------|---------|
+| Framework | React + TanStack Start | React 19, Start 1.x |
+| Bundler | Vite | 7.x |
+| Language | TypeScript (strict) | 5.7+ |
+| Routing | TanStack Router (file-based) | 1.x |
+| Styling | Tailwind CSS + CSS custom properties | 4.x |
+| UI Components | shadcn/ui (install as needed) | latest |
+| Icons | Lucide React | 0.475+ |
+| Theming | next-themes (light/dark + system) | 0.4.x |
+| Font | Geist (fontsource) | — |
+| Server | Nitro (SSR + server functions) | nightly |
+
+## Project Structure
+
+```
+{app-name}/
+├── public/
+│   └── favicon.ico
+├── src/
+│   ├── components/
+│   │   ├── theme-provider.tsx       # next-themes wrapper
+│   │   └── ui/                      # Minimal starter components (button, input, label, textarea)
+│   ├── hooks/
+│   │   └── use-mobile.ts           # useIsMobile() — viewport < 768px
+│   ├── lib/
+│   │   └── utils.ts                 # cn() — clsx + tailwind-merge
+│   ├── routes/
+│   │   ├── __root.tsx               # Root layout (HTML shell, Geist font, ThemeProvider)
+│   │   ├── index.tsx                # Home page ("STRAYL" + theme toggle)
+│   │   └── routeTree.gen.ts         # Auto-generated route tree (DO NOT EDIT)
+│   ├── router.tsx                   # Router config (empty context, scroll restoration)
+│   └── styles.css                   # Tailwind 4 theme (colors, fonts, radius)
+├── components.json                  # shadcn/ui config (style: new-york)
+├── package.json
+├── tsconfig.json
+└── vite.config.ts                   # Vite + Nitro + TanStack Start + Tailwind plugins
+```
+
+## Critical Files — Know Before Editing
+
+### `src/routes/__root.tsx` — App Shell
+
+Uses `shellComponent` (NOT `component`) to define the HTML document structure:
+
+```typescript
+import { HeadContent, Scripts, createRootRoute } from '@tanstack/react-router'
+import '@fontsource-variable/geist'
+import { ThemeProvider } from '../components/theme-provider'
+import appCss from '../styles.css?url'
+
+export const Route = createRootRoute({
+  head: () => ({
+    meta: [
+      { charSet: 'utf-8' },
+      { name: 'viewport', content: 'width=device-width, initial-scale=1' },
+      { title: 'Strayl' },
+    ],
+    links: [
+      { rel: 'stylesheet', href: appCss },
+      { rel: 'icon', href: '/favicon.ico' },
+    ],
+  }),
+  shellComponent: RootDocument,
+})
+
+function RootDocument({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <head><HeadContent /></head>
+      <body>
+        <ThemeProvider>{children}</ThemeProvider>
+        <Scripts />
+      </body>
+    </html>
+  )
+}
+```
+
+**To add auth context**, add `beforeLoad` — it works alongside `shellComponent`:
+```typescript
+export const Route = createRootRoute({
+  beforeLoad: async () => {
+    const user = await getUser();
+    return { user };
+  },
+  head: () => ({ ... }),
+  shellComponent: RootDocument,
+})
+```
+
+### `src/router.tsx` — Router Instance
+
+```typescript
+export const getRouter = () => {
+  const router = createRouter({
+    routeTree,
+    context: {},           // ← empty by default; auth adds user here
+    scrollRestoration: true,
+    defaultPreloadStaleTime: 0,
+  })
+  return router
+}
+```
+
+### `vite.config.ts` — Plugin Order Matters
+
+```typescript
+plugins: [
+  nitro(),                 // SSR / server functions
+  viteTsConfigPaths(),     // @/* path aliases
+  tailwindcss(),           // Tailwind CSS 4
+  tanstackStart(),         // TanStack Start framework
+  viteReact(),             // React Fast Refresh
+]
+```
+
+**Do NOT rewrite this file.** Use `edit_file` to add plugins if needed.
+
+### `src/styles.css` — Tailwind CSS 4 Theme
+
+Uses `@theme inline {}` directive (NOT `tailwind.config.js`):
+
+```css
+@import "tailwindcss";
+@import "tw-animate-css";
+
+@custom-variant dark (&:is(.dark *));
+@variant dark (&:where(.dark, .dark *));
+
+@theme inline {
+  --color-background: var(--background);
+  --color-primary: var(--primary);
+  --font-sans: "Geist Variable", ui-sans-serif, system-ui, sans-serif;
+  /* ... radius, animations */
+}
+
+:root { /* light theme colors */ }
+.dark { /* dark theme colors */ }
+```
+
+**To add custom colors**, edit the `:root` and `.dark` blocks. To add font families, add `@theme inline {}` entries.
+
+## UI Components
+
+The template ships with only **4 minimal starter components** in `src/components/ui/`: `button`, `input`, `label`, `textarea`. These are simple, unstyled wrappers — just enough to get started.
+
+### Adding More Components
+
+Use **shadcn/ui** to add any components you need:
+
+```bash
+npx shadcn@latest add card dialog sheet select badge separator scroll-area tabs accordion dropdown-menu
+```
+
+You can add any shadcn/ui component this way. Always install components as needed rather than building custom ones from scratch.
+
+### Important
+
+- **Do NOT hardcode a fixed set of UI components into every app.** Each app should have components appropriate for its purpose.
+- **Design each app's UI uniquely** — use different layouts, color schemes, and component combinations. Avoid repeating the same card/dialog/sheet pattern everywhere.
+- Use Tailwind CSS utility classes directly for custom layouts. Not everything needs a component wrapper.
+- For complex components (data tables, charts, calendars, etc.), install them via shadcn: `npx shadcn@latest add table chart calendar`
+
+## Protected Files — Edit Only, Never Rewrite
+
+- `package.json` — use `npm install <pkg>`, use `edit_file` for scripts
+- `tsconfig.json` — edit specific fields only
+- `vite.config.ts` — edit, don't rewrite (plugin order matters)
+- `src/styles.css` — append or edit (Tailwind @theme config)
+- `src/routes/__root.tsx` — edit carefully (fonts, providers, beforeLoad)
+- `src/routeTree.gen.ts` — NEVER edit (auto-generated by TanStack Router)
+
+## Best Practices
+
+- **Do NOT** use `npm create`, `npx create-vite`, or other scaffolding tools
+- Always use the `--name` flag to specify the project name
+- After creation, work inside the `{app-name}/` directory for all file edits
+- Start editing from `src/routes/index.tsx` and create new routes as files in `src/routes/`
+- Add UI components via `npx shadcn@latest add <component>` as needed — do NOT install alternative UI libraries (no MUI, Chakra, Ant Design, etc.)
+- New routes auto-register via TanStack Router file-based routing (the `routeTree.gen.ts` regenerates on dev server restart)
+- For protected routes, use the `_authed.tsx` layout pattern (see `authentication` skill)
+- For server-side logic, use `createServerFn` (see `api-creation` skill)
+- **Run `npm run build` after your first server function + route are written.** Build errors surface immediately when the codebase is small and easy to fix. Catching import/bundling errors early prevents hours of debugging later.
+- **NEVER use `await import()` for server functions in components.** Always static imports + `useServerFn()` for mutations. See `api-creation` skill for correct patterns.