Refactor examples and introduce modular templates

Reorganized example projects to use a new modular structure, moving and renaming starter, plugin, and showcase examples under 'examples/'. Added new quickstart and integration templates, removed legacy tutorials and scripts, and updated documentation to reflect the new module-based architecture. Introduced a pnpm-lock.yaml merge driver, improved .gitignore, and updated CLI commands and docs for the new workflow. Added new CLI commands and created a separate 'create' package for project scaffolding.

Author: hotlong

.changeset/config.json

@@ -12,10 +12,7 @@
       "@objectql/sdk",
       "@objectql/server",
       "@objectql/types",
-      "@objectql/platform-node",
-      "@objectql/starter-basic",
-      "@objectql/starter-express-api",
-      "@objectql/starter-enterprise"
+      "@objectql/platform-node"
     ]
   ],
   "linked": [],

.gitattributes

@@ -0,0 +1,4 @@
+# pnpm-lock.yaml merge driver
+# This custom merge driver automatically resolves conflicts in pnpm-lock.yaml
+# by regenerating the lock file using 'pnpm install'
+pnpm-lock.yaml merge=pnpm-merge

.gitignore

@@ -15,4 +15,6 @@ docs/.vitepress/dist
 *.db
 
 # Example tutorials CHANGELOG (auto-generated, not tracked)
-examples/tutorials/*/CHANGELOG.md
+examples/tutorials/*/CHANGELOG.md
+# Generated Types
+generated/

.vscode/launch.json

