Refactor docs: move and restructure concepts section

Moved and renamed framework documentation files to the concepts section, added new architecture and introduction docs in both English and Chinese, and updated meta files accordingly. Removed obsolete framework and objectql protocol-spec files, and updated references in index and meta files to reflect the new structure. This improves organization and clarity of the documentation, consolidating conceptual materials under a unified path.

Author: hotlong

content/docs/framework/ai-codex.mdx content/docs/concepts/ai-codex.mdxcontent/docs/framework/ai-codex.mdx renamed to content/docs/concepts/ai-codex.mdx

@@ -305,7 +305,7 @@ npx typedoc --out docs/api src/
 ### 1. Clear Context
 
 When conversing with AI, clearly specify:
-- Using ObjectStack framework
+- Using ObjectStack concepts
 - Protocol specifications to follow
 - Target database type (if special requirements)
 

content/docs/concepts/architecture.mdx

@@ -0,0 +1,94 @@
+---
+title: Architecture Overview
+description: Understanding the ObjectStack Trinity. How ObjectQL, ObjectOS, and ObjectUI collaborate to build the Enterprise Kernel.
+---
+
+# Architecture Overview
+
+ObjectStack is not a monolithic framework. It is a composable ecosystem designed around a **Layered Architecture**. We call this the **"ObjectStack Trinity."**
+
+Each layer is decoupled and communicates via standard JSON protocols. This allows you to swap out implementations (e.g., swapping the React renderer for a Flutter renderer) without breaking the rest of the stack.
+
+
+
+## The Trinity
+
+### 1. The Data Layer: ObjectQL
+**"The Universal Protocol"**
+
+At the foundation lies ObjectQL. It is responsible for **Data Definition** and **Data Access**.
+
+* **Role:** Defines *Structure* (Schema) and *Intent* (Query AST).
+* **Responsibility:** It knows *what* a "Customer" object looks like, but it doesn't know *who* is accessing it or *how* it is displayed.
+* **Key Component:** The **Compiler**. It takes an abstract query (`find customers where active = true`) and translates it into optimized SQL for the specific underlying database (Postgres, SQLite, MySQL).
+
+### 2. The Control Layer: ObjectOS
+**"The Business Kernel"**
+
+Sitting in the middle is ObjectOS. It is responsible for **Orchestration** and **Governance**.
+
+* **Role:** Manages the *Lifecycle* of a request.
+* **Responsibility:**
+    * **Identity:** "Who is this user?" (Authentication).
+    * **Security:** "Can they see this field?" (RBAC/ACL).
+    * **Sync:** "How do we merge these offline changes?" (Conflict Resolution).
+    * **Process:** "What happens after this record is saved?" (Workflows/Triggers).
+* **Key Concept:** It acts as the gateway. No direct database access is allowed; everything must pass through the OS Kernel.
+
+### 3. The View Layer: ObjectUI
+**"The Projection Engine"**
+
+At the top is ObjectUI. It is responsible for **Interaction** and **Rendering**.
+
+* **Role:** Consumes the Protocol to render the Interface.
+* **Responsibility:** It does not contain hardcoded forms. Instead, it asks ObjectQL: *"What is the schema for a Customer?"* and dynamically renders a layout based on that metadata.
+* **Key Concept:** **Server-Driven UI (SDUI)**. The backend dictates the layout, validation rules, and available actions. The frontend is merely a highly capable renderer.
+
+---
+
+## The Request Lifecycle
+
+To understand how these pieces fit together, let's trace a typical user interaction—for example, a Sales Rep updating a deal status while offline.
+
+### Step 1: Interaction (ObjectUI)
+The user clicks "Mark as Won" in the UI.
+* **ObjectUI** validates the input against the JSON Schema (loaded locally).
+* It does not send an API request immediately. It writes the change to the **Local Database** (e.g., SQLite/RxDB).
+* The UI updates instantly (0ms latency).
+
+### Step 2: Synchronization (ObjectOS Sync)
+When the network is available, the Client pushes a "Mutation Packet" to the Server.
+* **ObjectOS** receives the packet.
+* It authenticates the session (`@objectos/auth`).
+* It checks against the **Audit Log** for conflicts (e.g., did someone else edit this deal 5 minutes ago?).
+* It runs any server-side **Workflow** logic (e.g., "If Deal > $10k, trigger Manager Approval").
+
+### Step 3: Compilation (ObjectQL)
+Once ObjectOS approves the request, it passes the data operation to ObjectQL.
+* **ObjectQL** receives the AST: `UPDATE Deals SET Status = 'Won' WHERE ID = '123'`.
+* The **Compiler** translates this into the target dialect: `UPDATE "deals" SET "status" = 'Won'...`.
+* The **Driver** executes the SQL against the master PostgreSQL database.
+
+---
+
+## Deployment Topologies
+
+Because the architecture is protocol-driven, it supports various deployment models depending on your infrastructure needs.
+
+### A. The Monolith (Default)
+Ideal for small-to-medium enterprise apps.
+* **Frontend:** React Single Page App (SPA).
+* **Backend:** A single Node.js instance running ObjectOS + ObjectQL Core.
+* **Database:** Single PostgreSQL instance.
+
+### B. Local-First / Edge
+Ideal for field service apps, POS systems, and high-performance SaaS.
+* **Frontend:** ObjectUI + Embedded ObjectQL (Wasm) + SQLite.
+* **Backend:** ObjectOS running as a Sync Gateway (Stateless).
+* **Database:** Distributed SQL or simple object storage for replication logs.
+
+### C. Microservices Federation
+Ideal for large-scale enterprise integration.
+* Multiple ObjectOS instances (CRM Service, ERP Service, HR Service).
+* A centralized **Gateway** aggregates the ObjectQL schemas into a "Super Graph" (similar to GraphQL Federation).
+* ObjectUI renders a unified dashboard by consuming the federated schema.

