@vetala/vetala 0.1.0-beta

package/skill/react-vite-guide/references/vite-specific.md

@@ -0,0 +1,385 @@
+# Vite-Specific Patterns
+
+Configuration, conventions, and optimization patterns specific to Vite + React 19 SPA projects.
+
+---
+
+## 1. Project Setup
+
+### 1.1 Recommended Vite Config
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react-swc'
+import path from 'path'
+
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, './src'),
+    },
+  },
+  build: {
+    target: 'esnext',
+    rollupOptions: {
+      output: {
+        manualChunks: {
+          vendor: ['react', 'react-dom'],
+        },
+      },
+    },
+  },
+})
+```
+
+- **`@vitejs/plugin-react-swc`** — faster than Babel plugin, suitable for most projects
+- **`@vitejs/plugin-react`** — required when Babel plugins are needed (e.g., React Compiler, styled-components)
+
+### 1.2 React Compiler with Vite
+
+```typescript
+// vite.config.ts — with React Compiler (Babel plugin required)
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+const ReactCompilerConfig = { /* compiler options */ }
+
+export default defineConfig({
+  plugins: [
+    react({
+      babel: {
+        plugins: [
+          ['babel-plugin-react-compiler', ReactCompilerConfig],
+        ],
+      },
+    }),
+  ],
+})
+```
+
+React Compiler eliminates the need for manual `memo()`, `useMemo()`, and `useCallback()` in most cases.
+
+---
+
+## 2. Environment Variables
+
+### 2.1 Usage
+
+Vite exposes env variables on `import.meta.env` (not `process.env`).
+
+```typescript
+// Only variables prefixed with VITE_ are exposed to client code
+const apiUrl = import.meta.env.VITE_API_URL
+const mode = import.meta.env.MODE        // 'development' | 'production'
+const isDev = import.meta.env.DEV         // boolean
+const isProd = import.meta.env.PROD       // boolean
+```
+
+### 2.2 Type Safety
+
+```typescript
+// src/vite-env.d.ts
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  readonly VITE_API_URL: string
+  readonly VITE_APP_TITLE: string
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv
+}
+```
+
+### 2.3 Known Constraints
+
+```typescript
+// ❌ process.env is not available in Vite client code
+const url = process.env.REACT_APP_API_URL
+
+// ❌ Non-VITE_ prefixed vars are not exposed
+const secret = import.meta.env.SECRET_KEY // undefined
+
+// ✅ VITE_ prefix exposes the variable to client code
+const url = import.meta.env.VITE_API_URL
+```
+
+---
+
+## 3. Code Splitting
+
+### 3.1 Route-Based Splitting
+
+```tsx
+import { lazy, Suspense } from 'react'
+import { BrowserRouter, Routes, Route } from 'react-router-dom'
+
+const Home = lazy(() => import('./pages/Home'))
+const Dashboard = lazy(() => import('./pages/Dashboard'))
+const Settings = lazy(() => import('./pages/Settings'))
+
+function App() {
+  return (
+    <BrowserRouter>
+      <Suspense fallback={<PageSkeleton />}>
+        <Routes>
+          <Route path="/" element={<Home />} />
+          <Route path="/dashboard" element={<Dashboard />} />
+          <Route path="/settings" element={<Settings />} />
+        </Routes>
+      </Suspense>
+    </BrowserRouter>
+  )
+}
+```
+
+### 3.2 Named Exports with React.lazy
+
+`React.lazy` expects a default export. For named exports:
+
+```tsx
+// ✅ Re-export as default
+const MonacoEditor = lazy(() =>
+  import('./MonacoEditor').then(mod => ({ default: mod.MonacoEditor }))
+)
+```
+
+### 3.3 Manual Chunks
+
+```typescript
+// vite.config.ts
+export default defineConfig({
+  build: {
+    rollupOptions: {
+      output: {
+        manualChunks(id) {
+          if (id.includes('node_modules')) {
+            if (id.includes('react') || id.includes('react-dom')) {
+              return 'vendor-react'
+            }
+            if (id.includes('@radix-ui') || id.includes('@headlessui')) {
+              return 'vendor-ui'
+            }
+            return 'vendor'
+          }
+        },
+      },
+    },
+  },
+})
+```
+
+---
+
+## 4. Path Aliases
+
+### 4.1 Vite Config
+
+```typescript
+// vite.config.ts
+resolve: {
+  alias: {
+    '@': path.resolve(__dirname, './src'),
+    '@components': path.resolve(__dirname, './src/components'),
+    '@hooks': path.resolve(__dirname, './src/hooks'),
+    '@utils': path.resolve(__dirname, './src/utils'),
+  },
+}
+```
+
+### 4.2 TypeScript Config
+
+```json
+// tsconfig.json (or tsconfig.app.json)
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"],
+      "@components/*": ["./src/components/*"],
+      "@hooks/*": ["./src/hooks/*"],
+      "@utils/*": ["./src/utils/*"]
+    }
+  }
+}
+```
+
+Both configurations are kept in sync. Vite resolves at build time; TypeScript resolves for type checking.
+
+---
+
+## 5. CSS Integration
+
+### 5.1 CSS Modules
+
+```tsx
+// Button.module.css is automatically scoped
+import styles from './Button.module.css'
+
+function Button({ children }: { children: React.ReactNode }) {
+  return <button className={styles.primary}>{children}</button>
+}
+```
+
+### 5.2 Tailwind CSS v4
+
+```typescript
+// vite.config.ts
+import tailwindcss from '@tailwindcss/vite'
+
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss(),
+  ],
+})
+```
+
+```css
+/* src/index.css */
+@import 'tailwindcss';
+```
+
+### 5.3 Global CSS
+
+```tsx
+// src/main.tsx
+import './index.css'
+import { createRoot } from 'react-dom/client'
+import App from './App'
+
+createRoot(document.getElementById('root')!).render(<App />)
+```
+
+---
+
+## 6. Static Assets
+
+### 6.1 Importing Assets
+
+```tsx
+// Vite handles asset imports with hashed filenames
+import logoUrl from './assets/logo.svg'
+
+function Logo() {
+  return <img src={logoUrl} alt="Logo" width={120} height={40} />
+}
+```
+
+### 6.2 Public Directory
+
+Files in `public/` are served at root path and not processed by Vite:
+
+```tsx
+// public/favicon.ico → /favicon.ico
+<link rel="icon" href="/favicon.ico" />
+```
+
+### 6.3 SVG as Component
+
+```typescript
+// Using vite-plugin-svgr
+import { defineConfig } from 'vite'
+import svgr from 'vite-plugin-svgr'
+
+export default defineConfig({
+  plugins: [react(), svgr()],
+})
+```
+
+```tsx
+import Logo from './assets/logo.svg?react'
+
+function Header() {
+  return <Logo className="h-8 w-8" aria-hidden="true" />
+}
+```
+
+---
+
+## 7. Development Patterns
+
+### 7.1 Proxy API Requests
+
+```typescript
+// vite.config.ts
+export default defineConfig({
+  server: {
+    proxy: {
+      '/api': {
+        target: 'http://localhost:3001',
+        changeOrigin: true,
+      },
+    },
+  },
+})
+```
+
+### 7.2 HTTPS in Development
+
+```typescript
+// vite.config.ts
+import basicSsl from '@vitejs/plugin-basic-ssl'
+
+export default defineConfig({
+  plugins: [react(), basicSsl()],
+})
+```
+
+---
+
+## 8. Build Optimization
+
+### 8.1 Analyze Bundle Size
+
+```bash
+# Install rollup-plugin-visualizer
+npx vite build --mode analyze
+
+# Or add to vite.config.ts
+import { visualizer } from 'rollup-plugin-visualizer'
+
+export default defineConfig({
+  plugins: [
+    react(),
+    visualizer({ open: true, gzipSize: true }),
+  ],
+})
+```
+
+### 8.2 Preload Critical Assets
+
+```html
+<!-- index.html -->
+<head>
+  <link rel="preconnect" href="https://api.example.com" />
+  <link rel="preload" href="/fonts/inter.woff2" as="font" type="font/woff2" crossorigin />
+</head>
+```
+
+### 8.3 Compression
+
+```typescript
+// vite.config.ts
+import compression from 'vite-plugin-compression'
+
+export default defineConfig({
+  plugins: [
+    react(),
+    compression({ algorithm: 'gzip' }),
+    compression({ algorithm: 'brotliCompress' }),
+  ],
+})
+```
+
+---
+
+## References
+
+1. [https://vite.dev/guide/](https://vite.dev/guide/)
+2. [https://vite.dev/config/](https://vite.dev/config/)
+3. [https://vite.dev/guide/env-and-mode](https://vite.dev/guide/env-and-mode)
+4. [https://react.dev/learn/react-compiler](https://react.dev/learn/react-compiler)
+5. [https://tailwindcss.com/docs/installation/vite](https://tailwindcss.com/docs/installation/vite)

package/skill/react-vite-guide/references/web-interface.md

@@ -0,0 +1,146 @@
+# Web Interface Patterns
+
+UI/UX patterns for accessibility, forms, animation, performance, and content quality. Framework-agnostic patterns applicable to React + Vite SPA.
+
+---
+
+## Accessibility
+
+- `aria-label` attribute provides accessible names for icon-only buttons
+- `<label>` or `aria-label` associates form controls with descriptive text
+- Keyboard handlers (`onKeyDown`/`onKeyUp`) enable keyboard interaction on interactive elements
+- `<button>` is the semantic element for actions; `<a>`/`<Link>` is for navigation
+- `alt` attribute describes image content (`alt=""` marks decorative images)
+- `aria-hidden="true"` removes decorative icons from the accessibility tree
+- `aria-live="polite"` announces async updates (toasts, validation) to screen readers
+- Semantic HTML (`<button>`, `<a>`, `<label>`, `<table>`) provides built-in accessibility before ARIA
+- Heading hierarchy (`<h1>`–`<h6>`) structures page content; skip links provide keyboard navigation to main content
+- `scroll-margin-top` on heading anchors offsets fixed headers during anchor navigation
+
+## Focus States
+
+- `focus-visible:ring-*` or equivalent provides visible focus indicators on interactive elements
+- `outline-none` / `outline: none` removes the default focus indicator; a replacement is required for accessibility
+- `:focus-visible` triggers on keyboard focus only (not mouse clicks), unlike `:focus`
+- `:focus-within` applies styles when any child receives focus, useful for compound controls
+
+## Forms
+
+- `autocomplete` and meaningful `name` attributes enable browser autofill
+- Input `type` (`email`, `tel`, `url`, `number`) and `inputmode` trigger specialized mobile keyboards
+- `onPaste` with `preventDefault()` blocks user paste functionality
+- `htmlFor` or wrapping makes `<label>` clickable to focus its control
+- `spellCheck={false}` disables spellcheck for emails, codes, and usernames
+- Checkbox/radio label and control sharing a single hit target eliminates dead zones
+- Submit buttons remain enabled until request starts; a spinner indicates in-flight state
+- Inline errors next to fields with focus on first error provides immediate validation feedback
+- Placeholders ending with `…` and showing example patterns guide input format
+- `autocomplete="off"` on non-auth fields prevents password manager triggers
+- `beforeunload` event or router guard warns before navigation with unsaved changes
+
+## Animation
+
+- `prefers-reduced-motion` media query detects user preference for reduced animation
+- `transform` and `opacity` are compositor-friendly properties (GPU-accelerated)
+- `transition: all` animates every property including layout-triggering ones; explicit property listing is more performant
+- `transform-origin` determines the pivot point for transformations
+- SVG transforms on `<g>` wrapper with `transform-box: fill-box; transform-origin: center` apply transformations relative to the element's bounding box
+- Interruptible animations respond to user input mid-animation
+
+## Typography
+
+- `…` (ellipsis character) is the typographic standard; `...` (three dots) is not
+- `"` `"` (curly quotes) are typographic standard; `"` (straight quotes) are not
+- `&nbsp;` (non-breaking space) prevents line breaks: `10&nbsp;MB`, `⌘&nbsp;K`, brand names
+- Loading states conventionally end with `…`: `"Loading…"`, `"Saving…"`
+- `font-variant-numeric: tabular-nums` aligns numbers in columns and comparisons
+- `text-wrap: balance` or `text-pretty` on headings distributes text evenly across lines
+
+## Content Handling
+
+- `truncate`, `line-clamp-*`, or `break-words` handle long content in text containers
+- `min-w-0` on flex children enables text truncation within flex layouts
+- Empty states (empty strings/arrays) require explicit handling to prevent broken UI
+- User-generated content varies from short to very long inputs
+
+## Images
+
+- Explicit `width` and `height` on `<img>` prevents Cumulative Layout Shift (CLS)
+- `loading="lazy"` defers loading for below-fold images
+- `fetchpriority="high"` prioritizes loading for above-fold critical images
+
+## Performance
+
+- Virtualization (`virtua`, `content-visibility: auto`) handles large lists (>50 items) efficiently
+- Layout reads (`getBoundingClientRect`, `offsetHeight`, `offsetWidth`, `scrollTop`) trigger forced reflow when called during render
+- Batching DOM reads and writes separately avoids layout thrashing
+- Uncontrolled inputs avoid re-render cost per keystroke; controlled inputs incur render cost on every change
+- `<link rel="preconnect">` pre-establishes connections to CDN/asset domains
+- `<link rel="preload" as="font">` with `font-display: swap` loads critical fonts early
+
+## Navigation & State
+
+- URL query params store UI state (filters, tabs, pagination, expanded panels) for shareability
+- `<a>`/`<Link>` elements support Cmd/Ctrl+click and middle-click for new tab opening
+- `nuqs` or similar libraries sync `useState` with URL parameters for deep-linkable UI
+- Destructive actions support confirmation modals or undo windows
+
+## Touch & Interaction
+
+- `touch-action: manipulation` removes double-tap zoom delay on touch devices
+- `-webkit-tap-highlight-color` controls the tap highlight color on iOS/Android
+- `overscroll-behavior: contain` in modals/drawers/sheets prevents scroll chaining
+- During drag operations: text selection is disabled, `inert` attribute disables interaction on dragged elements
+- `autoFocus` triggers keyboard on mobile; suitable for desktop single primary inputs
+
+## Safe Areas & Layout
+
+- `env(safe-area-inset-*)` provides spacing values for device notches in full-bleed layouts
+- `overflow-x-hidden` on containers prevents unwanted horizontal scrollbars
+- CSS Flex/Grid provides layout without JavaScript measurement
+
+## Dark Mode & Theming
+
+- `color-scheme: dark` on `<html>` applies dark theme to native controls (scrollbar, inputs)
+- `<meta name="theme-color">` sets the browser chrome color to match page background
+- Native `<select>` requires explicit `background-color` and `color` for Windows dark mode
+
+## Locale & i18n
+
+- `Intl.DateTimeFormat` provides locale-aware date/time formatting
+- `Intl.NumberFormat` provides locale-aware number/currency formatting
+- `Accept-Language` header / `navigator.languages` detects user language preference
+
+## Hover & Interactive States
+
+- `hover:` state on buttons/links provides visual interaction feedback
+- Progressive contrast increase across hover/active/focus states provides clearer state hierarchy
+
+## Content & Copy
+
+- Active voice pattern: "Install the CLI" vs passive "The CLI will be installed"
+- Title Case (Chicago style) is the convention for headings and buttons
+- Numerals represent counts: "8 deployments" vs "eight deployments"
+- Specific button labels: "Save API Key" vs generic "Continue"
+- Error messages include fix/next step information alongside the problem
+- Second person is the standard voice; first person is not
+- `&` replaces "and" in space-constrained contexts
+
+---
+
+## Known Anti-patterns
+
+| Pattern | Effect |
+|---------|--------|
+| `user-scalable=no` / `maximum-scale=1` | Disables browser zoom |
+| `onPaste` + `preventDefault` | Blocks paste functionality |
+| `transition: all` | Animates layout-triggering properties |
+| `outline-none` without `:focus-visible` replacement | Removes focus indicator |
+| Inline `onClick` navigation without `<a>` | Breaks native link behavior |
+| `<div>`/`<span>` with click handlers | Missing keyboard/screen reader support |
+| Images without dimensions | Causes Cumulative Layout Shift |
+| Large arrays `.map()` without virtualization | Performance degradation on >50 items |
+| Form inputs without labels | Inaccessible to screen readers |
+| Icon buttons without `aria-label` | Missing accessible name |
+| Hardcoded date/number formats | Locale-incompatible |
+| `autoFocus` without justification | Triggers mobile keyboard unexpectedly |

