docs(approvals): unbreak the role-word ratchet after the lifecycle walkthrough

#3113's approval walkthrough pushed approvals.mdx from 5 to 9 uses of the
reserved word (ADR-0090 D3), which fails check-role-word on every PR cut
from main since.

Most were avoidable prose ("a business role like…", "`role:<r>`") and are
reworded to the canonical vocabulary. The one that remains is the warning
that the `type: 'role'` approver resolves against the better-auth
membership tier rather than a position — naming the literal enum value is
the point of the warning, and the better-auth boundary is exactly the
legitimate case the ratchet's own header calls out. Baseline ratcheted
5 → 6 for that one.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: os-zhuang

content/docs/automation/approvals.mdx

@@ -133,10 +133,11 @@ 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' }`.
+**The `type: 'role'` approver is not a position.** That approver kind resolves
+against the better-auth membership tier (`owner` / `admin` / `member`) — not
+your business hierarchy. Pointing it at something like `sales_manager` matches
+nobody, and the request silently ends up with no approvers. Use
+`{ type: 'position', value: 'sales_manager' }` instead.
 </Callout>
 
 ### The approver finds it in their queue
@@ -150,8 +151,9 @@ 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.
+`approverId` accepts a user id, an email, or a membership-tier reference — 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`.
 

scripts/role-word-baseline.json

@@ -3,7 +3,7 @@
   "content/docs/ai/index.mdx": 2,
   "content/docs/api/error-catalog.mdx": 1,
   "content/docs/api/wire-format.mdx": 1,
-  "content/docs/automation/approvals.mdx": 5,
+  "content/docs/automation/approvals.mdx": 6,
   "content/docs/automation/hooks.mdx": 1,
   "content/docs/concepts/architecture.mdx": 4,
   "content/docs/concepts/metadata-lifecycle.mdx": 1,