feat: describe-ui --no-raw and skill guidance to keep agent context small

[4faramita]

Summary

Two changes that reduce what an agent pays to read the screen:

1. describe-ui --no-raw (top-level, ios, android): with --json, omit the raw accessibility tree (data.raw) from the envelope. outline / entries / lists are unchanged.
2. A Keeping output small section in the bundled skill: prefer the text outline, pair --json with --no-raw, verify via the outline instead of screenshots, reuse the verify read as the next observe, batch known sequences.

Default behavior is untouched: bare describe-ui still prints the text outline, and --json without --no-raw still carries raw.

Measured savings

On a real app screen (40 outline entries; tokens estimated at ~4 ASCII chars/token, screenshots per Claude's pixel formula):

Change	Before	After	Saving
--no-raw on ui --json	26.6 KB ≈ 6,600 tokens	9.7 KB ≈ 2,400 tokens	-63%
Skill: text outline instead of --json	≈ 6,600 tokens/call	≈ 520 tokens/call	-92%
Skill: verify via outline, not screenshot	≈ 1,500 tokens/shot	≈ 520 tokens	-65%
Skill: reuse verify read as next observe	2 ui reads/step	1 read/step	-45% reads

Combined on a 10-step agent task: -39% (agent already on the text loop) to -80% (agent on a --json loop) total context consumption.

Before / after

The default text outline (unchanged):

App: OrderDemo  402x874

[Top  y<120]
  @1  StaticText  "09:41"  (51,22 46x20)
  @2  RadioButton  "Orders"  (20,66 81x36)  selected
  @3  RadioButton  "Cart"  (101,66 73x36)

[Content  y=120..754]
  @8 #1  Cell  "Order #1024, 2 items"  (0,120 402x76)
  @9 #2  Cell  "Order #1023, 5 items"  (0,196 402x76)

ui --json, before (and still the default):

{
  "ok": true,
  "data": {
    "appLabel": "OrderDemo",
    "entries": [ /* full labels, frames, states */ ],
    "lists":   [ /* … */ ],
    "outline": "…",
    "raw":     { /* full AX tree: ~70% of the payload */ },
    "screen":  { /* … */ }
  }
}

ui --json --no-raw:

{
  "ok": true,
  "data": {
    "appLabel": "OrderDemo",
    "entries": [ /* identical */ ],
    "lists":   [ /* identical */ ],
    "outline": "…",
    "screen":  { /* identical */ }
  }
}

When --json is still used, and why quality is unaffected

describe-ui defaults to the text outline; agents reach for --json in two cases: coordinate math on entries[].frame / screen, and full untruncated label / value (the outline truncates labels at 60 graphemes, values at 30). Both live in entries, not in raw.

With --no-raw the envelope is byte-identical minus the raw key. raw is a debugging passthrough with no in-repo consumer (the Viewer included), no skill workflow reads it, and selector resolution (@N, --label) happens CLI-side against the AX snapshot, independent of what the agent read. Dropping it also keeps large screens from pushing the payload past agent-harness output truncation (30,000 chars in Claude Code) mid-JSON, which previously produced unparseable output and retries.

Tests

• Tests/DescribeUINoRawTests.swift: flag parses on all three surfaces, the top-level forwarder copies it, and a result built without the tree encodes no raw key at all (not "raw": null). make test: 822 green.
• Live spot check on a booted simulator: default text and default --json outputs byte-identical to before (modulo the status-bar clock); --no-raw envelope identical minus raw.