Split ObjectQL Protocol Specification into focused documents in subfolder

content/docs/02-objectql/protocol-spec/aggregation.mdx

@@ -0,0 +1,145 @@
+---
+title: Aggregation Operations
+description: Complete reference for grouping and aggregating data in ObjectQL
+---
+
+# Aggregation Operations
+
+This document provides the complete specification for ObjectQL's Aggregation operations.
+
+## GroupBy
+
+```typescript
+db.aggregate(objectName: string, options: AggregateOptions)
+
+interface AggregateOptions {
+  group_by: string[]
+  having?: Filter[]
+  fields?: AggregateField[]
+  sort?: string | Sort[]
+  limit?: number
+}
+```
+
+### Basic GroupBy
+
+```typescript
+// Count by category
+await db.aggregate('product', {
+  group_by: ['category'],
+  fields: [
+    { field: '_id', function: 'count', alias: 'total' }
+  ]
+})
+
+// Result: [
+//   { category: 'Electronics', total: 45 },
+//   { category: 'Books', total: 123 }
+// ]
+```
+
+### Multiple Groupings
+
+```typescript
+// Sales by year and quarter
+await db.aggregate('order', {
+  group_by: ['YEAR(created)', 'QUARTER(created)'],
+  fields: [
+    { field: 'amount', function: 'sum', alias: 'total_sales' },
+    { field: '_id', function: 'count', alias: 'order_count' }
+  ],
+  sort: 'YEAR(created) desc, QUARTER(created) desc'
+})
+```
+
+## Aggregate Functions
+
+```typescript
+// Count
+{ field: '_id', function: 'count' }
+
+// Sum
+{ field: 'amount', function: 'sum' }
+
+// Average
+{ field: 'price', function: 'avg' }
+
+// Min
+{ field: 'price', function: 'min' }
+
+// Max
+{ field: 'price', function: 'max' }
+
+// Distinct count
+{ field: 'customer_id', function: 'count_distinct' }
+```
+
+## Having Clause
+
+Filter aggregated results:
+
+```typescript
+await db.aggregate('order', {
+  group_by: ['customer_id'],
+  fields: [
+    { field: 'amount', function: 'sum', alias: 'total_spent' },
+    { field: '_id', function: 'count', alias: 'order_count' }
+  ],
+  having: [
+    ['total_spent', '>', 1000]    // Only customers who spent > 1000
+  ]
+})
+```
+
+## Complete Aggregation Example
+
+```typescript
+// Monthly sales report with filters
+const monthlySales = await db.aggregate('invoice', {
+  // Pre-aggregation filters (WHERE clause)
+  filters: [
+    ['status', '=', 'paid'],
+    ['created', '>=', '2024-01-01']
+  ],
+
+  // Group by
+  group_by: ['YEAR(created)', 'MONTH(created)'],
+
+  // Aggregate calculations
+  fields: [
+    { field: 'amount', function: 'sum', alias: 'revenue' },
+    { field: '_id', function: 'count', alias: 'invoice_count' },
+    { field: 'amount', function: 'avg', alias: 'avg_invoice' },
+    { field: 'customer_id', function: 'count_distinct', alias: 'unique_customers' }
+  ],
+
+  // Post-aggregation filters (HAVING clause)
+  having: [
+    ['revenue', '>', 50000]  // Only months with revenue > 50k
+  ],
+
+  // Sort results
+  sort: 'YEAR(created) desc, MONTH(created) desc',
+
+  // Limit results
+  limit: 12  // Last 12 months
+})
+
+// Result: [
+//   {
+//     year: 2024,
+//     month: 3,
+//     revenue: 125000,
+//     invoice_count: 45,
+//     avg_invoice: 2777.78,
+//     unique_customers: 32
+//   },
+//   ...
+// ]
+```
+
+## Next Steps
+
+- Learn [Query DSL](/docs/02-objectql/protocol-spec/query-dsl) for basic queries
+- Master [Mutation Operations](/docs/02-objectql/protocol-spec/mutation) for data modification
+- Review [Schema Definition](/docs/02-objectql/protocol-spec/schema-definition) for data modeling

content/docs/02-objectql/protocol-spec/index.mdx

