Revise getting started docs and add VS Code extension recommendations

Updated README and documentation to emphasize YAML-based metadata, improved quick start instructions, and highlighted the importance of the ObjectQL VS Code extension. Added .vscode/extensions.json files to example projects to recommend relevant extensions for better developer experience.

Author: hotlong

README.md

@@ -45,82 +45,54 @@ ObjectQL is organized as a Monorepo to ensure modularity and universal compatibi
 
 ## ⚡ Quick Start
 
-### 0. Use the Generator (Recommended)
+### 1. Create a New Project
 
 The fastest way to start is using the CLI to scaffold a new project.
 
 ```bash
-# Create a new project
+# Generate a new project
 npm create @objectql@latest my-app
 
-# Choose a template when prompted (hello-world or starter)
+# Choose 'starter' for a complete example or 'hello-world' for minimal setup
 ```
 
-### 1. Manual Installation
+### 2. Install VS Code Extension (Critical 🚨)
 
-If you prefer to install manually:
+For the best experience, install the official extension. It provides **Intelligent IntelliSense** and **Real-time Validation** for your YAML models.
 
-```bash
-# Install core and a driver (e.g., Postgres or SQLite)
-npm install @objectql/core @objectql/driver-sql sqlite3
-```
+*   Search for **"ObjectQL"** in the VS Code Marketplace.
+*   Or open your new project, and VS Code will recommend it automatically via `.vscode/extensions.json`.
 
-### 2. The Universal Script
+### 3. Define Metadata (The "Object")
 
-ObjectQL can run in a single file without complex configuration.
+ObjectQL uses **YAML** as the source of truth. Create a file `src/objects/story.object.yml`:
 
-```typescript
-import { ObjectQL } from '@objectql/core';
-import { SqlDriver } from '@objectql/driver-sql';
-
-async function main() {
-  // 1. Initialize Driver (In-Memory SQLite)
-  const driver = new SqlDriver({
-    client: 'sqlite3',
-    connection: { filename: ':memory:' }, 
-    useNullAsDefault: true
-  });
-
-  // 2. Initialize Engine
-  const app = new ObjectQL({
-    datasources: { default: driver }
-  });
-
-  // 3. Define Schema (The "Object")
-  // In a real app, this would be loaded from a .yml file
-  app.registerObject({
-    name: "users",
-    fields: {
-      name: { type: "text", required: true },
-      email: { type: "email", unique: true },
-      role: { 
-        type: "select", 
-        options: ["admin", "user"], 
-        defaultValue: "user" 
-      }
-    }
-  });
-
-  await app.init();
-
-  // 4. Enjoy Type-Safe(ish) CRUD
-  const ctx = app.createContext({ isSystem: true });
-  const repo = ctx.object('users');
-
-  // Create
-  await repo.create({ name: 'Alice', email: 'alice@example.com' });
-
-  // Find
-  const users = await repo.find({
-    filters: [['role', '=', 'user']]
-  });
-  
-  console.log(users);
-}
+```yaml
+name: story
+label: User Story
+fields:
+  title:
+    type: text
+    required: true
+  status:
+    type: select
+    options: [draft, active, done]
+    default: draft
+  points:
+    type: number
+    scale: 0
+    default: 1
+```
+
+### 4. Run & Play
+
+Start the development server. ObjectQL will automatically load your YAML files and generate the database schema.
 
-main();
+```bash
+npm run dev
 ```
 
+
 ---
 
 ## 🔌 The Driver Ecosystem

docs/guide/getting-started.md

@@ -26,22 +26,51 @@ npm create @objectql@latest my-app -- --template hello-world
 
 This will create a new project with all necessary dependencies.
 
-### 2. Standard Setup (Project Tracker)
+### 2. Install VS Code Extension (Recommended) 🚨
+
+To treat your metadata like code (with validation and autocomplete), install the **Standard ObjectStack AI Extension**.
+
+1.  Open Visual Studio Code.
+2.  Go to the **Extensions** view (`Cmd+Shift+X`).
+3.  Search for `ObjectQL` and install.
+4.  Alternatively, when you open the created project, VS Code will prompt you to install recommended extensions.
+
+> **Why?** The extension understands your `*.object.yml` files, validating field types and relationships in real-time, just like TypeScript.
+
+### 3. Define the Protocol (Your Meta-Schema)
+
+Instead of passing objects to a constructor, we define them in YAML. This is the "AI-Native" way—separate the **Instruction** (YAML) from the **Execution** (Runtime).
+
+Create a file `src/objects/todo.object.yml`:
+
+```yaml
+name: todo
+label: Task
+fields:
+  title: 
+    type: text
+    required: true
+    searchable: true
+  completed: 
+    type: boolean
+    default: false
+  priority:
+    type: select
+    options: [low, medium, high]
+    default: medium
+```
 
-For building real applications, use the `showcase` template. This sets up a proper folder structure with YAML metadata, TypeScript logic hooks, and relationship management.
+### 4. Run the Project
 
 ```bash