@@ -2,14 +2,12 @@
   "version": "2.0.0",
   "tasks": [
     {
-      "label": "Run Studio: Basic Script",
+      "label": "Run Dev Server",
       "type": "shell",
-      "command": "node",
+      "command": "pnpm",
       "args": [
-        "packages/cli/dist/index.js",
-        "studio",
-        "--dir",
-        "examples/starters/basic-script"
+        "objectql",
+        "dev"
       ],
       "group": "test",
       "presentation": {

.vscode/tasks.json

@@ -45,7 +45,20 @@ ObjectQL is organized as a Monorepo to ensure modularity and universal compatibi
 
 ## ⚡ Quick Start
 
-### 1. Installation
+### 0. Use the Generator (Recommended)
+
+The fastest way to start is using the CLI to scaffold a new project.
+
+```bash
+# Create a new project
+npm create @objectql@latest my-app
+
+# Choose a template when prompted (hello-world or starter)
+```
+
+### 1. Manual Installation
+
+If you prefer to install manually:
 
 ```bash
 # Install core and a driver (e.g., Postgres or SQLite)
@@ -274,6 +287,44 @@ For a complete status report on ObjectQL's implementation against the documented
 
 ---
 
+## 🛠️ Development & Contributing
+
+If you fork or clone the repository to contribute or run examples from source:
+
+1. **Setup Workspace**
+   ```bash
+   git clone https://github.com/objectql/objectql.git
+   cd objectql
+   npm install -g pnpm
+   pnpm install
+   ```
+
+2. **Build Packages**
+   You must build the core libraries before running examples, as they rely on local workspace builds.
+   ```bash
+   pnpm build
+   ```
+
+3. **Run Examples**
+   
+   These examples run as **scripts** to demonstrate the ObjectQL Core Engine capabilities (Validation, CRUD, Logic Hooks). They use an in-memory SQLite database.
+
+   **Starter (Project Tracker):**
+   ```bash
+   # Starts the API Server (http://localhost:3000)
+   pnpm --filter @objectql/example-project-tracker start
+   
+   # Note: Sample data (projects.data.yml) is automatically loaded on startup
+   ```
+
+   **Enterprise ERP:**
+   ```bash
+   pnpm --filter @objectql/example-enterprise-erp start
+   # Output: Plugin initialization, Employee creation logs, Audit trails
+   ```
+
+---
+
 ## ⚖️ License
 
 ObjectQL is open-source software licensed under the [MIT License](https://www.google.com/search?q=LICENSE).

README.md

@@ -86,5 +86,5 @@ curl -X POST http://localhost:3000/api/objectql \
 ### Auto-Generated Specs
 
 For automated tool ingestion, use the following endpoints:
-- **OpenAPI / Swagger**: `/api/docs/swagger.json`
+- **OpenAPI / Swagger**: `/openapi.json` (Used by `/docs` UI)
 - **GraphQL Schema**: `/api/graphql/schema`

docs/api/index.md

@@ -16,26 +16,30 @@ You can then run it via `npx objectql` or add scripts to your `package.json`.
 
 ### 2.1 `init` (Create Project)
 
-Create a new ObjectQL project from a starter template.
+The recommended way to create a new ObjectQL project is using the initialization package.
 
 ```bash
-npx objectql init [options]
+npm create @objectql@latest [name] [options]
 ```
 
 **Options:**
 
 | Option | Alias | Default | Description |
 | :--- | :--- | :--- | :--- |
-| `--template <template>` | `-t` | `basic` | Template to use (`basic`, `express-api`, `enterprise`). |
-| `--name <name>` | `-n` | - | Project name. |
-| `--dir <path>` | `-d` | - | Target directory. |
+| `--template <template>` | `-t` | `starter` | Template to use (`starter`, `hello-world`). |
 | `--skip-install` | | `false` | Skip dependency installation. |
 | `--skip-git` | | `false` | Skip git initialization. |
 
 **Example:**
 
 ```bash
-npx objectql init -t express-api -n my-app
+npm create @objectql@latest my-app -- --template showcase
+```
+
+Alternatively, if you already have the CLI installed globally or in a project, you can use the legacy `init` command:
+
+```bash
+npx objectql init [options]
 ```
 
 ### 2.2 `generate` (Type Generation)
@@ -86,23 +90,43 @@ npx objectql new object customer
 
 ## 3. Development Tools
 
-### 3.1 `serve` (Dev Server)
+### 3.1 `dev` (Development Server)
 
-Start a standalone development server.
-**Alias**: `s`
+Start the development server with hot-reload support.
+**Alias**: `d`
 
 ```bash
-npx objectql serve [options]
+npx objectql dev [options]
 ```
 
 **Options:**
 
 | Option | Alias | Default | Description |
 | :--- | :--- | :--- | :--- |
 | `--port <number>` | `-p` | `3000` | Port to listen on. |
-| `--dir <path>` | `-d` | `.` | Directory containing schema. |
+| `--dir <path>` | `-d` | `.` | Root module directory (context). |
+| `--config <path>` | `-c` | - | Path to `objectql.config.ts`. |
+| `--modules <items>` | | - | Comma-separated list of modules to load (overrides config). Supports NPM packages (`@org/pkg`) or local paths (`./src/mod`). |
+| `--no-watch` | | `false` | Disable file watching. |
+
+### 3.2 `start` (Production Server)
+
+good Start the server in production mode.
+
+```bash
+npx objectql start [options]
+```
+
+**Options:**
+
+| Option | Alias | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `--port <number>` | `-p` | `3000` | Port to listen on. |
+| `--dir <path>` | `-d` | `.` | Root module directory (context). |
+| `--config <path>` | `-c` | - | Path to `objectql.config.ts`. |
+| `--modules <items>` | | - | Comma-separated list of modules to load (overrides config). |
 
-### 3.2 `studio` (Admin UI)
+### 3.3 `studio` (Admin UI)
 
 Starts the web-based admin studio to browse data and view schema.
 **Alias**: `ui`

docs/guide/cli.md

@@ -10,8 +10,11 @@ import { ObjectQL } from '@objectql/core';
 
 export const db = new ObjectQL({
     connection: 'sqlite://data.db', // 1. Infrastructure
-    presets: ['@objectql/preset-auth'], // 2. Base Capabilities
-    source: ['src'], // 3. Application Logic
+    modules: [
+         '@my-org/module-crm',    // 2. External Module (NPM)
+         './src/modules/billing'  // 3. Local Module
+    ],
+    // source: ... (Deprecated, use modules)
     plugins: [] // 4. Extensions
 });
 ```
@@ -26,14 +29,12 @@ The Connection String URI defining the database connection.
 
 The engine will automatically load the appropriate driver (`@objectql/driver-sql` or `@objectql/driver-mongo`).
 
-### `source` (string | string[])
-One or more directory paths (relative or absolute) containing your schema files (`*.object.yml`).
-The loader scans these directories recursively.
+### `modules` (string[])
+A list of modules to load. A module can be:
+1.  **An NPM Package**: (e.g., `@objectql/starter-crm`). The loader resolves the package and looks for `src` or root directory files.
+2.  **A Local Directory**: (e.g., `./src/my-module`). The loader scans the directory for schema files (`*.object.yml`).
 
-### `presets` (string[])
-A list of NPM packages to load as presets.
-ObjectQL will try to resolve the package and load schema files from its directory.
-Useful for sharing common business objects (User, Role, File, etc.).
+This unifies the previous concepts of `source`, `dir` and `presets`.
 
 ### `plugins` ((ObjectQLPlugin | string)[])
 A list of plugin instances OR package names to extend the core functionality.

docs/guide/configuration.md

@@ -8,23 +8,40 @@
 2.  **Universal Protocol**: The query language is a JSON AST, making it easy for frontends or AI agents to generate queries.
 3.  **Action & Hook System**: Built-in support for "Button Actions" (RPC) and "Triggers" (Hooks), allowing you to model **Behavior** alongside **Data**.
 
-## Quick Start: The "Hello World"
+## Quick Start
 
-You can experience ObjectQL with a single file. No YAML, no complex config.
+The fastest way to get started is using the CLI to scaffold a project.
 
-### 1. Minimal Setup
+### 1. Create a New Project
 
-Install the core and SQLite driver (for zero-config database).
+The easiest way to start is using the generator.
 
 ```bash
-npm install @objectql/core @objectql/driver-sql sqlite3
-# or
-pnpm add @objectql/core @objectql/driver-sql sqlite3
+# Standard Setup (Recommended) - Full Project Tracker Demo
+npm create @objectql@latest my-app -- --template starter
+
+# Minimal Setup - Single File
+npm create @objectql@latest my-app -- --template hello-world
 ```
 
-### 2. The Universal Script
+This will create a new project with all necessary dependencies.
+
+### 2. Standard Setup (Project Tracker)
+
+For building real applications, use the `showcase` template. This sets up a proper folder structure with YAML metadata, TypeScript logic hooks, and relationship management.
 
-Create `index.ts`. This script defines the schema, boots the engine, and runs queries in one go.
+```bash
+npm create @objectql@latest project-tracker -- --template showcase
+```
+
+This structure follows our **Best Practices**:
+*   **`src/objects/*.object.yml`**: Data definitions.
+*   **`src/hooks/*.hook.ts`**: Business logic.
+*   **`src/index.ts`**: Application entry point.
+
+## Manual Setup (The Hard Way)
+
+If you prefer to set up manually or add ObjectQL to an existing project:
 
 ```typescript
 import { ObjectQL } from '@objectql/core';
@@ -82,13 +99,12 @@ async function main() {
         // Detects 'sqlite', 'postgres', 'mongodb' automatically
         connection: 'sqlite://data.db', 
 
-        // 2. Schema Source
-        // Where your *.object.yml files are located
-        source: ['src/objects'],
-
-        // 3. Load Presets (Optional)
-        // Load standard objects from npm packages
-        presets: ['@objectql/preset-auth']
+        // 2. Load Modules
+        // Load schema from local directories OR npm packages
+        modules: [
+            'src/objects',           // Local Module
+            '@objectql/module-auth'  // External Module (NPM)
+        ]
     });
 
     await db.init();