Merge pull request #680 from objectstack-ai/copilot/update-docs-map-format-support

Author: hotlong

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

@@ -28,6 +28,8 @@ When a business requirement changes, you must update code in **three or four pla
 
 ObjectStack centralizes the "Intent" into a **single Protocol Definition**:
 
+<Tabs items={['Array Format', 'Map Format']}>
+<Tab value="Array Format">
 ```typescript
 // ONE definition — everything else derives from it
 import { defineStack } from '@objectstack/spec';
@@ -42,6 +44,29 @@ export default defineStack({
   }],
 });
 ```
+</Tab>
+<Tab value="Map Format">
+```typescript
+// Map keys become the `name` field automatically
+import { defineStack } from '@objectstack/spec';
+
+export default defineStack({
+  objects: {
+    user: {
+      label: 'User',
+      fields: {
+        phone: { label: 'Phone Number', type: 'phone', required: true },
+      },
+    },
+  },
+});
+```
+</Tab>
+</Tabs>
+
+<Callout type="info">
+**Array or Map?** `defineStack()` accepts both formats for all named metadata collections (`objects`, `apps`, `flows`, etc.). Map keys are injected as the `name` field — pick whichever style you prefer.
+</Callout>
 
 From this single definition, ObjectStack automatically:
 

content/docs/guides/cheatsheets/backward-compatibility.mdx

@@ -28,6 +28,7 @@ ObjectStack follows [Semantic Versioning 2.0.0](https://semver.org/) (`MAJOR.MIN
 - **Zod schemas** are part of the public API surface. Adding optional properties is a MINOR change; removing or renaming properties is a MAJOR change.
 - **TypeScript types** inferred from Zod (`z.infer<typeof Schema>`) follow the same guarantees as their source schemas.
 - **Helper functions** (e.g., `defineStack`, `defineStudioPlugin`) maintain their call signatures within a MAJOR version.
+- **Input formats** — `defineStack()` accepts both array and map (Record) format for all named metadata collections. Both formats are guaranteed stable within a MAJOR version.
 - **Enum values** are append-only within a MAJOR version. Existing values are never removed or renamed in MINOR/PATCH releases.
 - **Default values** in schemas are not changed in MINOR/PATCH releases unless fixing a documented bug.
 

content/docs/guides/cheatsheets/protocol-diagram.mdx

@@ -253,7 +253,7 @@ flowchart LR
 
 | Stage | Description |
 |:---|:---|
-| `defineStack()` | Developer declares objects, fields, views in `objectstack.config.ts` |
+| `defineStack()` | Developer declares objects, fields, views in `objectstack.config.ts` (array or map format) |
 | Manifest | Compiled configuration package with all metadata |
 | Schema Registry | In-memory registry of all object and field definitions |
 | JSON Schema | Generated JSON Schema files for IDE validation |

content/docs/guides/common-patterns.mdx

@@ -17,6 +17,8 @@ This guide covers the most common patterns you will use when building applicatio
 
 Define a basic object with common fields for create, read, update, and delete operations.
 
+<Tabs items={['Array Format', 'Map Format']}>
+<Tab value="Array Format">
 ```typescript
 import { defineStack } from '@objectstack/spec';
 
@@ -42,6 +44,34 @@ export default defineStack({
   ]
 });
 ```
+</Tab>
+<Tab value="Map Format">
+```typescript
+import { defineStack } from '@objectstack/spec';
+
+export default defineStack({
+  objects: {
+    project: {
+      label: 'Project',
+      fields: {
+        title: { label: 'Title', type: 'text', required: true, maxLength: 200 },
+        description: { label: 'Description', type: 'textarea' },
+        status: { label: 'Status', type: 'select', options: [
+          { label: 'Planning', value: 'planning', default: true },
+          { label: 'Active', value: 'active' },
+          { label: 'Complete', value: 'complete' },
+          { label: 'Archived', value: 'archived' }
+        ]},
+        owner: { label: 'Owner', type: 'lookup', reference: 'user' },
+        due_date: { label: 'Due Date', type: 'date' },
+        budget: { label: 'Budget', type: 'currency', currencyConfig: { precision: 2, defaultCurrency: 'USD' } },
+      },
+    },
+  },
+});
+```
+</Tab>
+</Tabs>
 
 ---
 
@@ -403,6 +433,8 @@ Restrict field visibility and editability based on user profiles.
 
 Combine these patterns into a complete `defineStack()` configuration:
 
+<Tabs items={['Array Format', 'Map Format']}>
+<Tab value="Array Format">
 ```typescript
 import { defineStack } from '@objectstack/spec';
 
@@ -429,6 +461,32 @@ export default defineStack({
   ]
 });
 ```
+</Tab>
+<Tab value="Map Format">
+```typescript
+import { defineStack } from '@objectstack/spec';
+
+export default defineStack({
+  objects: {
+    // Pattern 1: CRUD objects
+    project: { label: 'Project', fields: {/* ... */} },
+    // Pattern 2: Master-detail
+    task: { label: 'Task', fields: {/* ... */} },
+  },
+  apps: {
+    // Pattern 5: Navigation
+  },
+  flows: {
+    // Pattern 6: Automations
+    // Pattern 7: Approval workflows
+  },
+  agents: {
+    // Pattern 8: AI agents
+  },
+});
+```
+</Tab>
+</Tabs>
 
 <Callout type="tip">
 **Next Steps:**  

content/docs/guides/data-flow.mdx

@@ -51,7 +51,7 @@ sequenceDiagram
 
 | Stage | What Happens |
 |:---|:---|
-| `defineStack()` | Developer declares objects, fields, views, flows in TypeScript |
+| `defineStack()` | Developer declares objects, fields, views, flows in TypeScript (array or map format) |
 | Compile | CLI validates all definitions against Zod schemas |
 | Manifest | Compiled metadata package containing all configuration |
 | Kernel Boot | Kernel loads the manifest and initializes the plugin graph |

content/docs/guides/troubleshooting.mdx

@@ -164,13 +164,20 @@ Common mistakes:
 
 **Fix:**
 ```typescript
-// Ensure the object is included in the stack
+// Ensure the object is included in the stack (array format)
 export default defineStack({
   objects: [
     { name: 'project_task', /* ... */ }
   ]
 });
 
+// Or use map format (key becomes the name)
+export default defineStack({
+  objects: {
+    project_task: { /* ... */ }
+  }
+});
+
 // Use the exact same name when querying
 client.records.find('project_task', { /* query */ });
 ```