objectstack-ai · huangyiirene · Jan 20, 2026 · Jan 20, 2026 · Jan 20, 2026 · Jan 20, 2026
diff --git a/apps/site/content/docs/data-access/index.mdx b/apps/site/content/docs/data-access/index.mdx
@@ -0,0 +1,99 @@
+---
+title: Data Access
+description: Learn how to query and access data using ObjectQL's type-safe SDK and JSON-based protocol
+---
+
+ObjectQL provides powerful data access capabilities through a **JSON-based Protocol** that works seamlessly across different database backends. Unlike SQL strings or Query Builders, ObjectQL queries are structured data that are type-safe, serializable, and perfect for AI agents.
+
+## Overview
+
+The data access layer in ObjectQL is designed to be:
+
+- **Type-Safe**: Full TypeScript support with auto-generated types from your schema
+- **Database Agnostic**: The same query works on MongoDB, PostgreSQL, SQLite, and more
+- **AI-Friendly**: Structured JSON format prevents hallucinations and syntax errors
+- **Serializable**: Queries can be sent over HTTP, stored in files, or logged for debugging
+
+## Key Topics
+
+### [Querying Data](/docs/data-access/querying)
+
+Learn the fundamentals of querying data with ObjectQL:
+- Find operations and filters
+- Sorting and pagination
+- Field selection and data expansion
+- Aggregations and grouping
+- Complex queries with nested conditions
+
+### [Client SDK](/docs/data-access/sdk)
+
+Use the TypeScript SDK for type-safe data access:
+- Installation and setup
+- Basic CRUD operations
+- Advanced querying techniques
+- Error handling
+- TypeScript integration
+
+### [Query Best Practices](/docs/data-access/best-practices)
+
+Optimize your queries for performance:
+- Query optimization strategies
+- Avoiding N+1 problems
+- Efficient data loading
+- Caching strategies
+- Performance benchmarks
+
+## Quick Example
+
+```typescript
+import { ObjectQL } from '@objectql/core';
+
+// Initialize ObjectQL
+const app = new ObjectQL({
+  datasources: { 
+    default: driver 
+  }
+});
+
+await app.init();
+const ctx = app.createContext({ isSystem: true });
+
+// Query data with filters
+const products = await ctx.object('product').find({
+  fields: ['name', 'price', 'category'],
+  filters: [
+    ['category', '=', 'electronics'],
+    'and',
+    ['price', '<', 1000]
+  ],
+  sort: [['price', 'asc']],
+  top: 10
+});
+
+console.log('Products:', products);
+```
+
+## JSON Query Protocol
+
+All queries in ObjectQL follow a consistent JSON structure:
+
+```json
+{
+  "op": "find",
+  "object": "product",
+  "args": {
+    "fields": ["name", "price"],
+    "filters": [["category", "=", "electronics"]],
+    "top": 10
+  }
+}
+```
+
+This structure makes it easy for frontends, AI agents, and external systems to generate safe, valid queries.
+
+## Next Steps
+
+- Start with **[Querying Data](/docs/data-access/querying)** to learn the basics
+- Explore the **[Client SDK](/docs/data-access/sdk)** for type-safe access
+- Review **[Best Practices](/docs/data-access/best-practices)** for optimization strategies
+- Check the **[API Reference](/docs/reference/api)** for complete documentation
diff --git a/apps/site/content/docs/server/index.mdx b/apps/site/content/docs/server/index.mdx
@@ -0,0 +1,147 @@
+---
+title: Server & Deployment
+description: Learn how to configure, integrate, and deploy ObjectQL applications
+---
+
+ObjectQL is designed to be **framework-agnostic** and can be integrated with any Node.js server or deployed to various environments. This section covers server configuration, integration patterns, and deployment strategies.
+
+## Overview
+
+The server layer in ObjectQL provides:
+
+- **Multiple Framework Support**: Express, Next.js, Fastify, and more
+- **API Styles**: REST, JSON-RPC, GraphQL, and WebSocket support
+- **Configuration Management**: Environment-based configuration
+- **Plugin System**: Extend functionality with plugins
+- **Microservices**: Federation and distributed architectures
+
+## Key Topics
+
+### [Configuration](/docs/server/configuration)
+
+Configure your ObjectQL application:
+- Database connections
+- Environment variables
+- Metadata loading
+- Driver configuration
+- Runtime options
+
+### [Server Integration](/docs/server/integration)
+
+Integrate ObjectQL with web frameworks:
+- Express.js setup
+- Next.js integration
+- Fastify adapter
+- Custom server setup
+- HTTP API exposure
+
+### [Microservices & Federation](/docs/server/microservices)
+
+Build distributed systems with ObjectQL:
+- Service federation
+- Remote data sources
+- Cross-service queries
+- Load balancing
+- Service discovery
+
+### [Plugin System](/docs/server/plugins)
+
+Extend ObjectQL with plugins:
+- Creating custom plugins
+- Plugin lifecycle
+- Bundling behavior
+- Sharing plugins
+- Official plugins
+
+## Quick Setup
+
+### Express Integration
+
+```typescript
+import express from 'express';
+import { ObjectQL } from '@objectql/core';
+import { SqlDriver } from '@objectql/driver-sql';
+import { createNodeHandler } from '@objectql/server';
+
+const app = express();
+
+// Initialize ObjectQL
+const objectql = new ObjectQL({
+  datasources: {
+    default: new SqlDriver({
+      client: 'postgresql',
+      connection: process.env.DATABASE_URL
+    })
+  }
+});
+
+await objectql.init();
+
+// Mount ObjectQL handler
+app.use('/api/objectql', createNodeHandler(objectql));
+
+// Start server
+app.listen(3000, () => {
+  console.log('Server running on http://localhost:3000');
+});
+```
+
+### Configuration File
+
+```typescript
+// objectql.config.ts
+import { defineConfig } from '@objectql/core';
+
+export default defineConfig({
+  datasources: {
+    default: {
+      driver: 'sql',
+      client: 'postgresql',
+      connection: {
+        host: process.env.DB_HOST,
+        database: process.env.DB_NAME,
+        user: process.env.DB_USER,
+        password: process.env.DB_PASSWORD
+      }
+    }
+  },
+  modules: [
+    'src/objects',
+    '@objectql/module-auth'
+  ]
+});
+```
+
+## Deployment Patterns
+
+### Traditional Server
+
+Deploy to VPS, EC2, or dedicated servers:
+- Process management with PM2
+- Nginx reverse proxy
+- Environment configuration
+- Database migrations
+
+### Serverless
+
+Deploy to serverless platforms:
+- AWS Lambda
+- Vercel Functions
+- Cloudflare Workers
+- Database connection pooling
+
+### Containers
+
+Deploy with Docker:
+- Dockerfile configuration
+- Docker Compose setup
+- Kubernetes deployment
+- Health checks and monitoring
+
+## Next Steps
+
+- Configure your application with **[Configuration](/docs/server/configuration)**
+- Integrate with your framework using **[Server Integration](/docs/server/integration)**
+- Scale with **[Microservices](/docs/server/microservices)**
+- Extend with the **[Plugin System](/docs/server/plugins)**
+- Review **[API Reference](/docs/reference/api)** for complete documentation
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
@@ -54,7 +54,9 @@ const guideSidebar = [
   {
     text: 'Low-Code UI',
     items: [
-      { text: 'Page & Layouts', link: '/guide/page-metadata' },
+      { text: 'Pages & Layouts', link: '/spec/page' },
+      { text: 'Views', link: '/spec/view' },
+      { text: 'Forms', link: '/spec/form' },
     ]
   },
   {

diff --git a/docs/IMPLEMENTATION_SUMMARY.md b/docs/IMPLEMENTATION_SUMMARY.md
@@ -1,8 +1,6 @@
-# ObjectQL Attachment API - Implementation Summary
+# Attachment API Implementation Summary
 
-## Overview
-
-This implementation adds comprehensive file attachment functionality to ObjectQL, enabling seamless file upload, storage, and download capabilities through REST API endpoints.
+Implementation documentation for ObjectQL's comprehensive file attachment system. This summary covers file storage abstraction, REST API endpoints, upload/download functionality, and integration with object metadata for seamless file management.
 
 ## What Has Been Implemented
 

diff --git a/docs/METADATA_TYPES_IMPLEMENTATION.md b/docs/METADATA_TYPES_IMPLEMENTATION.md
@@ -1,8 +1,6 @@
-# Metadata Type Definitions - Implementation Summary
+# Metadata Type Definitions Implementation
 
-## Overview
-
-This PR implements complete TypeScript type definitions for all ObjectQL metadata formats. Previously, only some metadata types (Object, Validation, Permission, etc.) had TypeScript definitions. This implementation adds the missing types to achieve 100% coverage.
+Complete TypeScript type definitions for all ObjectQL metadata formats. This implementation document covers the 100% type coverage achievement, including views, forms, pages, reports, menus, apps, actions, hooks, and workflows—ensuring full type safety across the metadata system.
 
 ## New Type Definitions Added
 

diff --git a/docs/ai/building-apps.md b/docs/ai/building-apps.md
@@ -1,6 +1,6 @@
-# Building AI-Native Apps
+# Building AI-Native Applications
 
-ObjectQL is engineered to be the ideal data layer for AI Agents and LLMs. By providing a **Structure-First** protocol (JSON AST) instead of raw strings (SQL), it drastically reduces hallucinations and injection risks.
+Learn how to use ObjectQL as the data layer for AI applications. This comprehensive guide covers RAG (Retrieval-Augmented Generation), semantic search, vector databases, and building AI agents with structured data protocols.
 
 ## 1. Why ObjectQL for AI?
 

diff --git a/docs/ai/cli-usage.md b/docs/ai/cli-usage.md
@@ -1,6 +1,6 @@
-# AI-Powered CLI
+# AI-Powered Command Line Interface
 
-The ObjectQL CLI provides AI-powered commands to generate and validate applications using natural language.
+Learn how to use ObjectQL's AI-powered CLI for generating applications, validating metadata, and getting interactive assistance through natural language commands powered by large language models.
 
 ## Overview
 

diff --git a/docs/ai/coding-assistant.md b/docs/ai/coding-assistant.md
@@ -1,8 +1,6 @@
-# AI Coding Assistant Guide
+# AI Coding Assistant Configuration
 
-One of the core design goals of ObjectQL is to be the **most LLM-friendly backend protocol**.
-
-If you are using **Cursor**, **GitHub Copilot Chat**, **Windsurf**, or **ChatGPT** for development, please copy the following **System Prompt** into your AI configuration or project rules (e.g., `.cursorrules`). 
+Learn how to configure AI coding assistants (GitHub Copilot, Cursor, Windsurf) to become ObjectQL experts. This guide provides specialized system prompts that teach LLMs the ObjectQL protocol and best practices. 
 This allows the AI to accurately understand ObjectQL's syntax and best practices.
 
 ## How to Use Effectively

diff --git a/docs/ai/generating-apps.md b/docs/ai/generating-apps.md
@@ -1,8 +1,6 @@
-# Generating Apps with AI
+# Generating Applications with AI
 
-Because ObjectQL applications are defined primarily by **Metadata** (YAML/JSON) rather than **Code** (Classes/Functions), LLMs can generate complete, working backends in a single pass.
-
-This is "Zero-Shot Microservice Generation".
+Learn how to generate complete ObjectQL applications from natural language descriptions. This guide covers zero-shot microservice generation, prompt templates, and best practices for AI-powered app creation using LLMs.
 
 ## The Workflow
 

diff --git a/docs/ai/index.md b/docs/ai/index.md
@@ -1,9 +1,6 @@
 # AI-Native Development
 
-ObjectQL resides at the intersection of Data and Artificial Intelligence. It is designed to be "AI-Native" in two distinct ways:
-
-1.  **For AI Agents**: It serves as the perfect structured memory system (Long-term Memory) and tool interface for AI agents.
-2.  **By AI Agents**: Its metadata-driven, protocol-first architecture makes it incredibly easy for LLMs to write valid code for it.
+ObjectQL bridges Data and Artificial Intelligence with AI-native architecture designed for both AI agents (as a structured memory system and tool interface) and by AI agents (with metadata-driven, LLM-friendly code generation).
 
 ## Overview
 

diff --git a/docs/ai/programmatic-api.md b/docs/ai/programmatic-api.md
@@ -1,6 +1,6 @@
-# Programmatic AI API
+# Programmatic AI Agent API
 
-The ObjectQL AI Agent provides a programmatic API for generating and validating applications in your Node.js code.
+Learn how to use the ObjectQL AI Agent programmatically in your Node.js applications. This guide covers the TypeScript API for building custom development tools, web UIs, and automation with AI-powered generation and validation.
 
 ## Overview
 

diff --git a/docs/api/attachments.md b/docs/api/attachments.md
@@ -1,6 +1,6 @@
-# Attachment API Specification
+# File Attachments and Upload API
 
-**Version:** 1.0.0
+Learn how to handle file uploads, attachments, and media in ObjectQL. This comprehensive specification covers attachment fields, upload endpoints, storage strategies, and file management best practices.
 
 This document specifies how to handle file uploads, image uploads, and attachment field types in ObjectQL APIs.
 
@@ -1236,7 +1236,7 @@ Configure file storage behavior using environment variables:
 ## Related Documentation
 
 - [Object Definition Specification](../spec/object.md) - Field type definitions
-- [API Reference](./README.md) - Complete API documentation
+- [API Reference](./index.md) - Complete API documentation
 - [Validation Rules](../spec/validation.md) - File validation configuration
 - [Server Integration](../guide/server-integration.md) - Setting up file storage
 

diff --git a/docs/api/authentication.md b/docs/api/authentication.md
@@ -1,4 +1,6 @@
-# Authentication & Authorization
+# Authentication and Authorization
+
+Learn how to secure your ObjectQL APIs with authentication and authorization. This guide covers authentication methods, JWT tokens, role-based access control (RBAC), and permission enforcement strategies.
 
 ## Authentication Methods
 

diff --git a/docs/api/client-sdk.md b/docs/api/client-sdk.md
@@ -1,6 +1,6 @@
-# Client SDK Usage Guide
+# Client SDK Usage
 
-This guide demonstrates how to use the ObjectQL TypeScript client SDK to interact with Data API and Metadata API from frontend applications.
+Learn how to use the ObjectQL TypeScript client SDK for frontend applications. This comprehensive guide covers SDK installation, configuration, API calls, and type-safe data access from JavaScript/TypeScript clients.
 
 ## Installation
 

diff --git a/docs/api/custom-routes.md b/docs/api/custom-routes.md
@@ -1,4 +1,6 @@
-# Custom API Routes Configuration
+# Custom API Routes
+
+Learn how to configure custom API routes in ObjectQL. This guide covers route definitions, custom endpoints, middleware integration, and extending the default API with your own handlers.
 
 ## Overview
 

diff --git a/docs/api/error-handling.md b/docs/api/error-handling.md
@@ -1,4 +1,6 @@
-# Error Handling
+# Error Handling and Response Format
+
+Learn about ObjectQL's error handling system and unified response format. This guide covers error codes, response structures, validation errors, and best practices for handling failures gracefully.
 
 ## Error Response Format
 

diff --git a/docs/api/examples.md b/docs/api/examples.md
@@ -1,4 +1,6 @@
-# Examples
+# API Examples
+
+Practical examples demonstrating common ObjectQL API patterns and use cases. Learn through real-world scenarios including user registration, authentication flows, data queries, and business logic integration.
 
 ## Example 1: User Registration Flow