@famgia/omnify-ai-guides 2.0.15

package/dist/knowledge/omnify/partial-schema-guide.md.stub

@@ -0,0 +1,353 @@
+# Partial Schema Guide
+
+## Overview
+
+Partial schemas (`kind: partial`) allow packages to extend or provide default schemas without modifying main application files.
+
+```yaml
+# packages/sso-client/schemas/User.yaml
+kind: partial
+priority: 10
+
+properties:
+  sso_token:
+    type: String
+    nullable: true
+```
+
+## Key Concepts
+
+### Target is Inferred from Filename
+
+**No `target` field needed.** The target schema is determined by the filename:
+
+```
+User.yaml → targets User schema
+Permission.yaml → targets Permission schema
+Team.yaml → targets Team schema
+```
+
+### Merge Behavior
+
+| Scenario                                                        | Result                      |
+| --------------------------------------------------------------- | --------------------------- |
+| Main app has `User.yaml` + Package has `User.yaml` (partial)    | Merge into main User        |
+| Main app has NO `User.yaml` + Package has `User.yaml` (partial) | Partial becomes User schema |
+| Multiple packages have `User.yaml` (partial)                    | Merge via priority          |
+
+## Priority System
+
+Lower number = Higher priority = Merged first = Wins conflicts
+
+```yaml
+kind: partial
+priority: 10  # High priority (1-49)
+priority: 50  # Default priority
+priority: 90  # Low priority (51-100)
+```
+
+### Priority Ranges
+
+| Range  | Use For                   |
+| ------ | ------------------------- |
+| 1-20   | Core system packages      |
+| 21-40  | Feature modules           |
+| 41-60  | Business logic extensions |
+| 61-80  | Tenant customizations     |
+| 81-100 | Development/testing       |
+
+## Use Cases
+
+### 1. Package Provides Default Schema
+
+SSO package provides default User schema if main app has none:
+
+```yaml
+# packages/sso-client/schemas/User.yaml
+kind: partial
+priority: 10
+
+displayName:
+  ja: ユーザー
+  en: User
+
+options:
+  timestamps: true
+  authenticatable: true
+
+properties:
+  email:
+    type: Email
+    unique: true
+  name:
+    type: String
+  console_user_id:
+    type: BigInt
+    nullable: true
+```
+
+**Result:**
+- Apps WITH existing User.yaml → SSO fields merge into their User
+- Apps WITHOUT User.yaml → Package's User becomes the User schema
+
+### 2. Package Extends Existing Schema
+
+Add fields to main app's User:
+
+```yaml
+# packages/billing/schemas/User.yaml
+kind: partial
+priority: 50
+
+properties:
+  stripe_customer_id:
+    type: String
+    nullable: true
+  subscription_status:
+    type: String
+    nullable: true
+```
+
+**Result:** User schema has all original properties + billing properties
+
+### 3. Multiple Packages Extend Same Schema
+
+```
+Main App: schemas/auth/User.yaml (regular schema)
+├─ SSO Package: User.yaml (partial, priority: 10)
+└─ Billing Package: User.yaml (partial, priority: 50)
+```
+
+**Merge Order:**
+1. SSO Package (priority 10) merges first
+2. Billing Package (priority 50) merges second
+3. Main app properties always win over partials
+
+## Configuration
+
+### omnify.config.ts
+
+```typescript
+const config: OmnifyConfig = {
+  schemasDir: './schemas',
+
+  additionalSchemaPaths: [
+    {
+      path: './packages/sso-client/database/schemas',
+      namespace: 'Sso',
+      // Optional: Package-specific output
+      output: {
+        laravel: {
+          base: './packages/sso-client',
+          modelsNamespace: 'Vendor\\SsoClient\\Models',
+          modelsPath: 'src/Models',
+        },
+      },
+    },
+  ],
+};
+```
+
+## File Structure Examples
+
+### Package with Partial Schemas
+
+```
+packages/sso-client/
+├── database/
+│   └── schemas/
+│       ├── User.yaml          # kind: partial (extends/provides User)
+│       ├── Permission.yaml    # kind: partial (provides Permission)
+│       ├── Role.yaml          # regular schema (package-only)
+│       └── RolePermission.yaml
+├── src/
+│   └── Models/
+└── composer.json
+```
+
+### Main App Schemas
+
+```
+schemas/
+├── auth/
+│   └── User.yaml              # Main User schema (takes priority)
+├── blog/
+│   ├── Post.yaml
+│   └── Comment.yaml
+└── shop/
+    └── Product.yaml
+```
+
+## Property Merge Rules
+
+| Scenario                      | Result                       |
+| ----------------------------- | ---------------------------- |
+| Property only in main         | Main property used           |
+| Property only in partial      | Partial property added       |
+| Property in both              | **Main wins**                |
+| Property in multiple partials | Higher priority partial wins |
+
+### Example: Property Conflict
+
+```yaml
+# Main app User.yaml
+properties:
+  name:
+    type: String
+    length: 100
+
+# Package User.yaml (partial)
+properties:
+  name:              # Same property!
+    type: Text       # Different type
+    nullable: true
+```
+
+**Result:** `name` remains `String(100)` from main app
+
+## What Partials Can Define
+
+| ✅ Allowed   | ❌ Not Allowed      |
+| ----------- | ------------------ |
+| properties  | options.id         |
+| displayName | options.timestamps |
+| priority    | options.softDelete |
+| -           | options.tableName  |
+
+## Best Practices
+
+### 1. Use Descriptive Filenames
+
+```
+✅ User.yaml         # Clear: extends/provides User
+✅ Permission.yaml   # Clear: extends/provides Permission
+❌ UserExtension.yaml  # Confusing (targets UserExtension, not User)
+```
+
+### 2. Prefix Package-Specific Fields
+
+```yaml
+# ✅ Good: Unique, prefixed names
+sso_token:
+billing_status:
+console_user_id:
+
+# ❌ Bad: Generic names that might conflict
+token:
+status:
+user_id:
+```
+
+### 3. Document Dependencies
+
+```yaml
+# User.yaml
+# Package: @famgia/sso-client
+# Requires: Role schema from same package
+# Priority: 10 (core system)
+
+kind: partial
+priority: 10
+
+properties:
+  role:
+    type: Association
+    relation: ManyToOne
+    target: Role
+```
+
+### 4. Keep Partials Focused
+
+```yaml
+# ✅ Good: Single responsibility
+# sso-client/User.yaml - Only SSO fields
+kind: partial
+properties:
+  sso_token:
+    type: String
+  console_user_id:
+    type: BigInt
+
+# ❌ Bad: Mixed responsibilities
+# Don't put billing + SSO + notifications in one partial
+```
+
+## Troubleshooting
+
+### Partial Not Merging
+
+**Problem:** Package partial not appearing in generated model
+
+**Check:**
+1. Package path in `additionalSchemaPaths`?
+2. Filename matches target? (User.yaml → User)
+3. `kind: partial` set correctly?
+
+```bash
+# Verify schemas loaded
+npx omnify generate --verbose
+```
+
+### Property Conflict
+
+**Problem:** Partial property being ignored
+
+**Reason:** Main app has same property (main always wins)
+
+**Solution:** 
+- Use different property name in partial
+- Or remove from main app if partial should own it
+
+### Priority Not Working
+
+**Problem:** Wrong partial winning in conflict
+
+**Check:**
+```yaml
+# Lower number = higher priority
+priority: 10  # Wins over
+priority: 50  # This one
+```
+
+## Generate Output
+
+```bash
+npx omnify generate
+```
+
+**Console shows:**
+```
+→ Loading schemas from /app/schemas
+→ Loading schemas from 1 additional path(s)
+  • ./packages/sso-client/schemas [Sso]: 2 schema(s) + 2 partial(s)
+→ Validating schemas...
+✓ Generation complete!
+```
+
+## Quick Reference
+
+```yaml
+# Minimal partial schema
+kind: partial
+properties:
+  new_field:
+    type: String
+
+# Full partial schema
+kind: partial
+priority: 10
+
+displayName:
+  ja: 拡張
+  en: Extension
+
+properties:
+  field1:
+    type: String
+    displayName:
+      ja: フィールド1
+      en: Field 1
+  field2:
+    type: Int
+    nullable: true
+```

