Restructure documentation for independent protocol website with Fumadocs root categories

.github/prompts/README.md

@@ -292,8 +292,8 @@ When designing protocols, benchmark against:
 
 ### Repository Documentation
 - [ARCHITECTURE.md](../../ARCHITECTURE.md) - System architecture
-- [DEVELOPMENT_ROADMAP.md](../../DEVELOPMENT_ROADMAP.md) - Development plan
-- [PRIORITIES.md](../../PRIORITIES.md) - Priority matrix
+- [DEVELOPMENT_ROADMAP.md](../../internal/planning/DEVELOPMENT_ROADMAP.md) - Development plan
+- [PRIORITIES.md](../../internal/planning/PRIORITIES.md) - Priority matrix
 - [README.md](../../README.md) - Project overview
 
 ### Protocol Documentation

ARCHITECTURE.md

@@ -474,6 +474,6 @@ Same Protocol → Different Renderers:
 ---
 
 **For more details, see:**
-- [DEVELOPMENT_ROADMAP.md](./DEVELOPMENT_ROADMAP.md) - Complete development plan
-- [PRIORITIES.md](./PRIORITIES.md) - What to work on next
+- [DEVELOPMENT_ROADMAP.md](./internal/planning/DEVELOPMENT_ROADMAP.md) - Complete development plan
+- [PRIORITIES.md](./internal/planning/PRIORITIES.md) - What to work on next
 - [packages/spec/README.md](./packages/spec/README.md) - Technical documentation

CONTRIBUTING.md

@@ -52,8 +52,8 @@ pnpm test
 ### 1. Choose What to Work On
 
 Before starting, review:
