objectstack-ai · os-zhuang · Jul 4, 2026 · Jul 4, 2026
diff --git a/content/docs/api/index.mdx b/content/docs/api/index.mdx
@@ -9,6 +9,16 @@ ObjectStack generates its entire API surface — REST endpoints, realtime protoc
 
 ObjectStack exposes a fully typed REST API. All endpoints use JSON request/response bodies. The API is **service-driven** — routes are only available when the corresponding plugin is installed. Use the [Discovery endpoint](#discovery) to determine what services are available at runtime.
 
+### Surfaces at a glance
+
+| Surface | Status in this repo |
+| :--- | :--- |
+| **REST** | ✅ Auto-generated from the protocol (`@objectstack/rest`) — CRUD, query, batch, metadata, packages |
+| **Realtime** | ✅ WebSocket subscriptions plus SSE streaming (`@objectstack/service-realtime`) |
+| **MCP** | ✅ Objects and opted-in actions exposed as Model Context Protocol tools ([AI module](/docs/ai)) |
+| **GraphQL** | ⚠️ Route is wired but **bring-your-own service**: `/graphql` returns 501 unless an implementation of the `IGraphQLService` contract is registered — none ships in the open framework |
+| **OData** | ⚠️ Vocabulary only: REST list endpoints accept OData-style operators (e.g. `$top`), but there is no standalone OData endpoint |
+
 <Callout type="info">
 **Base URL**: Configurable, defaults to `/api/v1`. All paths below are relative to the base URL.
 </Callout>

diff --git a/content/docs/automation/index.mdx b/content/docs/automation/index.mdx
@@ -1,31 +1,50 @@
 ---
 title: Automation
-description: Hooks, flows, workflows, approvals, and webhooks — the process engine that reacts to data changes and drives business processes.
+description: 18 hook events, 20+ extensible flow node types, scheduled flows, approvals, and durable webhooks — the process engine that reacts to your data.
 ---
 
 # Automation
 
-Automation is ObjectStack's process engine: it lets you attach business logic to your data model **declaratively** — as metadata — instead of scattering it through application code. It is a cross-protocol capability: automations are declared in the Automation Protocol namespace and executed by the ObjectOS runtime against ObjectQL data.
+Automation is ObjectStack's process engine: you attach business logic to the data model **declaratively** — as metadata — instead of scattering it through application code. It is a cross-protocol capability: automations are declared in the Automation Protocol namespace and executed by the ObjectOS runtime against ObjectQL data.
+
+The smallest useful automation is a hook (from the CRM example app):
+
+```typescript
+import type { Hook, HookContext } from '@objectstack/spec/data';
+
+export const OpportunityStageHook: Hook = {
+  name: 'opportunity_stage_probability',
+  object: 'crm_opportunity',
+  events: ['beforeInsert', 'beforeUpdate'],
+  priority: 100,
+  handler: async (ctx: HookContext) => {
+    const input = ctx.input as { stage?: string; probability?: number };
+    if (input.stage === 'closed_won') input.probability = 100;
+    if (input.stage === 'closed_lost') input.probability = 0;
+  },
+};
+```
 
 ## The building blocks
 
-- **Hooks** run custom logic before/after record operations (create, update, delete) — the workhorse for validation-with-side-effects, denormalization, and integrations.
-- **Flows** are node-based visual logic (screen flows, autolaunched flows, scheduled flows).
-- **Workflows** model a record's lifecycle as a **finite state machine**: states, transitions, and guards.
-- **Approvals** add human sign-off steps to a process.
-- **Webhooks** deliver events to external systems over HTTP with retry semantics.
+- **Hooks** intercept **18 lifecycle events** — before/after each of find, findOne, count, aggregate, insert, update, delete, updateMany, deleteMany. Hooks support priority ordering, fire-and-forget `async` mode, CEL `condition` guards, and a `retryPolicy` with backoff ([Hooks](/docs/automation/hooks)).
+- **Flows** are node-based processes with **20 built-in node types** (decision, loop, create/update/delete record, http, notify, script, screen, wait, subflow, parallel/join gateways, …) — and the set is **registry-extensible**: plugins can contribute new node types via `registerNodeExecutor`. Flows launch on record changes, on a schedule, from a screen, or via API ([Flows](/docs/automation/flows)).
+- **Workflows** model a record's lifecycle as a **finite state machine**: states, transitions, and guards ([Workflows](/docs/automation/workflows)).
+- **Approvals** are flow nodes with approver resolution, approve/reject decisions, and escalation ([Approvals](/docs/automation/approvals)).
+- **Webhooks** deliver events to external systems through a **durable outbox** — exponential/linear/fixed retry with dead-lettering, HMAC signing, and an admin redeliver endpoint ([Webhook Delivery](/docs/automation/webhooks)).
+- **Scheduled jobs** run on `setInterval` or cron via the job service, alongside `schedule`-type flows.
 
 Rule of thumb: model *state* with workflows, model *steps* with flows, use hooks for *code-level* reactions, and webhooks to *notify the outside world*.
 
 ## What's in this module
 
 <Cards>
-  <Card href="/docs/automation/hooks" title="Hooks" description="Before/after hooks on record operations" />
+  <Card href="/docs/automation/hooks" title="Hooks" description="18 before/after events on record operations" />
   <Card href="/docs/automation/hook-bodies" title="Hook & Action Bodies (L1/L2)" description="The two authoring levels for hook logic" />
-  <Card href="/docs/automation/flows" title="Flows" description="Flow metadata and node-based automation" />
+  <Card href="/docs/automation/flows" title="Flows" description="Node-based automation, screen flows, scheduled flows" />
   <Card href="/docs/automation/workflows" title="Workflows" description="State-machine lifecycle modeling" />
-  <Card href="/docs/automation/approvals" title="Approvals" description="Approval process recipe" />
-  <Card href="/docs/automation/webhooks" title="Webhook Delivery" description="Outbound event delivery and retries" />
+  <Card href="/docs/automation/approvals" title="Approvals" description="Approval nodes: approvers, decisions, escalation" />
+  <Card href="/docs/automation/webhooks" title="Webhook Delivery" description="Durable outbox, retries, HMAC signing" />
 </Cards>
 
 ## Related

diff --git a/content/docs/data-modeling/field-types.mdx b/content/docs/data-modeling/field-types.mdx
@@ -5,7 +5,7 @@ description: Complete reference for all 48 ObjectStack field types with per-type
 
 # Field Type Gallery
 
-ObjectStack provides **48 field types** covering every data modeling need — from basic text and numbers to AI vectors and rich media. This guide organizes them by category with per-type configuration details.
+ObjectStack provides **49 field types** covering every data modeling need — from basic text and numbers to AI vectors and rich media. This guide organizes them by category with per-type configuration details.
 
 <Callout type="info">
 **Source:** `packages/spec/src/data/field.zod.ts`  
@@ -647,7 +647,7 @@ These properties are available on **all** field types:
 | `name` | `string` | **required** | Machine name (snake_case) |
 | `label` | `string` | — | Human-readable display label |
 | `description` | `string` | — | Field description / help text |
-| `type` | `FieldType` | **required** | One of the 48 field types |
+| `type` | `FieldType` | **required** | One of the 49 field types |
 | `required` | `boolean` | `false` | Whether the field is required |
 | `unique` | `boolean` | `false` | Enforce uniqueness |
 | `multiple` | `boolean` | `false` | Allow array of values |

diff --git a/content/docs/data-modeling/fields.mdx b/content/docs/data-modeling/fields.mdx
@@ -1,11 +1,11 @@
 ---
 title: Field Metadata
-description: Configure field types and properties — 40+ field types for text, numbers, dates, relationships, and more
+description: Configure field types and properties — 49 field types for text, numbers, dates, relationships, and more
 ---
 
 # Field Metadata
 
-A **Field** defines an individual property within an Object. ObjectStack provides 40+ field types covering text, numbers, dates, selections, relationships, files, calculations, and specialized types like vectors and QR codes.
+A **Field** defines an individual property within an Object. ObjectStack provides 49 field types covering text, numbers, dates, selections, relationships, files, calculations, and specialized types like vectors and QR codes.
 
 ## Basic Usage
 

diff --git a/content/docs/data-modeling/index.mdx b/content/docs/data-modeling/index.mdx
@@ -1,34 +1,58 @@
 ---
 title: Data Modeling
-description: Define objects, fields, relationships, validation, formulas, and queries — the ObjectQL layer that every other module builds on.
+description: Objects, 49 field types, relationships, validation, CEL formulas, and a compiled query AST — the ObjectQL layer every other module builds on.
 ---
 
 # Data Modeling
 
-Data modeling is where every ObjectStack application starts: you declare **objects** (business entities), their **fields**, **relationships**, and **validation rules** as metadata, and the platform derives the database schema, APIs, permissions surface, and UI from that single definition. This module is the practical documentation for the **ObjectQL layer** — the Data Protocol described normatively in the [ObjectQL spec](/docs/protocol/objectql).
+Every ObjectStack application starts here: you declare **objects** (business entities), their **fields**, **relationships**, and **validation rules** as typed metadata, and the platform derives the database schema, REST API, permission surface, and UI from that single definition. This module is the practical documentation for the **ObjectQL layer** — the Data Protocol specified normatively in the [ObjectQL spec](/docs/protocol/objectql).
 
-## How it fits together
+A real object definition looks like this (from the CRM example app):
 
-- An **Object** is the unit of modeling (a table/collection with fields, actions, triggers, and permissions attached).
-- Queries are expressed as a JSON **AST** that the runtime validates and a **driver** compiles into SQL/NoSQL for the underlying store — the same model runs on Postgres, MySQL, SQLite, or MongoDB.
-- Validation and **formula (CEL) expressions** live in the metadata, so they are enforced identically in the API, UI, and automation layers.
-- Data that lives outside ObjectStack can join the model through **external datasources** (federation).
+```typescript
+import { ObjectSchema, Field } from '@objectstack/spec/data';
+
+export const Lead = ObjectSchema.create({
+  name: 'crm_lead',
+  label: 'Lead',
+  pluralLabel: 'Leads',
+  icon: 'funnel',
+  description: 'An inbound prospect not yet qualified as an opportunity.',
+  fields: {
+    name: Field.text({ label: 'Lead Name', required: true, searchable: true, maxLength: 200 }),
+    email: Field.email({ label: 'Email', searchable: true }),
+    phone: Field.phone({ label: 'Phone' }),
+    company: Field.text({ label: 'Company', searchable: true, maxLength: 200 }),
+  },
+});
+```
+
+That one definition is enough to get a persisted table, CRUD + query endpoints, permission checks, and generated list views and forms.
+
+## What the data layer actually gives you
+
+- **49 field types** — from `text`, `currency`, and `lookup`/`master_detail` relationships to `formula`, `summary`, `signature`, `qrcode`, and `vector` (with HNSW/IVFFlat index config for AI embeddings). See the [Field Types gallery](/docs/data-modeling/field-types).
+- **Validation as metadata** — required/format rules, CEL script validation with access to `previous.<field>`, uniqueness via indexes, and severity levels — enforced identically in API, UI, and automation.
+- **CEL expressions** — formula fields and computed defaults share one expression language ([Expressions](/docs/data-modeling/formulas)).
+- **A compiled query AST** — queries are JSON documents validated against the protocol, then compiled by a driver into native queries with joins, aggregations, window functions, HAVING, and subqueries. The [query cheat sheet](/docs/data-modeling/queries) covers the syntax; the [spec](/docs/protocol/objectql/query-syntax) is normative.
+- **Four database drivers in this repo** — `driver-sql` (PostgreSQL / MySQL / SQLite via Knex), `driver-mongodb`, `driver-memory` (in-memory, for tests and demos), and `driver-sqlite-wasm` (SQLite in the browser / WebContainers). The same model runs unchanged on any of them.
+- **External datasource federation** — introspect an existing external database, import selected tables into the catalog, and query them alongside native objects ([External Datasources](/docs/data-modeling/external-datasources)).
 
 ## What's in this module
 
 <Cards>
   <Card href="/docs/data-modeling/schema-design" title="Schema Design" description="End-to-end guide: designing objects, field groups, and real-world schemas" />
   <Card href="/docs/data-modeling/objects" title="Objects" description="Object metadata: definition, options, and API operations" />
   <Card href="/docs/data-modeling/fields" title="Fields" description="Field metadata and configuration" />
-  <Card href="/docs/data-modeling/field-types" title="Field Types" description="Gallery of every field type with examples" />
+  <Card href="/docs/data-modeling/field-types" title="Field Types" description="Gallery of all 49 field types with examples" />
   <Card href="/docs/data-modeling/relationships" title="Relationships & Lookups" description="Lookup, master-detail, and cross-object modeling" />
-  <Card href="/docs/data-modeling/validation" title="Validation" description="Validation metadata and rule authoring" />
+  <Card href="/docs/data-modeling/validation" title="Validation" description="Validation metadata and CEL rule authoring" />
   <Card href="/docs/data-modeling/formulas" title="Expressions (CEL)" description="Formula fields and computed logic" />
   <Card href="/docs/data-modeling/queries" title="Queries" description="Query syntax quick reference" />
   <Card href="/docs/data-modeling/indexing" title="Database Indexing" description="Index configuration and performance" />
   <Card href="/docs/data-modeling/seed-data" title="Seed Data & Fixtures" description="Ship demo and reference data with your app" />
   <Card href="/docs/data-modeling/external-datasources" title="External Datasources" description="Federate external databases into the model" />
-  <Card href="/docs/data-modeling/drivers" title="Database Drivers" description="Configure SQL, MongoDB, and in-memory drivers" />
+  <Card href="/docs/data-modeling/drivers" title="Database Drivers" description="Configure SQL, MongoDB, in-memory, and WASM drivers" />
   <Card href="/docs/data-modeling/analytics" title="Analytics Datasets" description="Model datasets for dashboards and reports" />
 </Cards>
 

diff --git a/content/docs/getting-started/quick-reference.mdx b/content/docs/getting-started/quick-reference.mdx
@@ -18,7 +18,7 @@ Core business logic and data modeling schemas.
 
 | Protocol | Source File | Key Schemas | Purpose |
 |:---------|:-----------|:------------|:--------|
-| **[Field](/docs/references/data/field)** | `field.zod.ts` | Field, FieldType, SelectOption | 44 field types for data modeling |
+| **[Field](/docs/references/data/field)** | `field.zod.ts` | Field, FieldType, SelectOption | 49 field types for data modeling |
 | **[Object](/docs/references/data/object)** | `object.zod.ts` | Object, ObjectCapabilities | Object/table definitions |
 | **[Query](/docs/references/data/query)** | `query.zod.ts` | Query, QueryOptions | Query AST with joins, aggregations |
 | **[Filter](/docs/references/data/filter)** | `filter.zod.ts` | QueryFilter, FilterCondition | Advanced filtering operators |

diff --git a/content/docs/index.mdx b/content/docs/index.mdx
@@ -5,7 +5,9 @@ description: Technical documentation for ObjectStack.
 
 # ObjectStack Documentation
 
-ObjectStack is an AI-native business backend protocol for structured, auditable business applications. You declare your application — data model, logic, permissions, and UI — as metadata, and the platform derives the database, APIs, automation, and interface from that single artifact.
+ObjectStack is an AI-native business backend protocol for structured, auditable business applications. You author your application — data model, logic, permissions, and UI — as typed metadata in TypeScript (`defineStack()`), compile it to a self-contained artifact (`objectstack.json`), and the runtime derives everything else: the database schema across four interchangeable drivers, a generated REST + realtime API, permission-checked automation, and server-driven UI. AI agents act through the same typed, permission-aware surface — never through raw SQL or scraped UI.
+
+One protocol definition, 15 namespaces, 49 field types, one artifact — every engine (SQL, React, MCP) is a consumer of the same source of truth.
 
 ## Start here