docs: restructure documentation site for developer experience

content/docs/getting-started/core-concepts.mdx

@@ -0,0 +1,160 @@
+---
+title: Core Concepts
+description: The foundational ideas behind ObjectStack — metadata-driven development, protocol-first design, and the principles that shape every decision
+---
+
+import { Scale, Code2, Database, ScrollText, Laptop } from 'lucide-react';
+
+# Core Concepts
+
+Before diving into code, understanding these foundational ideas will make everything else click.
+
+## Metadata-Driven Development
+
+Metadata-driven development is a paradigm shift where **application logic is defined by declarative data (metadata), not imperative code.**
+
+### The Problem with Code-First
+
+In traditional development, the "Intent" (e.g., *"This field is a required email address"*) is scattered across multiple layers:
+
+1. **Database:** SQL constraints (`NOT NULL`, `CHECK`)
+2. **Backend:** ORM validation (TypeORM decorators, Prisma schemas)
+3. **Frontend:** UI validation (React Hook Form + Zod)
+4. **Documentation:** API specs (OpenAPI/Swagger)
+
+When a business requirement changes, you must update code in **three or four places**. This is **Implementation Coupling**.
+
+### The ObjectStack Way
+
+ObjectStack centralizes the "Intent" into a **single Protocol Definition**:
+
+```typescript
+// ONE definition — everything else derives from it
+import { defineStack } from '@objectstack/spec';
+
+export default defineStack({
+  objects: [{
+    name: 'user',
+    label: 'User',
+    fields: [
+      { name: 'phone', label: 'Phone Number', type: 'phone', required: true },
+    ],
+  }],
+});
+```
+
+From this single definition, ObjectStack automatically:
+
+✅ Generates database schema
+✅ Creates validation rules
+✅ Builds CRUD APIs
+✅ Renders form fields
+✅ Produces API documentation
+
+### The Three Truths
+
+1. **The UI is a Projection** — The form is generated from the schema, not hand-coded
+2. **The API is a Consequence** — REST/GraphQL endpoints appear automatically from object definitions
+3. **The Schema is the Application** — Your entire business logic lives in metadata files
+
+### When to Use Metadata-Driven
+
+✅ **Great for:** CRUD apps, SaaS platforms, admin panels, rapid prototyping, multi-tenant systems
+
+❌ **Not ideal for:** Pixel-perfect custom UIs, real-time 3D/games, highly unique domains
+
+---
+
+## Design Principles
+
+ObjectStack is governed by four unshakable principles:
+
+<Cards>
+  <Card
+    icon={<Scale />}
+    title="I. Protocol Neutrality"
+    description="The Protocol is law. The Implementation is merely an opinion."
+  />
+  <Card
+    icon={<Code2 />}
+    title="II. Mechanism over Policy"
+    description="Provide the tools to build rules, do not hardcode the rules themselves."
+  />
+  <Card
+    icon={<Database />}
+    title="III. Single Source of Truth"
+    description="There is no 'Code'. There is only Schema."
+  />
+  <Card
+    icon={<ScrollText />}
+    title="IV. Local-First by Default"
+    description="The Cloud is a sync peer, not a master."
+  />
+</Cards>
+
+### Protocol Neutrality
+
+**"The Protocol is neutral. The Engine is replaceable."**
+
+- **Spec before Engine:** Features must be defined in the Specification layer before any engine code is written
+- **Zero Leakage:** Implementation details (React, SQL, etc.) never leak into Protocol definitions
+
+This ensures ObjectStack apps can run on Node.js + PostgreSQL today, Python + SQLite tomorrow, or Rust WASM in the browser.
+
+### Mechanism over Policy
+
+**"Give them the physics, not the simulation."**
+
+| Layer | Responsibility | Example |
+| :--- | :--- | :--- |
+| **Protocol** | Defines capabilities | `allowRead: string` (a slot for a formula) |
+| **App** | Defines business logic | `allowRead: "$user.role == 'admin'"` |
+| **Engine** | Enforces the logic | Compiles formula to SQL `WHERE` clause |
+
+### Single Source of Truth
+
+In ObjectStack, **the Object Protocol is the only truth:**
+
+- The Database is a *derivative* of the Protocol
+- The UI is a *projection* of the Protocol
+- The API is a *consequence* of the Protocol
+
+Change the Protocol → the entire system adapts automatically.
+
+### Local-First by Default
+
+All interactions should be instant (0ms latency). The user's data lives on their device; the server is a sync hub.
+
+```
+Traditional: Click → Wi-Fi → ISP → Cloud → DB → Response
+Local-First: Click → Local DB → UI Update (0ms)
+```
+
+---
+
+## Naming Conventions
+
+ObjectStack enforces strict naming rules for consistency:
+
+| Element | Convention | Examples |
+|---------|-----------|----------|
+| **Object names** (machine) | `snake_case` | `todo_task`, `user_profile` |
+| **Field names** (machine) | `snake_case` | `first_name`, `is_active` |
+| **Export names** (constants) | `PascalCase` | `TodoTask`, `UserProfile` |
+| **Config keys** (properties) | `camelCase` | `maxLength`, `defaultValue` |
+
+## Summary
+
+| Aspect | Traditional | Metadata-Driven |
+| :--- | :--- | :--- |
+| **Definition** | Code in multiple files | Single metadata definition |
+| **Changes** | Update 3-4 places | Update once |
+| **Type Safety** | Manual synchronization | Automatic from Zod |
+| **Flexibility** | Locked to tech stack | Technology agnostic |
+| **Boilerplate** | High (300+ lines) | Low (30 lines) |
+
+## Next Steps
+
+- [Architecture](/docs/getting-started/architecture) — How the protocol layers work together
+- [Quick Start](/docs/getting-started/quick-start) — Build your first app in 5 minutes
+- [Glossary](/docs/getting-started/glossary) — Key terminology

