@famgia/omnify-ai-guides 2.0.15

package/dist/knowledge/cursor-rules/schema-create.mdc.stub

@@ -0,0 +1,440 @@
+---
+description: "Step-by-step schema creation workflow: 1) Read guide, 2) Create YAML, 3) npx omnify generate, 4) Validate output, 5) Migrate. CRITICAL: String defaults must be plain values without quotes wrapper!"
+globs: ["schemas/**/*.yaml", "schemas/**/*.yml", "{{LARAVEL_ROOT}}database/migrations/**"]
+alwaysApply: false
+---
+
+# Omnify Schema Creation Workflow
+
+> **Usage:** Mention `@schema-create` in chat OR this rule auto-applies when editing schema files
+
+## 📋 Workflow Steps
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  1. READ GUIDE     →  Read schema guide documentation           │
+│  2. CREATE SCHEMA  →  Create/modify YAML schema file            │
+│  3. GENERATE       →  Run `npx omnify generate`                 │
+│  4. VALIDATE       →  Check generated code matches requirements │
+│  5. MIGRATE        →  Run database migration                    │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Step 1: Read Schema Guide 📖
+
+**MUST READ before creating schema:**
+
+```bash
+# Read the schema guide
+cat .claude/omnify/guides/omnify/schema-guide.md
+# OR
+cat packages/omnify/ai-guides/schema-guide.md
+```
+
+**Key Documentation:**
+- Schema syntax and property types
+- Relationships (belongsTo, hasMany, etc.)
+- Validation rules (nullable, minLength, maxLength)
+- Display names (ja, en, vi)
+- Special types (JapaneseName, JapaneseAddress, etc.)
+
+---
+
+## Step 2: Create Schema 📝
+
+### Schema File Location
+
+```
+schemas/
+├── {domain}/           # Group by domain
+│   ├── {Model}.yaml    # PascalCase filename
+│   └── {Enum}.yaml     # Enum schemas
+└── shared/             # Shared enums/types
+```
+
+### Basic Schema Template
+
+```yaml
+# schemas/{domain}/{ModelName}.yaml
+name: ModelName
+kind: object
+
+displayName:
+  ja: モデル名
+  en: Model Name
+
+options:
+  timestamps: true      # created_at, updated_at
+  softDelete: false     # deleted_at
+
+properties:
+  # Required field
+  name:
+    type: String
+    length: 100
+    displayName:
+      ja: 名前
+      en: Name
+    placeholder:
+      ja: 例：田中太郎
+      en: e.g. John Doe
+
+  # Optional field
+  description:
+    type: Text
+    nullable: true
+    displayName:
+      ja: 説明
+      en: Description
+
+  # Enum field
+  status:
+    type: OrderStatus
+    default: pending
+    displayName:
+      ja: ステータス
+      en: Status
+
+  # Relationship
+  category:
+    type: Category
+    relation: belongsTo
+    nullable: true
+```
+
+### From SQL/Database Requirements
+
+When creating schema from SQL or database design:
+
+```yaml
+# SQL: VARCHAR(255) NOT NULL
+property_name:
+  type: String
+  length: 255
+
+# SQL: VARCHAR(100) NULL
+property_name:
+  type: String
+  length: 100
+  nullable: true
+
+# SQL: TEXT
+property_name:
+  type: Text
+
+# SQL: INT / BIGINT
+property_name:
+  type: Int  # or BigInt
+
+# SQL: DECIMAL(10,2)
+property_name:
+  type: Float
+
+# SQL: BOOLEAN DEFAULT false
+property_name:
+  type: Boolean
+  default: false
+
+# SQL: DATE
+property_name:
+  type: Date
+
+# SQL: DATETIME / TIMESTAMP
+property_name:
+  type: DateTime
+
+# SQL: ENUM('draft', 'published', 'archived')
+# → Create separate enum schema
+```
+
+---
+
+## Step 3: Generate Code 🔧
+
+```bash
+# Generate all code from schemas
+npx omnify generate
+```
+
+**What gets generated:**
+- TypeScript types & Zod schemas
+- Laravel migrations & models
+- API resources & controllers
+- Form requests & validation
+
+---
+
+## Step 4: Validate Generated Code ✅
+
+### ⚠️ CRITICAL for SQL-based schemas
+
+**If creating schema from SQL requirements, MUST verify:**
+
+```bash
+# 1. Check generated migration matches SQL design
+cat {{LARAVEL_ROOT}}database/migrations/*_create_{table_name}_table.php
+
+# 2. Check TypeScript types match requirements
+cat {{TYPESCRIPT_BASE}}/omnify/schemas/{ModelName}.ts
+
+# 3. Check Laravel model relationships
+cat {{LARAVEL_BASE}}/Models/{ModelName}.php
+```
+
+### Validation Checklist
+
+| Check          | What to Verify                               |
+| -------------- | -------------------------------------------- |
+| ✅ Column names | snake_case in migration matches schema       |
+| ✅ Column types | VARCHAR, TEXT, INT match schema types        |
+| ✅ Nullable     | NULL/NOT NULL matches `nullable: true/false` |
+| ✅ Defaults     | DEFAULT values match `default:` in schema    |
+| ✅ Foreign keys | Relationships generate correct FK            |
+| ✅ Indexes      | Required indexes are present                 |
+
+### If Generated Code is Wrong
+
+```
+┌─────────────────────────────────────────┐
+│  Generated code doesn't match SQL?      │
+│                                         │
+│  1. Fix the YAML schema                 │
+│  2. Run `npx omnify generate` again     │
+│  3. Verify generated code               │
+│  4. Repeat until correct                │
+└─────────────────────────────────────────┘
+```
+
+**Common fixes:**
+
+```yaml
+# Problem: Column should be nullable
+# Fix: Add nullable: true
+property_name:
+  type: String
+  nullable: true  # ← Add this
+
+# Problem: Wrong column length
+# Fix: Adjust length
+property_name:
+  type: String
+  length: 255  # ← Change this
+
+# Problem: Missing default value
+# Fix: Add default
+status:
+  type: OrderStatus
+  default: pending  # ← Add this
+
+# Problem: Wrong relationship type
+# Fix: Change relation
+category:
+  type: Category
+  relation: belongsTo  # belongsTo, hasMany, hasOne, belongsToMany
+```
+
+### ⚠️ CRITICAL: DB Functions NOT Allowed in Default
+
+```yaml
+# ❌ WRONG - DB functions are NOT allowed
+failed_at:
+  type: Timestamp
+  default: CURRENT_TIMESTAMP  # ERROR!
+
+# ✅ CORRECT - Use useCurrent option
+failed_at:
+  type: Timestamp
+  useCurrent: true            # Equivalent to CURRENT_TIMESTAMP
+
+updated_at:
+  type: Timestamp
+  useCurrent: true
+  useCurrentOnUpdate: true    # ON UPDATE CURRENT_TIMESTAMP
+
+# ❌ WRONG - UUID() function
+external_id:
+  type: Uuid
+  default: UUID()             # ERROR!
+
+# ✅ CORRECT - Static value or nullable
+external_id:
+  type: Uuid
+  nullable: true              # Let application generate
+```
+
+---
+
+## Step 5: Run Migration 🗄️
+
+```bash
+# Run migration
+php artisan migrate
+
+# If migration fails, rollback and fix
+php artisan migrate:rollback
+# Fix schema, regenerate, try again
+```
+
+---
+
+## 🔄 Complete Workflow Example
+
+```bash
+# 1. Read guide
+cat .claude/omnify/guides/omnify/schema-guide.md
+
+# 2. Create schema file
+# schemas/shop/Product.yaml
+
+# 3. Generate code
+npx omnify generate
+
+# 4. Validate (especially for SQL-based requirements)
+cat {{LARAVEL_ROOT}}database/migrations/*_create_products_table.php
+# If wrong: fix schema → regenerate → validate again
+
+# 5. Run migration
+php artisan migrate
+```
+
+---
+
+## 📌 Quick Reference
+
+### Property Types
+
+| Type       | SQL      | TypeScript                |
+| ---------- | -------- | ------------------------- |
+| `String`   | VARCHAR  | `string`                  |
+| `Text`     | TEXT     | `string`                  |
+| `LongText` | LONGTEXT | `string`                  |
+| `Int`      | INT      | `number`                  |
+| `BigInt`   | BIGINT   | `number`                  |
+| `Float`    | DECIMAL  | `number`                  |
+| `Boolean`  | BOOLEAN  | `boolean`                 |
+| `Date`     | DATE     | `string`                  |
+| `DateTime` | DATETIME | `string`                  |
+| `Email`    | VARCHAR  | `string`                  |
+| `Url`      | VARCHAR  | `string`                  |
+| `Json`     | JSON     | `Record<string, unknown>` |
+
+### Japanese Compound Types
+
+| Type                  | Fields Generated                                                                                             |
+| --------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `JapaneseName`        | `{prefix}_lastname`, `{prefix}_firstname`, `{prefix}_kana_lastname`, `{prefix}_kana_firstname`               |
+| `JapaneseAddress`     | `{prefix}_postal_code`, `{prefix}_prefecture`, `{prefix}_address1`, `{prefix}_address2`, `{prefix}_address3` |
+| `JapaneseBankAccount` | `{prefix}_bank_code`, `{prefix}_bank_name`, `{prefix}_branch_code`, etc.                                     |
+
+### Relationship Types
+
+| Relation        | Description | Foreign Key                        |
+| --------------- | ----------- | ---------------------------------- |
+| `belongsTo`     | N:1         | `{property}_id` on this table      |
+| `hasMany`       | 1:N         | `{this_model}_id` on related table |
+| `hasOne`        | 1:1         | `{this_model}_id` on related table |
+| `belongsToMany` | N:N         | Pivot table                        |
+
+---
+
+## ⚠️ Common Mistakes
+
+```yaml
+# ❌ CRITICAL: String defaults with quotes produce CURLY QUOTES!
+default: "'cloud'"     # ❌ Produces: ''cloud'' (broken!)
+default: "'member'"    # ❌ Produces: ''member'' (broken!)
+
+# ✅ CORRECT: Just the value, no quotes wrapper
+default: cloud         # ✅ Produces: 'cloud'
+default: member        # ✅ Produces: 'member'
+
+# ❌ Wrong: Missing displayName for non-English projects
+name:
+  type: String
+  # Missing displayName!
+
+# ✅ Correct: Always add displayName
+name:
+  type: String
+  displayName:
+    ja: 名前
+    en: Name
+
+# ❌ Wrong: Hardcoded enum values in property
+status:
+  type: String
+  enum: [draft, published]  # Don't do this
+
+# ✅ Correct: Create separate enum schema
+status:
+  type: PostStatus  # Reference enum schema
+```
+
+---
+
+## 🔌 Partial Schema (Package Extensions)
+
+Partial schemas allow packages to extend or provide default schemas.
+
+**Target = Filename** (no `target` field needed):
+
+```yaml
+# packages/sso-client/schemas/User.yaml
+kind: partial
+priority: 10  # Lower = higher priority
+
+properties:
+  sso_token:
+    type: String
+    nullable: true
+  console_user_id:
+    type: BigInt
+    nullable: true
+```
+
+### Behavior
+
+| Scenario                    | Result                      |
+| --------------------------- | --------------------------- |
+| Main app has `User.yaml`    | Partial merges into main    |
+| Main app has NO `User.yaml` | Partial becomes User schema |
+
+### Priority System
+
+```yaml
+priority: 10  # High (1-49): Core packages
+priority: 50  # Default: Feature modules  
+priority: 90  # Low (51-100): Customizations
+```
+
+**For detailed guide:** See `.claude/omnify/guides/omnify/partial-schema-guide.md`
+
+---
+
+## 📦 Load Schemas from Laravel Package
+
+Configure additional schema paths in `omnify.config.ts`:
+
+```typescript
+const config: OmnifyConfig = {
+  schemasDir: './schemas',
+
+  // Additional schema paths from packages
+  additionalSchemaPaths: [
+    {
+      path: './packages/your-package/database/schemas',
+      namespace: 'YourPackage',
+    },
+  ],
+
+  // ... other config
+};
+```
+
+Then generate:
+
+```bash
+npx omnify generate
+```

