Complete comprehensive revision of .github/copilot-instructions.md

- Updated architecture tables with actual package structure
- Added all missing packages (platform-node, sdk, starters)
- Expanded dependency graph with platform and SDK layers
- Added comprehensive metadata types section (12 types)
- Added documentation references for specs, guides, and API
- Added build & test command section
- Added examples & starters information
- Added common patterns & best practices with code examples
- Expanded package descriptions to match actual implementations

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

.github/copilot-instructions.md

@@ -50,53 +50,337 @@ You must strictly enforce the following dependency rules:
 
 1. **The Base:** `@objectql/types` is the bottom layer. It relies on NOTHING.
 2. **The Facade:** `@objectql/core` depends on `types`.
-3. **The Drivers:** `@objectql/driver-*` depends on `types` (to implement interfaces) and external libs (knex, mongodb).
-4. **The Server:** `@objectql/server` depends on `core` and `types`.
+3. **Platform Layer:** `@objectql/platform-node` depends on `types` and `core` for Node.js-specific features.
+4. **The Drivers:** `@objectql/driver-*` depends on `types` (to implement interfaces) and external libs (knex, mongodb).
+5. **The SDK:** `@objectql/sdk` (remote driver) depends on `types` only.
+6. **The Server:** `@objectql/server` depends on `core` and `types`.
+7. **The Tools:** `@objectql/cli` and `@objectql/studio` depend on `core`, `types`, and may use platform-specific packages.
+
+**Critical Rules:**
 * 🔴 **FORBIDDEN:** Drivers must **NOT** depend on `core`. This prevents circular dependencies.
 * 🔴 **FORBIDDEN:** `types` and `core` must **NOT** import Node.js native modules (`fs`, `net`, `crypto`) to ensure browser compatibility (except where polyfilled or ignored in browser builds).
+* 🔴 **FORBIDDEN:** Universal packages (`types`, `core`, `sdk`) must work in both Node.js and browser environments.
 
 ## 4. Specific Package Instructions
 
-### 📦 `packages/types`
+### 📦 `packages/foundation/types`
 
 * **Content:**
-* `interface ObjectConfig`: The shape of the JSON schema.
-* `interface ObjectQLDriver`: The interface that all drivers must implement.
-* `interface IObjectRegistry`: The interface for registry behavior.
-* `enum FieldType`: `'text' | 'select' | 'lookup' ...`
-* `class ObjectQLError`: Shared error types.
+* `interface ObjectConfig`: The shape of object metadata schema.
+* `interface FieldConfig`: Field definition and validation configuration.
+* `interface Driver`: The interface that all drivers must implement.
+* `interface MetadataRegistry`: The interface for registry behavior.
+* `interface ValidationConfig`: Validation rules configuration.
+* `interface HookConfig`: Hook/trigger definitions.
+* `interface ActionConfig`: Custom RPC action definitions.
+* `interface PageConfig`: UI page metadata.
+* `interface PermissionConfig`: Access control rules.
+* `interface MenuConfig`: Navigation menu definitions.
+* `interface AppConfig`: Application container metadata.
 
-* **Rule:** Keep it extremely lightweight. No business logic.
+* **Rule:** Keep it extremely lightweight. No business logic. Pure types only.
 
-### 📦 `packages/core` (The User Entry Point)
+### 📦 `packages/foundation/core` (The User Entry Point)
 
 * **Content:**
 * `class ObjectQL`: The main class (similar to TypeORM `DataSource`).
