Restore docs/guide directory (server-side documentation)

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

Author: Copilot

docs/guide/architecture/overview.md

@@ -0,0 +1,34 @@
+# Architecture & Concepts
+
+ObjectQL is built with a modular architecture that separates the data definition (Metadata) from the execution engine (Driver). This design allows applications to run on different database stacks (SQL vs NoSQL) without changing the business logic.
+
+## High-Level Overview
+
+An ObjectQL application consists of three main layers:
+
+1.  **Metadata Layer**: JSON/YAML files that define the shape of your data (`.object.yml`) and operations.
+2.  **Core Engine**: The `ObjectQL` class that loads metadata, validates requests, and orchestrates execution.
+3.  **Driver Layer**: Adapters that translate ObjectQL requests into database-specific queries (SQL, Mongo Protocol, etc.).
+
+## Dependency Graph
+
+The project is structured as a monorepo with strict dependency rules to ensure scalability and maintainability.
+
+*   **`@objectql/types`**: The shared contract. Contains all interfaces (`ObjectConfig`, `ObjectQLDriver`). Has **zero dependencies**.
+*   **`@objectql/core`**: The main runtime. It depends on `types`.
+*   **`@objectql/driver-*`**: Database adapters. They implement interfaces from `types` but do **not** depend on `core` (avoiding circular dependencies).
+
+## Core Concepts
+
+### 1. Metadata-First
+In traditional ORMs (like TypeORM or Prisma), you define classes/schema in code. In ObjectQL, the schema is data itself. This allows:
+*   Dynamic schema generation at runtime.
+*   Building "No-Code" table designers.
+*   Hot-reloading of data structure without recompiling.
+
+### 2. Universal Protocol
+ObjectQL uses a unified JSON-based query language (AST). This allows frontends, AI agents, or external systems to send complex queries (`filters`, `expand`, `aggregates`) in a safe, serializable format.
+
+### 3. Logic: Actions & Hooks
+*   **Hooks**: Intercept standard CRUD operations (e.g., "Before Create", "After Update") to enforce business rules.
+*   **Actions**: Define custom RPC methods (e.g., "Approve Invoice") exposed via the API.

docs/guide/architecture/why-objectql.md

@@ -0,0 +1,54 @@
+# Why ObjectQL?
+
+In the era of AI automation, the requirements for backend infrastructure have shifted. We are no longer just building for human users on web forms; we are building systems that **AI Agents** need to read, understand, and manipulate.
+
+## The Problem with Traditional ORMs
+
+Tools like TypeORM, Prisma, or Sequelize are fantastic for human developers. They rely heavily on:
+1.  **Complex TypeScript Types**: Great for IDE autocomplete, but invisible to an LLM running in a production execution environment.
+2.  **Chained Method Calls**: `db.users.where(...).include(...)`. This requires the AI to synthesize valid executable code, which is prone to syntax errors and hallucinations.
+3.  **Code-First Schema**: The schema is buried in class definitions, making it hard to extract a simple "map" of the data for the AI context window.
+
+## The ObjectQL Solution: Protocol-First
+
+ObjectQL treats **Logic as Data**.
+
+### 1. Schema is JSON (The Context)
+Instead of parsing TypeScript files, an AI Agent can simply read a JSON definition. This is the native tongue of LLMs.
+
+```json
+{
+  "name": "contact",
+  "fields": { "email": { "type": "text", "required": true } }
+}
+```
+
+This compact format fits perfectly in RAG (Retrieval-Augmented Generation) contexts.
+
+### 2. Queries are ASTs (The Action)
+To fetch data, the AI doesn't need to write SQL or function code. It generates a JSON object (Abstract Syntax Tree).
+
+```json
+{
+  "op": "find",
+  "from": "contact",
+  "filters": [["email", "contains", "@gmail.com"]]
+}
+```
+*   **Safe**: No SQL Injection possible. The Driver handles escaping.
+*   **Deterministic**: It either parses or it fails. No subtle logic bugs from misplaced parentheses in code.
+*   **Portability**: The same JSON runs on Mongo, Postgres, or a REST API.
+
+## Comparison
+
+| Feature | Traditional ORM | ObjectQL |
+| :--- | :--- | :--- |
+| **Schema Definition** | TypeScript Classes / Migration Files | JSON / YAML Metadata |
+| **Query Language** | Fluent API / Raw SQL | JSON AST |
+| **Runtime** | Node.js / Python Runtime | Universal Protocol (Any Language) |
+| **AI Friendliness** | Low (Requires Code Gen) | High (Requires JSON Gen) |
+| **Dynamic Fields** | Hard (Migration required) | Native (Metadata-driven) |
+
+## Conclusion
+
+If you are building a Copilot, an Autonomous Agent, or a Low-Code platform, ObjectQL provides the structured, safe, and descriptive layer that connects your LLM to your database.

