Merge pull request #198 from objectstack-ai/copilot/update-code-documentation-examples

Author: hotlong

README.md

@@ -91,21 +91,32 @@ For the best experience, install the official extension. It provides **Intellige
 
 ObjectQL uses **YAML** as the source of truth. Create a file `src/objects/story.object.yml`:
 
+**Key Convention (v4.0+):** The object `name` is **inferred from the filename** - no redundant `name:` field needed!
+
 ```yaml
-name: story
+# File: story.object.yml
+# Object name is automatically inferred as 'story' ✅
 label: User Story
 fields:
   title:
     type: text
     required: true
+    label: Story Title
   status:
     type: select
-    options: [draft, active, done]
-    default: draft
+    options:
+      - label: Draft
+        value: draft
+      - label: Active
+        value: active
+      - label: Done
+        value: done
+    defaultValue: draft
   points:
     type: number
     scale: 0
-    default: 1
+    defaultValue: 1
+    label: Story Points
 ```
 
 ### 4. Run & Play
@@ -174,11 +185,21 @@ import { MemoryDriver } from '@objectql/driver-memory';
 const driver = new MemoryDriver();
 const app = new ObjectQL({ datasources: { default: driver } });
 
+// Define object following latest ObjectStack specification
 app.registerObject({
-  name: 'tasks',
+  name: 'tasks',  // Required for programmatic registration
+  label: 'Tasks',
   fields: {
-    title: { type: 'text', required: true },
-    completed: { type: 'boolean', defaultValue: false }
+    title: { 
+      type: 'text', 
+      required: true,
+      label: 'Task Title'
+    },
+    completed: { 
+      type: 'boolean', 
+      defaultValue: false,
+      label: 'Completed'
+    }
   }
 });
 

content/docs/ai/coding-assistant.mdx

@@ -74,25 +74,39 @@ navigation:
 
 ### 2. Object Definition (Schema)
 Objects are defined in `<name>.object.yml`.
+
+**Key Convention (v4.0+):** The object `name` is **inferred from the filename** - no redundant `name:` field needed!
+
 Supported types: `text`, `number`, `boolean`, `date`, `datetime`, `json`, `lookup`, `select`.
 
 Example `todo.object.yml`:
 ```yaml
-name: todo
+# File: todo.object.yml
+# Object name is inferred as 'todo' ✅
 label: Todo Item
 fields:
   title:
     type: text
     required: true
+    label: Task Title
   completed:
     type: boolean
     defaultValue: false
+    label: Completed
   priority:
     type: select
-    options: [low, medium, high]
+    label: Priority Level
+    options:
+      - label: Low
+        value: low
+      - label: Medium
+        value: medium
+      - label: High
+        value: high
   owner:
     type: lookup
     reference_to: user
+    label: Owner
 ```
 
 ### 3. Data Operations (API)

content/docs/ai/generating-apps.mdx

@@ -41,42 +41,65 @@ To get the best results, use a prompt that enforces the ObjectQL schema format.
 
 ```yaml
 # agent.object.yml
-name: agent
+# Object name inferred as 'agent'
+label: Real Estate Agent
 fields:
   name:
     type: text
     required: true
+    label: Agent Name
   email:
     type: email
     required: true
+    label: Email Address
   phone:
     type: phone
+    label: Phone Number
   license_number:
     type: text
+    label: License Number
   status:
     type: select
-    options: [active, inactive]
+    label: Status
+    options:
+      - label: Active
+        value: active
+      - label: Inactive
+        value: inactive
 ```
 
 ```yaml
 # property.object.yml
-name: property
+# Object name inferred as 'property'
+label: Property
 fields:
   address:
     type: textarea
     required: true
+    label: Property Address
   price:
     type: currency
+    label: Listing Price
   bedrooms:
     type: number
+    label: Number of Bedrooms
   bathrooms:
     type: number
+    label: Number of Bathrooms
   listing_agent:
     type: lookup
     reference_to: agent
+    label: Listing Agent
   status:
     type: select
-    options: [for_sale, sold, pending]
+    label: Listing Status
+    options:
+      - label: For Sale
+        value: for_sale
+      - label: Sold
+        value: sold
+      - label: Pending
+        value: pending
 ```
 
 ## Automating the Process

content/docs/data-access/best-practices.mdx

