docs: rebalance prose cleanup and add trimming skill

packages/ui/user-approval/README.md

@@ -6,6 +6,6 @@ Each request must belong to an open agent turn. The service appends a paired `ap
 
 Answerers are `approval/request` waterfall listeners. Return an outcome to answer for an owned agent or call `next()` to delegate. Agent-scoped listeners receive only that agent's requests; compose one terminal answerer per deployment because sibling listener order is not a policy priority mechanism. The ACP bridge is the shipped human answerer.
 
-`ApprovalPolicy` is `'ask'` or `'never'`. The effective value is the last `approval/policy` event, falling back to config; `setApprovalPolicy()` is the write path. `'never'` rejects before interactive dispatch and is exposed to the model through the prompt and a coalesced switch notice.
+`ApprovalPolicy` is `'ask'` or `'never'`. The effective value is the last `approval/policy` event, falling back to config; `setApprovalPolicy()` is the write path. `'never'` rejects before interactive dispatch and is the only policy stated in the prompt. Switches produce at most one coalesced notice whose header marker distinguishes user changes from operator/config changes.
 
 The tools pipeline consumes this seam for `ask` decisions and the sandboxed bash tool uses it for escalated retries. See the [approval-seam RFC](../../../docs/rfc/implemented/feature/2026-07-06-approval-seam.md) and [sandbox RFC](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md).

packages/ui/user-approval/src/index.ts

@@ -171,7 +171,8 @@ function hasOpenTurn(events: readonly SessionEvent[]): boolean {
 }
 
 /**
- * Append the sole durable representation of a session policy override.
+ * Append the sole durable representation of a session policy override. Invalid
+ * values throw before the log changes; consumers fold the new value on each read.
  * @param session - the session the override belongs to.
  * @param policy - the policy in effect until the next switch.
  */

packages/ui/user-approval/tests/approval.spec.ts

@@ -438,7 +438,7 @@ describe('approval policy (the approval/policy fold)', () => {
   it('never is unbypassable even by an answerer PREPENDED after the service mounts', async () => {
     // Cordis prepend unshifts ahead of every existing listener, including any gate LISTENER the
     // service could register — which is exactly why the 'never' decision lives inside request()
-    // instead.
+    // instead. This eager grant would bypass a listener-based gate and therefore must never run.
     const ctx = new Context()
     await ctx.plugin(ApprovalService, { policy: 'never' })
     const consulted = vi.fn()