diff --git a/.agents/skills/inkreach-teable/api-reference/trigger-types.md b/.agents/skills/inkreach-teable/api-reference/trigger-types.md
index f6660e9..3c6c116 100644
--- a/.agents/skills/inkreach-teable/api-reference/trigger-types.md
+++ b/.agents/skills/inkreach-teable/api-reference/trigger-types.md
@@ -61,7 +61,14 @@ inkreach-teable trigger set <wfId> --type recordUpdated --table-id tblXXX \
 - ⚠️ **Key is `fieldIds`, NOT `watchFieldIds`.**
 - ⚠️ recordUpdated **ignores `conditions`** — use `recordCondition` if you need filtering.
 
-**Output:** `record.id`, `record.fields.*`, `record.oldFields.*` (pre-update values), `user`, `tableId`, `changedFieldIds`.
+**Output:** `record.id`, `record.fields.*` (post-update values), `record.oldFields.*` (pre-update values, field-ID keys), `user`, `tableId`, `changedFieldIds` (array of field IDs whose value changed).
+
+**changedFieldIds / oldFields semantics** (delivered on both v1 and v2 API update paths):
+- `oldFields` = full pre-update field snapshot keyed by field ID; `changedFieldIds` = deep-equal diff of before/after snapshots.
+- `fieldIds` watch-filter matches against `changedFieldIds`.
+- On batch mode (`_batch`), each `records[]` entry carries its own `changedFieldIds` + `oldFields`.
+- ⚠️ **Fires on REST API record updates only** (`PATCH /api/table/{tableId}/record[/{recordId}]`, including programmatic/automation writes). Browser grid cell edits go through ShareDB ops and do **not** fire this trigger.
+- Values resolve to `undefined` (not `[]`) if the emitting path could not snapshot before-values — scripts should guard `changedFieldIds ?? []`.
 
 ---
 
@@ -96,7 +103,7 @@ inkreach-teable trigger set <wfId> --type recordCondition --table-id tblXXX \
 ```
 Common operators: `is`, `isNot`, `isEmpty`, `isNotEmpty`, `isAnyOf`, `isNoneOf`, `contains`, `isGreater`, `isLess`, `isAfter`, `isBefore`.
 
-**Output:** `record.id`, `record.fields.*`, `record.oldFields.*`, `user`, `tableId`.
+**Output:** `record.id`, `record.fields.*`, `user`, `tableId`; on update events also `record.oldFields.*` + `changedFieldIds` (see §2 semantics).
 
 ---
 
@@ -115,7 +122,7 @@ inkreach-teable trigger set <wfId> --type recordCreatedOrUpdated --table-id tblX
 - Ignores `fieldIds` (watches all fields).
 - `conditions` optional.
 
-**Output:** same as recordCreated + `record.oldFields.*` on updates.
+**Output:** same as recordCreated; on update events also `record.oldFields.*` + `changedFieldIds` (see §2 semantics).
 
 ---