（功能） | **权限集 / 配置文件**
*（布尔标志）* | **安全角色**
*（"点阵"）* | 将功能权利（例如，"导出数据"）与数据范围解耦，可以实现更灵活的分配。 | -| **他们坐在哪里？**
（层次结构） | **角色**
*（报告线）* | **业务单元**
*（部门树）* | "角色"意味着逻辑报告（VP 可以看到经理），而"BU"意味着僵化的部门孤岛。 | -| **他们可以看到什么数据？**
（可见性） | **共享规则**
*（标准和所有权）* | **访问团队**
*（临时）* | **共享规则**是"杀手级功能"。它们允许诸如"将 > 100 万的交易与财务共享"之类的逻辑，而 Microsoft 的静态层次结构无法轻松表达。 | -| **超级访问** | **查看全部 / 修改全部** | **组织级别**（绿点） | 将"超级访问"与标准"读取"分开可防止意外数据泄漏。 | - -## 2. 协议 - -该模型通过三个关键协议实现： - -### A. 配置文件和权限集 -* **什么：** 定义对象和字段的"CRUD"访问权限。 -* **类比：** 你的门禁卡。它说"你可以打开 3 层的门"。 -* **示例：** `leads: { read: true, edit: false }`。 - -### B. OWD（组织范围默认值） -* **什么：** 你*不拥有*的记录的基线可见性。 -* **类比：** 办公室门的默认状态。它们是锁定的（私有）还是打开的（公共只读）？ -* **示例：** `Quote: Private`（只有所有者看到它）。 - -### C. 共享规则 -* **什么：** OWD 的例外，用于开放访问权限。 -* **类比：** "如果你是销售副总裁，你可以进入 CEO 的办公室。" -* **示例：** `IF amount > 1,000,000 SHARE WITH Group:Executives READ/WRITE`。 - -## 3. 执行流程 - -每个查询都通过**安全内核**。 - -```mermaid -graph TD - A[用户请求] --> B{配置文件检查} - B -- 拒绝 --> X[403 禁止] - B -- 允许 --> C{字段级安全} - C -- 剥离字段 --> D{共享计算} - D -- 添加 WHERE 子句 --> E[最终查询] -``` - -### A. 功能权限（`src/data/permission.zod.ts`） -定义**基线**。 -* 如果 `allowRead = false`，则用户无法看到*任何*记录，无论共享如何。 -* 如果 `allowRead = true`，则用户可以看到*他们自己的*记录（所有权）。 - -### B. 结构层次结构（`src/system/role.zod.ts`） -定义**报告线**。 -* 用户被分配到一个角色（例如，"销售经理"）。 -* **自动继承**："销售经理"隐式看到"销售代表"拥有的数据。 -* *注意：这最接近 Microsoft 的"业务单元"概念。* - -### C. 数据访问范围（`src/data/sharing.zod.ts`） -定义**扩展**。 -* 我们从"私有"（OWD）开始。 -* 我们通过**共享规则**扩展访问权限。 - * **基于标准**："如果状态 = '已发布'，则与所有内部用户共享。" - * **基于所有者**："将'西部地区'记录与'西部 VP'共享。" - -## 3. 术语映射 - -如果你来自 Microsoft/Dynamics 生态系统： - -* **安全角色（用户级别）** -> `allowRead: true` -* **安全角色（BU 级别）** -> `allowRead: true` + `共享规则（与角色共享）` -* **安全角色（组织级别）** -> `viewAllRecords: true` -* **业务单元** -> `角色`（功能层次结构） - -## 4. 高级：矩阵管理（区域管理） - -对于单一报告线（"角色"）不足的大型全球企业，ObjectStack 实现了**区域管理**协议（`src/system/territory.zod.ts`）。 - -这在不破坏严格角色层次结构的情况下解决了"矩阵组织"问题。 - -* **角色层次结构（HR/报告）**："谁向谁报告？"（稳定） - * 示例：销售代表向销售经理报告。 -* **区域层次结构（市场/收入）**："谁拥有哪个市场？"（灵活，多重分配） - * 示例：销售代表可能被分配到"西海岸（地理）"和"医疗保健（行业）"。 - -**工作原理：** -1. **客户/交易**根据规则分配给**区域**（例如，`State = 'CA'`）。 -2. **用户**被分配给**区域**。 -3. 用户可以访问其区域中的记录，*无论*其角色如何。 - -这与 **Salesforce 企业区域管理**和 **Oracle Sales Cloud** 的最佳实践保持一致。 diff --git a/content/docs/concepts/security_architecture.mdx b/content/docs/concepts/security_architecture.mdx deleted file mode 100644 index e4880cbc5..000000000 --- a/content/docs/concepts/security_architecture.mdx +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: Security Architecture -description: The "Defense in Depth" Model. Why we chose Metadata-Driven Security over Code-Based Security. ---- - -import { ShieldAlert, Users, key, Lock } from 'lucide-react'; - -# ObjectStack Security Model: The "Defense in Depth" Architecture - -ObjectStack adopts the **"Salesforce-style"** metadata-driven security model. This is chosen over the Microsoft (Dataverse) model for its superior granularity and decoupling, which is essential for complex enterprise scenarios. - -## 1. Comparison of Major Models - -| Layer | ObjectStack / Salesforce | Microsoft Dataverse (Dynamics) | Why we chose ObjectStack's way? | -| :--- | :--- | :--- | :--- | -| **Who is this?** | **User + Identity** | User + Azure AD | Standard OIDC/SAML integration. | -| **What can they do?**
(Functionality) | **Permission Set / Profile**
*(Boolean Flags)* | **Security Role**
*(The "Matrix" of Dots)* | Decoupling functional rights (e.g., "Export Data") from data scope allows more flexible assignment. | -| **Where do they sit?**
(Hierarchy) | **Role**
*(Reporting Line)* | **Business Unit**
*(Department Tree)* | "Role" implies logical reporting (VP can see Manager), whereas "BU" implies rigid department silos. | -| **What data can they see?**
(Visibility) | **Sharing Rules**
*(Criteria & Ownership)* | **Access Teams**
*(Ad-hoc)* | **Sharing Rules** are the "Killer Feature". They allow logic like "Share Deal > 1M with Finance", which Microsoft's static hierarchy cannot easily express. | -| **Super Access** | **View All / Modify All** | **Organization Level** (Green Dot) | Separating "Super Access" from standard "Read" prevents accidental data leaks. | - -## 2. The Protocols - -The Model is implemented via three key protocols: - -### A. Profiles & Permission Sets -* **What:** Defines "CRUD" access on Objects and Fields. -* **Analogy:** Your Keycard. It says "You can open doors on Level 3". -* **Example:** `leads: { read: true, edit: false }`. - -### B. OWD (Organization-Wide Defaults) -* **What:** The baseline visibility for records you *do not own*. -* **Analogy:** The default state of the office doors. Are they locked (Private) or open (Public Read Only)? -* **Example:** `Quote: Private` (Only owner sees it). - -### C. Sharing Rules -* **What:** Exceptions to the OWD to open up access. -* **Analogy:** "You can enter the CEO's office IF you are the VP of Sales." -* **Example:** `IF amount > 1,000,000 SHARE WITH Group:Executives READ/WRITE`. - -## 3. The Enforcement Flow - -Every query passes through the **Security Kernel**. - -```mermaid -graph TD - A[User Request] --> B{Profile Check} - B -- Deny --> X[403 Forbidden] - B -- Allow --> C{Field Level Security} - C -- Strip Fields --> D{Sharing Calculation} - D -- Add WHERE Clause --> E[Final Query] -``` - - -### A. Functional permissions (`src/data/permission.zod.ts`) -Defines the **Baseline**. -* If `allowRead = false`, the user cannot see *any* record, regardless of sharing. -* If `allowRead = true`, the user can see *their own* records (Ownership). - -### B. Structural Hierarchy (`src/system/role.zod.ts`) -Defines the **Reporting Line**. -* A user is assigned to one Role (e.g., "Sales Manager"). -* **Automatic Inheritance**: The "Sales Manager" implicitly sees data owned by "Sales Rep". -* *Note: This is closest to Microsoft's "Business Unit" concept.* - -### C. Data Access Scope (`src/data/sharing.zod.ts`) -Defines the **Expansion**. -* We start with "Private" (OWD). -* We expand access via **Sharing Rules**. - * **Criteria-based**: "If Status = 'Published', share with All Internal Users." - * **Owner-based**: "Share 'Western Region' records with 'Western VP'." - -## 3. Terminology Map - -If you are coming from the Microsoft/Dynamics ecosystem: - -* **Security Role (User Level)** -> `allowRead: true` -* **Security Role (BU Level)** -> `allowRead: true` + `Sharing Rule (Share with Role)` -* **Security Role (Org Level)** -> `viewAllRecords: true` -* **Business Unit** -> `Role` (Functional Hierarchy) - -## 4. Advanced: Matrix Management (Territory Management) - -For large global enterprises where a single reporting line ("Role") is insufficient, ObjectStack implements the **Territory Management** protocol (`src/system/territory.zod.ts`). - -This solves the "Matrix Organization" problem without breaking the strict Role hierarchy. - -* **Role Hierarchy (HR/Reporting)**: "Who reports to whom?" (Stable) - * Example: A Sales Rep reports to a Sales Manager. -* **Territory Hierarchy (Market/Revenue)**: "Who owns which market?" (Flexible, Multi-assignment) - * Example: A Sales Rep might be assigned to both "West Coast (Geo)" and "Healthcare (Industry)". - -**How it works:** -1. **Accounts/Deals** are assigned to **Territories** based on rules (e.g., `State = 'CA'`). -2. **Users** are assigned to **Territories**. -3. Users gain access to records in their Territories, *regardless* of their Role. - -This aligns with best practices from **Salesforce Enterprise Territory Management** and **Oracle Sales Cloud**. - - diff --git a/content/docs/concepts/terminology.cn.mdx b/content/docs/concepts/terminology.cn.mdx deleted file mode 100644 index 1ffc39517..000000000 --- a/content/docs/concepts/terminology.cn.mdx +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: 术语表 -description: ObjectStack 生态系统的词汇表。使用相同的语言。 ---- - -import { Book, Server, Code, Database } from 'lucide-react'; - -为了有效地浏览 ObjectStack 生态系统，了解我们使用的特定词汇是有帮助的。虽然许多术语在计算机科学中是标准的，但在我们的"协议驱动"上下文中，有些术语具有特定的细微差别。 - -## 生态系统 - -### ObjectStack -整个协议和参考实现套件的总称。它被组织成分组到三个架构层的 **11 个协议命名空间**。 - -### 协议命名空间（Protocol Namespace） -使用 Zod 定义的相关 schema 和类型的逻辑分组。ObjectStack 有 11 个协议命名空间：数据（Data）、驱动（Driver）、权限（Permission）、UI、系统（System）、认证（Auth）、内核（Kernel）、Hub、AI、API 和自动化（Automation）。 - ---- - -## 11 个协议命名空间 - -### 数据协议（Data Protocol） -定义核心业务数据模型。包括对象 schema、字段类型、验证规则、查询 AST 和过滤条件。这是 ObjectQL 的基础。 - -### 驱动协议（Driver Protocol） -用于连接各种存储引擎（PostgreSQL、MongoDB、SQLite、Redis 等）的数据库适配器接口。驱动实现 CRUD 操作和查询执行的标准接口。 - -### 权限协议（Permission Protocol） -访问控制系统，包括对象级权限（CRUD）、字段级安全（FLS）、共享规则和区域管理。确定谁可以查看和修改哪些数据。 - -### UI 协议（UI Protocol） -用于构建用户界面的服务器驱动 UI 规范。包括应用结构、视图（列表/表单/看板/日历）、仪表板、报表、主题和操作。 - -### 系统协议（System Protocol） -基础设施服务，包括事件总线、作业调度、翻译（i18n）和审计日志。管理系统级关注点。 - -### 认证协议（Auth Protocol） -身份和访问管理，包括用户账户、会话、角色、组织结构以及各种认证策略（OAuth、SAML、LDAP 等）。 - -### 内核协议（Kernel Protocol） -插件系统和运行时管理。包括插件生命周期、清单定义、日志配置和运行时上下文。ObjectOS 的核心。 - -### Hub 协议（Hub Protocol） -SaaS 和市场功能，包括多租户、许可、市场插件和部署配置。实现商业分发。 - -### AI 协议（AI Protocol） -人工智能功能，包括 AI 代理、RAG 管道、自然语言查询（NLQ）、预测模型、成本跟踪和编排。 - -### API 协议（API Protocol） -外部通信层，包括 REST 契约、API 发现、实时订阅（WebSocket/SSE）和路由配置。 - -### 自动化协议（Automation Protocol） -业务流程自动化，包括工作流（状态机）、流程（可视化逻辑）和 Webhook（HTTP 回调）。 - ---- - -## 架构概念 - -### 协议驱动（Protocol-Driven） -一种开发范式，其中逻辑在静态声明性数据格式（JSON/YAML）中使用 Zod schema 定义，而不是命令式代码。目标是将**意图**（业务逻辑）与**实现**（技术堆栈）分离。 - -### 本地优先（Local-First） -一种架构模式，其中应用程序首先读取和写入嵌入在用户设备（客户端）上的数据库。网络同步在后台进行。这确保了零延迟交互和离线可用性。 - -### 数据库编译器（Database Compiler） -一个系统，它接受高级查询 AST（抽象语法树）并将其编译为优化的数据库查询字符串（例如，SQL）。这与 ORM 形成对比，ORM 通常充当运行时包装器对象。 - -### 虚拟字段（Virtual Field） -在数据协议 schema 中定义的字段，该字段在数据库表中不物理存在，而是即时计算的。 -* *示例：* 在编译时注入到 `SELECT` 语句中的 SQL 子查询或表达式。 - ---- - -## 数据和 Schema - -### 对象（Object/Entity） -ObjectStack 中数据建模的基本单元。大致相当于 SQL 中的"表"或 NoSQL 中的"集合"。对象定义包括字段、操作、触发器和权限。 - -### 驱动程序（Driver） -允许数据层与特定底层存储引擎通信的适配器插件（驱动协议）。 -* *示例：* `@objectstack/driver-postgres`、`@objectstack/driver-mongodb`、`@objectstack/driver-sqlite`。 - -### AST（抽象语法树） -查询或 schema 的中间表示。数据协议在驱动将其转换为 SQL/NoSQL 查询之前，将 JSON 请求解析为 AST。这允许在执行之前进行安全验证和优化。 - -### 清单（Manifest） -ObjectStack 插件的入口点配置文件（内核协议）。它使用清单 schema 声明依赖项、资源和扩展。 - ---- - -## 界面和逻辑 - -### 布局（Layout） -在 UI 协议中定义的 JSON 结构，描述组件的视觉排列。布局可以嵌套和动态（例如，主-明细、网格、看板）。 - -### 工作流（Workflow） -定义为**有限状态机（FSM）**的业务流程（自动化协议）。它由状态（例如，`draft`、`approved`）、转换和守卫组成。 - -### 流程（Flow） -可视化逻辑自动化工具（自动化协议），允许使用基于节点的编辑器构建业务流程。支持屏幕流程、自动启动流程和计划流程。 - -### 操作（Action） -可以由用户（UI 按钮）或系统事件（工作流转换）触发的离散逻辑单元（UI 协议）。操作定义按钮行为和导航。 - -### 组件注册表（Component Registry） -UI 运行时中的映射，它将字符串标识符（例如，`"chart.bar"`）链接到真实的 React 组件。这允许 UI 协议动态实例化 UI 元素。 - ---- - -## 治理 - -### 空间（Space/Workspace） -多租户的逻辑隔离单元（Hub 协议）。单个 ObjectStack 实例可以托管多个空间。数据通过租户隔离策略物理隔离。 - -### FLS（字段级安全） -一种细粒度权限模型（权限协议），其中访问控制应用于单个字段（列），而不仅仅是整个对象（行）。 - -### OWD（组织范围默认值） -对象中记录的默认共享级别（权限协议）。在应用共享规则之前确定基线访问级别。 - -### 区域（Territory） -分层访问控制模型（权限协议），根据地理或组织边界授予数据访问权限。 - -### TCK（技术兼容性工具包） -一套测试，验证驱动程序或渲染器是否符合官方 ObjectStack 协议。如果新驱动程序通过 TCK，则认证为兼容。 diff --git a/content/docs/developers/cli-tools.mdx b/content/docs/developers/cli-tools.mdx new file mode 100644 index 000000000..428429081 --- /dev/null +++ b/content/docs/developers/cli-tools.mdx @@ -0,0 +1,1062 @@ +--- +title: CLI Tools +description: Master the objectstack-cli for project scaffolding, code generation, validation, and deployment. +--- + +# CLI Tools + +The **objectstack-cli** is your command-line companion for building, managing, and deploying ObjectStack applications. It provides code generators, validators, migration tools, and deployment utilities. + +Think of it as the **"rails" or "create-react-app"** for ObjectStack - automating repetitive tasks and enforcing best practices. + +--- + +## 🎯 What Can CLI Do? + +
+ {/* Label */}
+
+
+ {/* Toolbar */}
+ {!readonly && (
+
+ );
+}
+```
+
+### Step 3: Register the Widget
+
+```typescript
+// src/index.ts
+import { defineWidget } from '@objectstack/spec';
+import { RichEditor } from './RichEditor';
+
+export default defineWidget({
+ name: 'rich_editor',
+ label: 'Rich Text Editor',
+ description: 'WYSIWYG editor with formatting toolbar',
+ version: '1.0.0',
+ author: 'Your Name',
+
+ // Supported field types
+ supportedTypes: ['text', 'textarea', 'longtext'],
+
+ // Widget component
+ component: RichEditor,
+
+ // Configuration options
+ settings: {
+ toolbar: {
+ type: 'select',
+ label: 'Toolbar Style',
+ options: [
+ { label: 'Full', value: 'full' },
+ { label: 'Minimal', value: 'minimal' },
+ ],
+ default: 'full',
+ },
+ maxLength: {
+ type: 'number',
+ label: 'Max Length',
+ default: 10000,
+ },
+ },
+});
+```
+
+### Step 4: Build & Test
+
+```bash
+# Development mode with hot reload
+npm run dev
+
+# Build for production
+npm run build
+
+# Output: dist/index.js, dist/index.css
+```
+
+---
+
+## 🧩 Widget Props Interface
+
+Every widget receives the `FieldWidgetProps` interface:
+
+```typescript
+import { FieldWidgetProps } from '@objectstack/spec';
+
+interface FieldWidgetProps {
+ // ============================================================================
+ // Value & Change Handling
+ // ============================================================================
+
+ /**
+ * Current field value.
+ * Type depends on field type (string, number, boolean, array, object).
+ */
+ value: any;
+
+ /**
+ * Callback to update the field value.
+ * Call this when user interaction changes the value.
+ */
+ onChange: (newValue: any) => void;
+
+ // ============================================================================
+ // Field State
+ // ============================================================================
+
+ /**
+ * Whether the field is read-only.
+ * When true, display the value but don't allow editing.
+ */
+ readonly: boolean;
+
+ /**
+ * Whether the field is required.
+ * Show visual indicator (e.g., asterisk) when true.
+ */
+ required: boolean;
+
+ /**
+ * Validation error message.
+ * Display this in your widget's error UI.
+ */
+ error?: string;
+
+ // ============================================================================
+ // Metadata
+ // ============================================================================
+
+ /**
+ * Complete field definition from schema.
+ * Contains type, label, description, constraints, etc.
+ */
+ field: Field;
+
+ /**
+ * The complete record being edited.
+ * Useful for conditional logic and cross-field dependencies.
+ */
+ record?: Record
+
+
+
+
+ )}
+
+ {/* Editor Content */}
+
+
+
+ {readonly ? (
+ // Read-only mode: just show the color
+
+ ) : (
+ // Edit mode: show picker
+
+ );
+}
+```
+
+**Usage in Field Definition:**
+
+```typescript
+import { Field } from '@objectstack/spec';
+
+const fields = {
+ brand_color: Field.text({
+ label: 'Brand Color',
+ widget: 'color_picker',
+ }),
+};
+```
+
+---
+
+### Example 2: Signature Pad
+
+```typescript
+// src/SignaturePad.tsx
+import React, { useRef, useEffect } from 'react';
+import { FieldWidgetProps } from '@objectstack/spec';
+import SignatureCanvas from 'react-signature-canvas';
+
+export function SignaturePad(props: FieldWidgetProps) {
+ const { value, onChange, readonly, field } = props;
+ const sigCanvas = useRef
+
+
+ {readonly ? (
+ // Read-only: display signature image
+ value ? 
:
+ );
+}
+```
+
+---
+
+### Example 3: Map Location Picker
+
+```typescript
+// src/MapPicker.tsx
+import React, { useState } from 'react';
+import { FieldWidgetProps } from '@objectstack/spec';
+import { MapContainer, TileLayer, Marker, useMapEvents } from 'react-leaflet';
+
+function LocationMarker({ position, onPositionChange }) {
+ useMapEvents({
+ click(e) {
+ onPositionChange(e.latlng);
+ },
+ });
+
+ return position ? No signature
+ ) : ( + // Edit mode: canvas + <> +
+
+
+
+ )}
+
+
+
+
+
+
+ {position && (
+
+ );
+}
+```
+
+---
+
+### Example 4: Rating Stars
+
+```typescript
+// src/StarRating.tsx
+import React from 'react';
+import { FieldWidgetProps } from '@objectstack/spec';
+import { Star } from 'lucide-react';
+
+export function StarRating(props: FieldWidgetProps) {
+ const { value, onChange, readonly, field, options } = props;
+ const maxStars = options?.maxStars || 5;
+
+ return (
+ + Lat: {position.lat.toFixed(6)}, Lng: {position.lng.toFixed(6)} +
+ )} +
+
+
+
+ );
+}
+```
+
+---
+
+### Example 5: JSON Editor
+
+```typescript
+// src/JsonEditor.tsx
+import React, { useState } from 'react';
+import { FieldWidgetProps } from '@objectstack/spec';
+import CodeMirror from '@uiw/react-codemirror';
+import { json } from '@codemirror/lang-json';
+
+export function JsonEditor(props: FieldWidgetProps) {
+ const { value, onChange, readonly, error, field } = props;
+ const [jsonError, setJsonError] = useState
+ {[...Array(maxStars)].map((_, index) => {
+ const starValue = index + 1;
+ return (
+
+ );
+ })}
+
+
+ {value > 0 && {value} / {maxStars}}
+
+
+
+
+ );
+}
+```
+
+---
+
+## 🎛️ Widget Configuration
+
+Widgets can accept custom options:
+
+```typescript
+// Widget definition
+export default defineWidget({
+ name: 'star_rating',
+ component: StarRating,
+
+ settings: {
+ maxStars: {
+ type: 'number',
+ label: 'Maximum Stars',
+ default: 5,
+ min: 1,
+ max: 10,
+ },
+ allowHalf: {
+ type: 'checkbox',
+ label: 'Allow Half Stars',
+ default: false,
+ },
+ },
+});
+```
+
+**Usage in Field:**
+
+```typescript
+const fields = {
+ satisfaction: Field.number({
+ label: 'Satisfaction Rating',
+ widget: 'star_rating',
+ widgetOptions: {
+ maxStars: 5,
+ allowHalf: false,
+ },
+ }),
+};
+```
+
+---
+
+## 🔄 Handling Complex Values
+
+### Arrays
+
+```typescript
+// Tags widget
+export function TagsWidget(props: FieldWidgetProps) {
+ const { value = [], onChange } = props;
+
+ const addTag = (tag: string) => {
+ onChange([...value, tag]);
+ };
+
+ const removeTag = (index: number) => {
+ onChange(value.filter((_, i) => i !== index));
+ };
+
+ return (
+
+ {value.map((tag, i) => (
+
+ {tag}
+
+
+ ))}
+ {
+ if (e.key === 'Enter') {
+ addTag(e.currentTarget.value);
+ e.currentTarget.value = '';
+ }
+ }}
+ placeholder="Add tag..."
+ />
+
+ );
+}
+```
+
+### Objects
+
+```typescript
+// Address widget
+export function AddressWidget(props: FieldWidgetProps) {
+ const { value = {}, onChange } = props;
+
+ const updateField = (field: string, fieldValue: any) => {
+ onChange({ ...value, [field]: fieldValue });
+ };
+
+ return (
+
+ updateField('street', e.target.value)}
+ />
+ updateField('city', e.target.value)}
+ />
+ updateField('state', e.target.value)}
+ />
+ updateField('zip', e.target.value)}
+ />
+
+ );
+}
+```
+
+---
+
+## 🌐 Vue & Svelte Examples
+
+### Vue 3 Widget
+
+```vue
+
+
+
+
+
+
+```
+
+### Svelte Widget
+
+```svelte
+
+
+
+
+```
+
+---
+
+## 🎨 Styling Widgets
+
+### CSS Modules
+
+```typescript
+// src/RichEditor.module.css
+.widget {
+ display: flex;
+ flex-direction: column;
+ gap: 8px;
+}
+
+.label {
+ font-weight: 600;
+ color: var(--color-text-primary);
+}
+
+.toolbar {
+ display: flex;
+ gap: 4px;
+ padding: 8px;
+ background: var(--color-bg-secondary);
+ border-radius: 4px;
+}
+
+.error {
+ color: var(--color-error);
+ font-size: 12px;
+}
+```
+
+```typescript
+// src/RichEditor.tsx
+import styles from './RichEditor.module.css';
+
+export function RichEditor(props: FieldWidgetProps) {
+ return (
+
+
+ {/* ... */}
+
+ );
+}
+```
+
+### Tailwind CSS
+
+```typescript
+export function RichEditor(props: FieldWidgetProps) {
+ return (
+
+
+
+ );
+}
+```
+
+---
+
+## 📦 Building & Distributing
+
+### Build Configuration
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+ plugins: [react()],
+ build: {
+ lib: {
+ entry: './src/index.ts',
+ name: 'MyWidget',
+ formats: ['es', 'umd'],
+ fileName: (format) => `index.${format}.js`,
+ },
+ rollupOptions: {
+ external: ['react', 'react-dom', '@objectstack/spec'],
+ output: {
+ globals: {
+ react: 'React',
+ 'react-dom': 'ReactDOM',
+ '@objectstack/spec': 'ObjectStack',
+ },
+ },
+ },
+ },
+});
+```
+
+### Package.json
+
+```json
+{
+ "name": "@mycompany/objectstack-widget-richeditor",
+ "version": "1.0.0",
+ "main": "./dist/index.umd.js",
+ "module": "./dist/index.es.js",
+ "types": "./dist/index.d.ts",
+ "exports": {
+ ".": {
+ "import": "./dist/index.es.js",
+ "require": "./dist/index.umd.js",
+ "types": "./dist/index.d.ts"
+ },
+ "./style.css": "./dist/style.css"
+ },
+ "files": ["dist"],
+ "keywords": ["objectstack", "widget", "richeditor"],
+
+ "objectstack": {
+ "type": "widget",
+ "entry": "./dist/index.es.js",
+ "styles": "./dist/style.css"
+ },
+
+ "peerDependencies": {
+ "@objectstack/spec": "^1.0.0",
+ "react": "^18.0.0",
+ "react-dom": "^18.0.0"
+ }
+}
+```
+
+---
+
+## 🧪 Testing Widgets
+
+### Component Tests
+
+```typescript
+// tests/RichEditor.test.tsx
+import { render, screen, fireEvent } from '@testing-library/react';
+import { RichEditor } from '../src/RichEditor';
+
+describe('RichEditor Widget', () => {
+ it('renders label', () => {
+ render(
+
+ {/* Editor content */}
+
+ {props.error && (
+ {props.error}
+ )}
+
+
+ onChange(e.target.value)}
+ disabled={readonly}
+ />
+ {error && {error}}
+ {field.description && {field.description}}
+
+ );
+}
+```
+
+### 2. Debounce Expensive Operations
+
+```typescript
+import { useDebouncedCallback } from 'use-debounce';
+
+export function MyWidget(props: FieldWidgetProps) {
+ const debouncedChange = useDebouncedCallback(
+ (value) => props.onChange(value),
+ 300
+ );
+
+ return debouncedChange(e.target.value)} />;
+}
+```
+
+### 3. Validate Input
+
+```typescript
+export function NumberWidget(props: FieldWidgetProps) {
+ const { value, onChange, field } = props;
+
+ const handleChange = (newValue: string) => {
+ const num = parseFloat(newValue);
+
+ // Validate against field constraints
+ if (field.min !== undefined && num < field.min) return;
+ if (field.max !== undefined && num > field.max) return;
+
+ onChange(num);
+ };
+
+ return handleChange(e.target.value)} />;
+}
+```
+
+### 4. Support Accessibility
+
+```typescript
+export function MyWidget(props: FieldWidgetProps) {
+ const { field, error, required } = props;
+ const inputId = `field-${field.name}`;
+ const errorId = `${inputId}-error`;
+
+ return (
+
+
+
+ {error && {error}}
+
+ );
+}
+```
+
+### 5. Optimize Re-renders
+
+```typescript
+import { memo } from 'react';
+
+export const MyWidget = memo((props: FieldWidgetProps) => {
+ // Component implementation
+}, (prevProps, nextProps) => {
+ // Custom comparison
+ return prevProps.value === nextProps.value &&
+ prevProps.error === nextProps.error &&
+ prevProps.readonly === nextProps.readonly;
+});
+```
+
+---
+
+## 🔗 Related Resources
+
+- [ObjectUI Protocol](/docs/protocols/objectui)
+- [Field Types Reference](/docs/guides/field-types)
+- [Plugin Development](/docs/development/writing-plugins)
+
+---
+
+## 🆘 Troubleshooting
+
+### Widget Not Rendering
+
+Check that it's registered properly:
+
+```typescript
+export default defineWidget({
+ name: 'my_widget',
+ component: MyWidget,
+ supportedTypes: ['text'],
+});
+```
+
+### onChange Not Working
+
+Ensure you're calling it correctly:
+
+```typescript
+onChange(newValue); // ✅ Correct
+onChange({ target: { value: newValue } }); // ❌ Wrong
+```
+
+### Styles Not Loading
+
+Import CSS in your entry point:
+
+```typescript
+import './styles.css';
+export { MyWidget } from './MyWidget';
+```
+
+---
+
+Ready to build your custom widget? Start with the [Quick Start](#quick-start) guide! 🎨
diff --git a/content/docs/developers/index.mdx b/content/docs/developers/index.mdx
new file mode 100644
index 000000000..c78ad0d2f
--- /dev/null
+++ b/content/docs/developers/index.mdx
@@ -0,0 +1,371 @@
+---
+title: Development & Extension
+description: Extend ObjectStack with plugins, custom widgets, and drivers to build powerful business applications.
+---
+
+# Development & Extension
+
+ObjectStack is designed for **extensibility at every layer**. Whether you're building a custom field widget, integrating a third-party API, or creating an entirely new database driver, the platform provides clean interfaces and powerful abstractions.
+
+## 🎯 What You Can Extend
+
+{/* your UI */}
;
-}
-```
-
-### How do I contribute to ObjectStack?
-
-See the [Contributing Guide](https://github.com/objectstack-ai/spec/blob/main/CONTRIBUTING.md).
-
-We welcome:
-- Bug reports
-- Documentation improvements
-- Driver implementations
-- Renderer implementations
-- Example applications
-
-## Business Questions
-
-### What's the license?
-
-**Apache 2.0** (open source, permissive).
-
-You can:
-- ✅ Use commercially
-- ✅ Modify and distribute
-- ✅ Use in proprietary software
-- ✅ Sublicense
-
-### Is there commercial support?
-
-Not yet. Commercial support and managed hosting are planned for the future.
-
-For now:
-- Community support via GitHub Discussions
-- Professional consulting available (contact team)
-
-### Can I build a SaaS product with ObjectStack?
-
-**Absolutely!** ObjectStack is designed for multi-tenant SaaS platforms.
-
-Many use cases:
-- Internal developer platforms
-- Vertical SaaS (industry-specific apps)
-- White-label solutions
-- Agency client portals
-
-### Who is behind ObjectStack?
-
-ObjectStack is an **open-source project** created by the ObjectStack AI team. See [GitHub Contributors](https://github.com/objectstack-ai/spec/graphs/contributors).
-
-## Common Errors
-
-### "Schema validation failed"
-
-**Cause:** Your schema definition doesn't match the Zod schema.
-
-**Solution:** Check the error message for which field failed. Common issues:
-- Missing required fields
-- Wrong field type
-- Invalid enum value
-
-### "Driver not found"
-
-**Cause:** Kernel can't find the database driver.
-
-**Solution:**
-```typescript
-import { MemoryDriver } from '@objectstack/driver-memory';
-
-kernel.registerDriver('memory', new MemoryDriver());
-```
-
-### "Circular dependency in lookup fields"
-
-**Cause:** Two objects reference each other, creating a cycle.
-
-**Solution:** Use lazy references:
-```typescript
-Field.lookup({
- reference: () => import('./other-object'),
-})
-```
-
-## Still Have Questions?
-
-- 📖 Check the [Guides](/docs/guides/getting-started)
-- 💬 Ask in [GitHub Issues](https://github.com/objectstack-ai/spec/issues)
-- 🐛 Report bugs in [GitHub Issues](https://github.com/objectstack-ai/spec/issues)
-- 📧 Email: support@objectstack.dev (for urgent issues)
diff --git a/content/docs/guides/advanced/ai-integration-guide.mdx b/content/docs/guides/advanced/ai-integration-guide.mdx
deleted file mode 100644
index 344f70ef7..000000000
--- a/content/docs/guides/advanced/ai-integration-guide.mdx
+++ /dev/null
@@ -1,809 +0,0 @@
----
-title: AI Integration Guide
-description: Complete guide to building AI-powered ObjectStack applications
----
-
-# AI Integration Guide
-
-> **Complete guide to building AI-powered ObjectStack applications**
-
-## Table of Contents
-
-1. [Introduction](#introduction)
-2. [AI Protocols Overview](#ai-protocols-overview)
-3. [Getting Started](#getting-started)
-4. [Building AI Agents](#building-ai-agents)
-5. [Implementing RAG](#implementing-rag)
-6. [Natural Language Queries](#natural-language-queries)
-7. [Model Registry](#model-registry)
-8. [Production Best Practices](#production-best-practices)
-9. [Example Applications](#example-applications)
-
----
-
-## Introduction
-
-ObjectStack provides a comprehensive AI protocol suite enabling you to build intelligent, context-aware applications. This guide covers all AI capabilities from RAG pipelines to natural language query processing.
-
-### What You Can Build
-
-- **Intelligent Assistants**: Context-aware chatbots with function calling
-- **Natural Language Interfaces**: Query data using plain English
-- **Code Generators**: Generate ObjectStack apps from descriptions
-- **Smart Automation**: AI-powered workflows and decision making
-
----
-
-## AI Protocols Overview
-
-ObjectStack includes four core AI protocols:
-
-### 1. Agent Protocol (`@objectstack/spec/ai/agent`)
-Define autonomous AI agents with:
-- Model configuration
-- Function calling (tools)
-- Knowledge base access (RAG)
-- Access control
-
-### 2. Model Registry Protocol (`@objectstack/spec/ai/model-registry`)
-Centralized LLM management:
-- Model configurations
-- Prompt templates
-- Fallback handling
-- Health monitoring
-
-### 3. RAG Pipeline Protocol (`@objectstack/spec/ai/rag-pipeline`)
-Retrieval-Augmented Generation:
-- Vector store configuration
-- Embedding models
-- Chunking strategies
-- Retrieval methods (similarity, MMR, hybrid)
-
-### 4. Natural Language Query Protocol (`@objectstack/spec/ai/nlq`)
-Transform natural language to ObjectQL:
-- Intent detection
-- Entity recognition
-- Timeframe parsing
-- Field mapping
-
----
-
-## Getting Started
-
-### Installation
-
-```bash
-npm install @objectstack/spec
-```
-
-### Basic Agent
-
-```typescript
-import { Agent } from '@objectstack/spec';
-
-const myAgent: Agent = {
- name: 'my_assistant',
- label: 'My AI Assistant',
- role: 'Customer Support Specialist',
- instructions: 'You are a helpful assistant.',
-
- model: {
- provider: 'openai',
- model: 'gpt-4-turbo-preview',
- temperature: 0.7,
- },
-
- active: true,
-};
-```
-
----
-
-## Building AI Agents
-
-### Agent Components
-
-#### 1. Identity & Role
-```typescript
-const agent: Agent = {
- name: 'support_agent', // snake_case identifier
- label: 'Support Agent', // Display name
- avatar: '/avatars/bot.png', // Optional avatar
- role: 'Customer Support', // Agent persona
-};
-```
-
-#### 2. Instructions (System Prompt)
-```typescript
-instructions: `You are an experienced customer support agent.
-
-Your responsibilities:
-- Answer questions professionally
-- Create support tickets when needed
-- Escalate complex issues
-
-Always be polite and solution-oriented.`
-```
-
-#### 3. Model Configuration
-```typescript
-model: {
- provider: 'openai',
- model: 'gpt-4-turbo-preview',
- temperature: 0.7, // Creativity (0-2)
- maxTokens: 2048, // Response length
- topP: 0.9, // Nucleus sampling
-}
-```
-
-#### 4. Tools (Function Calling)
-```typescript
-tools: [
- {
- type: 'action',
- name: 'create_ticket',
- description: 'Create a new support ticket',
- },
- {
- type: 'query',
- name: 'search_tickets',
- description: 'Search existing tickets',
- },
- {
- type: 'vector_search',
- name: 'kb_search',
- description: 'Search knowledge base',
- },
- {
- type: 'flow',
- name: 'escalate_to_human',
- description: 'Transfer to human agent',
- },
-]
-```
-
-#### 5. Knowledge Base (RAG)
-```typescript
-knowledge: {
- topics: ['product_docs', 'faq', 'troubleshooting'],
- indexes: ['support_kb_v2'],
-}
-```
-
-#### 6. Access Control
-```typescript
-access: ['support_team', 'customers'],
-active: true,
-```
-
-### Advanced Agent Example
-
-```typescript
-import { Agent } from '@objectstack/spec';
-
-export const DataAnalystAgent: Agent = {
- name: 'data_analyst_ai',
- label: 'AI Data Analyst',
- avatar: '/avatars/analyst.png',
- role: 'Business Intelligence Analyst',
-
- instructions: `You are a data analyst helping users understand business metrics.
-
-Skills:
-- Interpret natural language questions about data
-- Generate ObjectQL queries
-- Create visualizations
-- Provide actionable insights
-
-Be precise, data-driven, and clear.`,
-
- model: {
- provider: 'openai',
- model: 'gpt-4',
- temperature: 0.3, // Lower for precision
- maxTokens: 4096,
- },
-
- tools: [
- {
- type: 'query',
- name: 'execute_objectql',
- description: 'Execute ObjectQL queries on data',
- },
- {
- type: 'action',
- name: 'create_dashboard',
- description: 'Generate dashboard from metrics',
- },
- {
- type: 'action',
- name: 'generate_chart',
- description: 'Create visualizations',
- },
- ],
-
- knowledge: {
- topics: ['sql_guides', 'metrics_definitions'],
- indexes: ['analytics_kb'],
- },
-
- access: ['analysts', 'executives', 'managers'],
- active: true,
-};
-```
-
----
-
-## Implementing RAG
-
-### Why RAG?
-
-RAG (Retrieval-Augmented Generation) enables AI to:
-- Access up-to-date information
-- Reduce hallucinations
-- Provide source citations
-- Scale beyond context windows
-
-### RAG Pipeline Configuration
-
-```typescript
-import { RAGPipelineConfig } from '@objectstack/spec';
-
-const myRAG: RAGPipelineConfig = {
- name: 'knowledge_base',
- label: 'Knowledge Base RAG',
- description: 'RAG for product documentation',
-
- // 1. Embedding Model
- embedding: {
- provider: 'openai',
- model: 'text-embedding-3-large',
- dimensions: 3072,
- batchSize: 100,
- },
-
- // 2. Vector Store
- vectorStore: {
- provider: 'pinecone',
- indexName: 'kb-prod',
- namespace: 'v2',
- dimensions: 3072,
- metric: 'cosine',
- },
-
- // 3. Chunking Strategy
- chunking: {
- type: 'markdown',
- maxChunkSize: 1000,
- respectHeaders: true,
- respectCodeBlocks: true,
- },
-
- // 4. Retrieval Method
- retrieval: {
- type: 'mmr', // Maximal Marginal Relevance
- topK: 5,
- fetchK: 20,
- lambda: 0.7, // Balance relevance vs diversity
- },
-
- // 5. Optional Reranking
- reranking: {
- enabled: true,
- model: 'rerank-english-v3.0',
- provider: 'cohere',
- topK: 3,
- },
-
- // 6. Document Loaders
- loaders: [
- {
- type: 'directory',
- source: '/docs',
- fileTypes: ['.md', '.txt', '.pdf'],
- recursive: true,
- },
- ],
-
- maxContextTokens: 6000,
- enableCache: true,
- cacheTTL: 3600,
-};
-```
-
-### Chunking Strategies
-
-#### Fixed Size
-```typescript
-chunking: {
- type: 'fixed',
- chunkSize: 512,
- chunkOverlap: 50,
- unit: 'tokens',
-}
-```
-
-#### Semantic Chunking
-```typescript
-chunking: {
- type: 'semantic',
- minChunkSize: 100,
- maxChunkSize: 1000,
-}
-```
-
-#### Recursive Text Splitting
-```typescript
-chunking: {
- type: 'recursive',
- separators: ['\n\n', '\n', '. ', ' '],
- chunkSize: 1000,
- chunkOverlap: 100,
-}
-```
-
-#### Markdown-Aware
-```typescript
-chunking: {
- type: 'markdown',
- maxChunkSize: 1500,
- respectHeaders: true,
- respectCodeBlocks: true,
-}
-```
-
-### Retrieval Methods
-
-#### Similarity Search
-```typescript
-retrieval: {
- type: 'similarity',
- topK: 5,
- scoreThreshold: 0.7,
-}
-```
-
-#### MMR (Diverse Results)
-```typescript
-retrieval: {
- type: 'mmr',
- topK: 5,
- fetchK: 20,
- lambda: 0.5, // 0=diverse, 1=relevant
-}
-```
-
-#### Hybrid (Vector + Keyword)
-```typescript
-retrieval: {
- type: 'hybrid',
- topK: 10,
- vectorWeight: 0.7,
- keywordWeight: 0.3,
-}
-```
-
-### Querying RAG
-
-```typescript
-import { RAGQueryRequest } from '@objectstack/spec';
-
-const request: RAGQueryRequest = {
- query: 'How do I configure authentication?',
- pipelineName: 'knowledge_base',
- topK: 5,
- metadataFilters: {
- category: 'security',
- },
- includeMetadata: true,
- includeSources: true,
- executeQuery: false, // Just retrieve, don't generate
-};
-```
-
----
-
-## Natural Language Queries
-
-### NLQ Configuration
-
-```typescript
-import { NLQModelConfig } from '@objectstack/spec';
-
-const nlqConfig: NLQModelConfig = {
- modelId: 'gpt-4-turbo',
-
- // Prompt Engineering
- systemPrompt: `Convert natural language to ObjectQL.
- Available objects: account, opportunity, task`,
-
- includeSchema: true,
- includeExamples: true,
-
- // Features
- enableIntentDetection: true,
- enableEntityRecognition: true,
- enableFuzzyMatching: true,
- enableTimeframeDetection: true,
-
- // Caching
- enableCaching: true,
- cacheTTL: 3600,
-};
-```
-
-### Field Synonyms
-
-Help NLQ understand natural variations:
-
-```typescript
-import { FieldSynonymConfig } from '@objectstack/spec';
-
-const synonyms: FieldSynonymConfig[] = [
- {
- object: 'account',
- field: 'name',
- synonyms: [
- 'customer name',
- 'company name',
- 'organization name',
- 'account name',
- ],
- examples: [
- 'show accounts by customer name',
- 'find companies with name containing Acme',
- ],
- },
- {
- object: 'opportunity',
- field: 'amount',
- synonyms: [
- 'value',
- 'deal size',
- 'revenue',
- 'worth',
- ],
- },
-];
-```
-
-### Query Templates
-
-Pre-built patterns for common queries:
-
-```typescript
-import { QueryTemplate } from '@objectstack/spec';
-
-const topNTemplate: QueryTemplate = {
- id: 'top-n-by-field',
- name: 'top_n_by_field',
- label: 'Top N Records',
-
- pattern: 'top {n} {object} by {field}',
-
- variables: [
- { name: 'n', type: 'value', required: true },
- { name: 'object', type: 'object', required: true },
- { name: 'field', type: 'field', required: true },
- ],
-
- astTemplate: {
- object: '{object}',
- sort: [{ field: '{field}', order: 'desc' }],
- limit: '{n}',
- },
-
- examples: [
- 'top 10 accounts by revenue',
- 'top 5 opportunities by amount',
- ],
-};
-```
-
-### Processing NLQ Requests
-
-```typescript
-import { NLQRequest, NLQResponse } from '@objectstack/spec';
-
-const request: NLQRequest = {
- query: 'show me all high priority tickets from last week',
-
- context: {
- userId: 'user-123',
- currentObject: 'ticket',
- defaultLimit: 100,
- },
-
- includeAlternatives: true,
- maxAlternatives: 3,
- minConfidence: 0.7,
-
- executeQuery: true,
- maxResults: 50,
-};
-
-// Response includes:
-// - Parsed intent, entities, timeframe
-// - Generated ObjectQL AST
-// - Optional: Query results
-// - Confidence scores
-// - Alternative interpretations
-```
-
----
-
-## Model Registry
-
-### Registry Configuration
-
-```typescript
-import { ModelRegistry } from '@objectstack/spec';
-
-const registry: ModelRegistry = {
- name: 'production_registry',
-
- models: {
- 'gpt-4-turbo': {
- model: {
- id: 'gpt-4-turbo',
- name: 'GPT-4 Turbo',
- version: 'gpt-4-turbo-2024-04-09',
- provider: 'openai',
-
- capabilities: {
- textGeneration: true,
- functionCalling: true,
- reasoning: true,
- },
-
- limits: {
- maxTokens: 4096,
- contextWindow: 128000,
- rateLimit: {
- requestsPerMinute: 100,
- },
- },
-
- pricing: {
- inputCostPer1kTokens: 0.01,
- outputCostPer1kTokens: 0.03,
- },
- },
-
- status: 'active',
- priority: 10,
- fallbackModels: ['gpt-3.5-turbo'],
-
- healthCheck: {
- enabled: true,
- intervalSeconds: 300,
- status: 'healthy',
- },
- },
- },
-
- defaultModel: 'gpt-4-turbo',
- enableAutoFallback: true,
-};
-```
-
-### Prompt Templates
-
-Reusable prompts with variables:
-
-```typescript
-promptTemplates: {
- support_response: {
- id: 'support-v1',
- name: 'support_response',
- label: 'Support Response',
-
- system: 'You are a helpful support agent.',
- user: `Customer: {{customer_name}}
-Question: {{question}}
-Context: {{context}}`,
-
- variables: [
- { name: 'customer_name', type: 'string', required: true },
- { name: 'question', type: 'string', required: true },
- { name: 'context', type: 'string', required: false },
- ],
-
- modelId: 'gpt-4-turbo',
- temperature: 0.7,
- maxTokens: 2048,
-
- examples: [
- {
- input: {
- customer_name: 'John Doe',
- question: 'How do I reset my password?',
- },
- output: 'To reset your password...',
- },
- ],
- },
-}
-```
-
----
-
-## Production Best Practices
-
-### 1. Model Selection
-
-- **Reasoning tasks**: GPT-4, Claude 3 Opus
-- **Simple tasks**: GPT-3.5, Claude 3 Haiku
-- **Embeddings**: text-embedding-3-large
-- **Creative writing**: Claude 3 Sonnet
-
-### 2. Cost Optimization
-
-- Use smaller models for simple tasks
-- Enable caching for repeated queries
-- Batch embedding requests
-- Set appropriate token limits
-
-### 3. Error Handling
-
-```typescript
-{
- status: 'active',
- priority: 10,
- fallbackModels: ['backup-model'],
- healthCheck: {
- enabled: true,
- intervalSeconds: 300,
- },
-}
-```
-
-### 4. Security
-
-- Store API keys in environment variables
-- Use access control on agents
-- Validate user inputs
-- Implement rate limiting
-- Monitor for abuse
-
-### 5. Monitoring
-
-Track:
-- Response times
-- Token usage
-- Error rates
-- User satisfaction
-- Cache hit rates
-
-### 6. Testing
-
-```typescript
-import { NLQTrainingExample } from '@objectstack/spec';
-
-const trainingExamples: NLQTrainingExample[] = [
- {
- query: 'show all accounts created last month',
- expectedIntent: 'select',
- expectedObject: 'account',
- expectedAST: {
- object: 'account',
- filters: [['created_date', '>=', '2023-12-01']],
- },
- },
-];
-```
-
----
-
-## Example Applications
-
-### 1. AI Support Assistant
-[View Example](/docs/guides/examples/ai-support)
-
-**Features:**
-- RAG knowledge base
-- Ticket management
-- Escalation workflows
-- Customer satisfaction tracking
-
-**Architecture:**
-```
-Customer → GPT-4 Agent → RAG (Pinecone) → Actions → ObjectQL
-```
-
-### 2. AI Data Analyst
-[View Example](/docs/guides/examples/ai-analyst)
-
-**Features:**
-- Natural language queries
-- Auto-generate dashboards
-- Time-based analysis
-- Query templates
-
-### 3. AI Code Generator
-[View Example](/docs/guides/examples/ai-codegen)
-
-**Features:**
-- Generate ObjectStack apps
-- Schema validation
-- Best practices enforcement
-- RAG for documentation
-
-### 4. AI Sales Assistant
-[View Example](/docs/guides/examples/ai-sales)
-
-**Features:**
-- Lead qualification
-- Email personalization
-- Competitive intelligence
-- Deal insights
-
----
-
-## FAQ
-
-### When should I use RAG vs fine-tuning?
-
-**Use RAG when:**
-- Information changes frequently
-- You need source citations
-- Data is too large for context window
-- Privacy/compliance requirements
-
-**Use fine-tuning when:**
-- Teaching specific writing style
-- Domain-specific terminology
-- Consistent behavior needed
-- Cost optimization for high volume
-
-### How do I handle low confidence queries?
-
-```typescript
-if (response.parseResult.confidence < 0.7) {
- if (response.needsClarification) {
- // Ask user for clarification
- showSuggestions(response.suggestions);
- } else {
- // Show alternative interpretations
- showAlternatives(response.parseResult.alternatives);
- }
-}
-```
-
-### What vector database should I use?
-
-- **Pinecone**: Managed, easy to use
-- **Weaviate**: Open source, flexible
-- **Qdrant**: High performance, Rust-based
-- **pgvector**: PostgreSQL extension
-- **Chroma**: Local development
-
-### How do I optimize RAG performance?
-
-1. Use appropriate chunk sizes (500-1000 tokens)
-2. Enable reranking for accuracy
-3. Use MMR for diverse results
-4. Cache frequently accessed chunks
-5. Filter by metadata when possible
-6. Monitor retrieval metrics
-
----
-
-## Resources
-
-- [ObjectStack Documentation](https://docs.objectstack.ai)
-- [AI Protocol Reference](/docs/guides/packages/spec/src/ai)
-- [Example Applications](/docs/guides/examples)
-- [Discord Community](https://discord.gg/objectstack)
-
----
-
-## Next Steps
-
-1. Start with a simple agent
-2. Add RAG for your knowledge base
-3. Implement natural language queries
-4. Deploy to production
-5. Monitor and optimize
-
-Happy building! 🚀
diff --git a/content/docs/guides/advanced/ai-integration/meta.json b/content/docs/guides/advanced/ai-integration/meta.json
deleted file mode 100644
index 921f7be38..000000000
--- a/content/docs/guides/advanced/ai-integration/meta.json
+++ /dev/null
@@ -1,6 +0,0 @@
-{
- "title": "AI Integration",
- "pages": [
- "quick-start"
- ]
-}
diff --git a/content/docs/guides/advanced/ai-integration/quick-start.mdx b/content/docs/guides/advanced/ai-integration/quick-start.mdx
deleted file mode 100644
index c6e793980..000000000
--- a/content/docs/guides/advanced/ai-integration/quick-start.mdx
+++ /dev/null
@@ -1,178 +0,0 @@
----
-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
-
-## Overview
-
-ObjectStack provides built-in AI capabilities through the AI Protocol. This guide covers the essentials.
-
-## Agent Setup
-
-### 1. Define an AI Agent
-
-```typescript
-const agent = {
- name: 'sales_assistant',
- label: 'Sales Assistant',
- model: {
- provider: 'openai',
- modelName: 'gpt-4',
- temperature: 0.7,
- },
- tools: [
- 'query_records',
- 'create_record',
- 'send_email',
- ],
- systemPrompt: 'You are a helpful sales assistant...',
-};
-```
-
-### 2. Configure Model Registry
-
-```typescript
-const modelRegistry = {
- models: [
- {
- id: 'gpt-4',
- provider: 'openai',
- capabilities: ['chat', 'function_calling'],
- limits: {
- maxTokens: 8192,
- maxContextLength: 128000,
- },
- },
- ],
-};
-```
-
-## RAG Pipeline
-
-### Basic RAG Configuration
-
-```typescript
-const ragConfig = {
- knowledgeBases: ['product_docs', 'sales_playbook'],
-
- chunking: {
- strategy: 'semantic',
- chunkSize: 512,
- overlap: 50,
- },
-
- embedding: {
- model: 'text-embedding-ada-002',
- provider: 'openai',
- },
-
- vectorStore: {
- provider: 'pinecone',
- config: {
- apiKey: process.env.PINECONE_API_KEY,
- environment: 'production',
- },
- },
-
- retrieval: {
- topK: 5,
- minScore: 0.7,
- },
-};
-```
-
-## Natural Language Queries
-
-### Enable NLQ for Objects
-
-```typescript
-const nlqConfig = {
- enabled: true,
- objects: ['customer_account', 'opportunity'],
-
- fieldMappings: [
- {
- synonyms: ['revenue', 'sales', 'income'],
- field: 'annual_revenue',
- },
- {
- synonyms: ['company', 'business', 'organization'],
- field: 'account_name',
- },
- ],
-
- examples: [
- {
- query: 'show me high value customers',
- intent: 'list',
- filters: [{ field: 'annual_revenue', operator: 'gt', value: 1000000 }],
- },
- ],
-};
-```
-
-## Using AI Tools
-
-### Query with Natural Language
-
-```typescript
-const result = await ai.query({
- prompt: 'Show me all accounts in the technology industry with revenue over $1M',
- object: 'customer_account',
-});
-
-// Returns: QueryResult with structured data
-```
-
-### Generate with AI
-
-```typescript
-const generated = await ai.generate({
- prompt: 'Write a follow-up email for this customer',
- context: {
- customer: customerData,
- lastInteraction: interactionData,
- },
-});
-```
-
-## Best Practices
-
-1. **Prompt Engineering**
- - Be specific and clear
- - Provide context
- - Use examples
-
-2. **Model Selection**
- - Use appropriate model for task
- - Balance cost vs. capability
- - Consider latency requirements
-
-3. **RAG Optimization**
- - Chunk documents semantically
- - Use appropriate embedding models
- - Filter results by relevance score
-
-4. **Error Handling**
- - Handle model failures gracefully
- - Implement retry logic
- - Provide fallbacks
-
-## Examples
-
-See the following example implementations:
-
-- [AI Sales Assistant](/docs/examples/ai-sales/)
-- [AI Support Agent](/docs/examples/ai-support/)
-- [AI Code Generator](/docs/examples/ai-codegen/)
-- [AI Analyst](/docs/examples/ai-analyst/)
-
-For complete documentation, see [AI_INTEGRATION_GUIDE.md](/docs/guides/AI_INTEGRATION_GUIDE.md)
-
----
-
-**Last Updated**: 2026-01-22
diff --git a/content/docs/guides/advanced/meta.json b/content/docs/guides/advanced/meta.json
deleted file mode 100644
index 624f5b38e..000000000
--- a/content/docs/guides/advanced/meta.json
+++ /dev/null
@@ -1,9 +0,0 @@
-{
- "title": "Advanced Guides",
- "pages": [
- "ai-integration-guide",
- "ai-integration",
- "security",
- "performance"
- ]
-}
diff --git a/content/docs/guides/advanced/performance/meta.json b/content/docs/guides/advanced/performance/meta.json
deleted file mode 100644
index e4f6c882d..000000000
--- a/content/docs/guides/advanced/performance/meta.json
+++ /dev/null
@@ -1,6 +0,0 @@
-{
- "title": "Performance",
- "pages": [
- "optimization"
- ]
-}
diff --git a/content/docs/guides/advanced/performance/optimization.mdx b/content/docs/guides/advanced/performance/optimization.mdx
deleted file mode 100644
index b8bb38703..000000000
--- a/content/docs/guides/advanced/performance/optimization.mdx
+++ /dev/null
@@ -1,140 +0,0 @@
----
-title: Performance Optimization
-description: Strategies for optimizing ObjectStack Protocol implementations
----
-
-# Performance Optimization Guide
-
-> Strategies for optimizing ObjectStack Protocol implementations
-
-## Query Optimization
-
-### Select Only Needed Fields
-```typescript
-// ✅ Good
-const query = {
- select: ['id', 'name', 'email'],
- from: 'customer_account',
-};
-
-// ❌ Bad
-const query = {
- select: ['*'], // Unnecessary data
- from: 'customer_account',
-};
-```
-
-### Use Efficient Filters
-- Apply filters at database level
-- Use indexed fields in WHERE clauses
-- Implement pagination
-
-### Avoid N+1 Queries
-- Use joins instead of loops
-- Batch load related data
-- Use DataLoader pattern
-
-## Caching Strategies
-
-### Metadata Caching
-- Cache object/field definitions (1 hour TTL)
-- Cache user permissions (10 minutes TTL)
-- Use Redis for distributed caching
-
-### Query Result Caching
-```typescript
-const cacheKey = `query:${JSON.stringify(query)}`;
-const cached = await redis.get(cacheKey);
-if (cached) return JSON.parse(cached);
-
-const results = await executeQuery(query);
-await redis.setEx(cacheKey, 300, JSON.stringify(results));
-```
-
-### Cache Invalidation
-- Invalidate on data changes
-- Use cache tags/patterns
-- Implement TTL strategies
-
-## Database Indexing
-
-### Index Strategy
-```typescript
-const indexes = [
- { fields: ['email'], unique: true },
- { fields: ['status'] },
- { fields: ['industry', 'revenue'] }, // Composite
-];
-```
-
-### Best Practices
-- Index frequently queried fields
-- Use composite indexes for multi-field queries
-- Monitor and remove unused indexes
-
-## API Performance
-
-### Connection Pooling
-```typescript
-const pool = new Pool({
- min: 2,
- max: 10,
- idleTimeoutMillis: 30000,
-});
-```
-
-### Response Compression
-- Enable gzip compression
-- Only compress responses > 1KB
-- Use level 6 compression
-
-### Async Operations
-```typescript
-// Parallel execution
-const [accounts, opportunities] = await Promise.all([
- queryAccounts(),
- queryOpportunities(),
-]);
-```
-
-## Frontend Optimization
-
-### Lazy Loading
-- Load components on demand
-- Code splitting
-- Dynamic imports
-
-### Virtualization
-- Use virtual scrolling for long lists
-- Render only visible items
-- Implement infinite scroll
-
-### Memoization
-- Cache expensive computations
-- Use React.memo for components
-- useMemo for derived data
-
-## Monitoring
-
-### Performance Metrics
-- Track query duration
-- Log slow queries (> 1s)
-- Monitor cache hit rates
-
-### Profiling
-- Use EXPLAIN ANALYZE for queries
-- Profile application code
-- Monitor resource usage
-
-## Performance Targets
-
-| Metric | Target |
-|--------|--------|
-| API Response (p95) | < 500ms |
-| Database Query (p95) | < 200ms |
-| Page Load | < 2s |
-| Cache Hit Rate | > 80% |
-
----
-
-**Last Updated**: 2026-01-22
diff --git a/content/docs/guides/advanced/security/best-practices.mdx b/content/docs/guides/advanced/security/best-practices.mdx
deleted file mode 100644
index 9a3823d44..000000000
--- a/content/docs/guides/advanced/security/best-practices.mdx
+++ /dev/null
@@ -1,105 +0,0 @@
----
-title: Security Best Practices
-description: Comprehensive security guidelines for ObjectStack Protocol implementations
----
-
-# Security Best Practices Guide
-
-> Comprehensive security guidelines for ObjectStack Protocol implementations
-
-## Authentication & Authorization
-
-### Strong Authentication
-```typescript
-const authConfig = {
- providers: [
- {
- type: 'email_password',
- passwordPolicy: {
- minLength: 12,
- requireUppercase: true,
- requireNumbers: true,
- requireSpecialChars: true,
- },
- },
- ],
- twoFactor: {
- enabled: true,
- required: true,
- },
-};
-```
-
-### Session Management
-- Use short session lifetimes (1-24 hours)
-- Set secure cookie flags (httpOnly, secure, sameSite)
-- Invalidate sessions on password change
-
-### RBAC
-- Implement least privilege principle
-- Use role-based access control
-- Apply field-level security
-
-## Data Protection
-
-### Encryption
-- Encrypt sensitive fields at rest
-- Use HTTPS/TLS for all traffic
-- Implement proper key management
-
-### Data Masking
-- Mask sensitive data in logs
-- Sanitize error messages
-- Redact PII in responses
-
-## API Security
-
-### Rate Limiting
-- Limit API requests per user
-- Block brute force attacks
-- Implement exponential backoff
-
-### Input Validation
-- Validate all inputs with Zod schemas
-- Use parameterized queries
-- Prevent SQL/NoSQL injection
-
-### CORS & CSRF
-- Configure CORS properly
-- Enable CSRF protection
-- Validate origin headers
-
-## Secrets Management
-
-- Store secrets in environment variables
-- Never commit secrets to git
-- Rotate secrets regularly
-- Use secret management services
-
-## Audit & Compliance
-
-### Audit Logging
-- Log security events
-- Track data access
-- Monitor authentication attempts
-
-### Compliance
-- GDPR data export/erasure
-- HIPAA encryption requirements
-- SOC2 audit trails
-
-## Security Checklist
-
-- [ ] HTTPS enforced
-- [ ] MFA enabled
-- [ ] Rate limiting configured
-- [ ] Input validation on all endpoints
-- [ ] Secrets in environment variables
-- [ ] Audit logging enabled
-- [ ] Regular security updates
-
-For detailed information, see [AUTHENTICATION_STANDARD.md](/docs/AUTHENTICATION_STANDARD.md)
-
----
-
-**Last Updated**: 2026-01-22
diff --git a/content/docs/guides/advanced/security/meta.json b/content/docs/guides/advanced/security/meta.json
deleted file mode 100644
index 8e41b7a1f..000000000
--- a/content/docs/guides/advanced/security/meta.json
+++ /dev/null
@@ -1,6 +0,0 @@
-{
- "title": "Security",
- "pages": [
- "best-practices"
- ]
-}
diff --git a/content/docs/guides/custom-driver.cn.mdx b/content/docs/guides/custom-driver.cn.mdx
deleted file mode 100644
index 2c7416f12..000000000
--- a/content/docs/guides/custom-driver.cn.mdx
+++ /dev/null
@@ -1,136 +0,0 @@
----
-title: 构建自定义驱动
-description: 学习如何使用驱动接口为 ObjectStack 实现自定义数据库驱动。
----
-
-# 构建自定义驱动
-
-驱动程序（Driver）是 **ObjectQL** 引擎与底层数据存储（SQL、NoSQL、API 等）之间的桥梁。通过实现 `DriverInterface`，您可以将 ObjectStack 连接到任何数据源。
-
-本指南将以创建一个简单的 **内存驱动（In-Memory Driver）** 为例进行讲解。
-
-## 先决条件
-
-- 现有的 ObjectStack 工作区或插件包。
-- 依赖 `@objectstack/objectql` 和 `@objectstack/spec`。
-
-## 1. 驱动接口 (Driver Interface)
-
-所有驱动程序必须实现规范中定义的 `DriverInterface`。
-
-### 重要：ID 兼容性规范
-
-ObjectStack 协议强制要求所有记录必须包含一个类型为 `string` 的 `id` 字段。
-底层数据库可能使用不同的惯例（例如 MongoDB 使用 `_id`，SQL 使用 `int` 类型的 ID）。
-**驱动程序负责将这些转换为标准的字符串 `id`。**
-
-- **输入**: 当 `update` 或 `delete` 方法接收 `id` 参数时，将其视为唯一主键。
-- **输出**: 当 `find`、`create` 或 `update` 返回记录时，确保：
- - 必须包含 `id` 字段（字符串）。
- - 应移除或映射实现特定的 ID（如 `_id`）。
-
-```typescript
-import { DriverInterface, DriverOptions } from '@objectstack/spec';
-import { QueryAST, QueryResult } from '@objectstack/objectql';
-
-export class MyCustomDriver implements DriverInterface {
- name = 'MyCustomDriver';
-
- async connect() {
- // 初始化连接
- }
-
- async disconnect() {
- // 关闭连接
- }
-
- // ... CRUD 方法
-}
-```
-
-## 2. 实现 CRUD 操作
-
-您需要实现 `find`（查询）、`insert`（插入）、`update`（更新）和 `delete`（删除）方法。
-
-### Find (查询)
-
-`find` 方法接收一个 `QueryAST` 对象，其中包含结构化的查询信息（过滤、排序、分页）。
-
-```typescript
-async find(object: string, query: QueryAST, options?: DriverOptions): Promise