Add comprehensive documentation for ObjectQL hooks, API, security model, and metadata specifications

- Introduced examples and detailed explanations for lifecycle hooks in `logic-hooks-examples.md`.
- Expanded the `logic-hooks.md` to cover the lifecycle hooks, their signatures, and registration processes.
- Documented the ObjectQL API in `sdk-reference.md`, detailing context management, query and mutation APIs, and advanced features.
- Established a security model in `security-guide.md`, outlining RBAC and policy definitions.
- Specified metadata format and query language in `metadata-format.md` and `query-language.md`, respectively.
- Created a REST API reference in `http-protocol.md`, detailing standard and advanced endpoints for CRUD operations.

Author: hotlong

docs/README.md

@@ -0,0 +1,18 @@
+# ObjectQL Documentation
+
+We have organized the documentation into two main categories:
+
+## 1. [User & Developer Guide](./guide/README.md)
+**Target Audience**: Application Developers, Customer Success, End Users.
+**Content**:
+*   How to model data (Objects, Fields, Relationships).
+*   How to write business logic (Hooks, Actions).
+*   Using the Node.js SDK.
+*   Security configuration.
+
+## 2. [Protocol Specifications](./spec/README.md)
+**Target Audience**: System Architects, Driver Contributors, Integrators.
+**Content**:
+*   Metadata File Format Specification (YAML/JSON schema).
+*   Unified Query Language Protocol.
+*   Low-level HTTP API Reference.

docs/guide/README.md

@@ -0,0 +1,21 @@
+# Developer & User Guide
+
+Welcome to the ObjectQL User Guide. This documentation is designed to help you build applications using the ObjectQL platform.
+
+## 1. Essentials
+*   [**Data Modeling Guide**](./data-modeling.md) (Recommended First Read)
+    *   Learn how to define Objects, Fields, and Relationships.
+    *   Guide to using rich field types: Email, URL, Files, Images, and Formulas.
+*   [**Security Guide**](./security-guide.md)
+    *   Understanding authentication and permissions.
+
+## 2. Server-Side Logic
+*   [**SDK Reference**](./sdk-reference.md)
+    *   Using the Node.js API to query and manipulate data.
+*   [**Hooks**](./logic-hooks.md)
+    *   Writing triggers (before/after create, update, delete).
+*   [**Hooks Examples**](./logic-hooks-examples.md)
+    *   Real-world code snippets for automation.
+*   [**Custom Actions**](./logic-actions.md)
+    *   Defining custom RPC endpoints.
+

docs/guide/data-modeling.md

@@ -0,0 +1,80 @@
+# Data Modeling Guide
+
+Modeling your business data is the first step in building an ObjectQL application. This guide introduces the core concepts.
+
+## 1. Objects
+
+An **Object** is like a database table. It represents a business entity, such as a Customer, Order, or Product.
+
+```yaml
+# customer.object.yml
+name: customer
+label: Customer
+icon: user
+description: Stores customer information.
+fields:
+  name:
+    type: text
+    label: Full Name
+    required: true
+```
+
+## 2. Fields
+
+Fields store the data attributes for an object. ObjectQL provides a rich set of field types.
+
+### 2.1 Basic Types
+*   **Text & Area**: `text`, `textarea`, `markdown`, `html`
+*   **Numbers**: `number`, `currency`, `percent`
+*   **Switch**: `boolean` (checkbox)
+*   **Date**: `date`, `datetime`, `time`
+*   **System**: `password`, `auto_number`
+
+### 2.2 Format Types
+These types provide automatic validation and formatted display.
+*   **Email** (`email`): Validates email addresses.
+*   **Phone** (`phone`): Stores phone numbers.
+*   **URL** (`url`): Validates web links.
+
+### 2.3 Media & Files
+*   **File** (`file`): Upload generic documents.
+*   **Image** (`image`): Upload pictures with preview support.
+*   **Avatar** (`avatar`): User profile pictures.
+
+*Note: You can allow multiple files/images by setting `multiple: true`.*
+
+### 2.4 Location
+*   **Location** (`location`): Stores Latitude and Longitude. Useful for maps.
+
+### 2.5 Calculations
+*   **Formula**: Calculate values automatically based on other fields.
+    *   Example: `Total` = `Price` * `Quantity`
+*   **Summary**: Aggregate data from child records (e.g., Total Order Amount for a Customer).
+
+## 3. Relationships
+
+Linking objects together is powerful.
+
+*   **Lookup**: A simple link to another object. (e.g., An Order looks up a Customer).
+*   **Master-Detail**: A strong parent-child relationship. If the parent is deleted, children are deleted.
+
+```yaml
+# order.object.yml
+fields:
+  customer:
+    type: lookup
+    reference_to: customer
+    label: Customer
+```
+
+## 4. Attributes
+
+You can enforce rules on your data using attributes:
+
+*   `required`: Cannot be empty.
+*   `unique`: Must be unique in the whole table.
+*   `min`, `max`: Range validation for numbers.
+*   `defaultValue`: Automatic initial value.
+*   `hidden`: Hide from standard UI.
+*   `readonly`: Prevent editing in UI.
+

docs/ACTIONS.md docs/guide/logic-actions.mddocs/ACTIONS.md renamed to docs/guide/logic-actions.md

@@ -0,0 +1,11 @@
+# Protocol Specifications
+
+This section contains the technical specifications for the ObjectQL platform. It is intended for driver developers, system integrators, and anyone who needs to understand the low-level protocols.
+
+*   [**Metadata Format**](./metadata-format.md)
+    *   Complete definition of the YAML/JSON schema for Objects and Fields.
+    *   Includes new types: `file`, `image`, `location`, `formula`, `summary`, etc.
+*   [**Query Language (JSON)**](./query-language.md)
+    *   Specification of the Unified Query JSON format used by drivers and APIs.
+*   [**HTTP Protocol**](./http-protocol.md)
+    *   Standard REST API endpoints and payload formats.