docs/guide/cli.md

@@ -0,0 +1,258 @@
+# CLI Guide
+
+The ObjectQL CLI (`@objectql/cli`) is an essential tool for development, automating tasks like type generation and database migrations.
+
+## 1. Installation
+
+The CLI is typically installed as a dev dependency in your project.
+
+```bash
+npm install -D @objectql/cli
+```
+
+You can then run it via `npx objectql` or add scripts to your `package.json`.
+
+## 2. Core Commands
+
+### 2.1 `init` (Create Project)
+
+Create a new ObjectQL project from a starter template.
+
+```bash
+npx objectql init [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. |
+| `--skip-install` | | `false` | Skip dependency installation. |
+| `--skip-git` | | `false` | Skip git initialization. |
+
+**Example:**
+
+```bash
+npx objectql init -t express-api -n my-app
+```
+
+### 2.2 `generate` (Type Generation)
+
+Scans your `*.object.yml` files and generates TypeScript interfaces. This is crucial for maintaining type safety in your Hooks and Actions.
+**Alias**: `g`
+
+```bash
+npx objectql generate [options]
+```
+
+**Options:**
+
+| Option | Alias | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `--source <path>` | `-s` | `.` | Root directory to search for object files. |
+| `--output <path>` | `-o` | `./src/generated` | Directory where `.ts` files will be generated. |
+
+**Example:**
+
+```bash
+# Generate types from /src/objects to /src/types
+npx objectql generate --source ./src/objects --output ./src/types
+```
+
+### 2.3 `new` (Scaffold Metadata)
+
+Generate a new metadata file (Object, View, Form, etc.) in the project.
+
+```bash
+npx objectql new <type> <name> [options]
+```
+
+**Arguments:**
+*   `<type>`: The type of metadata to generate (e.g., `object`, `view`, `page`).
+*   `<name>`: The name of the file/entity.
+
+**Options:**
+
+| Option | Alias | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `--dir <path>` | `-d` | `.` | Output directory. |
+
+**Example:**
+```bash
+npx objectql new object customer
+```
+
+## 3. Development Tools
+
+### 3.1 `serve` (Dev Server)
+
+Start a standalone development server.
+**Alias**: `s`
+
+```bash
+npx objectql serve [options]
+```
+
+**Options:**
+
+| Option | Alias | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `--port <number>` | `-p` | `3000` | Port to listen on. |
+| `--dir <path>` | `-d` | `.` | Directory containing schema. |
+
+### 3.2 `studio` (Admin UI)
+
+Starts the web-based admin studio to browse data and view schema.
+**Alias**: `ui`
+
+```bash
+npx objectql studio [options]
+```
+
+**Options:**
+
+| Option | Alias | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `--port <number>` | `-p` | `3000` | Port to listen on. |
+| `--dir <path>` | `-d` | `.` | Directory containing schema. |
+| `--no-open` | | `false` | Do not open the browser automatically. |
+
+### 3.3 `repl` (Interactive Shell)
+
+Starts an interactive terminal similar to the MongoDB shell, allowing you to directly query your database using the ObjectQL API.
+**Alias**: `r`
+
+```bash
+npx objectql repl [options]
+```
+
+**Options:**
+
+| Option | Alias | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `--config <path>` | `-c` | - | Path to `objectql.config.ts/js`. |
+
+**Example Session:**
+
+```javascript
+objectql> await tasks.find({ status: 'todo' })
+[ { id: 1, title: 'Fix bug', status: 'todo' } ]
+```
+
+## 4. Internationalization (i18n)
+
+Tools for managing translations.
+
+### 4.1 `i18n extract`
+
+Extract translatable strings from metadata files into JSON.
+
+```bash
+npx objectql i18n extract [options]
+```
+
+**Options:**
+
+| Option | Alias | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `--source <path>` | `-s` | `.` | Source directory to scan. |
+| `--output <path>` | `-o` | `./src/i18n` | Output directory for translation files. |
+| `--lang <lang>` | `-l` | `en` | Language code. |
+
+### 4.2 `i18n init`
+
+Initialize i18n structure for a new language.
+
+```bash
+npx objectql i18n init <lang> [options]
+```
+
+**Options:**
+
+| Option | Alias | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `--base-dir <path>` | `-b` | `./src/i18n` | Base i18n directory. |
+
+### 4.3 `i18n validate`
+
+Validate translation completeness against a base language.
+
+```bash
+npx objectql i18n validate <lang> [options]
+```
+
+**Options:**
+
+| Option | Alias | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `--base-dir <path>` | `-b` | `./src/i18n` | Base i18n directory. |
+| `--base-lang <lang>` | | `en` | Base language to compare against. |
+
+## 5. Database Migration
+
+Manage database schema changes.
+
+### 5.1 `migrate`
+
+Run pending database migrations.
+
+```bash
+npx objectql migrate [options]
+```
+
+**Options:**
+
+| Option | Alias | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `--config <path>` | `-c` | - | Path to `objectql.config.ts/js`. |
+| `--dir <path>` | `-d` | `./migrations` | Migrations directory. |
+
+### 5.2 `migrate create`
+
+Create a new migration file.
+
+```bash
+npx objectql migrate create <name> [options]
+```
+
+**Options:**
+
+| Option | Alias | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `--dir <path>` | `-d` | `./migrations` | Migrations directory. |
+
+### 5.3 `migrate status`
+
+Show the status of migrations (applied/pending).
+
+```bash
+npx objectql migrate status [options]
+```
+
+**Options:**
+
+| Option | Alias | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `--config <path>` | `-c` | - | Path to `objectql.config.ts/js`. |
+| `--dir <path>` | `-d` | `./migrations` | Migrations directory. |
+
+## 6. Integration with Workflow
+
+We recommend adding the CLI commands to your lifecycle scripts.
+
+**package.json:**
+
+```json
+{
+  "scripts": {
+    "codegen": "objectql generate -s ./src -o ./src/generated",
+    "build": "npm run codegen && tsc",
+    "dev": "npm run codegen && ts-node src/index.ts",
+    "studio": "objectql studio"
+  }
+}
+```
+
+This ensures that whenever you build or start your app, your TypeScript types are perfectly synced with your YAML definitions.

docs/guide/configuration.md

@@ -0,0 +1,44 @@
+# Configuration
+
+ObjectQL is configured by passing an `ObjectQLConfig` object to the constructor.
+
+## Basic Layout
+
+```typescript
+// objectql.config.ts
+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
+    plugins: [] // 4. Extensions
+});
+```
+
+## Reference
+
+### `connection` (string)
+The Connection String URI defining the database connection.
+*   `sqlite://path/to/db`
+*   `postgres://user:pass@host:5432/db`
+*   `mongodb://host:27017/db`
+
+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.
+
+### `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.).
+
+### `plugins` ((ObjectQLPlugin | string)[])
+A list of plugin instances OR package names to extend the core functionality.
+See [Plugin System](./plugins.html) for details.
+
+### `objects` (Record<string, ObjectConfig>)
+(Advanced) In-memory definition of objects. Useful for dynamic runtime schema generation.
+Objects defined here take highest priority.