-* Methods: `connect()`, `register()`, `find()`, `create()`.
+* Methods: `init()`, `createContext()`, `getObject()`.
+* `class ObjectRepository`: Repository pattern for CRUD operations.
+* Methods: `find()`, `findOne()`, `create()`, `update()`, `delete()`.
+* `class Validator`: Metadata-driven validation engine.
+* Supports field-level, cross-field, and state machine validation.
+
+* **Role:** It orchestrates the flow. It validates requests and delegates execution to the injected `driver`.
+
+### 📦 `packages/foundation/platform-node`
+
+* **Content:**
+* `class ObjectLoader`: File-based metadata loader using glob patterns.
+* Supports `*.object.yml`, `*.validation.yml`, `*.permission.yml`, etc.
+* `class PluginManager`: Plugin system for extending functionality.
+
+* **Role:** Provides Node.js-specific utilities for loading metadata from the filesystem.
 
-* `class SimpleRegistry`: A default in-memory implementation of `IObjectRegistry`.
+### 📦 `packages/drivers/sql` (SQL Driver)
+
+* **Content:** Implementation of `Driver` interface using Knex.js.
+* **Role:**
+* Translate ObjectQL queries → SQL queries.
+* Support for PostgreSQL, MySQL, SQLite.
+* Hybrid storage strategy: Core columns + JSONB for dynamic fields.
+* Execute queries via Knex and map results back to ObjectQL format.
 
-* **Role:** It orchestrates the flow. It validates the request using `SimpleRegistry` and delegates execution to the injected `driver`.
+* **Note:** Drivers maintain their own minimal mapping of "Object Name → Table Name".
 
-### 📦 `packages/driver-*` (SQL / Mongo)
+### 📦 `packages/drivers/mongo` (MongoDB Driver)
 
-* **Content:** Implementation of `ObjectQLDriver`.
+* **Content:** Implementation of `Driver` interface using MongoDB Node.js driver.
 * **Role:**
-* Translate ObjectQL AST -> SQL / MongoDB Query.
-* Execute query via underlying lib (e.g., `knex`, `mongodb`).
-* Map DB results back to ObjectQL format.
+* Translate ObjectQL queries → MongoDB aggregation pipelines.
+* Support for schema-less data and rapid prototyping.
+* Native MongoDB performance with full CRUD and filtering support.
+
+### 📦 `packages/drivers/sdk` (Remote/HTTP Driver)
+
+* **Content:** Implementation of `Driver` interface for remote ObjectQL servers.
+* **Role:**
+* Connect to ObjectQL servers via HTTP/REST.
+* Useful for client-side applications (browser, mobile).
+* Translates local API calls to HTTP requests.
+
+* **Environment:** Universal (works in Node.js and browsers).
+
+### 📦 `packages/runtime/server`
+
+* **Content:** HTTP server adapter with Express middleware.
+* **Role:** 
+* Exposes ObjectQL operations via REST and JSON-RPC APIs.
+* Handlers: `createNodeHandler()`, `createMetadataHandler()`, `createStudioHandler()`.
+* Provides endpoints for CRUD operations, metadata introspection, and admin UI.
+
+### 📦 `packages/tools/cli`
 
-* **Note:** Drivers should maintain their own minimal mapping of "Object Name -> Table Name".
+* **Content:** Command-line interface for ObjectQL projects.
+* **Commands:**
+* `init`: Initialize new project from templates.
+* `validate`: Validate metadata files.
+* `migrate`: Database migration tools.
+* `studio`: Launch web-based admin console.
 
-### 📦 `packages/server`
+### 📦 `packages/tools/studio`
 
-* **Content:** HTTP adapter.
-* **Role:** Exposes ObjectQL operations via REST/GraphQL-like API.
+* **Content:** Web-based admin UI (React application).
+* **Features:**
+* Object browser and schema inspector.
+* Data grid with CRUD operations.
+* Search and filtering capabilities.
+* Modern, responsive design.
 