@@ -630,16 +630,26 @@ const uniqueCustomers = await app.object('order').distinct('customer_id', {
 
 ```yaml
 # task.object.yml
-name: task
+# Object name inferred as 'task'
+label: Task
 fields:
   status:
     type: select
-    options: [open, in_progress, completed]
+    label: Task Status
+    options:
+      - label: Open
+        value: open
+      - label: In Progress
+        value: in_progress
+      - label: Completed
+        value: completed
   assignee_id:
     type: lookup
     reference_to: users
+    label: Assignee
   due_date:
     type: date
+    label: Due Date
 
 indexes:
   # Composite index for common query

content/docs/logic/actions.mdx

@@ -40,8 +40,15 @@ actions:
         required: false
       method:
         type: select
-        options: [cash, card, transfer]
-        default: transfer
+        label: Payment Method
+        options:
+          - label: Cash
+            value: cash
+          - label: Card
+            value: card
+          - label: Transfer
+            value: transfer
+        defaultValue: transfer
 
   import_csv:
     type: global           # 'global' = acts on the collection

examples/integrations/browser/index.html

@@ -247,8 +247,10 @@ <h2>🖥️ Console Output</h2>
                 });
 
                 log('📝 Registering Notes schema...');
+                // Note: When using registerObject() programmatically, 'name' is required
+                // When using YAML files, the name is inferred from filename (latest ObjectStack spec)
                 window.app.registerObject({
-                    name: 'notes',
+                    name: 'notes',  // Required for programmatic registration
                     label: 'Notes',
                     fields: {
                         content: {

examples/integrations/express-server/src/task.object.yml

@@ -1,24 +1,71 @@
+# File: task.object.yml
+# Object name is inferred from filename as 'task'
 label: Tasks
+
+ai_context:
+  intent: "Track individual tasks and their completion status"
+  domain: task_management
+  common_queries:
+    - "Find pending tasks"
+    - "Show overdue tasks"
+    - "List tasks by priority"
+
 fields:
   title:
-    type: string
+    type: text
     label: Title
     required: true
+    ai_context:
+      intent: "Brief description of the task"
   description:
-    type: text
+    type: textarea
     label: Description
+    ai_context:
+      intent: "Detailed task information"
   status:
-    type: string
+    type: select
     label: Status
+    options:
+      - label: Pending
+        value: pending
+      - label: In Progress
+        value: in_progress
+      - label: Completed
+        value: completed
+      - label: Cancelled
+        value: cancelled
     defaultValue: pending
+    ai_context:
+      intent: "Current state of the task"
+      is_state_machine: true
+      transitions:
+        pending: [in_progress, cancelled]
+        in_progress: [completed, pending, cancelled]
+        completed: []
+        cancelled: [pending]
   priority:
-    type: string
+    type: select
     label: Priority
+    options:
+      - label: Low
+        value: low
+      - label: Medium
+        value: medium
+      - label: High
+        value: high
+      - label: Urgent
+        value: urgent
     defaultValue: medium
+    ai_context:
+      intent: "Task urgency level"
   due_date:
     type: date
     label: Due Date
+    ai_context:
+      intent: "Deadline for task completion"
   completed:
     type: boolean
     label: Completed
     defaultValue: false
+    ai_context:
+      intent: "Quick completion flag"

examples/integrations/express-server/src/user.object.yml

@@ -1,17 +1,48 @@
+# File: user.object.yml
+# Object name is inferred from filename as 'user'
 label: Users
+
+ai_context:
+  intent: "Manage user accounts and profiles"
+  domain: user_management
+  common_queries:
+    - "Find active users"
+    - "List users by age"
+    - "Search users by email"
+
 fields:
   name:
-    type: string
+    type: text
     label: Full Name
     required: true
+    ai_context:
+      intent: "User's full name for display"
   email:
-    type: string
+    type: email
     label: Email Address
     required: true
+    ai_context:
+      intent: "Primary contact email and login identifier"
   status:
-    type: string
+    type: select
     label: Status
+    options:
+      - label: Active
+        value: active
+      - label: Inactive
+        value: inactive
+      - label: Suspended
+        value: suspended
     defaultValue: active
+    ai_context:
+      intent: "Account status"
+      is_state_machine: true
+      transitions:
+        active: [inactive, suspended]
+        inactive: [active]
+        suspended: [active, inactive]
   age:
     type: number
     label: Age
+    ai_context:
+      intent: "User's age for demographic purposes"