package/dist/knowledge/cursor-rules/validation-rules.mdc.stub

@@ -0,0 +1,181 @@
+---
+description: "Omnify validation rules - Type-specific rules for Zod/Laravel validation"
+globs: ["schemas/**/*.yaml", "schemas/**/*.yml"]
+alwaysApply: false
+---
+
+# Omnify Validation Rules
+
+Validation rules in Omnify schema generate Zod schemas (TypeScript) and Laravel validation rules.
+
+## ⚠️ Important: Type Compatibility
+
+**Each rule is ONLY valid for specific property types!**
+Using a rule on wrong type will cause **schema validation error**.
+
+## Quick Reference
+
+| Rule | Valid Types | Zod Output | Laravel Output |
+|------|-------------|------------|----------------|
+| `required` | **All** | (no `.optional()`) | `required` |
+| `minLength` | String types | `.min(n)` | `min:n` |
+| `maxLength` | String types | `.max(n)` | `max:n` |
+| `url` | String types | `z.url()` | `url` |
+| `uuid` | String types | `z.uuid()` | `uuid` |
+| `ip` | String types | `z.ip()` | `ip` |
+| `ipv4` | String types | `z.ipv4()` | `ipv4` |
+| `ipv6` | String types | `z.ipv6()` | `ipv6` |
+| `alpha` | String types | `.regex()` | `alpha` |
+| `alphaNum` | String types | `.regex()` | `alpha_num` |
+| `alphaDash` | String types | `.regex()` | `alpha_dash` |
+| `numeric` | String types | `.regex()` | `numeric` |
+| `digits` | String types | `.length().regex()` | `digits:n` |
+| `digitsBetween` | String types | `.min().max().regex()` | `digits_between:min,max` |
+| `startsWith` | String types | `.startsWith()` | `starts_with:x` |
+| `endsWith` | String types | `.endsWith()` | `ends_with:x` |
+| `lowercase` | String types | `.refine()` | `lowercase` |
+| `uppercase` | String types | `.refine()` | `uppercase` |
+| `min` | Numeric types | `.gte(n)` | `min:n` |
+| `max` | Numeric types | `.lte(n)` | `max:n` |
+| `between` | Numeric types | `.gte().lte()` | `between:min,max` |
+| `gt` | Numeric types | `.gt(n)` | `gt:n` |
+| `lt` | Numeric types | `.lt(n)` | `lt:n` |
+| `multipleOf` | Numeric types | `.multipleOf(n)` | `multiple_of:n` |
+
+## Type Groups
+
+### String Types
+`String`, `Text`, `MediumText`, `LongText`, `Password`, `Email`
+
+### Numeric Types
+`TinyInt`, `Int`, `BigInt`, `Float`, `Decimal`
+
+## Examples
+
+### ✅ Correct Usage
+
+```yaml
+properties:
+  # String with URL validation
+  website:
+    type: String
+    nullable: true
+    rules:
+      url: true       # ✅ String type → url works
+
+  # String with pattern validation
+  username:
+    type: String
+    rules:
+      minLength: 3
+      maxLength: 20
+      alphaDash: true # ✅ Only letters, numbers, dash, underscore
+      lowercase: true # ✅ Must be lowercase
+
+  # Numeric with range validation
+  quantity:
+    type: Int
+    rules:
+      min: 0          # ✅ Int type → min works
+      max: 1000
+      multipleOf: 5   # ✅ Must be multiple of 5
+
+  # Decimal with precision
+  price:
+    type: Decimal
+    precision: 10
+    scale: 2
+    rules:
+      min: 0.01       # ✅ Decimal is numeric
+      max: 999999.99
+```
+
+### ❌ Wrong Usage (Causes Validation Error)
+
+```yaml
+properties:
+  # WRONG: url on Int
+  port:
+    type: Int
+    rules:
+      url: true       # ❌ ERROR: Int cannot use url rule
+
+  # WRONG: min on String
+  name:
+    type: String
+    rules:
+      min: 5          # ❌ ERROR: String cannot use min rule (use minLength)
+
+  # WRONG: startsWith on Float
+  rate:
+    type: Float
+    rules:
+      startsWith: "0." # ❌ ERROR: Float cannot use startsWith
+```
+
+## Common Patterns
+
+### Password Field
+```yaml
+password:
+  type: Password
+  rules:
+    required: true
+    minLength: 8
+    maxLength: 255
+```
+
+### Slug Field
+```yaml
+slug:
+  type: String
+  length: 100
+  unique: true
+  rules:
+    alphaDash: true
+    lowercase: true
+    minLength: 3
+    maxLength: 100
+```
+
+### Phone Number (String of digits)
+```yaml
+phone:
+  type: String
+  length: 15
+  rules:
+    numeric: true     # Only digits
+    digitsBetween: [10, 15]
+```
+
+### Positive Integer
+```yaml
+quantity:
+  type: Int
+  rules:
+    min: 0
+```
+
+### Percentage (0-100)
+```yaml
+discount:
+  type: Int
+  rules:
+    between: [0, 100]
+```
+
+### Price with Step
+```yaml
+price:
+  type: Decimal
+  precision: 10
+  scale: 2
+  rules:
+    min: 0
+    multipleOf: 0.01
+```
+
+## See Also
+
+- `omnify-schema.mdc` - Full schema reference
+- `schema-create.mdc` - Creating new schemas

