wix · hanag-wix · Jul 2, 2026
diff --git a/CLI App - Calculator Form/.agents/skills/wds-docs/SKILL.md b/CLI App - Calculator Form/.agents/skills/wds-docs/SKILL.md
@@ -0,0 +1,215 @@
+---
+name: wds-docs
+description: Wix Design System component reference. Use when building UI with @wix/design-system, choosing components, or checking props and examples. Triggers on "what component", "how do I make", "WDS", "show me props", component names like Button, Card, Modal, Box, Text, or when importing from @wix/design-system or @wix/wix-ui-icons-common. Also use when looking up spacing tokens (SP1-SP6) or icon names.
+compatibility: Requires @wix/design-system package installed in the project.
+---
+
+# WDS Documentation Navigator
+
+**Docs path:** `node_modules/@wix/design-system/dist/docs/`
+
+## CRITICAL: Never Read Entire Files
+
+Files are 200-900+ lines. Follow the staged discovery flow below.
+
+---
+
+## Stage 1: Find Component
+
+**Goal:** Search for component by feature/keyword
+
+```bash
+Grep: "table" in components.md
+Grep: "form\|input\|validation" in components.md
+Grep: "modal\|dialog\|popup" in components.md
+```
+
+**Output:** Component name + description + do/don'ts
+
+**Next:** Go to Stage 2 with component name
+
+---
+
+## Stage 2: Get Props + Example List
+
+**Goal:** Get props AND discover available examples
+
+```bash
+# 2a. Get props (small files OK to read, large files grep)
+Read: components/ButtonProps.md              # OK if <100 lines
+Grep: "### disabled" in components/BoxProps.md -A 3  # Box is huge
+
+# 2b. List available examples (ALWAYS grep, never read)
+Grep: "^### " in components/ButtonExamples.md -n
+```
+
+**Output from 2b:**
+```
+5:### Size
+17:### Skin
+71:### Affix
+123:### Disabled
+183:### Loading state
+```
+
+**Next:** Pick example(s) from list, go to Stage 3
+
+---
+
+## Stage 3: Fetch Specific Example
+
+**Goal:** Read only the example you need (~30-50 lines)
+
+```bash
+# Option A: Read with offset (line number from Stage 2)
+Read: components/ButtonExamples.md offset=183 limit=40
+
+# Option B: Grep with context
+Grep: "### Loading state" in components/ButtonExamples.md -A 40
+```
+
+**Output:** JSX code example for that specific feature
+
+---
+
+## Stage 4: Icons (when needed)
+
+```bash
+Grep: "Add\|Edit\|Delete\|Search" in icons.md
+```
+
+---
+
+## Flow Summary
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ Stage 1: Grep components.md for keyword                 │
+│          → finds: Button, Card, Table...                │
+└────────────────────┬────────────────────────────────────┘
+                     ↓
+┌─────────────────────────────────────────────────────────┐
+│ Stage 2a: Read/Grep {Component}Props.md                 │
+│           → gets: props with types & descriptions       │
+│                                                         │
+│ Stage 2b: Grep "^### " in {Component}Examples.md        │
+│           → gets: example names + line numbers          │
+│           "5:### Size, 71:### Affix, 183:### Loading"   │
+└────────────────────┬────────────────────────────────────┘
+                     ↓
+┌─────────────────────────────────────────────────────────┐
+│ Stage 3: Read offset=183 limit=40                       │
+│          → gets: specific example JSX code              │
+└────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Example Session: Product Page
+
+```bash
+# Stage 1: Find components
+Grep: "image\|card\|price" in components.md
+→ Image, Card, Text found
+
+# Stage 2a: Get Card props
+Read: components/CardProps.md
+
+# Stage 2b: List Card examples
+Grep: "^### " in components/CardExamples.md -n
+→ 5:### Basic, 25:### With media, 60:### Clickable
+
+# Stage 3: Fetch "With media" example
+Read: components/CardExamples.md offset=25 limit=35
+→ Gets Card with Image example code
+
+# Repeat Stage 2-3 for other components as needed
+```
+
+**Result:** ~80 lines read instead of 1500+
+
+---
+
+## Quick Reference
+
+| Stage | Command | Output |
+|-------|---------|--------|
+| 1. Find | `Grep: "keyword" in components.md` | Component name |
+| 2a. Props | `Read: {Name}Props.md` | Props list |
+| 2b. Examples | `Grep: "^### " in {Name}Examples.md` | Example names + lines |
+| 3. Fetch | `Read: offset=N limit=40` | Example code |
+| 4. Icons | `Grep: "IconName" in icons.md` | Icon exists |
+
+---
+
+## File Sizes
+
+| File | Lines | Strategy |
+|------|-------|----------|
+| components.md | ~970 | Grep, never read fully |
+| icons.md | ~400 | Grep for specific icon |
+| Most Props.md | 30-100 | Read fully OK |
+| BoxProps.md | 8000+ | Grep only! |
+| Most Examples.md | 100-600 | Grep → offset read |
+| PageExamples.md | 940 | Grep → offset read |
+
+---
+
+## Grep Patterns by Use Case
+
+```bash
+# Forms
+Grep: "form\|input\|validation" in components.md
+
+# Layout
+Grep: "layout\|page\|card\|box" in components.md
+
+# Data display
+Grep: "table\|list\|badge" in components.md
+
+# Feedback
+Grep: "notification\|toast\|loader" in components.md
+```
+
+---
+
+## Quick Component Mapping (Design → WDS)
+
+| Design Element | WDS Component | Notes |
+|----------------|---------------|-------|
+| Rectangle/container | `<Box>` | Layout wrapper |
+| Text button | `<TextButton>` | Secondary actions |
+| Input with label | `<FormField>` + `<Input>` | Wrap inputs |
+| Toggle | `<ToggleSwitch>` | On/off settings |
+| Modal | `<Modal>` + `<CustomModalLayout>` | Use together |
+| Grid | `<Layout>` + `<Cell>` | Responsive |
+
+---
+
+## Spacing (px → SP conversion)
+
+When designer specifies pixels, convert to the nearest SP token:
+
+| Token | Classic | Studio |
+|-------|---------|--------|
+| `SP1` | 6px | 4px |
+| `SP2` | 12px | 8px |
+| `SP3` | 18px | 12px |
+| `SP4` | 24px | 16px |
+| `SP5` | 30px | 20px |
+| `SP6` | 36px | 24px |
+
+```tsx
+<Box gap="SP2" padding="SP3">
+```
+
+Only use SP tokens for `gap`, `padding`, `margin` - not for width/height.
+
+---
+
+## Imports
+
+```tsx
+import { Button, Card, Image } from '@wix/design-system';
+import { Add, Edit, Delete } from '@wix/wix-ui-icons-common';
+```
diff --git a/CLI App - Calculator Form/.agents/skills/wix-cli-app-validation/SKILL.md b/CLI App - Calculator Form/.agents/skills/wix-cli-app-validation/SKILL.md
@@ -0,0 +1,176 @@
+---
+name: wix-cli-app-validation
+description: Use when testing app readiness, verifying runtime behavior, or validating before releases and after changes in the code. Triggers include validate, test, verify, check readiness, preview validation, build verification, TypeScript compilation.
+compatibility: Requires Wix CLI development environment.
+---
+
+# Wix App Validation
+
+Validates Wix CLI applications through a four-step sequential workflow: package installation, TypeScript compilation check, build, and preview.
+
+## Validation Workflow
+
+Execute these steps sequentially. Stop and report errors if any step fails.
+
+### Step 1: Package Installation
+
+Ensure all dependencies are installed before proceeding with the build.
+
+**Detect package manager:**
+- Check for `package-lock.json` → use `npm`
+- Check for `yarn.lock` → use `yarn`
+- Check for `pnpm-lock.yaml` → use `pnpm`
+- Default to `npm` if no lock file is found
+
+**Run installation command:**
+
+```bash
+# For npm
+npm install
+
+# For yarn
+yarn install
+
+# For pnpm
+pnpm install
+```
+
+**Success criteria:**
+- Exit code 0
+- All dependencies installed successfully
+- No missing peer dependencies warnings (unless expected)
+- `node_modules` directory exists and contains expected packages
+
+**On failure:** Report the installation errors, [check the debug log](#debug-log-on-errors) for detailed diagnostics, and stop validation. Common issues:
+- Network connectivity problems
+- Corrupted lock files
+- Version conflicts
+- Missing Node.js or package manager
+
+### Step 2: TypeScript Compilation Check
+
+Run TypeScript compiler to check for type errors.
+
+**Full project check:**
+```bash
+npx tsc --noEmit
+```
+
+**Targeted check (specific files/directories):**
+
+When validating after implementing a specific extension, you can run TypeScript checks on just those files:
+
+```bash
+# Check specific directory
+npx tsc --noEmit src/extensions/dashboard/pages/survey/**/*.ts src/extensions/dashboard/pages/survey/**/*.tsx
+
+# Check dashboard pages only
+npx tsc --noEmit src/extensions/dashboard/pages/**/*.ts src/extensions/dashboard/pages/**/*.tsx
+
+# Check site widgets only
+npx tsc --noEmit src/site/widgets/**/*.ts src/site/widgets/**/*.tsx
+
+# Check dashboard modals only
+npx tsc --noEmit src/extensions/dashboard/modals/**/*.ts src/extensions/dashboard/modals/**/*.tsx
+
+# Check backend only
+npx tsc --noEmit src/backend/**/*.ts
+```
+
+**When to use targeted checks:**
+- After implementing a single extension (faster feedback)
+- When debugging type errors in a specific area
+- During iterative development
+
+**When to use full project check:**
+- Before final validation
+- When changes affect shared types
+- Before building/deploying
+
+**Success criteria:**
+- Exit code 0
+- No TypeScript compilation errors
+- All type checks pass
+
+**On failure:** Report the specific TypeScript errors and stop validation. Common issues:
+- Type mismatches between expected and actual types
+- Missing type declarations for imported modules
+- Incorrect generic type parameters
+- Properties not existing on declared types
+- Incompatible function signatures
+
+### Step 3: Build Validation
+
+Run the build command and check for compilation errors:
+
+```bash
+npx wix build
+```
+
+**Success criteria:**
+- Exit code 0
+- No TypeScript errors
+- No missing dependencies
+
+**On failure:** Report the specific compilation errors, [check the debug log](#debug-log-on-errors) for detailed diagnostics, and stop validation.
+
+### Step 4: Preview Deployment
+
+Start the preview server:
+
+```bash
+npx wix preview
+```
+
+**Success criteria:**
+- Preview server starts successfully
+- Preview URLs are generated (both site and dashboard)
+
+**URL extraction:** Parse the terminal output to find both preview URLs. Look for patterns like:
+- Site preview: `Site preview: https://...` or `Site URL: https://...`
+- Dashboard preview: `Dashboard preview: https://...` or `Preview URL: https://...` or `Your app is available at: https://...`
+
+Extract both URLs and provide them to the user for manual verification.
+
+**On failure:** Report the preview startup errors, [check the debug log](#debug-log-on-errors) for detailed diagnostics, and stop validation.
+
+## Validation Report
+
+After completing all steps, provide a summary:
+
+**Pass:**
+- Dependencies: ✓ All packages installed successfully
+- TypeScript: ✓ No compilation errors
+- Build: ✓ Compiled successfully
+- Preview: ✓ Running at [URL]
+
+**Fail:**
+- Identify which step failed
+- Provide specific error messages
+- Suggest remediation steps
+
+## Debug Log on Errors
+
+When a validation step fails (non-zero exit code, error output, or the CLI crashes/hangs), check `.wix/debug.log` in the project root for the full error trace. **Only read this file when errors occur** — skip it when steps pass or when the terminal output already makes the error clear (e.g. a straightforward TypeScript type error).
+
+The `.wix/` directory is automatically created by the Wix CLI and contains internal configuration and log files. Don't edit it, but reading `debug.log` for troubleshooting is expected.
+
+```
+Read: .wix/debug.log
+
+# If the file is large, read the last 100 lines for the most recent errors
+Read: .wix/debug.log (with offset to the end)
+```
+
+## Common Issues
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Package installation fails | Missing lock file, network issues, or corrupted node_modules | Delete `node_modules` and lock file, then reinstall |
+| TypeScript compilation fails | Type mismatches, missing declarations, or incorrect types | Fix TypeScript errors shown in `npx tsc --noEmit` output |
+| Build fails | TypeScript errors, missing dependencies, or internal CLI error | Fix TypeScript errors in source; for non-obvious failures, check `.wix/debug.log` |
+| Preview fails to start | Port conflict, config issue, or internal CLI error | Check `wix.config.json`; if unclear, check `.wix/debug.log` for details |
+| Console errors in preview | Runtime exceptions | Check browser console output |
+| UI not rendering | Component errors | Review component code and imports |
+| CLI error with no clear message | Truncated terminal output | Read `.wix/debug.log` for the full error trace and stack details |
+| Mysterious failures after config change | Stale CLI state | Read `.wix/debug.log` to confirm, then delete `.wix/` and rebuild |