docs: killer README + install/update system

[james-s-hedwig]

Summary

Complete overhaul: human-first README, definitions table, use cases, agent guide, docs structure, cua update command, install.sh polish.

Changes

README.md — complete rewrite

• Leads with the pain: agents are blind without this
• Code demo at the top, speaks for itself
• Key Concepts table: every term defined before it's used (cuad, cua, ref, snapshot, pipe, transport, AX, CDP, AppleScript)
• 5 real use cases with code (Mail inbox, native form fill, locked screen Safari, screenshot + vision, assert in tests)
• Two agent integration examples: OpenClaw skill snippet + Python tool loop
• Performance numbers kept but reframed with "so what"
• All install methods + cua update

docs/QUICKSTART.md (new)

• Grant Accessibility permission step by step
• Grant Safari JS permission
• Start the daemon
• 5 commands to try right now
• Troubleshooting: empty snapshots, Safari failures, daemon issues

docs/AGENT-GUIDE.md (new)

• Full snapshot→act loop with code
• How to use refs safely (ref stability rules)
• When to use pipe vs snapshot+act
• Web automation guide
• Error handling: transport failure, locked screen, missing ref, daemon not running
• Pagination for large UIs
• OpenClaw skill example
• Best practices (7 rules)
• Full login flow example

docs/INSTALL.md (new)

• All install methods: Homebrew, shell script, build from source, manual binary
• Permissions setup (Accessibility + Safari JS) with step-by-step
• PATH setup for bash, zsh, fish
• Update section: cua update, Homebrew, re-run install.sh
• Version check: cua --version, update notice
• Uninstall instructions

cua update command (new)

• cua update — checks GitHub releases API, compares with current version, downloads and installs if newer
• cua update --check — check without installing
• Version notice: on each cua invocation, checks ~/.cua/version-check.json cache, prints notice if newer version available
• Background API check max once per 24h, stores result to ~/.cua/version-check.json

install.sh — polished

• Shows version being installed (fetches from GitHub API before download)
• Detects shell (bash/zsh/fish) for PATH suggestion
• --version flag: prints latest available version without installing
• After install: "Run cua update anytime to get the latest version"
• Updated REPO to armsteadj1/claw-use

skills/computer-use/SKILL.md — updated

• Added wait and assert command reference
• Added cua update and cua update --check to maintenance section
• Added locked-screen tip