Merge pull request #139 from objectstack-ai/copilot/optimize-document-titles-descriptions

Author: huangyiirene

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

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

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' },
     ]
   },
   {

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
 

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
 

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?
 

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
 

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

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
 

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