docs(readme): spell out capabilities above the fold

README.md

@@ -5,13 +5,42 @@ tasks, projects, areas and tags straight from the Things3 SQLite database
 (read-only) and writes via the `things:///` URL scheme and AppleScript — so the
 app stays the source of truth and your data never leaves the machine.
 
-**AI-friendly by design.** Every command speaks JSON (`-j` / `--json`) for
-clean piping into `jq`, agents, or scripts. A bundled agent skill ships in
-the binary itself — `things skill install claude` drops it into Claude
-Code, and `things skill show` prints the neutral source so you can append
-it to whatever your agent reads for instructions (e.g. a project
-`AGENTS.md` for Codex). Install once and your agent knows when to reach
-for `things` instead of guessing at AppleScript.
+```sh
+things                                 # today's tasks
+things inbox -j | jq                   # JSON for piping into anything
+things add "Buy milk" --when today --tags errand
+things edit 3 --add-tags urgent --deadline 2026-05-01
+things complete "Pay rent"             # by title, with interactive disambig
+things search migrate                  # full-text across titles + notes
+things open --project "Launch"         # reveal in the Things app
+```
+
+What it does:
+
+- **List & inspect** every built-in view (`today`, `inbox`, `upcoming`,
+  `anytime`, `someday`, `logbook`, `trash`, `deadlines`) plus projects,
+  areas, tags, and full-text search
+- **Create** tasks and projects with notes, schedules, deadlines, tags,
+  checklists, and headings
+- **Edit** anything mutable via `things:///update` — only the flags you
+  pass are sent, so unset fields stay untouched
+- **Complete, cancel, log**, or **reveal** items in the app
+- **Import** [Things JSON URL scheme](https://culturedcode.com/things/support/articles/2803573/)
+  payloads in bulk
+- **JSON everywhere** — every command supports `-j` / `--json` for clean
+  piping into `jq`, agents, or scripts
+
+**Teach your agent to drive it.** A bundled skill ships in the binary —
+install it once and your agent knows when to reach for `things` instead
+of guessing at AppleScript:
+
+```sh
+things skill install claude            # also: codex, pi
+```
+
+For other agents, `things skill show` prints the neutral source so you can
+append it to whatever your agent reads for instructions (e.g. a project
+`AGENTS.md`).
 
 ## CLI
 
@@ -64,6 +93,20 @@ things "Weekly Review"            # tasks in a project by name
 things -a Work                    # tasks in an area
 ```
 
+Output groups by project or area; numeric indices are stable for follow-up
+commands until the next listing:
+
+```text
+$ things
+    Launch v2
+1.  [ ]  Draft release notes      [docs]      today
+2.  [ ]  Cut RC build                          due:2026-04-30
+
+    Errands
+3.  [ ]  Buy milk                 [shopping]
+4.  [x]  Pick up dry cleaning
+```
+
 ### Inspecting tasks, projects, areas, tags
 
 | Command | Description |
@@ -84,6 +127,35 @@ things show "Pay rent"            # by title (interactive disambig)
 things search migrate             # full-text search
 ```
 
+```text
+$ things show 2
+Title:    Cut RC build
+UUID:     8K3FpQ2eRtNbHwpNiM71Eu
+Status:   Open
+Project:  Launch v2
+Tags:     release
+Deadline: 2026-04-30
+Created:  2026-04-12 09:14
+Notes:
+  Coordinate with marketing before tagging.
+Checklist:
+  [x] Bump version
+  [ ] Update changelog
+  [ ] Tag and push
+```
+
+`things projects` renders a one-line-per-project list; the leading glyph
+shows completion progress (`○` empty, `◔ ◑ ◕` partial, `●` done, `◌`
+cancelled):
+
+```text
+$ things projects
+◑  Launch v2          Work
+◔  Migrate API        Work
+○  Garden plan        Home
+●  Spring cleaning    Home
+```
+
 ### Creating tasks and projects
 
 `things add <title>` creates a task. `things project add <title>` creates a