package/dist/knowledge/laravel/README.md.stub

@@ -0,0 +1,59 @@
+# Backend Guides
+
+> Laravel 12, PHP 8.4, MySQL 8
+
+## Quick Navigation
+
+| Guide                                | Description                                   |
+| ------------------------------------ | --------------------------------------------- |
+| [architecture.md](./architecture.md) | Design philosophy, when to use Service/Action |
+| [controller.md](./controller.md)     | Thin controller pattern, CRUD template        |
+| [request.md](./request.md)           | Form validation, FormRequest                  |
+| [resource.md](./resource.md)         | API response format, dates                    |
+| [service.md](./service.md)           | When & how to use services                    |
+| [testing.md](./testing.md)           | PEST, 正常系/異常系                           |
+| [openapi.md](./openapi.md)           | Swagger documentation                         |
+| [datetime.md](./datetime.md)         | Carbon, UTC handling                          |
+
+## Related
+
+| Topic                    | Location                                                    |
+| ------------------------ | ----------------------------------------------------------- |
+| **Security rules**       | [/rules/security.md](../../rules/security.md)               |
+| **Performance rules**    | [/rules/performance.md](../../rules/performance.md)         |
+| **Naming conventions**   | [/rules/naming.md](../../rules/naming.md)                   |
+| **Checklist**            | [/checklists/backend.md](../../checklists/backend.md)       |
+| **New feature workflow** | [/workflows/new-feature.md](../../workflows/new-feature.md) |
+
+## Quick Patterns
+
+### Thin Controller
+
+```php
+public function store(UserStoreRequest $request): UserResource
+{
+    return new UserResource(User::create($request->validated()));
+}
+```
+
+### Resource with Dates
+
+```php
+public function toArray($request): array
+{
+    return [
+        'id' => $this->id,
+        'name' => $this->name,
+        'created_at' => $this->created_at?->toISOString(),
+    ];
+}
+```
+
+### When to Use What
+
+| Question                   | Answer          |
+| -------------------------- | --------------- |
+| Simple CRUD?               | Controller only |
+| Multi-step business logic? | Service         |
+| Single reusable action?    | Action class    |
+| Async task?                | Job             |