package/skill/skill-maker/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: skill-maker
+description: Generates AI agent skill packages with SKILL.md and optional bundled resources such as scripts/, references/, and assets/.
+---
+
+# Skill Maker Capabilities
+
+Skill generation tooling for AI agent capability packages.
+
+## Tools
+
+- **File system operations**: Create directories, write SKILL.md and reference files
+- **YAML parser**: Generate and validate frontmatter
+- **Markdown generator**: Structure capability documentation
+
+## Domains
+
+- **AI agent skills**: Primary domain - skill package structure and conventions
+- **Documentation**: SKILL.md authoring, capability vs behavior classification
+- **Repository management**: Directory layout and supporting resource organization
+
+## Workflow
+
+**Step 1: Input Validation (Required First)**
+
+Before generating any skill, validate user input through clarification loop.
+See [input_validation.md](references/input_validation.md) for the complete checklist and sufficiency criteria.
+
+**Step 2: Skill Generation**
+
+After all required information is collected, proceed with package creation.
+
+## Core Capabilities
+
+- **Input Validation**: Iterative clarification loop to gather required skill specifications
+- **Skill Package Generation**: Creates complete skill directory structures
+- **YAML Frontmatter Support**: Generates compliant frontmatter with name/description fields
+- **Resource Bundling**: Supports scripts/, references/, assets/ subdirectories
+
+## Supported Outputs
+
+- **`SKILL.md`**: Entry point with YAML frontmatter and capability index
+- **`references/`**: Detailed technical specifications and domain knowledge
+- **`scripts/`**: Executable automation code
+- **`assets/`**: Templates, images, boilerplate files
+
+## Technical References
+
+- **[input_validation.md](references/input_validation.md)**: **Required first step** - Input analysis and clarification loop
+- **[skill_structure.md](references/skill_structure.md)**: File structure specifications and directory purposes
+- **[frontmatter_spec.md](references/frontmatter_spec.md)**: YAML frontmatter field constraints and examples
+- **[content_spec.md](references/content_spec.md)**: Capability vs behavior content classification

