Merge branch 'main' of https://github.com/objectstack-ai/spec

Author: hotlong

content/docs/guides/index.mdx

@@ -37,9 +37,14 @@ The `@objectstack/cli` provides a complete development workflow:
 
 ## Documentation Structure
 
-- **[Example Apps](./examples)**: Run the built-in Todo, CRM, and BI examples to learn hands-on.
-- **[CLI](./cli)**: Command-line interface usage guide with all 11 commands.
-- **[Core (Microkernel)](./core)**: Architecture, plugins, services, and events.
-- **[Packages](./packages)**: Detailed reference of all packages in the monorepo.
+- **[Metadata Types](./metadata)**: Comprehensive guide to every metadata type used in application development — Object, Field, View, Page, App, Dashboard, Flow, Workflow, Validation, and Permission.
+- **[Data Modeling](./data-modeling)**: Best practices for designing robust data models.
+- **[Business Logic](./business-logic)**: Automation, workflows, and custom logic.
+- **[Plugins](./plugins)**: Building and extending the platform with plugins.
+- **[Authentication](./authentication)**: Authentication and identity management.
+- **[Security](./security)**: Access control, permissions, and row-level security.
+- **[AI Capabilities](./ai-capabilities)**: AI agents, RAG pipelines, and model integration.
+- **[API Reference](./api-reference)**: REST, GraphQL, and WebSocket APIs.
 - **[Client SDK](./client-sdk)**: TypeScript client and React hooks documentation.
 - **[Driver Configuration](./driver-configuration)**: Database driver setup and configuration.
+- **[Kernel Services](./kernel-services)**: Core microkernel architecture and services.

content/docs/guides/meta.json

@@ -1,4 +1,4 @@
 {
   "title": "Guides",
-  "pages": ["index", "data-modeling", "plugins", "business-logic", "authentication", "security", "ai-capabilities", "api-reference", "client-sdk", "driver-configuration", "kernel-services", "standards"]
+  "pages": ["index", "metadata", "data-modeling", "plugins", "business-logic", "authentication", "security", "ai-capabilities", "api-reference", "client-sdk", "driver-configuration", "kernel-services", "standards"]
 }

content/docs/guides/metadata/app.mdx

