feat: enhance documentation structure and add CLI tool for translation

Author: hotlong

README.md

@@ -1,53 +1,64 @@
-# docs
+# ObjectStack Documentation
 
-A multi-language documentation site built with Fumadocs, supporting English and Chinese.
+The official documentation for ObjectStack, built with Next.js (App Router) and [Fumadocs](https://fumadocs.vercel.app).
+
+## Project Structure
+
+This repository contains the documentation for:
+- **ObjectStack Platform**: The core development platform.
+- **ObjectQL**: The backend data protocol engine.
+- **ObjectUI**: The declarative UI engine.
+- **ObjectOS**: The runtime operating system.
 
 ## Features
 
-- 🌍 **Multi-language Support**: Full internationalization with English (en) and Chinese (zh-CN)
-- 📝 **MDX Content**: Write documentation using MDX for interactive content
-- 🔍 **Fast Search**: Quick search across all documentation
-- 🎨 **Modern UI**: Beautiful and responsive design with Fumadocs UI
-- 📱 **Mobile Friendly**: Fully responsive on all devices
+- 🌍 **Multi-language Support**: 
+  - Source: English (`content/docs`)
+  - Target: Chinese (`content/docs-zh-CN`) - *Auto-translated via AI*
+- 📝 **MDX Content**: Interactive documentation with Type-safe components.
+- 🛠️ **Automated Workflows**: 
+  - AI Translation CLI (`packages/docs-cli`)
+  - Broken link checking
+  - SEO optimization
 
 ## Getting Started
 
-### Installation
+### Prerequisites
 
-```bash
-npm install
-```
+- Node.js 18+
+- pnpm
 
-After cloning the repository, configure the Git merge driver for `pnpm-lock.yaml`:
+### Installation
 
 ```bash
-git config merge.pnpm-merge.name "pnpm-lock.yaml merge driver"
-git config merge.pnpm-merge.driver "pnpm install"
+pnpm install
 ```
 
-This helps avoid merge conflicts in the lock file by automatically regenerating it during merges.
-
 ### Development
 
+Start the development server:
+
 ```bash
-npm run dev
+pnpm run dev
 ```
 
-Visit `http://localhost:3000` to view the documentation site.
+Visit `http://localhost:3000` to view the documentation.
 
-### Build
+## Writing Documentation
 
-```bash
-npm run build
-```
+1. Create new MDX files in `content/docs`.
+2. Update `meta.json` in the corresponding directory.
+3. Commit your changes (CI will handle translation).
+
+### CLI Tools
 
-### Production
+We provide a custom CLI for translation tasks:
 
 ```bash
-npm start
+# Translate all files
+pnpm docs-cli translate --all
 ```
 
-## Building Multi-language Documentation
 
 For a comprehensive guide on how to build and maintain multi-language documentation, see the [Multi-language Documentation Guide](content/docs/i18n-guide.en.mdx) available in the documentation:
 

content/docs/00-intro/meta.json

@@ -1,4 +1,4 @@
 {
   "title": "Preamble & Design",
-  "pages": ["index", "welcome", "manifesto", "ai-codex"]
+  "pages": ["index", "welcome", "manifesto", "architecture", "ai-codex"]
 }

content/docs/01-quickstart/enterprise-integrators.mdx

@@ -303,13 +303,13 @@ export default {
 ### Step 4: Launch Containers
 
 ```bash
-docker-compose up -d
+docker compose up -d
 ```
 
 Check status:
 
 ```bash
-docker-compose ps
+docker compose ps
 ```
 
 Expected output:
@@ -325,13 +325,13 @@ objectos-redis      redis:7-alpine               Up 2 minutes
 
 ```bash
 # All services
-docker-compose logs -f
+docker compose logs -f
 
 # Just ObjectOS
-docker-compose logs -f objectos
+docker compose logs -f objectos
 
 # Last 100 lines
-docker-compose logs --tail=100 objectos
+docker compose logs --tail=100 objectos
 ```
 
 ### Step 6: Access Application
@@ -569,13 +569,13 @@ export default {
 
 ```bash
 # Check database is running
-docker-compose ps postgres
+docker compose ps postgres
 
 # Test connection
-docker-compose exec postgres psql -U objectstack -d objectstack
+docker compose exec postgres psql -U objectstack -d objectstack
 
 # Check logs
-docker-compose logs postgres
+docker compose logs postgres
 ```
 
 ### Permission Denied
@@ -590,13 +590,13 @@ GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO objectstack_user;
 
 ```bash
 # Check logs
-docker-compose logs objectos
+docker compose logs objectos
 
 # Validate config
-docker-compose config
+docker compose config
 
 # Restart containers
-docker-compose restart
+docker compose restart
 ```
 
 ## Next Steps

content/docs/index.mdx

@@ -1,27 +1,32 @@
 ---
-title: Welcome
-description: Welcome to ObjectStack Documentation
+title: Introduction
+description: ObjectStack - The Protocol-Driven Development Platform
 ---
 
-# Welcome to ObjectStack
+# ObjectStack Documentation
 
-ObjectStack is a comprehensive platform for building modern applications with powerful tools and frameworks.
+**ObjectStack** is a full-stack, local-first development platform designed for **data sovereignty** and **technical decoupling**. 
 
-## Our Products
+It standardizes the development process using a "Protocol-Driven" architecture, separating business logic from technical implementation.
 
-We offer three core products designed to streamline your development workflow:
+## Core Products
 
-- **ObjectUI**: A modern UI component library for building beautiful and responsive user interfaces
-- **ObjectQL**: A powerful query language and data access layer for efficient data operations
-- **ObjectOS**: An operating system framework that provides the foundation for building scalable applications
+ObjectStack consists of three integrated engines:
 
-## Features
+### [ObjectQL (Backend)](./02-objectql)
+The universal data protocol. Define your data models once in JSON schema, and run them on any database (SQLite, PostgreSQL, Oracle, etc.). 
 
-- **Multi-language Support**: Switch between English and Chinese
-- **Fast Search**: Quick search across all documentation
-- **Beautiful UI**: Modern and responsive design
-- **MDX Support**: Write docs with MDX for interactive content
+### [ObjectUI (Frontend)](./03-objectui)
+The declarative UI engine. Render enterprise-grade interfaces directly from your data protocols without writing repetitive component code.
+
+### [ObjectOS (Runtime)](./04-objectos)
+The operating system for your apps. Binds ObjectQL and ObjectUI together with built-in identity management, security, and access control.
 
 ## Getting Started
 
-Explore the documentation using the sidebar navigation. You can switch languages using the language selector in the top navigation bar.
+Ready to build? Choose your path:
+
+- 🚀 **[Quick Start Guide](./01-quickstart)**: Create your first app in under 10 minutes.
+- 💡 **[Core Concepts](./00-intro/welcome)**: Learn about the philosophy behind ObjectStack.
+- 🏗️ **[Architecture](./00-intro/architecture)**: Deep dive into the technical design.
+

packages/docs-cli/README.md

@@ -0,0 +1,55 @@
+# @docs/cli
+
+Internal CLI tool for automating documentation workflows for ObjectStack.
+
+## Features
+
+- **AI Translation**: Automatically translate MDX documentation from English to Chinese using OpenAI models.
+- **Smart Updates**: Can process specific files or bulk translate the entire documentation.
+
+## Installation
+
+This package is part of the monorepo workspace. Install dependencies from the root:
+
+```bash
+pnpm install
+```
+
+## Usage
+
+### Translate Documentation
+
+The `translate` command reads English documentation from `content/docs` and generates Chinese translations in `content/docs-zh-CN`.
+
+**Prerequisites:**
+You must set the following environment variables (in `.env` or your shell):
+
+```bash
+OPENAI_API_KEY=sk-...
+OPENAI_BASE_URL=https://api.openai.com/v1 # Optional
+```
+
+**Commands:**
+
+```bash
+# Translate a specific file
+pnpm docs-cli translate content/docs/00-intro/index.mdx
+
+# Translate multiple files
+pnpm docs-cli translate content/docs/00-intro/index.mdx content/docs/01-quickstart/index.mdx
+
+# Translate all files in content/docs
+pnpm docs-cli translate --all
+
+# Specify a custom model (default: gpt-4o)
+pnpm docs-cli translate --all --model gpt-4-turbo
+```
+
+### CI/CD Integration
+
+In CI environments, you can use the `CHANGED_FILES` environment variable to translate only modified files:
+
+```bash
+export CHANGED_FILES="content/docs/new-page.mdx"
+pnpm docs-cli translate
+```