package/dist/knowledge/omnify/react-form-guide.md.stub

@@ -0,0 +1,225 @@
+# Omnify React Form Guide
+
+This guide explains how to build forms using Omnify generated schemas with **Ant Design** and **TanStack Query**.
+
+## Setup
+
+Install the runtime package:
+
+```bash
+npm install @famgia/omnify-react
+```
+
+```typescript
+// omnify.config.ts
+import typescriptPlugin from '@famgia/omnify-typescript/plugin';
+
+export default defineConfig({
+  plugins: [
+    typescriptPlugin({
+      modelsPath: 'node_modules/.omnify/schemas',
+    }),
+  ],
+});
+```
+
+## Quick Start
+
+```tsx
+import { Form, Button } from 'antd';
+import {
+  useFormMutation,
+  JapaneseNameField,
+  setZodLocale,
+  zodRule,
+} from '@famgia/omnify-react';
+import { customerSchemas, customerI18n, type CustomerCreate } from './.omnify/schemas';
+import { api } from '@/lib/api';
+
+function CreateCustomerPage() {
+  const [form] = Form.useForm<CustomerCreate>();
+  setZodLocale('ja');
+
+  const mutation = useFormMutation<CustomerCreate>({
+    form,
+    mutationFn: (data) => api.post('/customers', data),
+    invalidateKeys: [['customers']],
+    successMessage: 'Customer created successfully',
+    onSuccess: () => form.resetFields(),
+  });
+
+  return (
+    <Form form={form} onFinish={mutation.mutate}>
+      <JapaneseNameField
+        schemas={customerSchemas}
+        i18n={customerI18n}
+        prefix="name"
+        showKana
+      />
+      <Button loading={mutation.isPending}>Save</Button>
+    </Form>
+  );
+}
+```
+
+## useFormMutation Hook
+
+```tsx
+import { useFormMutation } from '@famgia/omnify-react';
+
+const mutation = useFormMutation<CustomerCreate>({
+  form,
+  mutationFn: (data) => api.post('/customers', data),
+  invalidateKeys: [['customers']],
+  successMessage: 'Saved successfully',
+  onSuccess: () => form.resetFields(),
+});
+```
+
+### Options
+
+| Option           | Type                   | Description                         |
+| ---------------- | ---------------------- | ----------------------------------- |
+| `form`           | `FormInstance<T>`      | Ant Design form instance (required) |
+| `mutationFn`     | `(data: T) => Promise` | API call function (required)        |
+| `invalidateKeys` | `string[][]`           | Query keys to invalidate on success |
+| `successMessage` | `string`               | Toast message on success            |
+| `onSuccess`      | `(data) => void`       | Callback after success              |
+| `onError`        | `(error) => void`      | Callback after error                |
+
+### Laravel Error Handling
+
+The hook automatically handles Laravel validation errors (422):
+
+```json
+{
+  "message": "The given data was invalid.",
+  "errors": {
+    "email": ["The email has already been taken."]
+  }
+}
+```
+
+## Japanese Form Components
+
+### JapaneseNameField
+
+```tsx
+import { JapaneseNameField } from '@famgia/omnify-react';
+
+<JapaneseNameField
+  schemas={customerSchemas}
+  i18n={customerI18n}
+  prefix="name"        // name_lastname, name_firstname, etc.
+  required             // Show required asterisk
+  showKana={true}      // Show kana fields (default)
+/>
+```
+
+**Fields:** `{prefix}_lastname`, `{prefix}_firstname`, `{prefix}_kana_lastname`, `{prefix}_kana_firstname`
+
+### JapaneseAddressField
+
+```tsx
+import { JapaneseAddressField } from '@famgia/omnify-react';
+
+<JapaneseAddressField
+  form={form}
+  schemas={customerSchemas}
+  i18n={customerI18n}
+  prefix="address"
+  prefectureOptions={prefectureOptions} // Required for Select
+  enablePostalLookup={true}  // Postal code → address lookup
+/>
+```
+
+**Fields:** `{prefix}_postal_code`, `{prefix}_prefecture`, `{prefix}_address1`, `{prefix}_address2`, `{prefix}_address3`
+
+**Options:**
+- `prefectureOptions` - Select options for prefecture dropdown
+- `enablePostalLookup` - Enable postal code search
+- `autoSearch` - Auto-search when 7 digits entered
+- `usePrefectureId` - Use numeric ID instead of string enum
+
+### JapaneseBankField
+
+```tsx
+import { JapaneseBankField } from '@famgia/omnify-react';
+
+<JapaneseBankField
+  schemas={customerSchemas}
+  i18n={customerI18n}
+  prefix="bank"
+  accountTypeOptions={accountTypeOptions} // Required for Select
+/>
+```
+
+**Fields:** `{prefix}_bank_code`, `{prefix}_branch_code`, `{prefix}_account_type`, `{prefix}_account_number`, `{prefix}_account_holder`
+
+## Zod Validation with i18n
+
+```tsx
+import { zodRule, setZodLocale } from '@famgia/omnify-react';
+
+// Set locale once at component level
+setZodLocale('ja');
+
+// Use zodRule for field validation
+<Form.Item
+  name="email"
+  label="メールアドレス"
+  rules={[zodRule(customerSchemas.email, 'メールアドレス')]}
+>
+  <Input />
+</Form.Item>
+```
+
+## Kana Validation Rules
+
+```tsx
+import { kanaString, KATAKANA_PATTERN } from '@famgia/omnify-react';
+
+// Full-width katakana (default)
+const kanaSchema = kanaString();
+
+// Custom options
+const kanaSchema = kanaString({
+  fullWidthKatakana: true,
+  hiragana: true,
+  allowNumbers: true,
+});
+```
+
+### Kana Presets
+
+| Preset                  | Description            |
+| ----------------------- | ---------------------- |
+| `KATAKANA_FULL_WIDTH`   | 全角カタカナ (default) |
+| `KATAKANA_HALF_WIDTH`   | 半角カタカナ           |
+| `HIRAGANA`              | ひらがな               |
+| `KANA_ANY`              | All kana types         |
+| `KATAKANA_WITH_NUMBERS` | カタカナ + numbers     |
+
+## File Structure
+
+```
+node_modules/
+├── @famgia/omnify-react/    # Runtime package (npm)
+│   ├── components/          # JapaneseNameField, etc.
+│   ├── hooks/               # useFormMutation
+│   └── lib/                 # zodRule, kanaString, etc.
+└── .omnify/                 # Generated (regeneratable)
+    ├── schemas/
+    │   ├── Customer.ts
+    │   └── Post.ts
+    └── enum/
+        └── PostStatus.ts
+```
+
+## Tips
+
+1. **Use type generics** - `useFormMutation<CustomerCreate>` for type safety
+2. **Use `setZodLocale`** - Call once for localized validation messages
+3. **Use Japanese components** - Built-in i18n, validation, postal lookup
+4. **Set `invalidateKeys`** - Auto-refresh lists after mutations
+5. **Provide options for Select** - Components need `prefectureOptions` or `accountTypeOptions`