content/docs/getting-started/glossary.mdx

@@ -0,0 +1,125 @@
+---
+title: Glossary
+description: The Glossary of the ObjectStack Ecosystem. Speaking the same language.
+---
+
+import { Book, Server, Code, Database } from 'lucide-react';
+
+To navigate the ObjectStack ecosystem effectively, it is helpful to understand the specific vocabulary we use. While many terms are standard in computer science, some have specific nuances in our "Protocol-Driven" context.
+
+## The Ecosystem
+
+### ObjectStack
+The umbrella term for the entire suite of protocols and reference implementations. It is organized into **11 protocol namespaces** grouped into three architectural layers.
+
+### Protocol Namespace
+A logical grouping of related schemas and types defined with Zod. ObjectStack has 11 protocol namespaces: Data, Driver, Permission, UI, System, Auth, Kernel, Hub, AI, API, and Automation.
+
+---
+
+## The 11 Protocol Namespaces
+
+### Data Protocol
+Defines the core business data model. Includes Object schema, Field types, Validation rules, Query AST, and Filter conditions. This is the foundation of ObjectQL.
+
+### Driver Protocol
+Database adapter interface for connecting to various storage engines (PostgreSQL, MongoDB, SQLite, Redis, etc.). Drivers implement a standard interface for CRUD operations and query execution.
+
+### Permission Protocol
+Access control system including object-level permissions (CRUD), field-level security (FLS), sharing rules, and territory management. Determines who can see and modify what data.
+
+### UI Protocol
+Server-Driven UI specification for building user interfaces. Includes App structure, Views (List/Form/Kanban/Calendar), Dashboards, Reports, Themes, and Actions.
+
+### System Protocol
+Infrastructure services including Event Bus, Job Scheduling, Translation (i18n), and Audit Logging. Manages system-level concerns.
+
+### Auth Protocol
+Identity and access management including User accounts, Sessions, Roles, Organization structure, and various authentication strategies (OAuth, SAML, LDAP, etc.).
+
+### Kernel Protocol
+Plugin system and runtime management. Includes Plugin lifecycle, Manifest definition, Logger configuration, and Runtime Context. The core of ObjectOS.
+
+### Hub Protocol
+SaaS and marketplace features including Multi-tenancy, Licensing, Marketplace plugins, and Deployment configurations. Enables commercial distribution.
+
+### AI Protocol
+Artificial intelligence capabilities including AI Agents, RAG pipelines, Natural Language Query (NLQ), Predictive models, Cost tracking, and Orchestration.
+
+### API Protocol
+External communication layer including REST contracts, API discovery, Realtime subscriptions (WebSocket/SSE), and Routing configuration.
+
+### Automation Protocol
+Business process automation including Workflows (state machines), Flows (visual logic), and Webhooks (HTTP callbacks).
+
+---
+
+## Architecture Concepts
+
+### Protocol-Driven
+A development paradigm where logic is defined in static, declarative data formats (JSON/YAML) with Zod schemas rather than imperative code. The goal is to separate the **Intent** (Business Logic) from the **Implementation** (Tech Stack).
+
+### Local-First
+An architectural pattern where the application reads and writes to a database embedded on the user's device (the Client) first. Network synchronization happens in the background. This ensures zero-latency interactions and offline availability.
+
+### Database Compiler
+A system that takes a high-level query AST (Abstract Syntax Tree) and compiles it into an optimized database query string (e.g., SQL). This contrasts with an ORM, which typically acts as a runtime wrapper object.
+
+### Virtual Field
+A field defined in the Data Protocol schema that does not exist physically in the database table but is computed on the fly.
+* *Example:* A SQL subquery or expression injected into the `SELECT` statement at compile time.
+
+---
+
+## Data & Schema
+
+### Object (Entity)
+The fundamental unit of data modeling in ObjectStack. Roughly equivalent to a "Table" in SQL or a "Collection" in NoSQL. An Object definition includes Fields, Actions, Triggers, and Permissions.
+
+### Driver
+An adapter plugin (Driver Protocol) that allows the Data Layer to communicate with a specific underlying storage engine.
+* *Example:* `@objectstack/driver-postgres`, `@objectstack/driver-mongodb`, `@objectstack/driver-sqlite`.
+
+### AST (Abstract Syntax Tree)
+The intermediate representation of a query or schema. The Data Protocol parses a JSON request into an AST before the Driver translates it into SQL/NoSQL queries. This allows for security validation and optimization before execution.
+
+### Manifest
+The entry point configuration file (Kernel Protocol) for an ObjectStack Plugin. It declares dependencies, resources, and extensions using the Manifest schema.
+
+---
+
+## Interface & Logic
+
+### Layout
+A JSON structure defined in the UI Protocol that describes the visual arrangement of components. Layouts can be nested and dynamic (e.g., Master-Detail, Grid, Kanban).
+
+### Workflow
+A business process (Automation Protocol) defined as a **Finite State Machine (FSM)**. It consists of States (e.g., `draft`, `approved`), Transitions, and Guards.
+
+### Flow
+A visual logic automation tool (Automation Protocol) that allows building business processes using a node-based editor. Supports screen flows, autolaunched flows, and scheduled flows.
+
+### Action
+A discrete unit of logic (UI Protocol) that can be triggered by a user (UI button) or a system event (Workflow transition). Actions define button behaviors and navigation.
+
+### Component Registry
+A map within the UI Runtime that links a string identifier (e.g., `"chart.bar"`) to a real React Component. This allows the UI Protocol to instantiate UI elements dynamically.
+
+---
+
+## Governance
+
+### Space (Workspace)
+A logical isolation unit (Hub Protocol) for multi-tenancy. A single ObjectStack instance can host multiple Spaces. Data is physically segregated by tenant isolation strategies.
+
+### FLS (Field-Level Security)
+A granular permission model (Permission Protocol) where access control is applied to individual fields (columns), not just the whole object (row).
+
+### OWD (Organization-Wide Defaults)
+The default sharing level (Permission Protocol) for records in an object. Determines the baseline access level before sharing rules are applied.
+
+### Territory
+A hierarchical access control model (Permission Protocol) that grants data access based on geographic or organizational boundaries.
+
+### TCK (Technology Compatibility Kit)
+A suite of tests that validates if a Driver or Renderer complies with the official ObjectStack Protocol. If a new driver passes the TCK, it is certified as compatible.

