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

Author: hotlong

content/docs/developer/index.mdx

@@ -1,16 +1,94 @@
 ---
 title: Developer Guide
-description: Learn to build enterprise applications with the ObjectStack Protocol — from data modeling to AI agents
+description: Learn to build enterprise applications with the ObjectStack Protocol
 ---
 
 # Developer Guide
 
 This guide teaches you how to **build real applications** using the ObjectStack Protocol. Each section is hands-on, with code examples derived from the [CRM example app](https://github.com/objectstack-ai/spec/tree/main/examples/app-crm).
 
 <Callout type="tip">
-**New to ObjectStack?** Read the [Introduction](/docs/introduction) first to understand the protocol-driven architecture.
+**New to ObjectStack?** Start with the [Example Apps](/docs/framework/examples) to see working code, or read the [Introduction](/docs/introduction) for the architecture overview.
 </Callout>
 
+## Quick Start
+
+<Steps>
+
+### Create a project
+
+```bash
+npx @objectstack/cli init my-app
+cd my-app
+```
+
+### Define your first object
+
+The scaffolded project includes a sample object. Open `src/objects/my_app.ts`:
+
+```typescript
+import { Data } from '@objectstack/spec';
+
+const myApp: Data.Object = {
+  name: 'my_app',
+  label: 'My App',
+  ownership: 'own',
+  fields: {
+    name: {
+      type: 'text',
+      label: 'Name',
+      required: true,
+    },
+    description: {
+      type: 'textarea',
+      label: 'Description',
+    },
+    status: {
+      type: 'select',
+      label: 'Status',
+      options: [
+        { label: 'Draft', value: 'draft' },
+        { label: 'Active', value: 'active' },
+        { label: 'Archived', value: 'archived' },
+      ],
+      defaultValue: 'draft',
+    },
+  },
+};
+
+export default myApp;
+```
+
+### Launch the Studio
+
+```bash
+os studio
+```
+
+Open [http://localhost:3000/_studio/](http://localhost:3000/_studio/) to browse your objects, test the REST API, and inspect metadata. The server automatically provides:
+
+- **ObjectQL Engine** &mdash; Query layer with CRUD operations
+- **InMemory Driver** &mdash; Zero-config data storage for development
+- **Hono HTTP Server** &mdash; REST API at `/api/v1/{object}`
+- **Console UI** &mdash; Admin interface at `/_studio/`
+
+### Add more metadata
+
+```bash
+os g object customer       # Generate a new object
+os g action approve        # Generate an action
+os g flow onboarding       # Generate an automation flow
+```
+
+### Validate and build
+
+```bash
+os validate        # Check schema correctness
+os compile         # Generate production artifact
+```
+
+</Steps>
+
 ## Learning Path
 
 Follow these guides in order for the best experience:
@@ -43,99 +121,47 @@ Follow these guides in order for the best experience:
   />
 </Cards>
 
-## Quick Start
-
-### 1. Scaffold a new project
-
-```bash
-npx @objectstack/cli init my-app
-cd my-app && pnpm install
-```
-
-### 2. Define your first object
-
-```typescript
-// src/objects/customer.object.ts
-import { ObjectSchema, Field } from '@objectstack/spec/data';
-
-export const Customer = ObjectSchema.create({
-  name: 'customer',
-  label: 'Customer',
-  fields: {
-    name: Field.text({ label: 'Name', required: true }),
-    industry: Field.select({
-      label: 'Industry',
-      options: [
-        { label: 'Technology', value: 'technology' },
-        { label: 'Finance', value: 'finance' },
-      ],
-    }),
-    revenue: Field.currency({ label: 'Revenue' }),
-  },
-});
-```
-
-### 3. Validate and build
-
-```bash
-npx objectstack validate   # Check schema correctness
-npx objectstack compile     # Generate TypeScript types
-npx objectstack dev         # Start dev server
-```
-
-### 4. Add a view
-
-```typescript
-// src/views/customer_list.view.ts
-import { ListView } from '@objectstack/spec/ui';
-
-export const CustomerList = ListView({
-  object: 'customer',
-  type: 'grid',
-  columns: [
-    { field: 'name', width: 200 },
-    { field: 'industry' },
-    { field: 'revenue' },
-  ],
-});
-```
-
 ## Project Structure
 
-A typical ObjectStack application:
+A typical ObjectStack application (generated by `os init`):
 
 ```
 my-app/
-├── objectstack.config.ts     # App manifest
+├── objectstack.config.ts     # App manifest + metadata wiring
+├── package.json
+├── tsconfig.json
 ├── src/
-│   ├── objects/              # Data models (ObjectQL)
-│   │   ├── customer.object.ts
-│   │   └── opportunity.object.ts
-│   ├── views/                # UI definitions (ObjectUI)
-│   │   ├── customer_list.view.ts
-│   │   └── customer_form.view.ts
-│   ├── flows/                # Automation (Flows, Workflows)
-│   │   └── welcome_email.flow.ts
-│   ├── security/             # Permissions & Sharing
-│   │   └── profiles.ts
-│   └── ai/                   # AI agents & RAG
-│       └── sales_assistant.agent.ts
+│   ├── objects/              # Data models (required)
+│   │   ├── index.ts          # Barrel export
+│   │   └── my_app.ts         # Object definition
+│   ├── actions/              # Buttons, batch operations
+│   ├── flows/                # Automation logic
+│   ├── apps/                 # Navigation definitions
+│   ├── dashboards/           # Analytics dashboards
+│   ├── agents/               # AI agents
+│   └── rag/                  # RAG pipelines
 └── test/                     # Tests
 ```
 
+**File naming conventions:**
+- **Object files:** `{name}.object.ts` or `{name}.ts` (one object per file)
+- **Action files:** `{name}.actions.ts`
+- **Flow files:** `{name}.flow.ts`
+- **Barrel exports:** Each directory has an `index.ts` that re-exports everything
+
 ## Key Concepts
 
-| Concept | Protocol | You Define | ObjectStack Generates |
+| Concept | Protocol | You Define | ObjectStack Provides |
 | :--- | :--- | :--- | :--- |
 | Data Model | ObjectQL | Objects, Fields, Validation | CRUD APIs, database schema, type safety |
-| User Interface | ObjectUI | Views, Pages, Dashboards | React components, navigation, responsive layout |
+| User Interface | ObjectUI | Views, Apps, Dashboards | React components, navigation, responsive layout |
 | Business Logic | Automation | Flows, Workflows, Triggers | Event handlers, approval chains, scheduled jobs |
 | Access Control | Security | Profiles, Permissions, Sharing | Middleware, RLS policies, field masking |
 | Intelligence | AI | Agents, RAG, Models | Chat interfaces, search indexes, predictions |
 
 ## Next Steps
 
-- [Data Modeling Guide →](./data-modeling) — Start building your data layer
-- [CLI Reference](/docs/framework/cli) — All available commands
-- [Protocol Reference](/docs/references) — Complete schema documentation
-- [Example: CRM App](https://github.com/objectstack-ai/spec/tree/main/examples/app-crm) — Full working example
+- [Example Apps](/docs/framework/examples) &mdash; Run the Todo, CRM, and BI examples
+- [Data Modeling Guide](/docs/developer/data-modeling) &mdash; Deep dive into objects and fields
+- [CLI Reference](/docs/framework/cli) &mdash; All available commands
+- [Protocol Reference](/docs/references) &mdash; Complete schema documentation

content/docs/framework/cli.mdx

@@ -15,27 +15,48 @@ pnpm add -D @objectstack/cli
 
 The CLI is available as `objectstack` or the shorter alias `os`.
 
-## Quick Start
+## Your First App in 2 Minutes
+
+<Steps>
+
+### Create a project
 
 ```bash
-# Initialize a new project
-os init my-app
+npx @objectstack/cli init my-app
+cd my-app
+```
 
-# Generate metadata
-os generate object task
-os generate view task
-os generate flow task
+This scaffolds a working project with `objectstack.config.ts`, a sample object, and all dependencies installed.
 
-# Validate configuration
-os validate
+### Add more metadata
+
+```bash
+os generate object customer    # Add a Customer object
+os generate action approve     # Add an action
+os generate flow onboarding    # Add an automation flow
+```
 
-# Start development server
-os dev
+### Launch the Studio
 
-# Compile for production
-os compile
+```bash
+os studio
 ```
 
+Open [http://localhost:3000/_studio/](http://localhost:3000/_studio/) — you'll see the Console UI with a data browser, metadata explorer, and API documentation.
+
+### Validate & Build
+
+```bash
+os validate          # Check schema correctness
+os compile           # Build production artifact → dist/objectstack.json
+```
+
+</Steps>
+
+<Callout type="tip">
+`os studio` = `os serve --dev --ui`. It starts a dev server with the Console UI, auto-loads ObjectQL, InMemory driver, and Hono HTTP server — zero config needed.
+</Callout>
+
 ## Commands
 
 ### Development
@@ -358,32 +379,33 @@ os compile path/to/my-config.ts
 
 ```bash
 # 1. Create project
-os init my-crm
+os init my-crm && cd my-crm
 
 # 2. Define your data model
 os g object account
 os g object contact
 os g object opportunity
 
-# 3. Add UI definitions
-os g view account
-os g view contact
-os g dashboard sales
-
-# 4. Add business logic
+# 3. Add business logic
 os g flow lead-qualification
 os g agent sales-assistant
 
-# 5. Validate everything
+# 4. Validate everything
 os validate
 
-# 6. Start development
-os dev
+# 5. Start development with Console UI
+os studio
 
-# 7. Build for production
+# 6. Build for production
 os compile
 ```
 
+## Next Steps
+
+- [Examples Guide](/docs/framework/examples) — Run the built-in example apps (Todo, CRM, BI)
+- [Developer Guide](/docs/developer) — Learn data modeling, security, and automation
+- [Protocol Reference](/docs/references) — Complete schema documentation
+
 ## CI/CD Integration
 
 All commands that produce output support `--json` for machine-readable output: