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)
 

content/docs/concepts/meta.cn.json

@@ -5,6 +5,7 @@
  "manifesto",
  "core-values",
  "architecture",
+ "plugin-architecture",
  "security_architecture",
  "enterprise-patterns",
  "ai-codex",

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.cn.json

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

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.cn.json

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

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.cn.json

@@ -0,0 +1,10 @@
+{
+ "title": "快速开始",
+ "root": true,
+ "pages": [
+ "build-first-app",
+ "backend-developers",
+ "frontend-developers",
+ "architects"
+ ]
+}

content/docs/quick-start/meta.json

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

content/docs/references/ai/meta.json

@@ -1,4 +1,3 @@
 {
- "title": "AI Protocol",
- "root": true
+ "title": "AI Protocol"
 }

content/docs/references/api/meta.json

@@ -1,6 +1,5 @@
 {
  "title": "API Protocol",
- "root": true,
  "pages": [
  "envelopes",
  "requests"

content/docs/references/data/meta.json

@@ -1,6 +1,5 @@
 {
  "title": "Data Protocol",
- "root": true,
  "pages": [
  "core",
  "logic",

content/docs/references/meta.cn.json

@@ -0,0 +1,13 @@
+{
+ "title": "API 参考",
+ "root": true,
+ "pages": [
+ "data",
+ "ui",
+ "system",
+ "ai",
+ "api",
+ "client-sdk",
+ "misc"
+ ]
+}

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"
  ]
 }

content/docs/references/system/meta.json

@@ -1,6 +1,5 @@
 {
  "title": "System Protocol",
- "root": true,
  "pages": [
  "identity",
  "integration",

content/docs/references/ui/meta.json

@@ -1,6 +1,5 @@
 {
  "title": "UI Protocol",
- "root": true,
  "pages": [
  "app",
  "views",

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