@@ -0,0 +1,101 @@
+---
+title: Protocol Specification
+description: Overview and reference guide for ObjectQL's protocol specification
+---
+
+# Protocol Specification
+
+ObjectQL uses a protocol-driven architecture with a comprehensive specification covering data modeling, querying, aggregation, and mutation operations. This specification ensures consistency across implementations and provides a clear contract for developers.
+
+## Core Components
+
+The ObjectQL protocol specification is divided into four main components:
+
+### [Schema Definition](/docs/02-objectql/protocol-spec/schema-definition)
+
+Define your data model with:
+- **Object definitions** - Database tables with metadata
+- **Field types** - Text, numeric, date/time, boolean, select, relationship, and special fields
+- **Field constraints** - Validation, indexes, and dependencies
+
+### [Query DSL](/docs/02-objectql/protocol-spec/query-dsl)
+
+Query your data with:
+- **Filters** - Comparison, string, list, null, and compound operators
+- **Sorting** - Single or multiple field ordering
+- **Pagination** - Limit and skip for efficient data retrieval
+- **Field selection** - Choose specific fields including related data
+
+### [Aggregation Operations](/docs/02-objectql/protocol-spec/aggregation)
+
+Analyze your data with:
+- **GroupBy** - Group records by one or more fields
+- **Aggregate functions** - Count, sum, average, min, max, distinct count
+- **Having clause** - Filter aggregated results
+- **Pre and post-aggregation filters** - WHERE and HAVING clauses
+
+### [Mutation Operations](/docs/02-objectql/protocol-spec/mutation)
+
+Modify your data with:
+- **Insert** - Create new records
+- **Update** - Modify existing records
+- **Delete** - Remove records
+- **Batch operations** - Efficient bulk operations
+
+## Protocol Principles
+
+The ObjectQL protocol follows these key principles:
+
+1. **Declarative** - Describe what you want, not how to get it
+2. **Type-safe** - Strong typing for reliability
+3. **Composable** - Build complex operations from simple building blocks
+4. **Efficient** - Optimized for performance at scale
+5. **Consistent** - Uniform patterns across all operations
+
+## Quick Start
+
+Here's a complete example using all protocol components:
+
+```typescript
+// 1. Define schema
+const schema = {
+  objects: {
+    customer: {
+      label: 'Customer',
+      fields: {
+        name: { type: 'text', required: true },
+        email: { type: 'email', unique: true },
+        status: { type: 'select', options: ['active', 'inactive'] }
+      }
+    }
+  }
+}
+
+// 2. Insert data
+await db.mutation('customer', {
+  action: 'insert',
+  data: { name: 'Acme Corp', email: 'contact@acme.com', status: 'active' }
+})
+
+// 3. Query data
+const customers = await db.query('customer', {
+  filters: [['status', '=', 'active']],
+  sort: 'name asc',
+  limit: 10
+})
+
+// 4. Aggregate data
+const stats = await db.aggregate('customer', {
+  group_by: ['status'],
+  fields: [{ field: '_id', function: 'count', alias: 'total' }]
+})
+```
+
+## Next Steps
+
+- Start with [Schema Definition](/docs/02-objectql/protocol-spec/schema-definition) to model your data
+- Learn [Query DSL](/docs/02-objectql/protocol-spec/query-dsl) to retrieve data
+- Master [Aggregation](/docs/02-objectql/protocol-spec/aggregation) for data analysis
+- Understand [Mutation Operations](/docs/02-objectql/protocol-spec/mutation) for data modification
+- Explore [Core Features](/docs/02-objectql/core-features) for advanced capabilities
+- Check [Core Concepts](/docs/02-objectql/core-concepts) for foundational knowledge

content/docs/02-objectql/protocol-spec/meta.json

@@ -0,0 +1,9 @@
+{
+  "title": "Protocol Specification",
+  "pages": [
+    "schema-definition",
+    "query-dsl",
+    "aggregation",
+    "mutation"
+  ]
+}

content/docs/02-objectql/protocol-spec/mutation.mdx

@@ -0,0 +1,78 @@
+---
+title: Mutation Operations
+description: Complete reference for inserting, updating, and deleting data in ObjectQL
+---
+
+# Mutation Operations
+
+This document provides the complete specification for ObjectQL's Mutation operations.
+
+## Insert
+
+```typescript
+await db.mutation('customer', {
+  action: 'insert',
+  data: {
+    name: 'Acme Corp',
+    email: 'contact@acme.com',
+    status: 'active'
+  }
+})
+```
+
+## Update
+
+```typescript
+await db.mutation('customer', {
+  action: 'update',
+  filters: [['_id', '=', customerId]],
+  data: {
+    status: 'inactive',
+    modified: new Date()
+  }
+})
+```
+
+## Delete
+
+```typescript
+await db.mutation('customer', {
+  action: 'delete',
+  filters: [['status', '=', 'archived']]
+})
+```
+
+## Batch Operations
+
+### Batch Insert
+
+```typescript
+// Batch insert
+await db.mutation('product', {
+  action: 'insert',
+  data: [
+    { name: 'Product 1', price: 10 },
+    { name: 'Product 2', price: 20 },
+    { name: 'Product 3', price: 30 }
+  ]
+})
+```
+
+### Batch Update
+
+```typescript
+// Batch update
+await db.mutation('task', {
+  action: 'update',
+  filters: [['project_id', '=', projectId]],
+  data: { status: 'cancelled' }
+})
+```
+
+## Next Steps
+
+- Learn [Query DSL](/docs/02-objectql/protocol-spec/query-dsl) for querying data
+- Explore [Aggregation](/docs/02-objectql/protocol-spec/aggregation) for data analysis
+- Review [Schema Definition](/docs/02-objectql/protocol-spec/schema-definition) for data modeling
+- Explore [Core Features](/docs/02-objectql/core-features) for performance optimizations
+- Master the [Server SDK](/docs/02-objectql/server-sdk) API reference