content/docs/getting-started/index.mdx

@@ -137,7 +137,7 @@ For more troubleshooting, see the [Troubleshooting & FAQ](/docs/guides/troublesh
 
 ## Next Steps
 
-- [Design Principles](/docs/concepts/design-principles) - Understand the philosophy
-- [Architecture](/docs/concepts/architecture) - Deep dive into the system
-- [Glossary](/docs/concepts/terminology) - Learn key terminology
-- [Core Concepts](/docs/core-concepts) - Metadata-driven development explained
+- [Core Concepts](/docs/getting-started/core-concepts) — Metadata-driven development & design principles
+- [Architecture](/docs/getting-started/architecture) — The three-layer protocol stack
+- [Glossary](/docs/getting-started/glossary) — Key terminology
+- [Quick Start](/docs/getting-started/quick-start) — Build your first app in 5 minutes

content/docs/getting-started/meta.json

@@ -1,4 +1,4 @@
 {
   "title": "Getting Started",
-  "pages": ["index", "quick-start", "examples", "cli"]
+  "pages": ["index", "quick-start", "core-concepts", "architecture", "examples", "cli", "glossary"]
 }

content/docs/getting-started/quick-start.mdx

@@ -96,27 +96,27 @@ Follow these guides in order for the best experience:
 <Cards>
   <Card
     title="1. Data Modeling"
-    href="./data-modeling"
+    href="/docs/guides/data-modeling"
     description="Design objects, fields, relationships, and validation rules. The foundation of every app."
   />
   <Card
     title="2. Business Logic"
-    href="./business-logic"
+    href="/docs/guides/business-logic"
     description="Implement workflows, approval flows, triggers, and formulas to automate business processes."
   />
   <Card
     title="3. Security Model"
-    href="./security"
+    href="/docs/guides/security"
     description="Configure profiles, permissions, sharing rules, and row-level security for enterprise-grade access control."
   />
   <Card
     title="4. AI Capabilities"
-    href="./ai-capabilities"
+    href="/docs/guides/ai-capabilities"
     description="Add AI agents, RAG pipelines, natural language queries, and predictive analytics."
   />
   <Card
     title="5. Development Standards"
-    href="./standards"
+    href="/docs/guides/standards"
     description="Naming conventions, project structure, testing strategies, and best practices."
   />
 </Cards>

content/docs/guides/error-catalog.mdx → content/docs/guides/cheatsheets/error-catalog.mdx

@@ -103,7 +103,7 @@ ObjectStack uses a structured error system with **9 error categories** and **41+
 
 ### `invalid_query`
 **Cause:** The query structure is malformed.  
-**Fix:** Check the query syntax against the [Query Cheat Sheet](/references/data/query-cheat-sheet).  
+**Fix:** Check the query syntax against the [Query Cheat Sheet](/docs/guides/cheatsheets/query-cheat-sheet).  
 **Retry:** `no_retry`
 
 ### `invalid_filter`

content/docs/guides/field-type-decision-tree.mdx → content/docs/guides/cheatsheets/field-type-decision-tree.mdx

@@ -8,7 +8,7 @@ description: Interactive guide for choosing the right ObjectStack field type —
 Not sure which field type to use? Follow this decision tree to find the right type for your data, then check the quick-reference table for details.
 
 <Callout type="info">
-**Full Details:** Once you've identified the right type, see the [Field Type Gallery](/references/data/field-type-gallery) for complete configuration properties.
+**Full Details:** Once you've identified the right type, see the [Field Type Gallery](/docs/guides/cheatsheets/field-type-gallery) for complete configuration properties.
 </Callout>
 
 ---

content/docs/guides/cheatsheets/meta.json

@@ -0,0 +1,15 @@
+{
+  "title": "Cheatsheets",
+  "pages": [
+    "quick-reference",
+    "field-type-gallery",
+    "field-type-decision-tree",
+    "field-validation-rules",
+    "query-cheat-sheet",
+    "error-catalog",
+    "wire-format",
+    "protocol-diagram",
+    "permissions-matrix",
+    "backward-compatibility"
+  ]
+}

content/docs/guides/wire-format.mdx → content/docs/guides/cheatsheets/wire-format.mdx

@@ -425,7 +425,7 @@ All errors follow a consistent structure defined by `ErrorResponseSchema`.
 ```
 
 <Callout type="info">
-**Error Codes:** See the [Error Catalog](/references/api/error-catalog) for the complete list of error codes and their meanings.
+**Error Codes:** See the [Error Catalog](/docs/guides/cheatsheets/error-catalog) for the complete list of error codes and their meanings.
 </Callout>
 
 ---

content/docs/guides/common-patterns.mdx

@@ -432,7 +432,7 @@ export default defineStack({
 
 <Callout type="tip">
 **Next Steps:**  
-- [Field Type Gallery](/references/data/field-type-gallery) — Choose the right field type  
-- [Query Cheat Sheet](/references/data/query-cheat-sheet) — Write powerful queries  
-- [Error Catalog](/references/api/error-catalog) — Handle errors gracefully
+- [Field Type Gallery](/docs/guides/cheatsheets/field-type-gallery) — Choose the right field type  
+- [Query Cheat Sheet](/docs/guides/cheatsheets/query-cheat-sheet) — Write powerful queries  
+- [Error Catalog](/docs/guides/cheatsheets/error-catalog) — Handle errors gracefully
 </Callout>