@famgia/omnify-ai-guides 2.0.15

package/dist/knowledge/cursor-rules/migrations-workflow.mdc.stub

@@ -0,0 +1,224 @@
+---
+description: "Schema-first workflow for database changes. NEVER use php artisan make:migration - always edit schemas/*.yaml and run npx omnify generate instead. This rule enforces the correct workflow when working with migrations."
+globs: ["{{LARAVEL_ROOT}}database/migrations/*.php"]
+alwaysApply: true
+---
+
+# ⛔ STOP: DO NOT CREATE MIGRATIONS MANUALLY
+
+## You MUST use Omnify Schema to create database changes
+
+When you need to modify the database structure, **NEVER** run:
+
+```bash
+# ❌ FORBIDDEN
+php artisan make:migration create_xxx_table
+php artisan make:migration add_xxx_to_xxx_table
+php artisan make:migration modify_xxx_column
+```
+
+---
+
+## ✅ CORRECT WORKFLOW
+
+### Step 1: Create or Edit Schema YAML
+
+```yaml
+# schemas/your-module/YourModel.yaml
+displayName:
+  ja: モデル名
+  en: Model Name
+
+properties:
+  field_name:
+    type: String
+    length: 255
+    displayName:
+      ja: フィールド名
+      en: Field Name
+```
+
+### Step 2: Generate Migrations
+
+```bash
+npx omnify generate
+```
+
+### Step 3: Run Migrations
+
+```bash
+php artisan migrate
+```
+
+---
+
+## Why This Rule Exists
+
+| Manual Migration | Omnify Schema |
+|------------------|---------------|
+| ❌ No TypeScript types | ✅ Auto-generated types |
+| ❌ No i18n labels | ✅ Auto-generated i18n |
+| ❌ No Zod validation | ✅ Auto-generated validation |
+| ❌ No API resources | ✅ Auto-generated API |
+| ❌ Inconsistent naming | ✅ Consistent naming |
+| ❌ Manual model updates | ✅ Auto-updated models |
+
+---
+
+## Schema-First Development Flow
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    SCHEMA YAML (Source of Truth)            │
+│               schemas/module/ModelName.yaml                  │
+└─────────────────────┬───────────────────────────────────────┘
+                      │
+                      ▼ npx omnify generate
+         ┌────────────┴────────────┬─────────────────┐
+         ▼                         ▼                 ▼
+┌─────────────────┐    ┌─────────────────┐   ┌─────────────────┐
+│   Migrations    │    │   Laravel       │   │   TypeScript    │
+│   (PHP)         │    │   Models        │   │   Types/Zod     │
+└─────────────────┘    └─────────────────┘   └─────────────────┘
+         │                         │                 │
+         ▼                         ▼                 ▼
+    php artisan              Ready to use        Frontend ready
+      migrate
+```
+
+---
+
+## 🚨 BEFORE Creating Any Migration
+
+### Ask yourself:
+
+1. **Can this be done with Omnify Schema?**
+   - New table? → Create new YAML schema
+   - New column? → Add property to YAML
+   - New index? → Add `index: true` to property
+   - Foreign key? → Add association to YAML
+
+2. **Is this schema-related?**
+   - YES → Edit YAML, run `npx omnify generate`
+   - NO → Only then consider manual migration
+
+---
+
+## When Manual Migrations ARE Allowed
+
+Only for operations **NOT supported** by Omnify:
+
+```bash
+# ✅ ALLOWED: Data migrations (not schema changes)
+php artisan make:migration migrate_old_data_to_new_format
+
+# ✅ ALLOWED: Complex SQL operations
+php artisan make:migration add_full_text_search_index
+
+# ✅ ALLOWED: Third-party package migrations
+php artisan vendor:publish --tag=package-migrations
+```
+
+**BUT NEVER for standard CRUD tables/columns!**
+
+---
+
+## Quick Reference: Schema vs Manual
+
+| Change Type | Use Omnify Schema | Manual OK |
+|-------------|:-----------------:|:---------:|
+| Create table | ✅ | ❌ |
+| Add column | ✅ | ❌ |
+| Modify column | ✅ | ❌ |
+| Add foreign key | ✅ | ❌ |
+| Add simple index | ✅ | ❌ |
+| Add pivot table | ✅ | ❌ |
+| Add enum column | ✅ | ❌ |
+| Data migration | ❌ | ✅ |
+| Full-text index | ❌ | ✅ |
+| Raw SQL changes | ❌ | ✅ |
+
+---
+
+## How to Add Common Schema Changes
+
+### New Table
+
+```yaml
+# schemas/shop/Product.yaml
+displayName:
+  ja: 商品
+  en: Product
+
+properties:
+  name:
+    type: String
+    length: 255
+  price:
+    type: Decimal
+    precision: 10
+    scale: 2
+```
+
+### New Column to Existing Table
+
+```yaml
+# Edit existing schemas/shop/Product.yaml
+properties:
+  # ... existing properties ...
+  
+  # Add new property
+  sku:
+    type: String
+    length: 50
+    unique: true
+```
+
+### Add Relationship
+
+```yaml
+# schemas/shop/Product.yaml
+associations:
+  category:
+    type: ManyToOne
+    target: Category
+    foreignKey: category_id
+```
+
+### Add Index
+
+```yaml
+properties:
+  email:
+    type: String
+    index: true  # Simple index
+    
+  # Or composite index
+indexes:
+  - columns: [first_name, last_name]
+    unique: true
+```
+
+---
+
+## Remember
+
+> **Schema YAML = Single Source of Truth**
+> 
+> All database structure changes should originate from YAML schemas.
+> The migration files are just **generated output**, not the source.
+
+---
+
+## If You're Unsure
+
+Read the schema guide:
+
+```bash
+cat .cursor/rules/omnify/schema-create.mdc
+# or
+cat schemas/README.md
+```
+
+Or ask:
+> "How do I add [field/table/relationship] using Omnify schema?"

package/dist/knowledge/cursor-rules/model-editable.mdc.stub

@@ -0,0 +1,120 @@
+---
+description: "User-editable Eloquent models. MUST read corresponding BaseModel before editing to avoid duplicating auto-generated code."
+globs: ["{{LARAVEL_BASE}}/Models/*.php"]
+alwaysApply: true
+---
+
+# Model Editing Rules
+
+These are **user-editable** model files that extend auto-generated BaseModels.
+
+## ⚠️ BEFORE EDITING - MANDATORY STEPS
+
+### 1. Read the BaseModel First
+
+Before editing `Post.php`, you **MUST** read `OmnifyBase/PostBaseModel.php` to understand:
+- What relations already exist
+- What `$fillable`, `$hidden`, `$casts` are defined
+- What traits are already used
+
+### 2. Check for Existing Features
+
+| Feature | Check in BaseModel | If exists, DO NOT duplicate |
+|---------|-------------------|----------------------------|
+| Relations | `author()`, `category()` | ❌ Already defined |
+| Fillable | `$fillable` array | ❌ Already defined |
+| Casts | `casts()` method | ❌ Already defined |
+| Traits | `use SoftDeletes` | ❌ Already used |
+
+## ❌ NEVER DUPLICATE
+
+```php
+// These are ALREADY in PostBaseModel - NEVER recreate!
+public function author() { ... }      // ❌ Duplicate
+public function category() { ... }    // ❌ Duplicate
+public function tags() { ... }        // ❌ Duplicate
+protected $fillable = [...]           // ❌ Duplicate
+protected function casts(): array     // ❌ Duplicate
+```
+
+## ✅ ONLY ADD Custom Logic
+
+```php
+class Post extends PostBaseModel
+{
+    // ✅ Custom query scopes
+    public function scopePublished($query)
+    {
+        return $query->where('status', 'published');
+    }
+
+    public function scopeFeatured($query)
+    {
+        return $query->whereNotNull('featured_image');
+    }
+
+    // ✅ Custom accessors (computed properties)
+    public function getReadTimeAttribute(): int
+    {
+        return (int) ceil(str_word_count($this->content) / 200);
+    }
+
+    public function getIsPublishedAttribute(): bool
+    {
+        return $this->status === 'published';
+    }
+
+    // ✅ Business logic methods
+    public function publish(): void
+    {
+        $this->update([
+            'status' => 'published',
+            'published_at' => now(),
+        ]);
+    }
+
+    // ✅ Custom relations NOT in schema
+    public function relatedPosts()
+    {
+        return $this->hasMany(Post::class, 'category_id', 'category_id')
+            ->where('id', '!=', $this->id);
+    }
+
+    // ✅ Event hooks
+    protected static function booted(): void
+    {
+        static::creating(function ($post) {
+            $post->slug = Str::slug($post->title);
+        });
+    }
+}
+```
+
+## Built-in Features from BaseModel
+
+### Localization (via HasLocalizedDisplayName trait)
+
+```php
+// Available on ALL models - use these instead of creating your own!
+Post::displayName('ja')                     // "投稿"
+Post::propertyDisplayName('title', 'ja')    // "タイトル"
+Post::allPropertyDisplayNamesForLocale('ja')
+```
+
+## Need to Add New Fields?
+
+**DO NOT** add to `$fillable` here. Instead:
+
+1. Edit schema YAML in `schemas/`
+2. Run `npx omnify generate`
+3. Run `php artisan migrate`
+
+The BaseModel will be updated automatically.
+
+## Quick Checklist Before Saving
+
+- [ ] Read `OmnifyBase/{Model}BaseModel.php` first
+- [ ] Not duplicating any relation from BaseModel
+- [ ] Not duplicating `$fillable`, `$hidden`, `$casts`
+- [ ] Only adding custom scopes, accessors, or business logic
+- [ ] Using `parent::booted()` if overriding `booted()`

package/dist/knowledge/cursor-rules/omnify-migrations.mdc.stub

@@ -0,0 +1,109 @@
+---
+description: "STOP! These are auto-generated Omnify migrations. DO NOT EDIT these files - edit schemas/*.yaml instead and run npx omnify generate"
+globs: ["{{LARAVEL_ROOT}}database/migrations/omnify/**/*.php"]
+alwaysApply: true
+---
+
+# ⛔ CRITICAL: DO NOT EDIT OMNIFY MIGRATIONS
+
+## These files are AUTO-GENERATED
+
+All files in `{{LARAVEL_ROOT}}database/migrations/omnify/` are automatically generated by Omnify.
+
+**ANY MANUAL CHANGES WILL BE OVERWRITTEN** when running `npx omnify generate`.
+
+---
+
+## ❌ ABSOLUTELY FORBIDDEN
+
+```php
+// NEVER modify files in {{LARAVEL_ROOT}}database/migrations/omnify/
+// Even "simple fixes" will be lost!
+```
+
+| Action | Result |
+|--------|--------|
+| Add column manually | ❌ Overwritten on next generate |
+| Modify column type | ❌ Overwritten on next generate |
+| Add index manually | ❌ Overwritten on next generate |
+| Fix "typo" | ❌ Overwritten on next generate |
+
+---
+
+## ✅ CORRECT APPROACH
+
+### 1. Edit the YAML Schema
+
+```yaml
+# schemas/auth/User.yaml
+properties:
+  # Add or modify properties HERE
+  new_field:
+    type: String
+    length: 100
+```
+
+### 2. Regenerate Migrations
+
+```bash
+npx omnify generate
+php artisan migrate
+```
+
+---
+
+## Need Custom Migration?
+
+For changes NOT supported by Omnify schemas:
+
+1. Create migration **OUTSIDE** the `omnify/` folder:
+
+```bash
+php artisan make:migration add_custom_field_to_users_table
+# Creates: database/migrations/2026_01_12_000000_add_custom_field_to_users_table.php
+# This is SAFE - Omnify won't touch it
+```
+
+2. Keep the omnify/ folder untouched
+
+---
+
+## Folder Structure
+
+```
+database/migrations/
+├── omnify/                    ← ⛔ AUTO-GENERATED - DO NOT EDIT
+│   ├── 2026_01_01_000000_create_users_table.php
+│   ├── 2026_01_01_000001_create_posts_table.php
+│   └── ...
+├── 2026_01_12_120000_add_custom_field.php  ← ✅ Safe to edit
+└── 2026_01_12_130000_custom_migration.php  ← ✅ Safe to edit
+```
+
+---
+
+## Quick Reference
+
+| Want to... | Do this |
+|------------|---------|
+| Add column | Edit schema YAML → `npx omnify generate` |
+| Modify column | Edit schema YAML → `npx omnify generate` |
+| Add index | Edit schema YAML → `npx omnify generate` |
+| Custom migration | `php artisan make:migration` (outside omnify/) |
+| Fix generation bug | Report issue or edit Omnify plugin |
+
+---
+
+## If You See This Warning
+
+If a file has this header:
+
+```php
+/**
+ * DO NOT EDIT - This file is auto-generated by Omnify.
+ * Any changes will be overwritten on next generation.
+ * ...
+ */
+```
+
+**STOP!** Do not edit this file. Edit the schema YAML instead.