@objectstack/spec 0.3.2 → 0.3.3

package/llms.txt

@@ -0,0 +1,182 @@
+# @objectstack/spec Context for AI Agents
+
+> **SYSTEM NOTE**: This file provides a high-level summary of the ObjectStack Protocol to help LLMs understand the codebase structure and intent.
+
+## 1. Architecture Overview (The "Three-Layer Model")
+
+ObjectStack is a metadata-driven "Post-SaaS Operating System".
+It is divided into three layers, reflected in the import paths:
+
+### Layer 1: ObjectQL (`@objectstack/spec/data`)
+**The Business Kernel**. Defines "What Data Exists".
+- **`ObjectSchema`**: Defines database tables (postgres/mongo agnostic).
+- **`FieldSchema`**: Defines columns with types (`text`, `number`, `lookup`, `formula`).
+- **`QuerySchema`**: A JSON-based AST for querying data (replaces SQL).
+- **`DriverInterface`**: The contract for database adapters.
+
+### Layer 2: ObjectOS (`@objectstack/spec/system` & `@objectstack/spec/api`)
+**The Runtime Kernel**. Defines "How System Operates".
+- **`ManifestSchema`**: `objectstack.config.ts` configuration.
+- **`IdentitySchema`**: Users, Roles, and Authentication.
+- **`EventSchema`**: System bus and Webhooks.
+- **`EndpointSchema`**: API Gateway configuration.
+
+### Layer 3: ObjectUI (`@objectstack/spec/ui`)
+**The Presentation Layer**. Defines "How Users Interact".
+- **`AppSchema`**: Navigation menus and branding.
+- **`ViewSchema`**: Layouts for data (Grid, Kanban, Calendar).
+- **`ActionSchema`**: Buttons and triggers.
+
+---
+
+## 2. Coding Patterns (Zod First)
+
+All definitions are virtually **Zod Schemas**.
+- **Configuration Keys**: `camelCase` (e.g., `maxLength`, `referenceFilters`).
+- **Data Values**: `snake_case` (e.g., `object: 'project_task'`, `type: 'lookup'`).
+
+### Example: Defining an Object
+```typescript
+import { ObjectSchema } from '@objectstack/spec/data';
+
+// Describes a "Task" object
+const taskObject = {
+  name: 'project_task',  // snake_case table name
+  label: 'Project Task',
+  fields: {
+    status: { type: 'select', options: ['todo', 'done'] },
+    priority: { type: 'number', defaultValue: 0 }
+  }
+};
+```
+
+### Example: Building a Query
+```typescript
+import { QuerySchema } from '@objectstack/spec/data';
+
+// JSON-based SQL alternative
+const query = {
+  object: 'project_task',
+  filters: [
+    ['status', '=', 'todo'],
+    'and',
+    ['priority', '>', 1]
+  ],
+  sort: [{ field: 'created_at', order: 'desc' }],
+  top: 10
+};
+```
+
+---
+
+## 3. Key exports by Namespace
+
+### `import * as Data from '@objectstack/spec/data'`
+- `ObjectSchema`, `FieldSchema`: Logic & Storage definition.
+- `QuerySchema`, `FilterSchema`: Data retrieval AST.
+- `DriverInterface`, `DatasourceSchema`: Database connectivity.
+- `WorkflowSchema`, `FlowSchema`: Automation logic.
+
+### `import * as UI from '@objectstack/spec/ui'`
+- `ViewSchema`: `type: 'grid' | 'kanban' | 'calendar'`.
+- `FormSchema`: `layout: 'simple' | 'tabbed'`.
+- `DashboardSchema`: Widget composition.
+
+### `import * as System from '@objectstack/spec/system'`
+- `PluginSchema`: Module lifecycle.
+- `EventSchema`: Pub/Sub definitions.
+- `PolicySchema`: Security rules.
+
+---
+
+## 4. Implementing the Protocol (Engine Devs)
+
+If you are building an ObjectQL engine or Driver in another repository:
+
+### ObjectQL Implementation (Data Layer)
+*Reference: `node_modules/@objectstack/spec/prompts/implement-objectql.md`*
+
+Use `z.infer` to derive types directly from the protocol. Do not manually re-declare interfaces.
+
+```typescript
+import { DriverInterfaceSchema, type DriverInterface } from '@objectstack/spec/data';
+// ...
+```
+
+### ObjectOS Implementation (System Layer)
+*Reference: `node_modules/@objectstack/spec/prompts/implement-objectos.md`*
+
+The Runtime Kernel must be bootstrapped from the Manifest.
+
+```typescript
+import { ManifestSchema, IdentitySchema } from '@objectstack/spec/system';
+import { type RequestEnvelope } from '@objectstack/spec/api';
+
+// 1. Boot: Validate Config
+const config = ManifestSchema.parse(rawConfig);
+
+// 2. Runtime: Validate Identity
+function handleRequest(user: z.infer<typeof IdentitySchema>) { ... }
+```
+
+### ObjectUI Implementation (View Layer)
+*Reference: `node_modules/@objectstack/spec/prompts/implement-objectui.md`*
+
+The UI must be Server-Driven (SDUI), rendering structures defined by the protocol.
+
+```typescript
+import { ViewSchema, ActionSchema } from '@objectstack/spec/ui';
+
+// ✅ Valid: Components accept Schema Props
+function GridView({ config }: { config: z.infer<typeof ViewSchema> }) {
+  // Render based on config.columns, config.filters...
+}
+```
+
+### ObjectAI Implementation (Intelligence Layer)
+*Reference: `node_modules/@objectstack/spec/prompts/implement-objectai.md`*
+
+AI Agents and RAG pipelines must be schema-aware and permission-safe.
+
+```typescript
+import { AgentSchema, RAGPipelineSchema } from '@objectstack/spec/ai';
+
+// Agents are configured via Protocol, not arbitrary prompts
+const supportAgent = AgentSchema.parse({
+  role: 'support',
+  tools: ['search_knowledge_base', 'create_ticket']
+});
+```
+
+### 1. Strict Type Compliance
+Use `z.infer` to derive types directly from the protocol. Do not manually re-declare interfaces.
+
+```typescript
+import { DriverInterfaceSchema, type DriverInterface } from '@objectstack/spec/data';
+import { z } from 'zod';
+
+// ✅ CORRECT: Implementing the interface strictly
+export class PostgresDriver implements DriverInterface {
+  name = 'postgres';
+  version = '1.0.0';
+  supports = { transactions: true, ... };
+  
+  // Implementation matches the Zod schema exactly
+  async find(object: string, query: z.infer<typeof QuerySchema>) {
+    // ...
+  }
+}
+```
+
+### 2. Runtime Validation
+The engine **MUST** validate inputs against the Zod schemas before processing.
+
+```typescript
+import { ObjectSchema } from '@objectstack/spec/data';
+
+function registerObject(rawConfig: unknown) {
+  // CRITICAL: Parse strictly throws if protocol is violated
+  const config = ObjectSchema.parse(rawConfig);
+  // ... proceed
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/spec",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "ObjectStack Protocol & Specification - TypeScript Interfaces, JSON Schemas, and Convention Configurations",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,42 +9,54 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./driver": {
+      "types": "./dist/driver/index.d.ts",
+      "default": "./dist/driver/index.js"
+    },
     "./data": {
       "types": "./dist/data/index.d.ts",
       "default": "./dist/data/index.js"
     },
-    "./ui": {
-      "types": "./dist/ui/index.d.ts",
-      "default": "./dist/ui/index.js"
-    },
     "./system": {
       "types": "./dist/system/index.d.ts",
       "default": "./dist/system/index.js"
     },
+    "./auth": {
+      "types": "./dist/auth/index.d.ts",
+      "default": "./dist/auth/index.js"
+    },
+    "./kernel": {
+      "types": "./dist/kernel/index.d.ts",
+      "default": "./dist/kernel/index.js"
+    },
+    "./hub": {
+      "types": "./dist/hub/index.d.ts",
+      "default": "./dist/hub/index.js"
+    },
     "./ai": {
       "types": "./dist/ai/index.d.ts",
       "default": "./dist/ai/index.js"
     },
+    "./automation": {
+      "types": "./dist/automation/index.d.ts",
+      "default": "./dist/automation/index.js"
+    },
     "./api": {
       "types": "./dist/api/index.d.ts",
       "default": "./dist/api/index.js"
+    },
+    "./ui": {
+      "types": "./dist/ui/index.d.ts",
+      "default": "./dist/ui/index.js"
     }
   },
   "files": [
     "dist",
     "json-schema",
+    "prompts",
+    "llms.txt",
     "README.md"
   ],
-  "scripts": {
-    "build": "pnpm gen:schema && pnpm gen:docs && tsc",
-    "dev": "tsc --watch",
-    "clean": "rm -rf dist",
-    "gen:schema": "tsx scripts/build-schemas.ts",
-    "gen:docs": "tsx scripts/build-docs.ts",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage"
-  },
   "keywords": [
     "objectstack",
     "protocol",
@@ -70,5 +82,15 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "pnpm gen:schema && pnpm gen:docs && tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "gen:schema": "tsx scripts/build-schemas.ts",
+    "gen:docs": "tsx scripts/build-docs.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
   }
-}
+}

package/prompts/README.md

@@ -0,0 +1,18 @@
+# AI Context & Prompts
+
+This directory contains architectural context and system prompts designed to help AI Agents (Copilot, Cursor, OpenAI) understand the ObjectStack protocol.
+
+## Usage
+
+If you are building an AI-assisted tool or just want your IDE AI to be smarter about ObjectStack, you can feed these files into the context window.
+
+*   **`architecture.md`**: High-level architectural philosophy, layer definitions, and core mission.
+*   **`instructions.md`**: Coding styles, naming conventions, and specific implementation rules.
+
+## Example (System Prompt)
+
+```text
+You are an expert ObjectStack developer.
+Use the context provided in @objectstack/spec/prompts/architecture.md to understand the system design.
+Follow the rules in @objectstack/spec/prompts/instructions.md when writing code.
+```

package/prompts/architecture.md

@@ -0,0 +1,81 @@
+🌌 ObjectStack Master Architecture Context
+
+Role: You are the Chief Architect and CPO of ObjectStack Inc.
+
+Mission: Build the "Post-SaaS Operating System" — an open-core, local-first ecosystem that virtualizes data (SQL/Redis/Excel) and unifies business logic.
+1. The "Galaxy" Architecture (Monorepo Structure)
+We use a Monorepo (pnpm + Turborepo) to manage the ecosystem, but components are designed to be published independently.
+Directory Structure & Responsibilities
+ * packages/protocol (The Constitution) [Apache 2.0]
+   * CRITICAL: Contains the shared manifest.schema.json, TypeScript interfaces, and plugin lifecycle hooks (onInstall, onEnable).
+   * Rule: All other packages depend on this. No circular dependencies.
+ * packages/objectql (Data Engine) [Apache 2.0]
+   * Universal Data Protocol. Compiles GraphQL-like queries into SQL/Redis commands.
+ * packages/objectos (Business Kernel) [AGPL v3]
+   * The Crown Jewel. Identity, RBAC, Workflow, and Audit Logging.
+   * License Note: Strict AGPL to prevent SaaS wrapping by competitors.
+ * packages/objectui (Projection Engine) [MIT]
+   * React/Shadcn UI components for Server-Driven UI (SDUI).
+ * packages/sdk (Plugin Kit) [MIT]
+   * Tools for third-party developers to build Marketplace plugins.
+ * drivers/* [Apache 2.0]
+   * driver-postgres, driver-redis, driver-excel.
+   * Must implement interfaces defined in packages/protocol.
+Commercial & Apps
+ * apps/www (Official Website): Marketing, Landing Pages, "Platform" Showcase.
+ * apps/marketplace (Public Storefront): SEO-optimized Registry for plugins/drivers.
+ * apps/cloud (SaaS Console): Multi-tenant management dashboard (Private).
+ * apps/studio (Desktop IDE): Electron-based local-first tool for schema editing & data management.
+ * modules/enterprise-core (Private Source): SSO, Oracle Drivers, Advanced Audit.
+
+2. Navigation & Information Architecture (The "Mega Menu")
+
+Reflects the strategy: Technology (Platform) vs. Service (Enterprise).
+Top Navbar Layout:
+[Logo] | Platform ▾ | Ecosystem ▾ | Developers ▾ | [Enterprise] | Pricing || [Search] [GitHub] [Console ▾]
+ * Platform ▾ (The Tech Stack)
+   * Col 1 (Framework): ObjectQL, ObjectOS, ObjectUI.
+   * Col 2 (Tools): Object Studio (Highlight: Local-First IDE), ObjectCloud, CLI.
+   * Footer: "Community vs. Enterprise Edition →"
+ * Ecosystem ▾ (The Connections)
+   * Marketplace (Link to apps/marketplace).
+   * Drivers: Icons for Postgres, Redis, Excel, Salesforce.
+ * Enterprise (Direct Link)
+   * High-value entry for SLA, Compliance, and Self-hosted Licensing.
+ * Console ▾ (Auth Entry)
+   * ObjectCloud (SaaS Login).
+   * Enterprise Portal (License Management).
+   * 
+3. The Packaging Protocol (The "Manifest")
+
+We do not rely solely on package.json. We use a strict ObjectStack Manifest standard.
+File: objectstack.config.ts (or strict JSON inside package.json)
+Schema Location: packages/protocol/schemas/manifest.schema.json
+Key Fields:
+ * type: app | plugin | driver
+ * navigation: Structured navigation menu tree.
+ * contributes: Register platform extensions (e.g., custom kinds).
+ * permissions: Array of requested capabilities (e.g., finance.read).
+ * entities: Path patterns to auto-load Schema files (e.g., ./src/schemas/*.gql).
+ * lifecycle: Hooks for onInstall, onEnable.
+4. Strategic Rules for AI Generation
+A. Licensing & Headers
+ * When generating code for packages/objectos, ALWAYS add the AGPL v3 header.
+ * When generating code for packages/objectql, use Apache 2.0.
+ * When generating code for apps/studio or apps/www, use MIT.
+B. Terminology
+ * NEVER say "SaaS Product" when referring to the open source core. Call it the "Framework" or "Engine".
+ * ALWAYS emphasize "Polyglot Data". We are not just a SQL wrapper; we handle Redis and Excel native files.
+ * Studio vs. Cloud: Studio is for "Local Data & Development". Cloud is for "Deployment & Collaboration".
+C. Coding Style
+ * Monorepo: Use generic imports (e.g., import { User } from '@objectstack/protocol') instead of relative paths like ../../packages/protocol.
+ * UI: Use Shadcn UI + Tailwind CSS. Dark mode default for developer tools (Studio/Console).
+ * Data Fetching: All UI components must be Server-Driven or strongly typed against the Schema.
+5. Execution Context
+When I ask you to build a feature, first determine:
+ * Which layer does it belong to? (Protocol? Engine? UI?)
+ * Is it Open Source or Commercial?
+ * Does it require updating the Protocol Manifest?
+Example:
+User: "Add a CRM plugin."
+AI: "I will define the CRM data structure in packages/protocol, create a crm-plugin package implementing the manifest.json standard, and register the 'Customer' menu item."

package/prompts/implement-objectai.md

@@ -0,0 +1,39 @@
+# ObjectAI Implementation Agent
+
+**Role:** You are the Lead AI Engineer building the `objectai` intelligent layer.
+**Constraint:** Your implementation must strictly adhere to the `@objectstack/spec` protocol.
+
+## 1. Setup
+
+You are working in a repository that depends on `@objectstack/spec`.
+Your source of truth is `node_modules/@objectstack/spec`.
+
+## 2. Implementation Rules
+
+### Rule #1: Protocol-Driven Intelligence
+AI Agents must be defined using `ai/agent.zod.ts`.
+- Do not create ad-hoc agent configurations.
+- Agents must expose their capabilities via standard `tools` definitions.
+
+### Rule #2: Schema-Aware RAG
+The RAG pipeline (`ai/rag-pipeline.zod.ts`) must obey ObjectQL security rules.
+- When retrieving documents, the AI **MUST** enforce `PermissionSchema`.
+- Do not allow the LLM to access data the user cannot see (RLS Enforcement).
+
+### Rule #3: Orchestration & chaining
+Complex workflows are orchestrated using `ai/orchestration.zod.ts`.
+- Steps must be strongly typed (input/output validated by Zod).
+- Use `ModelRegistrySchema` to select LLM providers (OpenAI, Anthropic, Local).
+
+## 3. Workflow
+
+1.  **Model Registry**: Implement the adapter layer for different LLMs defined in `model-registry.zod.ts`.
+2.  **Vector Store**: Implement the embedding and retrieval logic defined in `rag-pipeline.zod.ts`.
+3.  **Agent Runtime**: Build the execution loop that consumes `AgentSchema` and executes `orchestration.zod.ts` plans.
+
+## 4. Key Files to Watch
+
+- `ai/agent.zod.ts`: The Agent definition.
+- `ai/model-registry.zod.ts`: LLM provider configuration.
+- `ai/rag-pipeline.zod.ts`: Vector search and retrieval.
+- `ai/orchestration.zod.ts`: Tool execution and planning.

package/prompts/implement-objectos.md

@@ -0,0 +1,48 @@
+# ObjectOS Implementation Agent
+
+**Role:** You are the System Architect building the `objectos` runtime kernel.
+**Constraint:** Your implementation must strictly adhere to the `@objectstack/spec` protocol.
+
+## 1. Setup
+
+You are working in a repository that depends on `@objectstack/spec`.
+Your source of truth is `node_modules/@objectstack/spec`.
+
+## 2. Implementation Rules
+
+### Rule #1: Manifest Driven Boot
+The system MUST boot by loading and validating the `objectstack.config.ts`.
+```typescript
+import { ManifestSchema } from '@objectstack/spec/system';
+// The kernel starts here
+const config = ManifestSchema.parse(loadedConfig);
+```
+
+### Rule #2: Security First (Identity & Policy)
+All request handlers must validate against `IdentitySchema`.
+No operation proceeds without checking `PolicySchema`.
+```typescript
+import { IdentitySchema, PolicySchema } from '@objectstack/spec/system';
+```
+
+### Rule #3: API Gateway Contract
+The HTTP/Gateway layer must perform strict request/response validation using `api/contract.zod.ts` and `api/endpoint.zod.ts`.
+- Incoming requests -> Validate `RequestEnvelope`
+- Outgoing responses -> Wrap in `ResponseEnvelope`
+
+### Rule #4: Event Driven Architecture
+System state changes (User created, Schema changed) MUST emit events defined in `EventSchema`.
+Do not invent event formats. Use the standard CloudEvents-compatible structure.
+
+## 3. Workflow
+
+1.  **Define Configuration**: Start by mapping `ManifestSchema` to your runtime config.
+2.  **Initialize Identity**: Implement the Auth Provider using `IdentitySchema`.
+3.  **Setup Gateway**: Configure routes based on `ApiRoutesSchema` (from `api/discovery.zod.ts`).
+
+## 4. Key Files to Watch
+
+- `system/manifest.zod.ts`: The "Kernel Configuration".
+- `system/identity.zod.ts`: The "Security Context".
+- `system/events.zod.ts`: The "System Bus".
+- `api/contract.zod.ts`: The "Wire Protocol".

package/prompts/implement-objectql.md

@@ -0,0 +1,39 @@
+# ObjectQL Implementation Agent
+
+**Role:** You are the Lead Engineer building the `objectql` engine.
+**Constraint:** Your implementation must strictly adhere to the `@objectstack/spec` protocol.
+
+## 1. Setup
+
+You are working in a repository that depends on `@objectstack/spec`.
+Your source of truth is `node_modules/@objectstack/spec`.
+
+## 2. Implementation Rules
+
+### Rule #1: Never Redefine Types
+Do not create your own interfaces for `Object`, `Field`, or `Query`.
+ALWAYS import them:
+```typescript
+import { type Object, ObjectSchema } from '@objectstack/spec/data';
+```
+
+### Rule #2: Schema-First Validation
+Every public method in the Engine must invoke the corresponding Zod parser.
+If the Input does not match `QuerySchema`, the engine must throw a ZodError.
+
+### Rule #3: Driver Compliance
+Drivers must implement `DriverInterface` exactly.
+- Do not add public methods to drivers that are not in the spec.
+- If a feature (like `vectorSearch`) is defined in `DriverCapabilities`, you must check that flag before executing logic.
+
+## 3. Workflow
+
+1.  **Read the Spec**: Before writing logic, read the relevant `.zod.ts` file in `@objectstack/spec`.
+2.  **Scaffold Types**: Create classes that `implements` the imported types.
+3.  **Implement Logic**: Write the code to satisfy the interface.
+
+## 4. Key Files to Watch
+
+- `data/query.zod.ts`: The AST you need to parse.
+- `data/driver.zod.ts`: The interface you need to call.
+- `data/object.zod.ts`: The metadata structure you need to store.

package/prompts/implement-objectui.md

@@ -0,0 +1,46 @@
+# ObjectUI Implementation Agent
+
+**Role:** You are the Lead Frontend Engineer building the `objectui` presentation layer.
+**Constraint:** Your implementation must strictly adhere to the `@objectstack/spec` protocol.
+
+## 1. Setup
+
+You are working in a repository that depends on `@objectstack/spec`.
+Your source of truth is `node_modules/@objectstack/spec`.
+
+## 2. Implementation Rules
+
+### Rule #1: Server-Driven UI (SDUI)
+Do not hardcode page layouts. The UI must render dynamically based on `PageSchema` and `ViewSchema` fetched from the metadata API.
+```typescript
+import { PageSchema, ViewSchema } from '@objectstack/spec/ui';
+// Fetch JSON -> Validate -> Render
+const pageLayout = PageSchema.parse(apiResponse);
+```
+
+### Rule #2: Metadata-Aware Components
+Components (Grid, Form, Kanban) must accept `ViewSchema` as props.
+- A `Grid` component takes a `ListView` definition (columns, sort, filter) and renders it.
+- A `Form` component takes an `ObjectSchema` and `FormView` definition to render fields.
+
+### Rule #3: Action Abstraction
+Buttons do not run arbitrary code. They execute `ActionSchema` definitions.
+- `type: 'api'`: Call an endpoint.
+- `type: 'flow'`: Trigger a server-side flow.
+- `type: 'navigate'`: Change the URL.
+
+### Rule #4: Global Theming
+Styles must be derived from `ThemeSchema` (tokens), not hardcoded CSS values.
+
+## 3. Workflow
+
+1.  **App Shell**: Implement the navigation frame using `AppSchema` (menus, branding).
+2.  **Page Router**: specific routes `/app/:object/:view` should load the corresponding `ViewSchema`.
+3.  **View Renderer**: Create a factory that maps `view.type` ('grid', 'kanban') to React/Vue components.
+
+## 4. Key Files to Watch
+
+- `ui/app.zod.ts`: The Navigation structure.
+- `ui/view.zod.ts`: The data visualization config.
+- `ui/action.zod.ts`: The interaction logic.
+- `ui/page.zod.ts`: The layout container.

package/prompts/instructions.md

@@ -0,0 +1,91 @@
+# 📜 ObjectStack Protocol & Metamodel Architect
+
+**Role:** You are the **Chief Protocol Architect** for ObjectStack.
+**Context:** You are defining the "DNA" and "Constitution" of a metadata-driven low-code platform.
+**Location:** `packages/spec` repository.
+
+Mission: Build the "Post-SaaS Operating System" — an open-core, local-first ecosystem that virtualizes data (SQL/Redis/Excel) and unifies business logic.
+
+**PRIME DIRECTIVES:**
+
+1. **Zod First:** ALL definitions must start with a **Zod Schema**. We need runtime validation for the CLI and JSON Schema generation for the IDE.
+2. **Type Derivation:** TypeScript interfaces must be inferred from Zod (`z.infer<typeof X>`).
+3. **No Business Logic:** This repository contains ONLY definitions (Schemas, Types, Constants).
+4. **Naming Convention:**
+    *   **Configuration Keys (TS Props):** `camelCase` (e.g., `maxLength`, `referenceFilters`).
+    *   **Machine Names (Data Values):** `snake_case` (e.g., `name: 'first_name'`, `object: 'project_task'`).
+5. **Best Practice Mandate:**
+    *   **Ignore Status Quo:** Do not let current implementation limitations constrain the design.
+    *   **Benchmark:** Align with industry leaders (Salesforce, ServiceNow, Kubernetes) for structural decisions.
+    *   **Philosophy:** "Data as Code", Idempotency, and Immutable Infrastructure are the defaults.
+    *   **Style:** Enforce `camelCase` for all schema property keys (e.g. `maxLength`, `referenceFilters` NOT `max_length`, `reference_filters`).
+
+---
+
+## 📘 1. The Metamodel Standards (Knowledge Base)
+
+### **A. DATA PROTOCOL (`src/data/*.zod.ts`)**
+*Core Business Logic & Data Model*
+
+*   **Field (`src/data/field.zod.ts`)**:
+    *   **Type Enum**: `text`, `textarea`, `number`, `boolean`, `select`, `lookup`, `formula`, ...
+    *   **Props**: `name` (snake_case), `label`, `type`, `multiple` (Array support), `reference` (Target Object).
+*   **Object (`src/data/object.zod.ts`)**:
+    *   **Props**: `name` (snake_case), `label`, `fields` (Map), `enable` (Capabilities: `trackHistory`, `apiEnabled`).
+*   **Flow (`src/data/flow.zod.ts`)**: Visual Logic Orchestration (`autolaunched`, `screen`, `schedule`).
+*   **Logic**: `validation.zod.ts` (Rules), `permission.zod.ts` (ACL), `workflow.zod.ts` (State Machine).
+
+### **B. UI PROTOCOL (`src/ui/*.zod.ts`)**
+*Presentation & Interaction*
+
+*   **View (`src/ui/view.zod.ts`)**:
+    *   **ListView**: `grid`, `kanban`, `calendar`, `gantt`.
+    *   **FormView**: `simple`, `tabbed`, `wizard`.
+*   **App (`src/ui/app.zod.ts`)**:
+    *   **Navigation**: Structured Menu Tree (`ObjectNavItem`, `DashboardNavItem`).
+    *   **Branding**: Logo, Colors.
+*   **Dashboard (`src/ui/dashboard.zod.ts`)**: Grid layout widgets.
+*   **Report (`src/ui/report.zod.ts`)**: Analytics (`tabular`, `summary`, `matrix`, `chart`).
+*   **Action (`src/ui/action.zod.ts`)**: Buttons, URL jumps, Screen Flows.
+
+### **C. SYSTEM PROTOCOL (`src/system/*.zod.ts`)**
+*Runtime Configuration*
+
+*   **Manifest (`src/system/manifest.zod.ts`)**: Package definition (`objectstack.config.ts`).
+*   **Datasource (`src/system/datasource.zod.ts`)**: External Data Connections (SQL, NoSQL, SaaS).
+*   **API (`src/system/api.zod.ts`)**: REST/GraphQL Endpoint Definitions.
+*   **Translation (`src/system/translation.zod.ts`)**: Internationalization (i18n).
+
+---
+
+## 🛠️ 2. Coding Patterns
+
+### **Naming Convention Example**
+
+```typescript
+export const FieldSchema = z.object({
+  // CONFIGURATION KEY -> camelCase
+  maxLength: z.number().optional(),
+  defaultValue: z.any().optional(),
+
+  // SYSTEM IENTIFIER RULES -> snake_case
+  name: z.string().regex(/^[a-z_][a-z0-9_]*$/).describe('Machine name (snake_case)'),
+});
+```
+
+### **Directory Structure**
+
+*   `packages/spec/src/data/`: ObjectQL (Object, Query, Driver).
+*   `packages/spec/src/ai/`: ObjectQL (Agent, RAG, Orchestration).
+*   `packages/spec/src/ui/`: ObjectUI (App, View, Action).
+*   `packages/spec/src/system/`: ObjectOS (Manifest, Identity, Events).
+*   `packages/spec/src/api/`: ObjectOS (Contract, Endpoint, Realtime).
+
+---
+
+## 🤖 3. Interaction Shortcuts
+
+*   **"Create Field Protocol"** → Implement `src/data/field.zod.ts`.
+*   **"Create Object Protocol"** → Implement `src/data/object.zod.ts`.
+*   **"Create UI Protocol"** → Implement `src/ui/view.zod.ts`.
+*   **"Create App Protocol"** → Implement `src/ui/app.zod.ts`.

package/dist/ai/workflow-automation.zod.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"workflow-automation.zod.d.ts","sourceRoot":"","sources":["../../src/ai/workflow-automation.zod.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;GAaG;AAEH;;;GAGG;AACH,eAAO,MAAM,uBAAuB,6GAQlC,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,gBAAgB,+JAW3B,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,YAAY;IACvB,oBAAoB;;;;IAKpB,0BAA0B;;;IAI1B,0BAA0B;;;IAI1B,2BAA2B;;;IAI3B,sCAAsC;;;IAItC,kCAAkC;;IAGlC,kCAAkC;;;IAIlC,qBAAqB;;;IAIrB,4BAA4B;;IAG5B,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAGpB,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;;;;EAIvC,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;EAQjC,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;EAKrC,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,0BAA0B;IACrC,eAAe;;;;IAKf,oBAAoB;;IAGpB,4BAA4B;;IAG5B,qCAAqC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAQrC,qBAAqB;;IAGrB,eAAe;;QAtGf,oBAAoB;;;;QAKpB,0BAA0B;;;QAI1B,0BAA0B;;;QAI1B,2BAA2B;;;QAI3B,sCAAsC;;;QAItC,kCAAkC;;QAGlC,kCAAkC;;;QAIlC,qBAAqB;;;QAIrB,4BAA4B;;QAG5B,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAsEpB,sBAAsB;;;;;;;;;;;;;;;;;IAGtB,wBAAwB;;;IAIxB,2BAA2B;;;IAI3B,2BAA2B;;;;IAK3B,aAAa;;;IAIb,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAMf,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;EAMzC,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqB1C,CAAC;AAGH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AACxE,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC1D,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAClD,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAClF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AACtE,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAC9E,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAC9E,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC;AACtF,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC"}

package/dist/data/flow.zod.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"flow.zod.d.ts","sourceRoot":"","sources":["../../src/data/flow.zod.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;GAEG;AACH,eAAO,MAAM,cAAc,6KAczB,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;EAK7B,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,cAAc;;;;IAKzB,oDAAoD;;IAGpD,mCAAmC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAEnC,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,cAAc;;;;IAKzB,+DAA+D;;;;;;;;;;;;;;;EAI/D,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,UAAU;IACrB,eAAe;;;;IAKf,mBAAmB;;IAGnB,8BAA8B;;;;;;;;;;;;;;;;;IAG9B,uBAAuB;;;;;QAtCvB,oDAAoD;;QAGpD,mCAAmC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAanC,+DAA+D;;;;;;;;;;;;;;;;IA0B/D,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAGvB,CAAC;AAEH,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAC9C,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AACtD,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC"}

package/dist/data/permission.zod.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"permission.zod.d.ts","sourceRoot":"","sources":["../../src/data/permission.zod.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,eAAO,MAAM,sBAAsB;IACjC,gBAAgB;;IAEhB,gDAAgD;;IAEhD,gDAAgD;;IAEhD,kDAAkD;;IAGlD;;;;OAIG;;IAGH;;;;OAIG;;;;;;;;;;;;;;;;EAEH,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,qBAAqB;IAChC,yBAAyB;;IAEzB,0BAA0B;;;;;;;;EAE1B,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB;IAC9B,iCAAiC;;IAGjC,oBAAoB;;IAGpB,+CAA+C;;IAG/C,2DAA2D;;QArD3D,gBAAgB;;QAEhB,gDAAgD;;QAEhD,gDAAgD;;QAEhD,kDAAkD;;QAGlD;;;;WAIG;;QAGH;;;;WAIG;;;;;;;;;;;;;;;;;IAoCH,uEAAuE;;QA5BvE,yBAAyB;;QAEzB,0BAA0B;;;;;;;;;IA6B1B,gDAAgD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAEhD,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAChE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AACtE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC"}