-## 5. Development Standards
+### 📦 `packages/starters/*` (Templates)
+
+* **basic**: Minimal Node.js script example.
+* **enterprise**: Enterprise-scale metadata organization pattern with domain-driven structure.
+* **express-api**: Express.js server integration example.
+
+## 5. Metadata Types & Organization
+
+ObjectQL uses a **metadata-driven architecture**. All application logic, data models, and UI are defined in YAML/JSON files.
+
+### Core Metadata Types
+
+1. **Objects (`*.object.yml`)**: Data model definitions with fields, relationships, and indexes.
+2. **Validation (`*.validation.yml`)**: Field-level, cross-field, and state machine validation rules.
+3. **Permissions (`*.permission.yml`)**: Role-based access control and field-level security.
+4. **Hooks (`*.hook.ts`)**: Event-driven logic (beforeCreate, afterUpdate, etc.).
+5. **Actions (`*.action.ts`)**: Custom RPC methods and server-side functions.
+6. **Pages (`*.page.yml`)**: UI page layouts and components.
+7. **Views (`*.view.yml`)**: Data presentation configurations (list, grid, kanban).
+8. **Forms (`*.form.yml`)**: Data entry and editing interfaces.
+9. **Reports (`*.report.yml`)**: Analytics and BI configurations.
+10. **Menus (`*.menu.yml`)**: Navigation hierarchy and structure.
+11. **Applications (`*.app.yml`)**: Application container and configuration.
+12. **Workflows (`*.workflow.yml`)**: Business process automation.
+
+### Metadata File Naming Convention
+
+ObjectQL uses **filename-based identification**:
+- `project.object.yml` → Object name is `project`
+- `user.validation.yml` → Validation for `user` object
+- No need for redundant `name` property in most cases
+
+### Recommended Directory Structure
+
+```
+src/
+  objects/              # Core data models
+    *.object.yml       # Object definitions
+    *.validation.yml   # Validation rules
+    *.permission.yml   # Permission rules
+    *.hook.ts          # Hook implementations
+    *.action.ts        # Action implementations
+  
+  pages/               # UI pages
+    *.page.yml         # Page definitions
+  
+  views/               # Data presentation
+    *.view.yml         # View configurations
+    *.form.yml         # Form layouts
+  
+  reports/             # Analytics
+    *.report.yml       # Report definitions
+  
+  workflows/           # Business processes
+    *.workflow.yml     # Workflow definitions
+  
+  navigation/          # App structure
+    *.menu.yml         # Menu definitions
+    *.app.yml          # Application configs
+```
+
+## 6. Development Standards
 
 1. **Strict Typing:** `strict: true` in `tsconfig.json`. No `any` allowed unless absolutely necessary for low-level reflection.
 2. **Error Handling:** Throw `ObjectQLError` (from `types`) instead of generic `Error`.
-3. **Config Format:** The primary input format is `.object.yml`.
+3. **Config Format:** The primary input format is `.object.yml` (YAML) or `.object.json` (JSON).
 4. **NPM Scopes:** All internal imports must use the `@objectql/` scope (e.g., `import ... from '@objectql/types'`).
 5. **Language Requirement:** Always use English when generating code, comments, or documentation, even if the user prompts in another language.