@@ -0,0 +1,213 @@
+---
+title: App Metadata
+description: Define application containers with navigation, branding, and access control
+---
+
+# App Metadata
+
+An **App** is a logical container that bundles objects, views, pages, and dashboards into a cohesive application experience. It defines the navigation structure, branding, and access permissions.
+
+## Basic Structure
+
+```typescript
+const crmApp = {
+  name: 'crm',
+  label: 'CRM',
+  version: '1.0.0',
+  description: 'Customer Relationship Management',
+  icon: 'briefcase',
+  active: true,
+
+  branding: {
+    primaryColor: '#1a73e8',
+    logo: '/assets/crm-logo.svg',
+    favicon: '/assets/favicon.ico',
+  },
+
+  navigation: [
+    { type: 'object', label: 'Accounts', objectName: 'account', icon: 'building' },
+    { type: 'object', label: 'Contacts', objectName: 'contact', icon: 'users' },
+    { type: 'object', label: 'Opportunities', objectName: 'opportunity', icon: 'trending-up' },
+    { type: 'dashboard', label: 'Sales Dashboard', dashboardName: 'sales_overview', icon: 'bar-chart' },
+  ],
+
+  requiredPermissions: ['crm_access'],
+};
+```
+
+## App Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| `name` | `string` | ✅ | Machine name (`snake_case`) |
+| `label` | `string` | ✅ | Display name |
+| `version` | `string` | optional | App version |
+| `description` | `string` | optional | App description |
+| `icon` | `string` | optional | App icon (Lucide/Material) |
+| `active` | `boolean` | optional | Is app active (default: `true`) |
+| `isDefault` | `boolean` | optional | Is default app |
+| `navigation` | `NavigationItem[]` | ✅ | Navigation tree |
+| `branding` | `AppBranding` | optional | Visual customization |
+| `requiredPermissions` | `string[]` | optional | Required permissions to access |
+| `homePageId` | `string` | optional | Custom home page ID |
+| `objects` | `string[]` | optional | Objects included in this app |
+| `apis` | `string[]` | optional | API endpoints included |
+| `mobileNavigation` | `object` | optional | Mobile-specific navigation |
+
+## Navigation Items
+
+The navigation tree supports five item types, combined to create rich menu structures:
+
+### Object Navigation
+
+Links to an object's list view:
+
+```typescript
+{ type: 'object', label: 'Accounts', objectName: 'account', icon: 'building', viewName: 'all_accounts' }
+```
+
+### Dashboard Navigation
+
+Links to a dashboard:
+
+```typescript
+{ type: 'dashboard', label: 'Analytics', dashboardName: 'sales_overview', icon: 'bar-chart' }
+```
+
+### Page Navigation
+
+Links to a custom page:
+
+```typescript
+{ type: 'page', label: 'Settings', pageName: 'app_settings', icon: 'settings', params: { tab: 'general' } }
+```
+
+### URL Navigation
+
+Links to an external URL:
+
+```typescript
+{ type: 'url', label: 'Help Center', url: 'https://help.example.com', icon: 'help-circle', target: '_blank' }
+```
+
+### Group Navigation
+
+Groups items into collapsible sections with children:
+
+```typescript
+{
+  type: 'group',
+  label: 'Sales',
+  icon: 'dollar-sign',
+  expanded: true,
+  children: [
+    { type: 'object', label: 'Accounts', objectName: 'account', icon: 'building' },
+    { type: 'object', label: 'Contacts', objectName: 'contact', icon: 'users' },
+    { type: 'object', label: 'Opportunities', objectName: 'opportunity', icon: 'trending-up' },
+  ],
+}
+```
+
+### Common Navigation Properties
+
+All navigation items share these base properties:
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `id` | `string` | Unique identifier |
+| `label` | `string` | Display label |
+| `icon` | `string` | Icon name |
+| `visible` | `boolean \| string` | Visibility (boolean or expression) |
+
+## Branding
+
+Customize the visual appearance of the app:
+
+```typescript
+branding: {
+  primaryColor: '#1a73e8',    // Hex color code
+  logo: '/assets/logo.svg',   // Logo URL
+  favicon: '/assets/icon.ico', // Favicon URL
+}
+```
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `primaryColor` | `string` | Primary brand color (hex) |
+| `logo` | `string` | Logo image URL |
+| `favicon` | `string` | Favicon URL |
+
+## Mobile Navigation
+
+Configure mobile-specific navigation behavior:
+
+```typescript
+mobileNavigation: {
+  mode: 'bottom',
+  bottomNavItems: ['home', 'accounts', 'contacts', 'settings'],
+}
+```
+
+## Complete Example
+
+```typescript
+const projectApp = {
+  name: 'project_management',
+  label: 'Project Management',
+  version: '2.0.0',
+  description: 'Track projects, tasks, and team workload',
+  icon: 'folder-kanban',
+  active: true,
+
+  branding: {
+    primaryColor: '#6366f1',
+    logo: '/assets/pm-logo.svg',
+  },
+
+  navigation: [
+    {
+      type: 'page',
+      label: 'Home',
+      pageName: 'pm_home',
+      icon: 'home',
+    },
+    {
+      type: 'group',
+      label: 'Projects',
+      icon: 'folder',
+      expanded: true,
+      children: [
+        { type: 'object', label: 'Projects', objectName: 'project', icon: 'folder' },
+        { type: 'object', label: 'Tasks', objectName: 'project_task', icon: 'check-square', viewName: 'task_board' },
+        { type: 'object', label: 'Milestones', objectName: 'milestone', icon: 'flag' },
+      ],
+    },
+    {
+      type: 'group',
+      label: 'Reports',
+      icon: 'bar-chart',
+      children: [
+        { type: 'dashboard', label: 'Overview', dashboardName: 'project_overview', icon: 'layout-dashboard' },
+        { type: 'dashboard', label: 'Team Workload', dashboardName: 'team_workload', icon: 'users' },
+      ],
+    },
+    {
+      type: 'url',
+      label: 'Documentation',
+      url: 'https://docs.example.com/pm',
+      icon: 'book-open',
+      target: '_blank',
+    },
+  ],
+
+  requiredPermissions: ['pm_access'],
+  homePageId: 'pm_home',
+};
+```
+
+## Related
+
+- [Page Metadata](./page) — Custom pages referenced from navigation
+- [Dashboard Metadata](./dashboard) — Dashboards referenced from navigation
+- [View Metadata](./view) — Views displayed within navigation items
+- [Permission Metadata](./permission) — Access control for apps