-- **[PRIORITIES.md](./PRIORITIES.md)** - Current sprint priorities
-- **[DEVELOPMENT_ROADMAP.md](./DEVELOPMENT_ROADMAP.md)** - Long-term roadmap
+- **[PRIORITIES.md](./internal/planning/PRIORITIES.md)** - Current sprint priorities
+- **[DEVELOPMENT_ROADMAP.md](./internal/planning/DEVELOPMENT_ROADMAP.md)** - Long-term roadmap
 - **[GitHub Issues](https://github.com/objectstack-ai/spec/issues)** - Open issues
 
 ### 2. Create a Branch
@@ -406,7 +406,7 @@ Brief description of changes
 
 ### Getting Help
 
-- Review [PLANNING_INDEX.md](./PLANNING_INDEX.md) for documentation navigation
+- Review [PLANNING_INDEX.md](./internal/planning/PLANNING_INDEX.md) for documentation navigation
 - Check [ARCHITECTURE.md](./ARCHITECTURE.md) for system design
 - Read [QUICK_START_IMPLEMENTATION.md](./QUICK_START_IMPLEMENTATION.md) for implementation examples
 

README.md

@@ -15,29 +15,29 @@ This repository contains the core specifications, schemas, and protocols that po
 *   **[Installation Guide](./content/docs/guides/installation.mdx):** Setup instructions
 *   **[Contributing Guide](./CONTRIBUTING.md):** How to contribute to the project
 
-### Planning & Architecture
-*   **[Development Roadmap](./DEVELOPMENT_ROADMAP.md):** Complete development plan considering all future possibilities
-*   **[Priority Matrix](./PRIORITIES.md):** What to work on next, sprint planning guide
-*   **[Architecture Diagrams](./ARCHITECTURE.md):** Visual reference for the complete system
-*   **[Planning Index](./PLANNING_INDEX.md):** Complete guide to navigating planning documentation
+### Architecture & Design
+*   **[Architecture Overview](./content/docs/specifications/architecture/):** Deep dive into the three-layer architecture
+*   **[Data Layer (ObjectQL)](./content/docs/specifications/architecture/data-layer.mdx):** Query language and data abstraction
+*   **[UI Layer (ObjectUI)](./content/docs/specifications/architecture/ui-layer.mdx):** Server-driven UI protocol
+*   **[System Layer (ObjectOS)](./content/docs/specifications/architecture/system-layer.mdx):** Runtime kernel and plugins
 
-### Technical Documentation
+### Standards & Best Practices
+*   **[Naming Conventions](./content/docs/standards/naming-conventions.mdx):** Schema naming rules (camelCase vs snake_case)
+*   **[API Design](./content/docs/standards/api-design.mdx):** API design principles and patterns
+*   **[Error Handling](./content/docs/standards/error-handling.mdx):** Consistent error handling strategies
+*   **[Authentication](./content/docs/standards/authentication.mdx):** Authentication standards and implementation
+
+### Documentation Site
 The official documentation is built with Fumadocs and Next.js.
 
 *   **[Documentation Content](./content/docs/):** MDX documentation files (concepts, specifications, references)
 *   **[Documentation Site](./apps/docs/):** Fumadocs-powered Next.js app
-*   **[Technical Guides](./docs/):** In-depth technical guides and standards
 *   **[Live Site](http://localhost:3000/docs):** Run `pnpm docs:dev` to view locally
 
-### Architecture Deep Dives
-*   **[Data Layer (ObjectQL)](./docs/architecture/data-layer.md):** Query language and data abstraction
-*   **[UI Layer (ObjectUI)](./docs/architecture/ui-layer.md):** Server-driven UI protocol
-*   **[System Layer (ObjectOS)](./docs/architecture/system-layer.md):** Runtime kernel and plugins
-
-### Standards & Best Practices
-*   **[Naming Conventions](./docs/standards/naming-conventions.md):** Schema naming rules (camelCase vs snake_case)
-*   **[API Design](./docs/standards/api-design.md):** API design principles and patterns
-*   **[Error Handling](./docs/standards/error-handling.md):** Consistent error handling strategies
+### Planning & Internal Docs
+*   **[Development Roadmap](./internal/planning/DEVELOPMENT_ROADMAP.md):** Complete development plan
+*   **[Priority Matrix](./internal/planning/PRIORITIES.md):** What to work on next, sprint planning guide
+*   **[Planning Index](./internal/planning/PLANNING_INDEX.md):** Complete guide to navigating planning documentation
 
 ## 📦 Monorepo Structure
 
@@ -128,17 +128,17 @@ We welcome contributions! Please read our **[Contributing Guide](./CONTRIBUTING.
 ### Quick Start for Contributors
 
 1.  **Read the Docs**: Review [CONTRIBUTING.md](./CONTRIBUTING.md) for complete guidelines
-2.  **Check Priorities**: See [PRIORITIES.md](./PRIORITIES.md) for what to work on next
+2.  **Check Priorities**: See [PRIORITIES.md](./internal/planning/PRIORITIES.md) for what to work on next
 3.  **Understand Architecture**: Read [ARCHITECTURE.md](./ARCHITECTURE.md) for system overview
-4.  **Follow Standards**: Review [docs/standards/](./docs/standards/) for coding standards
+4.  **Follow Standards**: Review [content/docs/standards/](./content/docs/standards/) for coding standards
 
 ### Key Standards
 
-- **Naming Conventions**: See [docs/standards/naming-conventions.md](./docs/standards/naming-conventions.md)
+- **Naming Conventions**: See [content/docs/standards/naming-conventions.mdx](./content/docs/standards/naming-conventions.mdx)
   - Configuration keys: `camelCase` (e.g., `maxLength`, `referenceFilters`)
   - Machine names: `snake_case` (e.g., `name: 'project_task'`, `object: 'account'`)
-- **API Design**: Follow [docs/standards/api-design.md](./docs/standards/api-design.md)
-- **Error Handling**: Use patterns from [docs/standards/error-handling.md](./docs/standards/error-handling.md)
+- **API Design**: Follow [content/docs/standards/api-design.mdx](./content/docs/standards/api-design.mdx)
+- **Error Handling**: Use patterns from [content/docs/standards/error-handling.mdx](./content/docs/standards/error-handling.mdx)
 
 ### PR Checklist
 

RELEASE_NOTES.md

@@ -83,7 +83,7 @@ Version tag `v0.2.0` has been created for this release.
 ## 📚 Documentation
 
 Full documentation is available at:
-- Development Roadmap: [DEVELOPMENT_ROADMAP.md](DEVELOPMENT_ROADMAP.md)
+- Development Roadmap: [DEVELOPMENT_ROADMAP.md](internal/planning/DEVELOPMENT_ROADMAP.md)
 - Architecture: [ARCHITECTURE.md](ARCHITECTURE.md)
 - Quick Start: [QUICK_START_IMPLEMENTATION.md](QUICK_START_IMPLEMENTATION.md)
 

docs/AI_INTEGRATION_GUIDE.md → content/docs/guides/advanced/ai-integration-guide.mdx

@@ -1,3 +1,8 @@
+---
+title: AI Integration Guide
+description: Complete guide to building AI-powered ObjectStack applications
+---
+
 # AI Integration Guide
 
 > **Complete guide to building AI-powered ObjectStack applications**

content/docs/guides/advanced/ai-integration/meta.json

@@ -0,0 +1,6 @@
+{
+  "title": "AI Integration",
+  "pages": [
+    "quick-start"
+  ]
+}

docs/guides/ai-integration/quick-start.md → content/docs/guides/advanced/ai-integration/quick-start.mdx

@@ -1,3 +1,8 @@
+---
+title: AI Integration Quick Start
+description: Quick guide to integrating AI features into ObjectStack applications
+---
+
 # AI Integration Quick Start
 
 > Quick guide to integrating AI features into ObjectStack applications

content/docs/guides/advanced/meta.json

@@ -0,0 +1,9 @@
+{
+  "title": "Advanced Guides",
+  "pages": [
+    "ai-integration-guide",
+    "ai-integration",
+    "security",
+    "performance"
+  ]
+}

content/docs/guides/advanced/performance/meta.json

@@ -0,0 +1,6 @@
+{
+  "title": "Performance",
+  "pages": [
+    "optimization"
+  ]
+}

docs/guides/performance/optimization.md → content/docs/guides/advanced/performance/optimization.mdx

@@ -1,3 +1,8 @@
+---
+title: Performance Optimization
+description: Strategies for optimizing ObjectStack Protocol implementations
+---
+
 # Performance Optimization Guide
 
 > Strategies for optimizing ObjectStack Protocol implementations

docs/guides/security/best-practices.md → content/docs/guides/advanced/security/best-practices.mdx

@@ -1,3 +1,8 @@
+---
+title: Security Best Practices
+description: Comprehensive security guidelines for ObjectStack Protocol implementations
+---
+
 # Security Best Practices Guide
 
 > Comprehensive security guidelines for ObjectStack Protocol implementations

content/docs/guides/advanced/security/meta.json

@@ -0,0 +1,6 @@
+{
+  "title": "Security",
+  "pages": [
+    "best-practices"
+  ]
+}

content/docs/guides/meta.json

@@ -8,6 +8,8 @@
     "field-types",
     "view-configuration",
     "workflows-validation",
-    "custom-driver"
+    "custom-driver",
+    "advanced",
+    "migration"
   ]
 }

content/docs/guides/migration/index.mdx

@@ -0,0 +1,26 @@
+---
+title: Migration Guides
+description: Guides for migrating between versions
+---
+
+# Migration Guides
+
+This section contains guides for migrating your applications between different versions of the ObjectStack Protocol.
+
+## Available Guides
+
+### [Version 0.x to 1.x Migration](/docs/guides/migration/v0-to-v1)
+Complete guide for migrating from version 0.x to 1.x, including:
+- Breaking changes
+- New features
+- Migration steps
+- Code examples
+
+## Migration Best Practices
+
+1. **Read the Full Guide**: Understand all changes before starting
+2. **Backup Your Data**: Always create backups before migration
+3. **Test in Development**: Test the migration in a development environment first
+4. **Update Dependencies**: Ensure all dependencies are compatible
+5. **Review Breaking Changes**: Pay special attention to breaking changes
+6. **Run Tests**: Verify all tests pass after migration

content/docs/guides/migration/meta.json

@@ -0,0 +1,7 @@
+{
+  "title": "Migration Guides",
+  "pages": [
+    "index",
+    "v0-to-v1"
+  ]
+}

docs/migration/v0-to-v1.md → content/docs/guides/migration/v0-to-v1.mdx

@@ -1,3 +1,8 @@
+---
+title: Version 0.1.x to 1.0.0 Migration
+description: Guide for migrating from version 0.1.x to 1.0.0
+---
+
 # Migration Guide: v0.1.x to v1.0.0
 
 > Guide for migrating from version 0.1.x to 1.0.0

content/docs/meta.json

@@ -6,6 +6,7 @@
     "guides",
     "concepts",
     "specifications",
+    "standards",
     "references",
     "faq",
     "troubleshooting"

content/docs/quick-start/architects.mdx

@@ -498,5 +498,5 @@ app.get('/legacy', legacyController);
 ## Resources
 
 - **[Architecture Diagrams](https://github.com/objectstack-ai/spec/blob/main/ARCHITECTURE.md)** - Visual reference
-- **[Development Roadmap](https://github.com/objectstack-ai/spec/blob/main/DEVELOPMENT_ROADMAP.md)** - Future plans
+- **[Development Roadmap](https://github.com/objectstack-ai/spec/blob/main/internal/planning/DEVELOPMENT_ROADMAP.md)** - Future plans
 - **[Contributing Guide](https://github.com/objectstack-ai/spec/blob/main/CONTRIBUTING.md)** - How to contribute

content/docs/quick-start/backend-developers.mdx

@@ -390,7 +390,7 @@ describe('Task Object', () => {
 
 Coming from another framework? We've got you covered:
 
-- [Prisma → ObjectStack](/docs/migration/prisma)
-- [TypeORM → ObjectStack](/docs/migration/typeorm)
-- [Sequelize → ObjectStack](/docs/migration/sequelize)
-- [Mongoose → ObjectStack](/docs/migration/mongoose)
+- [Prisma → ObjectStack](/docs/guides/migration/prisma)
+- [TypeORM → ObjectStack](/docs/guides/migration/typeorm)
+- [Sequelize → ObjectStack](/docs/guides/migration/sequelize)
+- [Mongoose → ObjectStack](/docs/guides/migration/mongoose)

content/docs/quick-start/meta.json

@@ -1,5 +1,6 @@
 {
   "title": "Quick Start",
+  "root": true,
   "pages": [
     "build-first-app",
     "backend-developers",

content/docs/references/meta.json

@@ -1,11 +1,13 @@
 {
-  "label": "Protocol Reference",
-  "order": 100,
+  "title": "API Reference",
+  "root": true,
   "pages": [
     "data",
     "ui",
     "system",
     "ai",
+    "api",
+    "client-sdk",
     "misc"
   ]
 }

docs/architecture/data-layer.md → content/docs/specifications/architecture/data-layer.mdx

@@ -1,3 +1,8 @@
+---
+title: ObjectQL - Data Layer Architecture
+description: Deep dive into the ObjectQL (Object Query Language) data protocol architecture
+---
+
 # ObjectQL - Data Layer Architecture
 
 > Deep dive into the ObjectQL (Object Query Language) data protocol architecture

content/docs/specifications/architecture/index.mdx

@@ -0,0 +1,38 @@
+---
+title: Architecture
+description: Deep dive into the ObjectStack Protocol Architecture
+---
+
+# Architecture
+
+The ObjectStack Protocol is built on three core layers that work together to provide a complete metadata-driven platform.
+
+## Core Layers
+
+### [Data Layer (ObjectQL)](/docs/specifications/architecture/data-layer)
+The Data Layer defines the "Shape of Data" and business logic. It includes:
+- **Schema**: Objects and Fields with 23+ field types
+- **Logic**: Workflows, Triggers, Validation Rules, Formulas
+- **Security**: Permissions and Sharing Rules
+- **Query**: Abstract Syntax Tree (AST) for unified data access
+
+### [UI Layer (ObjectUI)](/docs/specifications/architecture/ui-layer)
+The UI Layer defines the "Shape of Interaction" for rendering interfaces:
+- **Views**: Grid, Kanban, Calendar, Gantt, List configurations
+- **Pages**: FlexiPage layouts with regions and components
+- **Navigation**: App menus and navigation structures
+- **Analytics**: Reports and Dashboards with widgets
+
+### [System Layer (ObjectOS)](/docs/specifications/architecture/system-layer)
+The System Layer defines the "Runtime Environment":
+- **Manifest**: Application packaging
+- **Identity**: Authentication, Roles, Licenses
+- **Integration**: Webhooks, API contracts, ETL Mappings
+- **Datasource**: Driver definitions for SQL, NoSQL, SaaS connectors
+
+## Design Principles
+
+1. **Data as Code**: All configurations are expressed as declarative metadata
+2. **Intent over Implementation**: Describe what you want, not how to build it
+3. **Local-First**: Works offline, syncs when connected
+4. **Driver Agnostic**: Abstract away storage implementation details

content/docs/specifications/architecture/meta.json

@@ -0,0 +1,9 @@
+{
+  "title": "Architecture",
+  "pages": [
+    "index",
+    "data-layer",
+    "ui-layer",
+    "system-layer"
+  ]
+}

docs/architecture/system-layer.md → content/docs/specifications/architecture/system-layer.mdx

@@ -1,3 +1,8 @@
+---
+title: ObjectOS - System Layer Architecture
+description: Deep dive into the ObjectOS (Operating System) runtime architecture
+---
+
 # ObjectOS - System Layer Architecture
 
 > Deep dive into the ObjectOS (Operating System) runtime architecture

docs/architecture/ui-layer.md → content/docs/specifications/architecture/ui-layer.mdx

@@ -1,3 +1,8 @@
+---
+title: ObjectUI - UI Layer Architecture
+description: Deep dive into the ObjectUI (Server-Driven UI) protocol architecture
+---
+
 # ObjectUI - UI Layer Architecture
 
 > Deep dive into the ObjectUI (Server-Driven UI) protocol architecture

content/docs/specifications/meta.json

@@ -3,6 +3,7 @@
   "root": true,
   "pages": [
     "index",
+    "architecture",
     "data",
     "ui",
     "server"

docs/standards/api-design.md → content/docs/standards/api-design.mdx

@@ -1,3 +1,8 @@
+---
+title: API Design Principles
+description: Guidelines for designing consistent and developer-friendly APIs in ObjectStack
+---
+
 # API Design Principles
 
 > Guidelines for designing consistent and developer-friendly APIs in ObjectStack

docs/AUTHENTICATION_STANDARD.md → content/docs/standards/authentication.mdx

@@ -1,3 +1,8 @@
+---
+title: Authentication Standard
+description: The standard authentication protocol specification for the ObjectStack ecosystem
+---
+
 # ObjectStack Authentication Standard
 
 The standard authentication protocol specification for the ObjectStack ecosystem.