package/dist/knowledge/omnify/schema-guide.md.stub

@@ -0,0 +1,144 @@
+# Omnify Schema Guide
+
+## Schema File Format
+
+Schemas are YAML files defining data models. Each file represents one entity.
+
+```yaml
+name: User
+displayName:
+  ja: ユーザー
+  en: User
+kind: object
+
+properties:
+  email:
+    type: Email
+    unique: true
+  name:
+    type: String
+  bio:
+    type: Text
+    nullable: true
+
+options:
+  timestamps: true
+  softDelete: true
+```
+
+## Property Types
+
+### String Types
+- `String` - VARCHAR(255)
+- `Text` - TEXT
+- `LongText` - LONGTEXT
+- `Email` - VARCHAR(255) for email addresses
+- `Password` - VARCHAR(255), hidden in serialization
+
+### Numeric Types
+- `Int` - INTEGER
+- `BigInt` - BIGINT
+- `TinyInt` - TINYINT
+- `Float` - DOUBLE
+- `Decimal` - DECIMAL(precision, scale)
+
+### Date/Time Types
+- `Date` - DATE
+- `Time` - TIME
+- `DateTime` - DATETIME
+- `Timestamp` - TIMESTAMP
+
+### Other Types
+- `Boolean` - BOOLEAN
+- `Json` - JSON
+- `Enum` - ENUM with values
+- `EnumRef` - Reference to enum schema
+
+## Property Options
+
+```yaml
+propertyName:
+  type: String
+  nullable: true       # Can be NULL
+  unique: true         # Unique constraint
+  default: "value"     # Default value
+  length: 100          # VARCHAR length
+  hidden: true         # Hide from JSON output
+  fillable: false      # Exclude from mass assignment
+```
+
+## ⚠️ Default Value Rules
+
+**DB functions NOT allowed in default:**
+
+```yaml
+# ❌ WRONG
+failed_at:
+  type: Timestamp
+  default: CURRENT_TIMESTAMP  # ERROR!
+
+# ✅ CORRECT
+failed_at:
+  type: Timestamp
+  useCurrent: true            # = CURRENT_TIMESTAMP
+
+updated_at:
+  type: Timestamp
+  useCurrent: true
+  useCurrentOnUpdate: true    # ON UPDATE CURRENT_TIMESTAMP
+```
+
+| Type | Valid Default | Invalid |
+|------|---------------|---------|
+| Int | 0, 100, -1 | AUTO_INCREMENT, RAND() |
+| Date | 2024-01-01 | CURRENT_DATE |
+| Time | 14:30:00 | CURRENT_TIME |
+| Timestamp | use `useCurrent` | CURRENT_TIMESTAMP |
+| Uuid | static UUID | UUID() |
+
+## Associations
+
+```yaml
+# Many-to-One (belongsTo)
+author:
+  type: Association
+  relation: ManyToOne
+  target: User
+  onDelete: CASCADE
+
+# One-to-Many (hasMany)
+posts:
+  type: Association
+  relation: OneToMany
+  target: Post
+
+# Many-to-Many (belongsToMany)
+tags:
+  type: Association
+  relation: ManyToMany
+  target: Tag
+  joinTable: post_tags
+
+# Polymorphic
+commentable:
+  type: Association
+  relation: MorphTo
+```
+
+## Indexes
+
+```yaml
+indexes:
+  - columns: [status, published_at]
+  - columns: [email]
+    unique: true
+```
+
+## Schema Options
+
+```yaml
+options:
+  timestamps: true   # Add created_at, updated_at
+  softDelete: true   # Add deleted_at
+  idType: BigInt     # Primary key type (Int, BigInt, Uuid)
+```