content/docs/concepts/core-values.mdx

@@ -1,8 +1,6 @@
 ---
 title: Core Values
 description: "Deep dive into the three pillars of ObjectStack: Protocol-Driven Architecture, Local-First Data Sovereignty, and Database Agnosticism."
-sidebar_position: 2
-slug: /concepts/core-values
 ---
 
 # Core Values

content/docs/concepts/enterprise-patterns.mdx

@@ -1,8 +1,6 @@
 ---
 title: Enterprise Patterns
 description: Handling complex ERP/CRM business logic (State Machines, Calculations, RBAC) using the Protocol-Driven approach.
-sidebar_position: 4
-slug: /concepts/enterprise-patterns
 ---
 
 # Enterprise Patterns

content/docs/concepts/index.cn.mdx

@@ -0,0 +1,112 @@
+---
+title: 导读：协议驱动范式
+description: 为什么世界需要一个通用的企业级全栈协议标准？从代码驱动转向协议驱动的架构变革。
+---
+
+# 导读：协议驱动范式 (The Protocol-Driven Paradigm)
+
+> "Code rots. Protocols endure." 
+> (代码会腐烂，协议永存。)
+
+在过去的一二十年里，企业软件开发陷入了一个西西弗斯式的循环：
+
+我们用 JSP 写了一遍 CRM，五年后用 Angular 重写，再过五年用 React 重写。后端也从 PHP 换到 Node.js，再到 Go。每一次技术栈的迭代，我们都在**重新实现完全相同的业务逻辑**——相同的表单验证、相同的权限判断、相同的审批流程。
+
+这种**“代码驱动（Code-Driven）”**的开发模式带来了巨大的隐性成本：**业务逻辑与技术实现紧密耦合**。当技术框架过时，业务资产也随之贬值，甚至成为技术债。
+
+**ObjectStack 的诞生，旨在终结这一循环。**
+
+## 什么是 ObjectStack？
+
+ObjectStack 不是一个简单的框架或库，它是一套**全栈应用开发协议标准（Standard Protocols）**。
+
+它主张将应用的**“意图（Intent）”**与**“实现（Implementation）”**彻底分离。通过标准化的 JSON 协议来定义数据、界面和流程，从而使业务逻辑独立于具体的编程语言和数据库技术。
+
+ObjectStack 的核心架构由三大支柱构成：
+
+1.  **ObjectQL (The Data Protocol):** 数据库无关的通用数据协议。
+2.  **ObjectUI (The View Protocol):** 声明式的通用界面协议。
+3.  **ObjectOS (The Runtime Protocol):** 负责编排与治理的业务操作系统。
+
+
+
+## 核心哲学
+
+### 1. 协议驱动开发 (Protocol-Driven Development)
+
+在传统开发中，业务逻辑被硬编码在函数中：
+
+```javascript
+// The Old Way: Imperative & Coupled
+function createOrder(data) {
+  if (data.amount > 1000 && !user.isManager) {
+    throw new Error("Need approval");
+  }
+  db.query("INSERT INTO orders ...");
+}
+
+```
+
+在 ObjectStack 中，业务逻辑被定义为**数据（Metadata/Protocol）**：
+
+```yaml
+# The ObjectStack Way: Declarative & Decoupled
+object: order
+fields:
+  amount: { type: currency }
+validation:
+  - rule: "amount > 1000"
+    guard: "!user.isManager"
+    message: "Need approval"
+
+```
+
+* **差异：** 上述 YAML 配置不依赖任何语言。它可以被 Node.js 后端执行，可以被 Python 脚本分析，甚至可以直接传输给前端进行即时校验。
+* **价值：** 你的业务逻辑成为了**可移植、可分析、可进化的数字资产**，而不仅仅是一堆即将过时的代码。
+
+### 2. 本地优先 (Local-First & Data Sovereignty)
+
+云原生（Cloud-Native）带来了便捷，但也剥夺了用户的数据主权。SaaS 厂商的数据孤岛让企业失去了对自己数据的物理控制权。
+
+ObjectStack 拥抱 **Local-First** 架构：
+
+* 应用首先在本地数据库（如 SQLite, RxDB）读写数据。
+* 操作即时响应，无需等待网络往返。
+* **ObjectOS** 负责在后台处理复杂的数据同步和冲突解决（CRDTs/LWW）。
+
+这意味着：**即便断网，你的企业软件依然可用；即便云服务商倒闭，你的数据依然在你手中。**
+
+### 3. 跨数据库 (Database-Agnostic)
+
+企业不应被数据库厂商锁定。
+
+**ObjectQL** 充当了一个**数据库编译器**的角色。你编写标准的 ObjectQL Schema 和 Query AST，引擎负责将其编译为：
+
+* **PostgreSQL** (用于生产环境)
+* **SQLite** (用于边缘设备或本地开发)
+* **MySQL / Oracle / SQL Server** (用于遗留系统集成)
+
+这种能力让架构师可以在不同的场景下选择最优的存储引擎，而无需重写任何业务代码。
+
+## 为什么是现在？
+
+AI 正在重塑软件工程。
+
+当 AI 辅助编程（Copilot）日益普及，我们发现 AI 生成**结构化的协议（JSON/YAML）**比生成**过程式的代码（JavaScript/Python）**要准确得多、安全得多。
+
+* AI 生成代码容易产生幻觉（Hallucinations）和 Bug。
+* AI 生成符合 Schema 的 JSON 配置则是确定性的、可校验的。
+
+ObjectStack 是**为 AI 时代设计的架构**。它提供了一套 AI 能够完美理解和操作的标准语义层，使得“通过对话生成软件”成为可能。
+
+## 概览
+
+在接下来的章节中，我们将深入探讨这套协议的细节：
+
+* 前往 **[架构全景](https://www.google.com/search?q=./03-architecture.md)** 查看各组件如何协作。
+* 前往 **[核心价值](https://www.google.com/search?q=./02-core-values.md)** 了解更多关于本地优先的思考。
+* 前往 **[企业级模式](https://www.google.com/search?q=./04-enterprise-patterns.md)** 了解如何处理复杂的 ERP 场景。
+
+:::tip 记住
+ObjectStack 的目标不是让你写代码写得更快，而是让你写的代码**活得更久**。
+:::

content/docs/concepts/index.mdx

@@ -0,0 +1,111 @@
+---
+title: "Introduction"
+description: Why the world needs a universal enterprise full-stack protocol standard. Shifting from Code-Driven to Protocol-Driven architecture.
+---
+
+# Introduction: The Protocol-Driven Paradigm
+
+> "Code rots. Protocols endure."
+
+For the past two decades, enterprise software development has been trapped in a Sisyphean cycle:
+
+We built CRMs with JSP, then rewrote them in Angular five years later, and rewrote them again in React five years after that. Backends shifted from PHP to Node.js, and then to Go. With every iteration of the tech stack, we are **re-implementing the exact same business logic**—the same form validations, the same permission checks, the same approval workflows.
+
+This **"Code-Driven"** development model carries a massive hidden cost: **Business logic is tightly coupled with technical implementation.** When the framework becomes obsolete, your business assets depreciate with it, eventually turning into technical debt.
+
+**ObjectStack was born to end this cycle.**
+
+## What is ObjectStack?
+
+ObjectStack is not just a framework or a library; it is a **Universal Full-Stack Application Protocol Standard**.
+
+It advocates for the complete separation of **"Intent"** from **"Implementation"**. By defining data, interfaces, and processes through standardized JSON protocols, business logic becomes independent of specific programming languages and database technologies.
+
+The core architecture of ObjectStack consists of three pillars:
+
+1.  **ObjectQL (The Data Protocol):** A database-agnostic universal data protocol.
+2.  **ObjectUI (The View Protocol):** A declarative universal interface protocol.
+3.  **ObjectOS (The Runtime Protocol):** A business operating system responsible for orchestration and governance.
+
+
+
+## Core Philosophy
+
+### 1. Protocol-Driven Development
+
+In traditional development, business logic is hard-coded into functions:
+
+```javascript
+// The Old Way: Imperative & Coupled
+function createOrder(data) {
+  if (data.amount > 1000 && !user.isManager) {
+    throw new Error("Need approval");
+  }
+  db.query("INSERT INTO orders ...");
+}
+
+```
+
+In ObjectStack, business logic is defined as **Data (Metadata/Protocol)**:
+
+```yaml
+# The ObjectStack Way: Declarative & Decoupled
+object: order
+fields:
+  amount: { type: currency }
+validation:
+  - rule: "amount > 1000"
+    guard: "!user.isManager"
+    message: "Need approval"
+
+```
+
+* **The Difference:** The YAML configuration above relies on no specific language. It can be executed by a Node.js backend, analyzed by a Python script, or even transmitted to the frontend for immediate client-side validation.
+* **The Value:** Your business logic becomes a **portable, analyzable, and evolvable digital asset**, rather than a pile of code destined for obsolescence.
+
+### 2. Local-First & Data Sovereignty
+
+Cloud-Native brings convenience, but it also strips users of data sovereignty. Data silos created by SaaS vendors leave enterprises without physical control over their own data.
+
+ObjectStack embraces a **Local-First** architecture:
+
+* Applications read and write data primarily to a local database (e.g., SQLite, RxDB).
+* Interactions are instantaneous, requiring no network round-trips.
+* **ObjectOS** handles complex data synchronization and conflict resolution (CRDTs/LWW) in the background.
+
+This means: **Even if the network goes down, your enterprise software remains usable. Even if the cloud provider goes bankrupt, your data remains in your hands.**
+
+### 3. Database-Agnostic
+
+Enterprises should not be locked into a specific database vendor.
+
+**ObjectQL** acts as a **Database Compiler**. You write standard ObjectQL Schema and Query ASTs, and the engine compiles them into:
+
+* **PostgreSQL** (For production environments)
+* **SQLite** (For edge devices or local development)
+* **MySQL / Oracle / SQL Server** (For legacy system integration)
+
+This capability allows architects to choose the optimal storage engine for different scenarios without rewriting a single line of business code.
+
+## Why Now?
+
+AI is reshaping software engineering.
+
+As AI-assisted programming (Copilot) becomes ubiquitous, we are discovering that AI generates **Structured Protocols (JSON/YAML)** far more accurately and safely than it generates **Imperative Code (JavaScript/Python)**.
+
+* AI-generated code is prone to hallucinations and bugs.
+* AI-generated JSON configuration, validated against a Schema, is deterministic and verifiable.
+
+ObjectStack is an **architecture designed for the AI Era**. It provides a standard semantic layer that AI can perfectly understand and manipulate, making "Software Generation via Conversation" a reality.
+
+## Overview
+
+In the following sections, we will explore the details of these protocols:
+
+* Go to **[Architecture Overview](https://www.google.com/search?q=./03-architecture.md)** to see how the components collaborate.
+* Go to **[Core Values](https://www.google.com/search?q=./02-core-values.md)** to learn more about Local-First thinking.
+* Go to **[Enterprise Patterns](https://www.google.com/search?q=./04-enterprise-patterns.md)** to understand how to handle complex ERP scenarios.
+
+:::tip Remember
+The goal of ObjectStack is not just to make you write code faster, but to make the code you write **live longer**.
+:::

content/docs/framework/manifesto.mdx content/docs/concepts/manifesto.mdxcontent/docs/framework/manifesto.mdx renamed to content/docs/concepts/manifesto.mdx

@@ -29,7 +29,7 @@ ObjectStack's protocol layer (ObjectQL, ObjectUI) consists purely of specificati
 
 **When designing protocols**:
 - Use standard JSON Schema format
-- Avoid introducing language or framework-specific concepts
+- Avoid introducing language or concepts-specific concepts
 - Keep protocols simple and extensible
 - Define in Spec layer first, implement in Engine layer second
 

content/docs/concepts/meta.json

@@ -0,0 +1,5 @@
+{
+  "title": "Concepts",
+  "root": true,
+  "pages": ["index", "core-values", "architecture", "enterprise-patterns", "terminology"]
+}

content/docs/concepts/terminology.mdx

@@ -1,8 +1,6 @@
 ---
 title: Terminology
 description: A glossary of key terms, concepts, and jargon used within the ObjectStack ecosystem.
-sidebar_position: 5
-slug: /concepts/terminology
 ---
 
 # Terminology