@famgia/omnify-laravel 0.0.113 → 0.0.115

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@famgia/omnify-laravel",
-  "version": "0.0.113",
+  "version": "0.0.115",
   "description": "Laravel migration and TypeScript type generator for omnify-schema",
   "type": "module",
   "main": "./dist/index.js",
@@ -25,9 +25,9 @@
     "README.md"
   ],
   "dependencies": {
-    "@famgia/omnify-types": "0.0.102",
-    "@famgia/omnify-core": "0.0.104",
-    "@famgia/omnify-atlas": "0.0.98"
+    "@famgia/omnify-types": "0.0.104",
+    "@famgia/omnify-atlas": "0.0.100",
+    "@famgia/omnify-core": "0.0.106"
   },
   "scripts": {
     "build": "tsup",

package/stubs/ai-guides/cursor/laravel-controller.mdc.stub

@@ -32,7 +32,7 @@ Route::get('/users', [UserController::class, 'index']);
 | `api.php` | `/api` | `/users` | `/users` |
 | `web.php` | (none) | `/dashboard` | `/dashboard` |
 
-**Full guide:** `.claude/guides/laravel/openapi.md`
+**Full guide:** `.claude/omnify/guides/laravel/openapi.md`
 
 ---
 

package/stubs/ai-guides/cursor/laravel-testing.mdc.stub

@@ -7,7 +7,7 @@ alwaysApply: false
 # Testing Rules (PEST)
 
 > **Agent:** Act as **@tester** agent
-> - Read `.claude/guides/laravel/testing.md` for full guide
+> - Read `.claude/omnify/guides/laravel/testing.md` for full guide
 
 ## How to Run Tests
 

package/stubs/ai-guides/cursor/laravel.mdc.stub

@@ -6,7 +6,8 @@ alwaysApply: false
 
 # Laravel Rules
 
-> **Documentation:** `.claude/guides/laravel/`
+> **Documentation:** `.claude/omnify/guides/laravel/`
+> **Team Migration Guide:** `.claude/omnify/guides/laravel/migrations-team.md`
 > **Specific Rules:** See also `laravel-controller.mdc`, `laravel-resource.mdc`, `laravel-request.mdc`, `laravel-testing.mdc`, `migrations-workflow.mdc`, `omnify-migrations.mdc`
 
 ## ⛔ CRITICAL: DO NOT EDIT
@@ -76,6 +77,32 @@ See `migrations-workflow.mdc` for complete guide.
 | Reusable action  | Action class       |
 | Async task       | Job                |
 
+## Authentication Models
+
+When `authenticatable: true` is set in schema, model extends `Authenticatable`:
+
+```yaml
+# schemas/auth/User.yaml
+options:
+  authenticatable: true
+  authenticatableLoginIdField: email
+  authenticatablePasswordField: password
+  authenticatableGuardName: web  # Optional: for multi-guard
+```
+
+**Required `config/auth.php` for custom guards:**
+
+```php
+'guards' => [
+    'admin' => ['driver' => 'session', 'provider' => 'admins'],
+],
+'providers' => [
+    'admins' => ['driver' => 'eloquent', 'model' => App\Models\Admin::class],
+],
+```
+
+**See:** `.claude/omnify/guides/omnify/schema-guide.md` → "Authenticatable Option - Detailed Guide"
+
 ## Pre-Edit Checklist
 
 **BEFORE editing any file, MUST:**
@@ -108,4 +135,4 @@ public function store(): JsonResponse
 | "Improve" unrelated code            | Change only what's needed |
 | Build for future "just in case"     | YAGNI - build when needed |
 
-**Full examples:** `.claude/guides/laravel/architecture.md`
+**Full examples:** `.claude/omnify/guides/laravel/architecture.md`

package/stubs/ai-guides/laravel/authentication.md.stub

@@ -0,0 +1,588 @@
+# Laravel Authentication with Omnify
+
+> Complete guide for implementing authentication using Omnify-generated models.
+
+## Overview
+
+When you set `authenticatable: true` in your schema, Omnify generates a Laravel model that:
+
+1. Extends `Illuminate\Foundation\Auth\User` (alias `Authenticatable`)
+2. Includes the `Notifiable` trait
+3. Auto-hides password and remember_token fields
+4. Works with Laravel's built-in auth system
+
+## Schema Configuration
+
+### Basic User Schema
+
+```yaml
+name: User
+displayName:
+  ja: ユーザー
+  en: User
+options:
+  timestamps: true
+  softDelete: true
+  authenticatable: true
+  authenticatableLoginIdField: email     # Field for login
+  authenticatablePasswordField: password # Field for password
+  # authenticatableGuardName: web        # Optional: guard name
+
+properties:
+  email:
+    type: Email
+    unique: true
+  password:
+    type: Password
+  name:
+    type: String
+```
+
+### Multi-Guard Setup (Admin + User)
+
+For separate admin and user authentication:
+
+**User Schema:**
+```yaml
+name: User
+options:
+  authenticatable: true
+  authenticatableGuardName: web
+
+properties:
+  email:
+    type: Email
+    unique: true
+  password:
+    type: Password
+  name:
+    type: String
+```
+
+**Admin Schema:**
+```yaml
+name: Admin
+options:
+  authenticatable: true
+  authenticatableGuardName: admin  # Different guard
+
+properties:
+  email:
+    type: Email
+    unique: true
+  password:
+    type: Password
+  name:
+    type: String
+  role:
+    type: EnumRef
+    enum: AdminRole
+```
+
+## Laravel Configuration
+
+### config/auth.php
+
+```php
+<?php
+
+return [
+    'defaults' => [
+        'guard' => 'web',
+        'passwords' => 'users',
+    ],
+
+    'guards' => [
+        'web' => [
+            'driver' => 'session',
+            'provider' => 'users',
+        ],
+        'admin' => [  // For Admin model
+            'driver' => 'session',
+            'provider' => 'admins',
+        ],
+        'api' => [    // For API authentication
+            'driver' => 'sanctum',
+            'provider' => 'users',
+        ],
+    ],
+
+    'providers' => [
+        'users' => [
+            'driver' => 'eloquent',
+            'model' => App\Models\User::class,
+        ],
+        'admins' => [  // For Admin model
+            'driver' => 'eloquent',
+            'model' => App\Models\Admin::class,
+        ],
+    ],
+
+    'passwords' => [
+        'users' => [
+            'provider' => 'users',
+            'table' => 'password_reset_tokens',
+            'expire' => 60,
+            'throttle' => 60,
+        ],
+        'admins' => [  // For Admin password reset
+            'provider' => 'admins',
+            'table' => 'password_reset_tokens',
+            'expire' => 60,
+            'throttle' => 60,
+        ],
+    ],
+
+    'password_timeout' => env('AUTH_PASSWORD_TIMEOUT', 10800),
+];
+```
+
+## Generated Model Structure
+
+### Base Model (Auto-generated, DO NOT EDIT)
+
+```php
+// app/Models/Base/UserBaseModel.php
+<?php
+
+namespace App\Models\Base;
+
+use Illuminate\Foundation\Auth\User as Authenticatable;
+use Illuminate\Notifications\Notifiable;
+
+/**
+ * DO NOT EDIT - This file is auto-generated by Omnify.
+ * Any changes will be overwritten on next generation.
+ */
+class UserBaseModel extends Authenticatable
+{
+    use Notifiable;
+    use HasLocalizedDisplayName;
+
+    protected $table = 'users';
+    protected $primaryKey = 'id';
+    public $timestamps = true;
+
+    protected $fillable = [
+        'email',
+        'password',
+        'name',
+    ];
+
+    protected $hidden = [
+        'password',
+        'remember_token',
+    ];
+
+    protected function casts(): array
+    {
+        return [
+            'email_verified_at' => 'datetime',
+            'password' => 'hashed',
+        ];
+    }
+}
+```
+
+### Your Model (Customizable)
+
+```php
+// app/Models/User.php
+<?php
+
+namespace App\Models;
+
+use App\Models\Base\UserBaseModel;
+
+class User extends UserBaseModel
+{
+    // Add your custom methods here
+    
+    public function posts(): HasMany
+    {
+        return $this->hasMany(Post::class);
+    }
+    
+    public function profile(): HasOne
+    {
+        return $this->hasOne(UserProfile::class);
+    }
+    
+    // Custom scopes
+    public function scopeActive($query)
+    {
+        return $query->where('status', 'active');
+    }
+    
+    // Custom accessors
+    public function getFullNameAttribute(): string
+    {
+        return $this->name;
+    }
+}
+```
+
+## Authentication Controllers
+
+### Login Controller
+
+```php
+<?php
+
+namespace App\Http\Controllers\Auth;
+
+use App\Http\Controllers\Controller;
+use App\Http\Requests\Auth\LoginRequest;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Support\Facades\Auth;
+
+class LoginController extends Controller
+{
+    public function store(LoginRequest $request): JsonResponse
+    {
+        $request->authenticate();
+        $request->session()->regenerate();
+
+        return response()->json([
+            'user' => Auth::user(),
+            'message' => 'ログインしました',
+        ]);
+    }
+
+    public function destroy(): JsonResponse
+    {
+        Auth::guard('web')->logout();
+        request()->session()->invalidate();
+        request()->session()->regenerateToken();
+
+        return response()->json([
+            'message' => 'ログアウトしました',
+        ]);
+    }
+}
+```
+
+### Login Request
+
+```php
+<?php
+
+namespace App\Http\Requests\Auth;
+
+use Illuminate\Auth\Events\Lockout;
+use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Support\Facades\Auth;
+use Illuminate\Support\Facades\RateLimiter;
+use Illuminate\Support\Str;
+use Illuminate\Validation\ValidationException;
+
+class LoginRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    public function rules(): array
+    {
+        return [
+            'email' => ['required', 'string', 'email'],
+            'password' => ['required', 'string'],
+        ];
+    }
+
+    public function authenticate(): void
+    {
+        $this->ensureIsNotRateLimited();
+
+        if (! Auth::attempt($this->only('email', 'password'), $this->boolean('remember'))) {
+            RateLimiter::hit($this->throttleKey());
+
+            throw ValidationException::withMessages([
+                'email' => __('auth.failed'),
+            ]);
+        }
+
+        RateLimiter::clear($this->throttleKey());
+    }
+
+    protected function ensureIsNotRateLimited(): void
+    {
+        if (! RateLimiter::tooManyAttempts($this->throttleKey(), 5)) {
+            return;
+        }
+
+        event(new Lockout($this));
+
+        $seconds = RateLimiter::availableIn($this->throttleKey());
+
+        throw ValidationException::withMessages([
+            'email' => trans('auth.throttle', [
+                'seconds' => $seconds,
+                'minutes' => ceil($seconds / 60),
+            ]),
+        ]);
+    }
+
+    protected function throttleKey(): string
+    {
+        return Str::transliterate(Str::lower($this->string('email')).'|'.$this->ip());
+    }
+}
+```
+
+## API Authentication (Laravel Sanctum)
+
+### Install Sanctum
+
+```bash
+composer require laravel/sanctum
+php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"
+php artisan migrate
+```
+
+### Add to User Model
+
+```php
+// app/Models/User.php
+use Laravel\Sanctum\HasApiTokens;
+
+class User extends UserBaseModel
+{
+    use HasApiTokens;  // Add this trait
+    
+    // ...
+}
+```
+
+### API Login Controller
+
+```php
+<?php
+
+namespace App\Http\Controllers\Api\Auth;
+
+use App\Http\Controllers\Controller;
+use App\Models\User;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Hash;
+use Illuminate\Validation\ValidationException;
+
+class TokenController extends Controller
+{
+    public function store(Request $request): JsonResponse
+    {
+        $request->validate([
+            'email' => 'required|email',
+            'password' => 'required',
+            'device_name' => 'required',
+        ]);
+
+        $user = User::where('email', $request->email)->first();
+
+        if (! $user || ! Hash::check($request->password, $user->password)) {
+            throw ValidationException::withMessages([
+                'email' => [__('auth.failed')],
+            ]);
+        }
+
+        return response()->json([
+            'token' => $user->createToken($request->device_name)->plainTextToken,
+            'user' => $user,
+        ]);
+    }
+
+    public function destroy(Request $request): JsonResponse
+    {
+        $request->user()->currentAccessToken()->delete();
+
+        return response()->json(['message' => 'Token revoked']);
+    }
+}
+```
+
+## Routes Configuration
+
+### Web Routes (routes/web.php)
+
+```php
+use App\Http\Controllers\Auth\LoginController;
+
+Route::middleware('guest')->group(function () {
+    Route::post('/login', [LoginController::class, 'store']);
+});
+
+Route::middleware('auth')->group(function () {
+    Route::post('/logout', [LoginController::class, 'destroy']);
+});
+```
+
+### API Routes (routes/api.php)
+
+```php
+use App\Http\Controllers\Api\Auth\TokenController;
+
+Route::post('/tokens', [TokenController::class, 'store']);
+
+Route::middleware('auth:sanctum')->group(function () {
+    Route::delete('/tokens', [TokenController::class, 'destroy']);
+    
+    Route::get('/user', function (Request $request) {
+        return $request->user();
+    });
+});
+```
+
+## Multi-Guard Middleware
+
+### Admin-Only Routes
+
+```php
+Route::middleware('auth:admin')->prefix('admin')->group(function () {
+    Route::get('/dashboard', [AdminDashboardController::class, 'index']);
+});
+```
+
+### Admin Login Controller
+
+```php
+public function store(AdminLoginRequest $request): JsonResponse
+{
+    if (! Auth::guard('admin')->attempt($request->only('email', 'password'))) {
+        throw ValidationException::withMessages([
+            'email' => __('auth.failed'),
+        ]);
+    }
+
+    $request->session()->regenerate();
+
+    return response()->json([
+        'admin' => Auth::guard('admin')->user(),
+    ]);
+}
+```
+
+## Common Patterns
+
+### Check Authentication
+
+```php
+// In controller
+if (Auth::check()) {
+    $user = Auth::user();
+}
+
+// In middleware
+Route::middleware('auth')->group(function () {
+    // Protected routes
+});
+
+// In Blade
+@auth
+    Welcome, {{ Auth::user()->name }}
+@endauth
+```
+
+### Get Current User
+
+```php
+// Via Auth facade
+$user = Auth::user();
+$userId = Auth::id();
+
+// Via request
+$user = $request->user();
+
+// Via helper
+$user = auth()->user();
+```
+
+### Password Hashing
+
+```php
+// Hash password (automatic in Omnify models via cast)
+$user->password = 'plain-text';  // Auto-hashed by 'hashed' cast
+$user->save();
+
+// Manual hashing if needed
+use Illuminate\Support\Facades\Hash;
+$hashed = Hash::make('plain-text');
+
+// Verify password
+if (Hash::check('plain-text', $user->password)) {
+    // Correct
+}
+```
+
+## Testing Authentication
+
+```php
+use App\Models\User;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+
+class AuthTest extends TestCase
+{
+    use RefreshDatabase;
+
+    public function test_user_can_login(): void
+    {
+        $user = User::factory()->create([
+            'email' => 'test@example.com',
+            'password' => 'password',
+        ]);
+
+        $response = $this->postJson('/login', [
+            'email' => 'test@example.com',
+            'password' => 'password',
+        ]);
+
+        $response->assertOk();
+        $this->assertAuthenticated();
+    }
+
+    public function test_authenticated_user_can_access_protected_route(): void
+    {
+        $user = User::factory()->create();
+
+        $response = $this->actingAs($user)
+            ->getJson('/api/user');
+
+        $response->assertOk();
+    }
+
+    public function test_guest_cannot_access_protected_route(): void
+    {
+        $response = $this->getJson('/api/user');
+
+        $response->assertUnauthorized();
+    }
+}
+```
+
+## Future: Trait-based Authentication
+
+> **Coming Soon:** In future versions, Omnify may support a trait-based approach:
+>
+> ```php
+> use Illuminate\Database\Eloquent\Model;
+> use Illuminate\Auth\Authenticatable;
+> use Illuminate\Contracts\Auth\Authenticatable as AuthenticatableContract;
+>
+> class UserBaseModel extends Model implements AuthenticatableContract
+> {
+>     use Authenticatable;  // Trait instead of extending class
+> }
+> ```
+>
+> This will provide more flexibility in model inheritance while maintaining 
+> full authentication support.
+
+## Summary
+
+| Option | Type | Default | When to Use |
+|--------|------|---------|-------------|
+| `authenticatable` | boolean | `false` | User can login |
+| `authenticatableLoginIdField` | string | `email` | Custom login field |
+| `authenticatablePasswordField` | string | `password` | Custom password field |
+| `authenticatableGuardName` | string | (none) | Multi-guard setup |

package/stubs/ai-guides/laravel/migrations-team.md.stub

@@ -0,0 +1,376 @@
+# Migration Team Workflow Guide
+
+> Best practices for managing database migrations in team development environments.
+
+## Overview
+
+Omnify follows **international standards** for database migration management:
+
+1. **Schema as Source of Truth** - YAML schemas define the database structure
+2. **Simple File Tracking** - Lock file tracks migrations for regeneration
+3. **CI Validation** - Automated checks ensure sync between schema and migrations
+4. **Git for Conflict Resolution** - Standard Git workflow handles merge conflicts
+
+## Migration Tracking System
+
+### Lock File Structure
+
+The `.omnify.lock` file tracks all generated migrations:
+
+```json
+{
+  "version": 2,
+  "migrations": [
+    {
+      "fileName": "2026_01_13_100000_create_users_table.php",
+      "timestamp": "2026_01_13_100000",
+      "tableName": "users",
+      "type": "create",
+      "generatedAt": "2026-01-13T10:00:00Z",
+      "schemas": ["User"],
+      "checksum": "sha256..."
+    }
+  ]
+}
+```
+
+### Key Fields
+
+| Field | Purpose |
+|-------|---------|
+| `fileName` | Full migration filename |
+| `timestamp` | Timestamp prefix for regeneration |
+| `tableName` | Table name for lookup |
+| `type` | Migration type (create/alter/drop/pivot) |
+| `checksum` | SHA-256 hash for integrity verification |
+
+## CI/CD Integration
+
+### GitHub Actions Example
+
+```yaml
+# .github/workflows/migration-check.yml
+name: Migration Check
+
+on: [push, pull_request]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          
+      - name: Install dependencies
+        run: npm ci
+        
+      - name: Check migrations sync
+        run: npx omnify generate --check
+        
+      - name: Test migrations (optional)
+        run: |
+          php artisan migrate:fresh --force
+          php artisan migrate:status
+```
+
+### CI Check Mode
+
+```bash
+# Check if migrations are in sync (for CI)
+npx omnify generate --check
+
+# Exit codes:
+# 0 = All migrations in sync ✅
+# 1 = Schema changes detected or migration issues ❌
+```
+
+Output example:
+```
+Omnify v1.0.113 - Generating Outputs
+
+✔ Loading schemas from schemas
+✔ Validating schemas...
+✔ Checking for changes...
+
+CI Check Mode Results:
+  Schemas: 12
+  Tracked migrations: 15
+  Migrations on disk: 15
+  Schema changes: 0
+
+✅ All migrations in sync
+```
+
+## Team Development Workflow
+
+### Standard Workflow
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  1. Edit YAML Schema                                        │
+│     schemas/module/Model.yaml                               │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│  2. Generate Migrations                                     │
+│     npx omnify generate                                     │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│  3. Commit Both                                             │
+│     git add schemas/ database/migrations/ .omnify.lock      │
+│     git commit -m "feat: add phone field to User"           │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│  4. CI Validates                                            │
+│     GitHub Actions runs: npx omnify generate --check        │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│  5. Merge & Deploy                                          │
+│     php artisan migrate                                     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Parallel Development
+
+When multiple developers work on different schemas:
+
+```
+Developer A                    Developer B
+    │                              │
+Edit User.yaml                Edit Product.yaml
+(add phone)                   (add sku)
+    │                              │
+omnify generate               omnify generate
+    │                              │
+Creates:                      Creates:
+alter_users_add_phone.php     alter_products_add_sku.php
+    │                              │
+    └──────────┬───────────────────┘
+               │
+          Git Merge
+               │
+    Both migrations exist ✅
+    (different tables, no conflict)
+```
+
+### Same Schema Conflict
+
+When multiple developers edit the SAME schema:
+
+```
+Developer A                    Developer B
+    │                              │
+Edit User.yaml                Edit User.yaml
+(add phone)                   (add address)
+    │                              │
+omnify generate               omnify generate
+    │                              │
+    └──────────┬───────────────────┘
+               │
+          Git Merge
+               │
+        ⚠️ YAML Conflict!
+               │
+    ┌──────────┴──────────┐
+    │                     │
+Resolve YAML            Keep both migrations
+(merge both fields)     (Laravel runs both)
+    │                     │
+    └──────────┬──────────┘
+               │
+           Result:
+    User.yaml has phone + address
+    Both migrations exist
+    Laravel runs in timestamp order ✅
+```
+
+## Handling Common Scenarios
+
+### Scenario 1: Accidentally Deleted Migration
+
+**Problem:** Migration file deleted but lock file still tracks it.
+
+**Detection:**
+```bash
+npx omnify generate
+
+⚠️  Migration file issues detected:
+  Missing files (1):
+    - 2026_01_13_100000_create_users_table.php
+```
+
+**Solutions:**
+```bash
+# Option 1: Restore from git
+git checkout -- database/migrations/omnify/
+
+# Option 2: Reset and regenerate (destructive!)
+npx omnify reset --migrations
+npx omnify generate --force
+```
+
+### Scenario 2: Stale Migration from Old Branch
+
+**Problem:** Branch created 1 month ago, merged today with old timestamp.
+
+**Detection:**
+```bash
+npx omnify generate
+
+⚠️  Stale migrations detected (old timestamp, not in lock file):
+    - 2026_01_04_100000_add_phone_to_users_table.php
+  These may be from merged branches. Review before running migrate.
+```
+
+**Action:**
+1. Review the migration - is it independent or dependent?
+2. If independent: Keep as-is, Laravel runs in timestamp order
+3. If dependent: Consider renaming with new timestamp
+
+### Scenario 3: CI Fails with "Schema changes detected"
+
+**Problem:** Someone edited schema but forgot to run generate.
+
+**Detection:**
+```bash
+npx omnify generate --check
+
+❌ Schema changes detected - run "npx omnify generate" to update migrations
+```
+
+**Solution:**
+```bash
+# Locally
+npx omnify generate
+git add .
+git commit --amend  # or new commit
+git push --force    # or regular push
+```
+
+## Best Practices
+
+### DO ✅
+
+1. **Always commit schema + migrations together**
+   ```bash
+   git add schemas/ database/migrations/omnify/ .omnify.lock
+   git commit -m "feat: add field to schema"
+   ```
+
+2. **Use CI to validate migrations**
+   ```bash
+   npx omnify generate --check
+   ```
+
+3. **Pull and migrate before starting new work**
+   ```bash
+   git pull
+   php artisan migrate
+   ```
+
+4. **Review stale migration warnings**
+   - Check dependencies before merging old branches
+
+### DON'T ❌
+
+1. **Don't manually edit migrations in `omnify/` folder**
+   - They will be overwritten!
+
+2. **Don't ignore CI failures**
+   - Always run `npx omnify generate` if CI fails
+
+3. **Don't commit migrations without schemas**
+   - Schema is source of truth
+
+4. **Don't skip stale warnings without review**
+   - Old timestamps might run before dependent migrations
+
+## Migration Validation
+
+### Check Commands
+
+```bash
+# Full check (for CI)
+npx omnify generate --check
+
+# Generate with stale warnings (default)
+npx omnify generate
+
+# Generate without stale warnings
+npx omnify generate --no-warn-stale
+
+# Force regenerate everything
+npx omnify generate --force
+```
+
+### Validation Checks
+
+| Check | Description | Exit Code |
+|-------|-------------|-----------|
+| Schema sync | Schema matches generated migrations | 1 if mismatch |
+| Missing files | Migration files exist on disk | 1 if missing |
+| Modified files | Files match stored checksum | Warning only |
+| Stale files | Old timestamp, not tracked | Warning only |
+
+## Troubleshooting
+
+### "Missing migration files"
+
+```bash
+# Check what's missing
+npx omnify generate --check
+
+# Restore from git
+git checkout -- database/migrations/omnify/
+
+# Or reset completely
+npx omnify reset --migrations
+npx omnify generate --force
+```
+
+### "Checksum mismatch"
+
+Someone manually edited an auto-generated file.
+
+```bash
+# Option 1: Regenerate
+npx omnify generate --force
+
+# Option 2: Reset lock file entry
+# (manually edit .omnify.lock to remove the entry)
+```
+
+### "Stale migrations"
+
+Old branch merged with old timestamps.
+
+```bash
+# Usually safe to ignore if migrations are independent
+# But review the migration order:
+
+php artisan migrate:status
+# Check: Will the old migration run before something it depends on?
+```
+
+## Summary
+
+| Workflow Step | Command |
+|---------------|---------|
+| Edit schema | Edit `schemas/*.yaml` |
+| Generate | `npx omnify generate` |
+| Commit | `git add schemas/ database/migrations/ .omnify.lock` |
+| CI Check | `npx omnify generate --check` |
+| Deploy | `php artisan migrate` |
+| Restore | `git checkout -- database/migrations/omnify/` |
+| Reset | `npx omnify reset --migrations` |