feat: add SDK and SQL driver documentation

- Introduced SDK documentation detailing features, installation, and usage examples for various environments including browser, Node.js, and frameworks like React and Vue.
- Added SQL Driver documentation covering installation, configuration, CRUD operations, query features, and best practices for organizing metadata in large projects.
- Created a new guide on organizing metadata for large projects, emphasizing domain-driven modules and best practices for structuring object definitions, actions, hooks, and translations.

Author: hotlong

apps/site/app/docs/layout.tsx

@@ -19,19 +19,15 @@ export default function Layout({ children }: { children: React.ReactNode }) {
     children: [...tree.children]
   };
 
-  // Find 'Reference' to insert before
-  const refIndex = modifiedTree.children.findIndex(n => n.name === 'Reference');
+  // Insert Protocol Specs link before the Reference section
+  const refIndex = modifiedTree.children.findIndex(
+    n => n.name === 'API Reference' || n.name === 'Reference'
+  );
 
   if (refIndex !== -1) {
     modifiedTree.children.splice(refIndex, 0, protocolLink as any);
   } else {
-    // If not found, try to find 'Ai' or 'AI'
-    const aiIndex = modifiedTree.children.findIndex(n => n.name === 'Ai' || n.name === 'AI');
-    if (aiIndex !== -1) {
-       modifiedTree.children.splice(aiIndex + 1, 0, protocolLink as any);
-    } else {
-       modifiedTree.children.push(protocolLink as any);
-    }
+    modifiedTree.children.push(protocolLink as any);
   }
 
   return (

apps/site/mdx-components.tsx

@@ -2,13 +2,16 @@ import defaultMdxComponents from 'fumadocs-ui/mdx';
 import type { MDXComponents } from 'mdx/types';
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
 import { Callout } from 'fumadocs-ui/components/callout';
+import { Step, Steps } from 'fumadocs-ui/components/steps';
 
 export function getMDXComponents(components?: MDXComponents): MDXComponents {
   return {
     ...defaultMdxComponents,
     Tab,
     Tabs,
     Callout,
+    Step,
+    Steps,
     ...components,
   };
 }

…ntent/docs/reference/foundation/core.mdx content/docs/architecture/core.mdxcontent/docs/reference/foundation/core.mdx renamed to content/docs/architecture/core.mdx content/docs/reference/foundation/core.mdx renamed to content/docs/architecture/core.mdx

@@ -869,14 +869,14 @@ app.registerObject({
 
 ## Related Documentation
 
-- **[Foundation Overview](/docs/reference/foundation)** - Trinity architecture
-- **[Types Reference](/docs/reference/foundation/types)** - Type definitions
-- **[Platform Node](/docs/reference/foundation/platform-node)** - Metadata loading
-- **[Drivers Overview](/docs/reference/drivers)** - Database drivers
-- **[Validation Guide](/docs/guides/validation)** - Advanced validation patterns
+- **[Foundation Overview](/docs/architecture)** - Trinity architecture
+- **[Types Reference](/docs/architecture/types)** - Type definitions
+- **[Platform Node](/docs/architecture/platform-node)** - Metadata loading
+- **[Drivers Overview](/docs/drivers)** - Database drivers
+- **[Validation Guide](/docs/logic)** - Advanced validation patterns
 
 ## Support
 
-- 📖 [API Reference](/docs/api)
+- 📖 [API Reference](/docs/reference)
 - 💬 [GitHub Discussions](https://github.com/objectstack-ai/objectql/discussions)
 - 🐛 [Report Issues](https://github.com/objectstack-ai/objectql/issues)

…tent/docs/reference/foundation/index.mdx content/docs/architecture/index.mdxcontent/docs/reference/foundation/index.mdx renamed to content/docs/architecture/index.mdx content/docs/reference/foundation/index.mdx renamed to content/docs/architecture/index.mdx

@@ -1,6 +1,6 @@
 ---
-title: Foundation Layer Overview
-description: The core architecture of ObjectQL - Types, Core Engine, and Platform Utilities
+title: Architecture
+description: Internal design of ObjectQL — the Trinity Architecture of Types, Core Engine, and Platform layer
 ---
 
 # Foundation Layer Overview
@@ -39,7 +39,7 @@ The Foundation Layer is the architectural backbone of ObjectQL, consisting of th
 
 ## Core Packages
 
-### [@objectql/types](/docs/reference/foundation/types)
+### [@objectql/types](/docs/architecture/types)
 
 **Role**: The API Contract & Type System Constitution
 
@@ -73,7 +73,7 @@ const project: ObjectConfig = {
 };
 ```
 
-### [@objectql/core](/docs/reference/foundation/core)
+### [@objectql/core](/docs/architecture/core)
 
 **Role**: The Runtime Engine & Business Logic Compiler
 
@@ -111,7 +111,7 @@ const projects = await ctx.object('project').find({
 });
 ```
 
-### [@objectql/platform-node](/docs/reference/foundation/platform-node)
+### [@objectql/platform-node](/docs/architecture/platform-node)
 
 **Role**: The Node.js Bridge
 
@@ -490,16 +490,16 @@ src/
 
 ## Related Documentation
 
-- **[Types Reference](/docs/reference/foundation/types)** - Complete type system documentation
-- **[Core Reference](/docs/reference/foundation/core)** - Runtime engine and APIs
-- **[Platform Node Reference](/docs/reference/foundation/platform-node)** - File system and plugin utilities
-- **[Driver Development](/docs/guides/drivers/extensibility)** - Building custom drivers
-- **[Validation Guide](/docs/guides/validation)** - Metadata-driven validation
+- **[Types Reference](/docs/architecture/types)** - Complete type system documentation
+- **[Core Reference](/docs/architecture/core)** - Runtime engine and APIs
+- **[Platform Node Reference](/docs/architecture/platform-node)** - File system and plugin utilities
+- **[Driver Development](/docs/extending/custom-drivers)** - Building custom drivers
+- **[Validation Guide](/docs/logic)** - Metadata-driven validation
 
 ## Next Steps
 
-1. **Understand the Types** → Read the [Types Reference](/docs/reference/foundation/types)
-2. **Build with Core** → Explore the [Core Reference](/docs/reference/foundation/core)
-3. **Load Metadata** → Learn about [Platform Node](/docs/reference/foundation/platform-node)
-4. **Choose a Driver** → Review [Drivers Overview](/docs/reference/drivers)
-5. **Deploy** → Check the [Deployment Guide](/docs/guides/deployment)
+1. **Understand the Types** → Read the [Types Reference](/docs/architecture/types)
+2. **Build with Core** → Explore the [Core Reference](/docs/architecture/core)
+3. **Load Metadata** → Learn about [Platform Node](/docs/architecture/platform-node)
+4. **Choose a Driver** → Review [Drivers Overview](/docs/drivers)
+5. **Deploy** → Check the [Deployment Guide](/docs/server)

content/docs/architecture/meta.json

@@ -0,0 +1,9 @@
+{
+  "title": "Architecture",
+  "pages": [
+    "index",
+    "types",
+    "core",
+    "platform-node"
+  ]
+}

…s/reference/foundation/platform-node.mdx …tent/docs/architecture/platform-node.mdxcontent/docs/reference/foundation/platform-node.mdx renamed to content/docs/architecture/platform-node.mdx content/docs/reference/foundation/platform-node.mdx renamed to content/docs/architecture/platform-node.mdx

@@ -848,16 +848,16 @@ This package includes:
 
 ## Related Packages
 
-- **[@objectql/core](/docs/reference/foundation/core)** - Core ObjectQL engine
-- **[@objectql/types](/docs/reference/foundation/types)** - Type definitions
+- **[@objectql/core](/docs/architecture/core)** - Core ObjectQL engine
+- **[@objectql/types](/docs/architecture/types)** - Type definitions
 - **[@objectql/cli](../../tools/cli)** - Command-line interface
 
 ## Related Documentation
 
-- **[Foundation Overview](/docs/reference/foundation)** - Trinity architecture
-- **[Core Reference](/docs/reference/foundation/core)** - Runtime engine
-- **[Types Reference](/docs/reference/foundation/types)** - Type system
-- **[Configuration Guide](/docs/guides/configuration)** - App configuration
+- **[Foundation Overview](/docs/architecture)** - Trinity architecture
+- **[Core Reference](/docs/architecture/core)** - Runtime engine
+- **[Types Reference](/docs/architecture/types)** - Type system
+- **[Configuration Guide](/docs/server/configuration)** - App configuration
 - **[Metadata Specification](/docs/spec)** - Metadata file formats
 
 ## Contributing
@@ -866,6 +866,6 @@ Contributions are welcome! Please see the main [repository README](https://githu
 
 ## Support
 
-- 📖 [API Reference](/docs/api)
+- 📖 [API Reference](/docs/reference)
 - 💬 [GitHub Discussions](https://github.com/objectstack-ai/objectql/discussions)
 - 🐛 [Report Issues](https://github.com/objectstack-ai/objectql/issues)

…tent/docs/reference/foundation/types.mdx content/docs/architecture/types.mdxcontent/docs/reference/foundation/types.mdx renamed to content/docs/architecture/types.mdx content/docs/reference/foundation/types.mdx renamed to content/docs/architecture/types.mdx

@@ -779,10 +779,10 @@ Recommended `tsconfig.json` settings when using `@objectql/types`:
 
 ## Related Documentation
 
-- **[Foundation Overview](/docs/reference/foundation)** - Trinity architecture explanation
-- **[Core Reference](/docs/reference/foundation/core)** - Runtime implementation
-- **[Validation Guide](/docs/guides/validation)** - Using validation types
-- **[Driver Development](/docs/guides/drivers/extensibility)** - Implementing Driver interface
+- **[Foundation Overview](/docs/architecture)** - Trinity architecture explanation
+- **[Core Reference](/docs/architecture/core)** - Runtime implementation
+- **[Validation Guide](/docs/logic)** - Using validation types
+- **[Driver Development](/docs/extending/custom-drivers)** - Implementing Driver interface
 - **[@objectstack/spec](https://github.com/objectstack-ai/spec)** - Formal protocol specifications
 
 ## Contributing
@@ -798,6 +798,6 @@ When contributing new types:
 
 ## Support
 
-- 📖 [API Reference](/docs/api)
+- 📖 [API Reference](/docs/reference)
 - 💬 [GitHub Discussions](https://github.com/objectstack-ai/objectql/discussions)
 - 🐛 [Report Issues](https://github.com/objectstack-ai/objectql/issues)

content/docs/data-access/best-practices.mdx

@@ -822,15 +822,15 @@ query {
 
 ## 11. Further Reading
 
-- [Query Language Specification](../spec/query-language.md) - Complete JSON-DSL reference
-- [Querying Guide](./querying.md) - Step-by-step query examples
-- [GraphQL API Documentation](../api/graphql.md) - GraphQL setup and usage
-- [REST API Documentation](../api/rest.md) - REST endpoint reference
+- [Filter Syntax Reference](/docs/data-access/filter-syntax) - Complete JSON-DSL reference
+- [Querying Guide](/docs/data-access/querying) - Step-by-step query examples
+- [GraphQL API Documentation](/docs/reference/api/graphql) - GraphQL setup and usage
+- [REST API Documentation](/docs/reference/api/rest) - REST endpoint reference
 
 ---
 
 **Need Help?**
 
-- 📖 [Documentation](../index.md)
+- 📖 [Documentation](/docs)
 - 💬 [Community Discord](https://discord.gg/objectql)
 - 🐛 [Report Issues](https://github.com/objectstack-ai/objectql/issues)

content/docs/data-access/index.mdx

@@ -25,14 +25,12 @@ Learn the fundamentals of querying data with ObjectQL:
 - Aggregations and grouping
 - Complex queries with nested conditions
 
-### [Client SDK](/docs/data-access/sdk)
+### [Client SDK](/docs/reference/api/client-sdk)
 
-Use the TypeScript SDK for type-safe data access:
-- Installation and setup
-- Basic CRUD operations
-- Advanced querying techniques
-- Error handling
-- TypeScript integration
+Use the TypeScript SDK for type-safe data access from browser and Node.js clients:
+- DataApiClient and MetadataApiClient
+- React and Vue hooks
+- Error handling and retry patterns
 
 ### [Query Best Practices](/docs/data-access/best-practices)
 
@@ -93,6 +91,6 @@ This structure makes it easy for frontends, AI agents, and external systems to g
 ## 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
+- Explore the **[Client SDK](/docs/reference/api/client-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
+- Check the **[Filter Syntax](/docs/data-access/filter-syntax)** for all available operators

content/docs/data-access/meta.json

@@ -1,8 +1,9 @@
 {
   "title": "Data Access",
   "pages": [
+    "index",
     "querying",
-    "sdk",
+    "filter-syntax",
     "best-practices"
   ]
 }