Fix critical documentation inconsistencies

Co-authored-by: hotlong <[email protected]>

Author: Copilot

content/docs/getting-started/index.mdx

@@ -55,11 +55,11 @@ fields:
     searchable: true
   completed: 
     type: boolean
-    default: false
+    defaultValue: false
   priority:
     type: select
     options: [low, medium, high]
-    default: medium
+    defaultValue: medium
 ```
 
 ### 4. Run the Project
@@ -173,12 +173,12 @@ ObjectQL shines when you need to add logic.
 Triggers logic automatically when data changes.
 
 ```typescript
-app.on('beforeCreate', 'todo', async (ctx) => {
-    if (ctx.doc.title === 'Sleep') {
+app.on('before:create', 'todo', async (ctx) => {
+    if (ctx.data.title === 'Sleep') {
         throw new Error("Cannot sleep yet!");
     }
     // Auto-tagging
-    ctx.doc.title = `[Task] ${ctx.doc.title}`;
+    ctx.data.title = `[Task] ${ctx.data.title}`;
 });
 ```
 

content/docs/logic/actions.mdx

@@ -139,7 +139,7 @@ The `params` section in YAML supports the same types as Object Fields. This allo
 params:
   assign_to:
     type: lookup
-    reference: user
+    reference_to: user
     label: Assign To Staff
 ```
 

content/docs/reference/spec/action.mdx

@@ -19,6 +19,32 @@ Unlike Hooks (which trigger automatically), Actions are explicitly invoked by th
 ### 1.2 Schema-First Inputs
 Input parameters (`params`) are defined using the same `FieldConfig` schema as object fields. This gives you free validation, type coercion, and UI generation.
 
+### 1.3 AI Context Support
+Actions support the `ai_context` property to provide semantic information for AI-assisted development and code generation.
+
+```yaml
+# File: order.object.yml
+actions:
+  approve_order:
+    type: record
+    label: Approve Order
+    ai_context:
+      intent: "Approve a pending order after verifying inventory and payment"
+      business_rules:
+        - "Only orders in 'Pending' status can be approved"
+        - "Must verify sufficient inventory before approval"
+        - "Payment must be confirmed"
+      examples:
+        - "Approve order #12345 after payment verification"
+        - "Batch approve all paid orders"
+```
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `intent` | `string` | Brief description of the action's business purpose. |
+| `business_rules` | `string[]` | Key constraints or validation requirements. |
+| `examples` | `string[]` | Typical use cases or invocation scenarios. |
+
 ## 2. Configuration (YAML)
 
 Actions are declared in your object definition file (`<object_name>.object.yml`).

content/docs/reference/spec/hook.mdx

@@ -22,6 +22,37 @@ Unlike traditional ORMs that provide generic contexts, ObjectQL hooks are **Type
 *   **Separation of Concerns**: `before` hooks focus on validation/mutation; `after` hooks focus on side-effects.
 *   **Change Tracking**: Built-in helpers like `isModified()` simplify "diff" logic.
 
+### AI Context Support
+
+While hooks are implemented in TypeScript files, you can document their business logic using `ai_context` in your object definition or validation rules for AI-assisted development.
+
+```yaml
+# File: project.object.yml
+label: Project
+description: "Project management with status tracking"
+
+ai_context:
+  intent: "Manage projects with automatic owner assignment and state validation"
+  business_rules:
+    - "Owner is auto-assigned on creation from current user"
+    - "Completed projects cannot be reopened"
+    - "Status changes trigger notifications"
+  hooks_description:
+    - "beforeCreate: Auto-assign owner and validate unique name"
+    - "beforeUpdate: Prevent reopening completed projects"
+    - "afterUpdate: Send notification when project completes"
+
+fields:
+  # ... field definitions
+```
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `hooks_description` | `string[]` | Documentation of hook behavior for AI understanding. |
+| `business_rules` | `string[]` | Key validation rules enforced by hooks. |
+
+**Note:** This ai_context goes in the object definition file, not the hook implementation file.
+
 ## 2. Supported Hooks
 
 | Hook | Operation | Context Properties | Purpose |

content/docs/reference/spec/object.mdx

@@ -565,7 +565,7 @@ fields:
   status:
     type: select
     required: true
-    default: planning
+    defaultValue: planning
     options:
       - value: planning
         label: Planning

content/docs/reference/spec/query-language.mdx

@@ -102,6 +102,8 @@ export interface UnifiedQuery {
 
 The `filters` property is a recursive array structure that eliminates the need for SQL strings.
 
+**Note:** This array-based syntax ([field, operator, value]) is used for **runtime queries**. For **validation rules** in YAML metadata, an object-based syntax (field/operator/value) is used instead. See [Validation Rules](./validation.mdx) for details.
+
 ### 3.1 Single Criterion
 A criterion is a tuple of `[Field, Operator, Value]`.
 

content/docs/reference/spec/validation.mdx

@@ -25,6 +25,10 @@ The filename (without the `.validation.yml` extension) automatically identifies
 
 ## 2. Root Structure
 
+**Important:** Validation rules use an **object-based syntax** (field/operator/value) while the [Query Language](./query-language.mdx) uses an **array-based syntax** ([field, operator, value]). This distinction exists because:
+- **Validation rules** are declarative metadata (YAML) optimized for readability and AI generation
+- **Query filters** are runtime AST (JSON) optimized for parsing and logical precedence
+
 ```yaml
 # File: project.validation.yml
 # Object "project" is inferred from filename!

content/docs/server/microservices.mdx

@@ -21,7 +21,7 @@ It must expose the metadata API (default in `@objectql/server`).
 ```typescript
 // user-service/index.ts
 const app = new ObjectQL({
-    source: './src/objects', // Defines 'user', 'role'
+    modules: ['./src/objects'], // Defines 'user', 'role'
     datasources: { ... }
 });
 // Exposes http://user-service:3000/api/metadata/objects