Refactor spec docs: restructure schema and add actions/hooks

Reorganized the spec documentation by splitting metadata-format.md into object.md, and updating sidebar and index to reflect new structure. Added new documentation for Actions (action.md) and Hooks (hook.md). Removed http-protocol.md and updated references to match the new organization.

Author: hotlong

docs/.vitepress/config.mts

@@ -43,12 +43,18 @@ export default defineConfig({
       // Sidebar for Spec section
       '/spec/': [
         {
-          text: 'Protocol Specifications',
+          text: 'Core Schema',
           items: [
             { text: 'Overview', link: '/spec/' },
-            { text: 'Metadata Format', link: '/spec/metadata-format' },
+            { text: 'Objects & Fields', link: '/spec/object' },
+            { text: 'Actions (RPC)', link: '/spec/action' },
+            { text: 'Hooks', link: '/spec/hook' },
+          ]
+        },
+        {
+          text: 'Data & Transport',
+          items: [
             { text: 'Query Language', link: '/spec/query-language' },
-            { text: 'HTTP Protocol', link: '/spec/http-protocol' }
           ]
         }
       ]

docs/spec/action.md

@@ -0,0 +1,27 @@
+# Action Definitions (RPC)
+
+Custom business logic can be defined in the `actions` section. Actions act as Remote Procedure Calls (RPC) scoped to the object.
+
+```yaml
+actions:
+  approve:
+    label: Approve Request
+    description: Approves the current record.
+    params:
+      comment:
+        type: textarea
+        label: Approval Comments
+    result:
+      type: boolean
+```
+
+## 1. Properties
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `label` | `string` | Display label (e.g., for buttons). |
+| `icon` | `string` | Icon name. |
+| `description` | `string` | Help text. |
+| `confirmText` | `string` | Confirmation message before execution. |
+| `params` | `Map<string, FieldConfig>` | Input parameters schema. Same structure as Object fields. |
+| `result` | `FieldConfig` | The shape of the return value. |

docs/spec/hook.md

@@ -0,0 +1,31 @@
+# Hooks (Triggers)
+
+Hooks allow you to execute server-side logic before or after database operations. They are defined in a separate `*.hook.ts` file or registered dynamically.
+
+## 1. Supported Hooks
+
+| Hook | Description | Context Properties |
+| :--- | :--- | :--- |
+| `beforeFind` | Before a query is executed. | `query` |
+| `afterFind` | After a query is executed (results available). | `query`, `result` |
+| `beforeCreate` | Before a record is inserted. | `doc` |
+| `afterCreate` | After a record is inserted. | `doc`, `result`, `id` |
+| `beforeUpdate` | Before a record is updated. | `id`, `doc`, `query` |
+| `afterUpdate` | After a record is updated. | `id`, `doc`, `result` |
+| `beforeDelete` | Before a record is deleted. | `id`, `query` |
+| `afterDelete` | After a record is deleted. | `id`, `result` |
+
+## 2. Hook Implementation
+
+```typescript
+import { ObjectQL } from '@objectql/core';
+
+// Inside your server-side loader
+const objectql = new ObjectQL();
+
+objectql.registerHook('projects', 'beforeCreate', async (ctx) => {
+    if (ctx.doc.budget < 0) {
+        throw new Error("Budget cannot be negative");
+    }
+});
+```

docs/spec/http-protocol.md

@@ -2,9 +2,12 @@
 
 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.
-*   [**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.
+## Core Schema
+*   [**Objects & Fields**](./object.md) - Defining data models, field types, and validation rules.
+*   [**Actions (RPC)**](./action.md) - Defining custom server-side functions and APIs.
+*   [**Hooks (Triggers)**](./hook.md) - Attaching logic to database events.
+*   [**App Definition**](./app.md) - Configuring menus and UI layout.
+
+## Data & Transport
+*   [**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.