package/skill/skill-maker/references/content_spec.md

@@ -0,0 +1,67 @@
+# Content Specification
+
+Defines the content classification for skill documentation.
+
+## Content Classification
+
+```yaml
+- category: Focus
+  capability: Static knowledge, syntax, API specs
+  behavior: Workflows, preferences, restrictions
+- category: Keywords
+  capability: "Is", "Has", "Supports", "Consists of"
+  behavior: "Always", "Never", "Should", "Must"
+- category: Subject
+  capability: Definition, Syntax, Parameters, Version
+  behavior: Formatting rules, interaction patterns
+```
+
+## Capability Examples
+
+- **"Always format dates as ISO 8601"**: "`DateUtils.toISO()` provides ISO 8601 formatting"
+- **"Ask user for file path if missing"**: "`readFile()` throws error if path is null"
+- **"Never use deprecated APIs"**: "`v2` API is current; `v1` API deprecated since 2024"
+
+## Recommended Body Sections
+
+The Markdown body after frontmatter has no format restrictions, but the following sections are recommended:
+
+- **Step-by-step instructions**: Guide agents through task execution
+- **Examples of inputs and outputs**: Concrete usage patterns
+- **Common edge cases**: Known pitfalls and how to handle them
+
+The full SKILL.md body loads when the skill activates. Consider splitting longer content into referenced files.
+
+## Content Types
+
+```yaml
+- type: Syntax & Usage
+  description: Exact usage patterns of code, commands, DSLs
+  location: SKILL.md or references/
+- type: Interface Specifications
+  description: Function signatures, component props, API schemas
+  location: references/
+- type: Data Models
+  description: Entity relationships, state definitions
+  location: references/
+- type: Environment/Versions
+  description: Supported versions, compatibility matrix
+  location: SKILL.md
+- type: Logic & Transformations
+  description: Deterministic input-to-output mappings
+  location: references/
+```
+
+## Size Constraints
+
+- **SKILL.md body**: <500 lines
+- **Reference files >100 lines**: Table of contents required
+- **Reference nesting**: One level deep from SKILL.md only
+
+## Anti-Patterns
+
+- **Duplicate Information**: Same content in SKILL.md and references
+- **Deeply Nested References**: References linking to other references
+- **Behavior as Capability**: Using capability language to describe rules
+- **Context Bloat**: Large code blocks in SKILL.md instead of references
+- **Missing Links**: Reference files not linked from SKILL.md