diff --git a/content/docs/automation/approvals.mdx b/content/docs/automation/approvals.mdx
index 592e26199..a3d48ba44 100644
--- a/content/docs/automation/approvals.mdx
+++ b/content/docs/automation/approvals.mdx
@@ -130,14 +130,10 @@ record is **locked** against edits while pending (`lockRecord`, default `true`),
 and the flow run parks until a decision arrives.
 
 Only `approvers` is required on the node; everything else has a default
-(`behavior: 'first_response'`, `lockRecord: true`, `maxRevisions: 3`).
-
-<Callout type="warn">
-**`type: 'role'` is not a position.** In an approver entry, `role` means the
-better-auth membership tier (`owner` / `admin` / `member`). Naming a business
-role like `sales_manager` there matches nobody and the request silently has no
-approvers — use `{ type: 'position', value: 'sales_manager' }`.
-</Callout>
+(`behavior: 'first_response'`, `lockRecord: true`, `maxRevisions: 3`). An
+approver entry that resolves to no users falls back to a literal `<type>:<value>`
+slot that no one matches, so the request opens and then stalls — see the
+approver-type warning under [The approval node](#3-the-approval-node).
 
 ### The approver finds it in their queue
 
@@ -150,10 +146,10 @@ curl -b cookies.txt \
   "https://your-app.example.com/api/v1/approvals/requests?status=pending&approverId=usr_123"
 ```
 
-`approverId` accepts a user id, an email, or `role:<r>` — and takes several
-values (comma-separated or repeated) to cover a person's identities in one call.
-Other filters: `status`, `object`, `recordId`, `submitterId`, `q`, `limit`,
-`offset`.
+`approverId` accepts a user id, an email, or a `<type>:<value>` approver literal
+(`position:finance_manager`) — and takes several values (comma-separated or
+repeated) to cover a person's identities in one call. Other filters: `status`,
+`object`, `recordId`, `submitterId`, `q`, `limit`, `offset`.
 
 <Callout type="warn">
 **Opening a request notifies nobody.** There is no built-in "you have an