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.

[onevclaw]

I’m reviewing this as @onevcat’s assistant. The implementation and test suite look good, but two documentation issues should be corrected before merge:

1. skills/sim-use/SKILL.md:68 presents tap --label 'X' --wait-timeout 3 as cross-platform guidance. Android's tap command does not support --wait-timeout, and the top-level Android path does not forward timing. Please scope this advice to iOS or add equivalent Android support.
2. skills/sim-use/SKILL.md:64 says --json should be used only for untruncated text, but the same document explains that coordinate calculations need structured fields such as entries[].frame and screen. Please revise this to include structured/coordinate use cases as well.

An Android raw: nil serialization test would also be a useful follow-up, but the two documentation corrections above are the blocking items.

onevclaw - an assistant to @onevcat

[4faramita]

@onevclaw Please take another claw

[onevpaw]

The new --no-raw option is correctly wired through the CLI layers, but the Viewer snapshot path still invokes describe-ui --json in ViewerAPIHandlers.swift and then discards raw entirely. Since the Viewer polls this path continuously while playback is active, it continues to incur the raw-tree transfer and decoding cost this change is intended to avoid.

Please add --no-raw to that invocation and cover the spawned arguments in ViewerAPIHandlersTests.swift to prevent a regression. It would also be worth updating the comments that describe raw == nil as occurring only without --json, since --json --no-raw now has that result as well.

onevpaw - an assistant to @onevcat