+6. **Metadata Loading:** Use `@objectql/platform-node` for file-based metadata loading in Node.js environments.
+7. **Validation:** Always validate metadata using the `Validator` class before executing operations.
+8. **Testing:** Write tests for drivers, validation rules, and business logic. Use Jest as the testing framework.
+
+## 7. Key Documentation References
+
+### Specifications
+- **[Metadata Standard](../docs/spec/metadata-standard.md)**: Complete overview of the metadata system.
+- **[Object Schema](../docs/spec/object.md)**: Object and field definitions.
+- **[Query Language](../docs/spec/query-language.md)**: JSON-DSL query protocol.
+- **[Validation Rules](../docs/spec/validation.md)**: Validation rule types and syntax.
+- **[Hooks](../docs/spec/hook.md)**: Event-driven triggers.
+- **[Actions](../docs/spec/action.md)**: Custom RPC methods.
+- **[Permissions](../docs/spec/permission.md)**: Access control system.
+- **[Pages](../docs/spec/page.md)**: UI page metadata.
+
+### Guides
+- **[Getting Started](../docs/guide/getting-started.md)**: Quick start guide.
+- **[Architecture](../docs/guide/architecture.md)**: System architecture and design.
+- **[Data Modeling](../docs/guide/data-modeling.md)**: Best practices for defining objects.
+- **[Querying](../docs/guide/querying.md)**: How to query data.
+- **[Formulas & Rules](../docs/guide/formulas-and-rules.md)**: Validation and calculation syntax.
+- **[Metadata Organization](../docs/guide/metadata-organization.md)**: Organizing large projects.
+- **[Server Integration](../docs/guide/server-integration.md)**: Running ObjectQL as an HTTP server.
+
+### API Reference
+- **[API Overview](../docs/api/README.md)**: Complete API documentation.
+- **[Authentication](../docs/api/authentication.md)**: Security and authentication.
+
+## 8. Build & Test Commands
+
+### Building the Project
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build all packages (TypeScript compilation)
+pnpm run build
+
+# Build specific package
+cd packages/foundation/core && pnpm run build
+```
+
+### Testing
+
+```bash
+# Run all tests
+pnpm test
+
+# Test specific package
+cd packages/foundation/core && pnpm test
+```
+
+### Development Tools
+
+```bash
+# Launch admin studio
+pnpm run studio
+
+# Generate documentation
+pnpm run docs:dev
+```
+
+## 9. Examples & Starters
+
+### Available Examples
+
+1. **`packages/starters/basic`**: Minimal Node.js script showing ObjectQL basics.
+2. **`packages/starters/express-api`**: Express.js server with ObjectQL REST API.
+3. **`packages/starters/enterprise`**: Enterprise-scale project structure with domain-driven organization.
+4. **`examples/tutorials/tutorial-task-manager`**: Task management application example.
+5. **`examples/tutorials/tutorial-crm-system`**: CRM system with accounts, contacts, and opportunities.
+6. **`examples/tutorials/tutorial-federation`**: Multi-database federation example.
+7. **`examples/plugins/audit-log`**: Plugin example for audit logging.
+
+### Using Starters
+
+Starters demonstrate best practices and provide templates for new projects:
+- **Basic**: Learn the fundamentals with a simple script.
+- **Express API**: See how to integrate ObjectQL into an Express server.
+- **Enterprise**: Understand how to organize metadata in large-scale applications with multiple modules.
+
+## 10. Common Patterns & Best Practices
+
+### Object Definition Pattern
+
+```yaml
+# File: project.object.yml
+# Name is inferred from filename
+
+label: Project
+fields:
+  name:
+    type: text
+    required: true
+    label: Project Name
+  
+  status:
+    type: select
+    options:
+      - { label: Planning, value: planning }
+      - { label: Active, value: active }
+      - { label: Completed, value: completed }
+  
+  owner:
+    type: lookup
+    reference_to: users
+    label: Project Owner
+```
+
+### Validation Pattern
+
+```yaml
+# File: project.validation.yml
+
+rules:
+  - name: valid_date_range
+    type: cross_field
+    rule:
+      field: end_date
+      operator: '>='
+      compare_to: start_date
+    message: End date must be after start date
+    severity: error
+```
+
+### Hook Pattern
+
+```typescript
+// File: project.hook.ts
+import { HookDefinition } from '@objectql/types';
+
+export const beforeCreate: HookDefinition = {
+  when: 'before.create',
+  async handler(ctx) {
+    // Auto-set created date
+    ctx.record.created_at = new Date();
+  }
+};
+```
+
+### Action Pattern
+
+```typescript
+// File: project.action.ts
+import { ActionDefinition } from '@objectql/types';
+
+export const completeProject: ActionDefinition = {
+  label: 'Complete Project',
+  async handler(ctx) {
+    const { id } = ctx.input;
+    await ctx.object('project').update(id, {
+      status: 'completed',
+      completed_at: new Date()
+    });
+    return { success: true };
+  }
+};
+```