-npm create @objectql@latest project-tracker -- --template showcase
+npm run dev
 ```
 
-This structure follows our **Best Practices**:
-*   **`src/objects/*.object.yml`**: Data definitions.
-*   **`src/hooks/*.hook.ts`**: Business logic.
-*   **`src/index.ts`**: Application entry point.
+ObjectQL will detect the new file, generate the necessary database tables (in SQLite by default), and start the server.
 
-## Manual Setup (The Hard Way)
+### 5. Manual Setup (Programmatic API)
 
-If you prefer to set up manually or add ObjectQL to an existing project:
+If you are integrating ObjectQL into an existing specialized backend (like a Lambda function or a custom script), you can use the Programmatic API.
 
 ```typescript
 import { ObjectQL } from '@objectql/core';
@@ -61,6 +90,7 @@ async function main() {
   });
 
   // 3. Define Metadata Inline (Code as Configuration)
+  // Note: We recommend YAML for scalability, but this works for scripts.
   app.registerObject({
     name: 'todo',
     fields: {
@@ -87,7 +117,7 @@ main();
 
 ## Scaling Up: The Metadata Approach
 
-Once you are comfortable with the core, you should move your definitions to YAML files.
+Once you are comfortable with the basics, notice that standard projects use file-based modules configuration.
 
 ```typescript
 import { ObjectQL } from '@objectql/core';

docs/tutorials/task-manager.md

@@ -17,27 +17,25 @@ npm install @objectql/core @objectql/server @objectql/driver-sql sqlite3 tsx
 
 ## 2. Define Your Schema
 
-Create a file named `project.object.yml`:
+Create a file named `src/objects/task.object.yml`:
 
 ```yaml
-name: project
-objects:
-  task:
-    label: Task
-    fields:
-      title:
-        type: text
-        required: true
-      completed:
-        type: boolean
-        default: false
-      priority:
-        type: select
-        options:
-          - label: Low
-            value: low
-          - label: High
-            value: high
+name: task
+label: Task
+fields:
+  title:
+    type: text
+    required: true
+  completed:
+    type: boolean
+    default: false
+  priority:
+    type: select
+    options:
+      - label: Low
+        value: low
+      - label: High
+        value: high
 ```
 
 ## 3. Start the Server

examples/quickstart/hello-world/.vscode/extensions.json

@@ -0,0 +1,7 @@
+{
+  "recommendations": [
+    "objectstack-ai.vscode-objectql",
+    "redhat.vscode-yaml",
+    "dbaeumer.vscode-eslint"
+  ]
+}

examples/showcase/enterprise-erp/.vscode/extensions.json

@@ -0,0 +1,7 @@
+{
+  "recommendations": [
+    "objectstack-ai.vscode-objectql",
+    "redhat.vscode-yaml",
+    "dbaeumer.vscode-eslint"
+  ]
+}

examples/showcase/project-tracker/.vscode/extensions.json

@@ -0,0 +1,7 @@
+{
+  "recommendations": [
+    "objectstack-ai.vscode-objectql",
+    "redhat.vscode-yaml",
+    "dbaeumer.vscode-eslint"
+  ]
+}