From 9895a850c4f8440cd26d87db53b8c4917dd7706f Mon Sep 17 00:00:00 2001
From: os-zhuang <jack@objectstack.ai>
Date: Sat, 27 Jun 2026 01:03:23 +0800
Subject: [PATCH] docs: document the `user` field type
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Follow-up to #2351 (the `user` field type). Brings the docs in line with the
shipped feature:

- references/data/field.mdx + seed-loader.mdx — regenerated (`gen:docs`) so the
  FieldType / reference enums list `user` (the merge added the type but didn't
  regenerate these committed reference pages).
- guides/data-modeling.mdx — new "User Fields" section: `Field.user()`,
  `multiple`, `defaultValue: 'current_user'`, and that it's a lookup specialized
  to sys_user (stored as an FK, zero-migration from `Field.lookup('sys_user')`).
- guides/standards.mdx — adds a User/Person row to the field-type selection table.

Only the user-related regenerated lines are included; unrelated generated-doc
drift was intentionally left out.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 content/docs/guides/data-modeling.mdx        | 26 ++++++++++++++++++++
 content/docs/guides/standards.mdx            |  1 +
 content/docs/references/data/field.mdx       |  1 +
 content/docs/references/data/seed-loader.mdx |  2 +-
 4 files changed, 29 insertions(+), 1 deletion(-)

diff --git a/content/docs/guides/data-modeling.mdx b/content/docs/guides/data-modeling.mdx
index 6855e7f211..a53198a4f1 100644
--- a/content/docs/guides/data-modeling.mdx
+++ b/content/docs/guides/data-modeling.mdx
@@ -263,6 +263,32 @@ Field.lookup('contact', {
 })
 ```
 
+### User Fields
+
+Pick a person — the equivalent of Airtable's *Collaborator* or Salesforce's
+`Lookup(User)`. A `user` field is a **lookup specialized to the built-in
+`sys_user` object**: it stores the user's id (a real foreign key), resolves to
+the user's name/avatar via `$expand`, and renders as a searchable people picker.
+You never reference `sys_user` by hand.
+
+```typescript
+// Single assignee
+Field.user({ label: 'Assignee' })
+
+// Collaborators / watchers (multiple)
+Field.user({ label: 'Watchers', multiple: true })
+
+// Auto-fill the acting user on create (record owner / reporter)
+Field.user({ label: 'Owner', defaultValue: 'current_user' })
+```
+
+`defaultValue: 'current_user'` stamps the authenticated user's id at insert time
+(the people-field counterpart to `'NOW()'` for timestamps). Because a `user`
+field is stored exactly like a lookup, an existing `Field.lookup('sys_user')`
+is equivalent at the storage layer — adopt `Field.user()` with no data
+migration. Record ownership and row-level security continue to use the existing
+`owner_id` convention.
+
 ### Address Field
 
 Structured address data:
diff --git a/content/docs/guides/standards.mdx b/content/docs/guides/standards.mdx
index 3c73b0a46e..8a56b20e44 100644
--- a/content/docs/guides/standards.mdx
+++ b/content/docs/guides/standards.mdx
@@ -146,6 +146,7 @@ export const MyObject = ObjectSchema.create({
 | Choice | `Field.select()` | Status, category, type |
 | Multiple choice | `Field.select({ multiple: true })` | Tags, skills |
 | Reference | `Field.lookup()` | Relationships |
+| User / Person | `Field.user()` | Assignee, owner, collaborators (picks a `sys_user`) |
 | Location | `Field.location()` | GPS coordinates |
 | Address | `Field.address()` | Mailing addresses |
 | Color | `Field.color()` | Brand colors, themes |
diff --git a/content/docs/references/data/field.mdx b/content/docs/references/data/field.mdx
index 7af95bcdc6..1b901ec805 100644
--- a/content/docs/references/data/field.mdx
+++ b/content/docs/references/data/field.mdx
@@ -120,6 +120,7 @@ const result = Address.parse(data);
 * `lookup`
 * `master_detail`
 * `tree`
+* `user`
 * `image`
 * `file`
 * `avatar`
diff --git a/content/docs/references/data/seed-loader.mdx b/content/docs/references/data/seed-loader.mdx
index a07bb92737..7809f223ad 100644
--- a/content/docs/references/data/seed-loader.mdx
+++ b/content/docs/references/data/seed-loader.mdx
@@ -94,7 +94,7 @@ Describes how a field reference is resolved during seed loading
 | **field** | `string` | ✅ | Source field name containing the reference value |
 | **targetObject** | `string` | ✅ | Target object name (snake_case) |
 | **targetField** | `string` | ✅ | Field on target object used for matching |
-| **fieldType** | `Enum<'lookup' \| 'master_detail'>` | ✅ | Relationship field type |
+| **fieldType** | `Enum<'lookup' \| 'master_detail' \| 'user'>` | ✅ | Relationship field type |
 
 
 ---