docs(skills): document fieldGroups MVP in schema skill and data-modeling guide

- Add "Field Groups (MVP)" section to skills/objectstack-schema/SKILL.md with a
  full worked example, ObjectFieldGroup property table, and migration scope
- Link fieldGroups in the "Important optional properties" table and references list
- Add "Field Groups" section to content/docs/guides/data-modeling.mdx (with TOC entry)
- Regenerate skill references via `pnpm --filter @objectstack/spec gen:skill-refs`
  so every skill's object.zod.ts copy now includes ObjectFieldGroupSchema
  (sync also picks up unrelated drift in manifest.zod.ts / dashboard.zod.ts /
  filter+query → objectstack-query move, per the script's source-of-truth role)

Agent-Logs-Url: https://github.com/objectstack-ai/framework/sessions/2dfd93fb-72b4-4e49-bbba-c239c6b5b81c

Co-authored-by: xuyushun441-sys <255036401+xuyushun441-sys@users.noreply.github.com>

Author: Copilot

content/docs/guides/data-modeling.mdx

@@ -14,8 +14,9 @@ Complete guide to designing robust data models in ObjectStack following enterpri
 3. [Relationships & Lookups](#relationships--lookups)
 4. [Validation Rules](#validation-rules)
 5. [Formula Fields](#formula-fields)
-6. [Database Indexing](#database-indexing)
-7. [Best Practices](#best-practices)
+6. [Field Groups](#field-groups)
+7. [Database Indexing](#database-indexing)
+8. [Best Practices](#best-practices)
 
 ---
 
@@ -482,6 +483,65 @@ Field.formula({
 
 ---
 
+## Field Groups
+
+Organize related fields into logical groups for forms, detail pages, and
+editors. The group protocol is intentionally minimal (MVP):
+
+- `ObjectSchema.fieldGroups` declares the groups; **array order is the
+  display order** (no separate `order` property).
+- `Field.group` assigns a field to a group by referencing an
+  `ObjectFieldGroup.key`. In-group display order equals the traversal
+  order of `fields`.
+- Fields whose `group` is unset (or references an undeclared key) render
+  in a default bucket after the declared groups.
+
+```typescript
+import { ObjectSchema } from '@objectstack/spec/data';
+
+export const Account = ObjectSchema.create({
+  name: 'account',
+  label: 'Account',
+
+  fieldGroups: [
+    { key: 'contact_info', label: 'Contact Information', icon: 'user' },
+    { key: 'billing',      label: 'Billing', defaultExpanded: false },
+    { key: 'system',       label: 'System',  visibleOn: '$user.isAdmin' },
+  ],
+
+  fields: {
+    name:            { type: 'text',  required: true, group: 'contact_info' },
+    email:           { type: 'email',                  group: 'contact_info' },
+    phone:           { type: 'phone',                  group: 'contact_info' },
+    vat_id:          { type: 'text',                   group: 'billing' },
+    billing_address: { type: 'address',                group: 'billing' },
+    created_at:      { type: 'datetime', readonly: true, group: 'system' },
+    created_by:      { type: 'lookup', reference: 'user', readonly: true, group: 'system' },
+  },
+});
+```
+
+### `ObjectFieldGroup` Properties
+
+| Property | Type | Description |
+|:---------|:-----|:------------|
+| `key` | `string` (snake_case) | Group machine key; referenced by `Field.group` |
+| `label` | `string` | Human-readable group header |
+| `icon` | `string?` | Lucide/Material icon name for the group header |
+| `description` | `string?` | Optional description under the header |
+| `defaultExpanded` | `boolean` (default `true`) | Whether the group is expanded initially |
+| `visibleOn` | `string?` | Expression controlling group-level visibility |
+
+### Supported Migrations (MVP)
+
+✅ Add / rename / delete / reorder groups — edit the `fieldGroups` array.
+✅ Assign an existing field to a group — set `Field.group`.
+
+⏳ Deferred (future iterations): explicit per-field in-group ordering, nested
+groups, permission-scoped group visibility beyond `visibleOn`.
+
+---
+
 ## Database Indexing
 
 Optimize query performance with indexes:

skills/objectstack-query/references/_index.md

@@ -6,7 +6,5 @@
 
 ## Core Schemas
 
-- [`data/query.zod.ts`](./data/query.zod.ts) — QueryAST, SortNode, AggregationNode, JoinNode, WindowFunction
-- [`data/filter.zod.ts`](./data/filter.zod.ts) — FilterCondition, FieldOperators, Comparison/Set/String operators
-
-## Dependencies (auto-resolved)
+- [`data/filter.zod.ts`](./data/filter.zod.ts) — Unified Query DSL Specification
+- [`data/query.zod.ts`](./data/query.zod.ts) — Sort Node

…ack-schema/references/data/filter.zod.ts …tack-query/references/data/filter.zod.tsskills/objectstack-schema/references/data/filter.zod.ts renamed to skills/objectstack-query/references/data/filter.zod.ts skills/objectstack-schema/references/data/filter.zod.ts renamed to skills/objectstack-query/references/data/filter.zod.ts

@@ -54,10 +54,25 @@ export const ManifestSchema = z.object({
     .regex(/^[a-z][a-z0-9_]{1,19}$/, 'Namespace must be 2-20 chars, lowercase alphanumeric + underscore')
     .optional()
     .describe('Short namespace identifier for metadata scoping (e.g. "crm", "todo")'),
-  
-  /** 
+
+  /**
+   * Default datasource for all objects in this package.
+   *
+   * When set, all objects defined in this package will use this datasource
+   * by default unless they explicitly override it with their own `datasource` field.
+   *
+   * This provides package-level datasource configuration without needing to
+   * specify it on every individual object.
+   *
+   * @example "memory"  // Use in-memory driver for all package objects
+   * @example "turso"   // Use Turso/LibSQL for all package objects
+   */
+  defaultDatasource: z.string().optional().default('default')
+    .describe('Default datasource for all objects in this package'),
+
+  /**
    * Package version following semantic versioning (major.minor.patch).
-   * 
+   *
    * @example "1.0.0"
    * @example "2.1.0-beta.1"
    */
@@ -77,17 +92,27 @@ export const ManifestSchema = z.object({
    * - adapter: Host adapter (Express, Fastify)
    */
   type: z.enum([
-    'plugin', 
+    'plugin',
     ...CORE_PLUGIN_TYPES,
-    'module', 
+    'module',
     'gateway',  // Deprecated: use 'server'
     'adapter'
   ]).describe('Type of package'),
-  
-  /** 
+
+  /**
+   * Deployment scope of this package.
+   * - `platform`: Provided by the runtime layer (auth, identity, i18n, etc.).
+   *   Never installed per-environment; always globally available.
+   * - `environment`: A business solution (CRM, project management, custom app).
+   *   Installed independently into each environment (Power Apps "solution" model).
+   */
+  scope: z.enum(['platform', 'environment']).default('environment')
+    .describe('Deployment scope: platform (runtime-global) or environment (per-env install)'),
+
+  /**
    * Human-readable name of the package.
    * Displayed in the UI for users.
-   * 
+   *
    * @example "Project Management"
    */
   name: z.string().describe('Human-readable package name'),

…tack-schema/references/data/query.zod.ts …stack-query/references/data/query.zod.tsskills/objectstack-schema/references/data/query.zod.ts renamed to skills/objectstack-query/references/data/query.zod.ts skills/objectstack-schema/references/data/query.zod.ts renamed to skills/objectstack-query/references/data/query.zod.ts

@@ -72,6 +72,7 @@ database table and exposes automatic CRUD APIs.
 | `datasource` | `'default'` | Target datasource ID for virtualized data |
 | `displayNameField` | `'name'` | Field used as record display name |
 | `enable` | — | Capability flags (trackHistory, searchable, apiEnabled, etc.) |
+| `fieldGroups` | — | Ordered list of logical field groups for forms/detail pages (see [Field Groups](#field-groups-mvp)) |
 
 ### Object Capabilities (`enable`)
 
@@ -92,6 +93,48 @@ Toggle system behaviours per object:
 
 ---
 
+## Field Groups (MVP)
+
+Organize fields into logical groups (e.g., "Contact Information", "Billing",
+"System") for forms, detail pages, and editors.
+
+- Declare groups on `ObjectSchema.fieldGroups` — **array order is the display order**.
+- Assign each field to a group via `Field.group`, which references an
+  `ObjectFieldGroup.key`. In-group display order equals the traversal order
+  of `fields`.
+- Group keys must be `snake_case`; group labels are human-readable.
+
+```typescript
+import { ObjectSchema } from '@objectstack/spec';
+
+export default ObjectSchema.create({
+  name: 'account',
+  label: 'Account',
+
+  fieldGroups: [
+    { key: 'contact_info', label: 'Contact Information', icon: 'user' },
+    { key: 'billing',      label: 'Billing', defaultExpanded: false },
+    { key: 'system',       label: 'System',  visibleOn: '$user.isAdmin' },
+  ],
+
+  fields: {
+    name:       { type: 'text',  required: true, group: 'contact_info' },
+    email:      { type: 'email',                  group: 'contact_info' },
+    phone:      { type: 'phone',                  group: 'contact_info' },
+    vat_id:     { type: 'text',                   group: 'billing' },
+    billing_address: { type: 'address',           group: 'billing' },
+    created_at: { type: 'datetime', readonly: true, group: 'system' },
+    created_by: { type: 'lookup', reference: 'user', readonly: true, group: 'system' },
+  },
+});
+```
+
+**Supported migrations at this layer:** add / rename / delete / reorder groups
+(edit the `fieldGroups` array), assign a field to a group (edit `Field.group`).
+Explicit per-field in-group ordering is deferred to a future iteration.
+
+---
+
 ## Quick Reference — Detailed Rules
 
 For comprehensive documentation with incorrect/correct examples:
@@ -299,7 +342,7 @@ When extending an object you do not own:
 - [rules/indexing.md](./rules/indexing.md) — Index types, composite/partial strategies
 - [rules/hooks.md](./rules/hooks.md) — Data lifecycle hooks quick reference (→ [objectstack-hooks](../objectstack-hooks/references/data-hooks.md))
 - [references/data/field.zod.ts](./references/data/field.zod.ts) — FieldType enum, FieldSchema
-- [references/data/object.zod.ts](./references/data/object.zod.ts) — ObjectSchema, capabilities
+- [references/data/object.zod.ts](./references/data/object.zod.ts) — ObjectSchema, capabilities, `ObjectFieldGroupSchema`
 - [references/data/validation.zod.ts](./references/data/validation.zod.ts) — Validation rule types
 - [references/data/hook.zod.ts](./references/data/hook.zod.ts) — Hook schema, HookContext
 - [Schema index](./references/_index.md) — All bundled schemas with dependency tree

skills/objectstack-quickstart/references/kernel/manifest.zod.ts

@@ -8,10 +8,8 @@
 
 - [`data/datasource.zod.ts`](./data/datasource.zod.ts) — Driver Identifier
 - [`data/field.zod.ts`](./data/field.zod.ts) — Field Type Enum
-- [`data/filter.zod.ts`](./data/filter.zod.ts) — Unified Query DSL Specification
 - [`data/hook.zod.ts`](./data/hook.zod.ts) — Hook Lifecycle Events
 - [`data/object.zod.ts`](./data/object.zod.ts) — API Operations Enum
-- [`data/query.zod.ts`](./data/query.zod.ts) — Sort Node
 - [`data/validation.zod.ts`](./data/validation.zod.ts) — ObjectStack Validation Protocol
 - [`security/permission.zod.ts`](./security/permission.zod.ts) — Entity (Object) Level Permissions
 

skills/objectstack-schema/SKILL.md

@@ -211,6 +211,68 @@ export const CDCConfigSchema = z.object({
   destination: z.string().describe('Destination endpoint (e.g., "kafka://topic", "webhook://url")'),
 });
 
+/**
+ * Object Field Group Schema — MVP (data-layer protocol)
+ * 
+ * Declares the set of logical field groups for an object. A group bundles
+ * related fields together for presentation in forms, detail pages, and
+ * editors (e.g., "Contact Info", "Billing", "System").
+ * 
+ * Design rules (MVP):
+ * - Group **order** is the declaration order of this array — no `order` property.
+ * - Field → group mapping is derived automatically from `Field.group`
+ *   matching `ObjectFieldGroup.key`; the **in-group display order** equals
+ *   the traversal order of `ObjectSchema.fields`.
+ * - Fields whose `group` is unset (or references an undeclared key) are
+ *   considered ungrouped and must be rendered by consumers in a default
+ *   bucket after the declared groups, preserving their field declaration order.
+ * - Extension packages and runtime code use `Field.group` to assign fields
+ *   to an existing group — no per-field order property is introduced at this
+ *   layer.
+ * 
+ * Migration operations supported by this MVP:
+ *   - add / rename / delete / reorder groups (via the array)
+ *   - assign an existing field to a group (via `Field.group`)
+ * 
+ * Deferred (not part of MVP):
+ *   - explicit per-field in-group ordering
+ *   - nested groups / sub-groups
+ *   - permission-scoped group visibility beyond `visibleOn`
+ * 
+ * @example
+ * ```ts
+ * fieldGroups: [
+ *   { key: 'contact_info', label: 'Contact Information', icon: 'user' },
+ *   { key: 'billing',      label: 'Billing',             defaultExpanded: false },
+ *   { key: 'system',       label: 'System',              visibleOn: '$user.isAdmin' },
+ * ]
+ * ```
+ */
+export const ObjectFieldGroupSchema = z.object({
+  /** Group key — referenced by `Field.group` to assign a field to this group. Must be snake_case. */
+  key: z.string().regex(/^[a-z_][a-z0-9_]*$/, {
+    message: 'Field group key must be lowercase snake_case (e.g., "contact_info", "billing", "system")',
+  }).describe('Group machine key (snake_case). Referenced by Field.group.'),
+
+  /** Human-readable label displayed as the group header. */
+  label: z.string().describe('Group display label'),
+
+  /** Optional Lucide/Material icon name for the group header. */
+  icon: z.string().optional().describe('Icon name (Lucide/Material) for the group header'),
+
+  /** Optional description / help text shown under the group header. */
+  description: z.string().optional().describe('Optional description shown under the group header'),
+
+  /** Whether the group is expanded by default. Defaults to `true`. */
+  defaultExpanded: z.boolean().optional().default(true).describe('Whether the group is expanded by default'),
+
+  /** Optional visibility expression — when false, the entire group is hidden (e.g., "$user.isAdmin", "status == \'closed\'"). */
+  visibleOn: z.string().optional().describe('Visibility condition expression; when false the group is hidden'),
+});
+
+export type ObjectFieldGroup = z.infer<typeof ObjectFieldGroupSchema>;
+export type ObjectFieldGroupInput = z.input<typeof ObjectFieldGroupSchema>;
+
 /**
  * Base Object Schema Definition
  * 
@@ -282,6 +344,23 @@ const ObjectSchemaBase = z.object({
     message: 'Field names must be lowercase snake_case (e.g., "first_name", "company", "annual_revenue")',
   }), FieldSchema).describe('Field definitions map. Keys must be snake_case identifiers.'),
   indexes: z.array(IndexSchema).optional().describe('Database performance indexes'),
+
+  /**
+   * Field Groups (MVP)
+   * 
+   * Declares logical groups for presenting fields in forms and detail
+   * pages. The **array order is the group display order**. Each field's
+   * `Field.group` references an entry's `key` to assign it to a group;
+   * within a group, fields are displayed in their `ObjectSchema.fields`
+   * declaration order.
+   * 
+   * See {@link ObjectFieldGroupSchema} for the full MVP contract and
+   * deferred features.
+   */
+  fieldGroups: z.array(ObjectFieldGroupSchema).refine(
+    (groups) => new Set(groups.map(g => g.key)).size === groups.length,
+    { message: 'fieldGroups[].key must be unique within an object' },
+  ).optional().describe('Ordered list of field groups (array order = display order). See ObjectFieldGroupSchema.'),
 
   /**
    * Advanced Data Management

skills/objectstack-schema/references/_index.md

@@ -253,6 +253,12 @@ export const DashboardSchema = z.object({
   /** Collection of widgets */
   widgets: z.array(DashboardWidgetSchema).describe('Widgets to display'),
 
+  /** Grid column count — defaults to 12 for a standard 12-column grid */
+  columns: z.number().int().min(1).max(24).optional().describe('Number of grid columns (default 12)'),
+
+  /** Grid gap in Tailwind spacing units (e.g. 4 = 1rem) */
+  gap: z.number().int().min(0).optional().describe('Grid gap in Tailwind spacing units'),
+
   /** Auto-refresh */
   refreshInterval: z.number().optional().describe('Auto-refresh interval in seconds'),