From 7c3fb5cbda3a9ffa92b4eab630602d510a001bc3 Mon Sep 17 00:00:00 2001
From: phil-accelbyte <225106921+phil-accelbyte@users.noreply.github.com>
Date: Tue, 5 May 2026 09:37:10 +0800
Subject: [PATCH] docs(readme): replace invalid command examples with valid
 ones

The Quick Start, API scope/version, and Exploring Commands sections
referenced commands that don't exist or use the wrong flag form:

- 'iam users list' -> 'iam users search' (no list method on users)
- '--userId' -> '--user-id' (kebab-case is the parser-recognised form)
- 'iam users get 123' -> 'iam roles get --role-id my-role'
  (positional args aren't accepted, and iam users get only supports
  admin/v3 so the multi-scope/multi-version example never worked;
  iam roles get genuinely covers admin v3+v4 and public v3)
---
 README.md | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index c8f2f80..0586ce4 100644
--- a/README.md
+++ b/README.md
@@ -102,20 +102,20 @@ Running `ags completions` without an argument detects the shell from `$SHELL` (o
 # Authenticate using the authorization code flow
 ags auth login
 
-# List IAM users
-ags iam users list --namespace my-game
+# Search users in a namespace
+ags iam users search --namespace my-game
 
 # Inspect a specific user
-ags iam users get --userId abc-123 --namespace my-game
+ags iam users get --namespace my-game --user-id abc-123
 
 # Preview a request without sending it
-ags iam users list --namespace my-game --dry-run
+ags iam users search --namespace my-game --dry-run
 
 # Generate a request body template
 ags iam roles create --skeleton > body.json
 
 # Discover commands programmatically (JSON)
-ags describe iam users list
+ags describe iam users search
 ```
 
 ## Usage
@@ -154,10 +154,10 @@ Generated service commands resolve to a contract — the combination of command,
 | `--api-version <vN>` | Pin a specific API version for the resolved scope |
 
 ```bash
-ags iam users get 123                                       # admin scope, default version
-ags iam users get 123 --api-scope public                    # public scope, default version
-ags iam users get 123 --api-version v3                      # admin scope, v3
-ags iam users get 123 --api-scope public --api-version v2   # fully pinned
+ags iam roles get --role-id my-role                                     # admin scope, default version
+ags iam roles get --role-id my-role --api-scope public                  # public scope, default version
+ags iam roles get --role-id my-role --api-version v3                    # admin scope, v3
+ags iam roles get --role-id my-role --api-scope public --api-version v3 # fully pinned
 ```
 
 Both flags only appear on commands that offer a choice. Run `ags describe <service> <resource> <method>` to see the full scope/version matrix for a command, including the default contract and supported versions per scope.
@@ -186,7 +186,7 @@ For machine-readable discovery, use `ags describe` instead of `--help`. It outpu
 ags describe
 
 # Introspect a specific command
-ags describe iam users list
+ags describe iam users search
 ```
 
 ## Authentication