Update README

1 files changed, 58 insertions, 25 deletions

diff --git a/README.md b/README.md
index 36e89db..f338808 100644
--- a/README.md
+++ b/README.md
@@ -1,16 +1,58 @@
 # cogops
 
-`cogops` is a command-line tool for performing batch operations on AWS Cognito user pools.\
-It supports synchronizing users into a local file, adding users to groups, and removing users from groups.
+`cogops` is a command-line tool for performing batch operations on AWS Cognito
+user pools.\
+It supports synchronizing users into a local file, adding users to groups, and
+removing users from groups.
 
-This project is designed to be simple, predictable, and operational-friendly.
+## Why
 
----
+Some of our internal systems rely on AWS Cognito Group membership for
+authorization. However, Cognito:
+
+- Does not support batch operations
+- Requires the opaque Cognito username for group changes
+- Does not allow group operations using the user’s email
+- Can throttle if performing requests per user per group
+- Each user lookup by email requires a full search query
+
+### Command sync Required?
+
+Our Cognito User Pool integrates with Google Identity Provider.
+
+Cognito usernames look like: **Google_AbCdEf1234567890**
+
+Emails are stored only as attributes and cannot be passed to Cognito Admin
+APIs. Other internal systems only know users by email — mismatch.
+
+Solution, the sync command downloads all users via paginated calls:
+
+```
+username,email
+Google_a3be23de...,user@example.com
+Google_91cfeacb...,another@example.com
+```
+
+This creates a local, up-to-date user index so later add and del operations
+run:
+
+- 1 direct request per user
+- No additional lookup/search required
+- No wasted API calls
+
+## Features
+
+- sync: Generates an optimized local mapping username,email of all Cognito
+  users
+- add: Add users in bulk to one or more groups
+- Concurrency Control
+- Operation timetout
 
 ## Requirements
 
 - Rust toolchain (Rust 1.75 or newer recommended)
-- AWS credentials with Administrator privileges for the target Cognito user pool
+- AWS credentials with Administrator privileges for the target Cognito user
+  pool
 - Access to the AWS API (environment variables, credential file, or IAM role)
 
 To install Rust:
@@ -26,8 +68,6 @@ rustc --version
 cargo --version
 ```
 
----
-
 ## Building
 
 Clone the repository and build the binary:
@@ -46,11 +86,10 @@ target/release/cogops
 
 You can add it to your PATH or move it to `/usr/local/bin`.
 
----
-
 ## AWS Credentials
 
-`cogops` uses the official AWS Rust SDK and respects all standard credential providers.
+`cogops` uses the official AWS Rust SDK and respects all standard credential
+providers.
 
 For example:
 
@@ -76,11 +115,10 @@ export AWS_REGION=us-east-1
 3. `del`\
    Remove users from one or more Cognito groups.
 
----
-
 ## 1. Synchronizing users (sync)
 
-This operation reads all users from the provided Cognito User Pool ID and writes them to a CSV file.
+This operation reads all users from the provided Cognito User Pool ID and
+writes them to a CSV file.
 
 Example:
 
@@ -99,8 +137,6 @@ carol,carol@example.com
 
 This file is later used by the `add` and `del` operations.
 
----
-
 ## 2. Adding users to groups (add)
 
 This operation requires two input files:
@@ -113,7 +149,7 @@ All emails will be normalized (lowercase, trim) before lookup.
 Example:
 
 ```
-cogops add   --pool-id us-east-1_ABC123   --sync-file cognito_sync.csv   --emails-file to_add.txt   --group admin   --group managers   --concurrency 10
+cogops add --pool-id us-east-1_ABC123   --sync-file cognito_sync.csv   --emails-file to_add.txt   --group admin   --group managers   --concurrency 10
 ```
 
 Where `to_add.txt` might contain:
@@ -124,15 +160,15 @@ carol@example.com
 john@example.com
 ```
 
-For each email, `cogops` resolves the username from the sync map and calls the Cognito Admin API to add the user to the specified groups.
+For each email, `cogops` resolves the username from the sync map and calls the
+Cognito Admin API to add the user to the specified groups.
 
 A progress bar is displayed during processing.
 
----
-
 ## 3. Removing users from groups (del) (WIP)
 
-This command mirrors the `add` command but removes users instead of adding them.
+This command mirrors the `add` command but removes users instead of adding
+them.
 
 Example:
 
@@ -140,8 +176,6 @@ Example:
 cogops del   --pool-id us-east-1_ABC123   --sync-file cognito_sync.csv   --emails-file to_remove.txt   --group admin   --concurrency 5
 ```
 
----
-
 ## Logging and verbosity
 
 `cogops` uses `tracing` for structured logging.
@@ -159,8 +193,7 @@ Or configure via `RUST_LOG`:
 RUST_LOG=debug cogops add ...
 ```
 
----
-
 ## License
 
-Licensed under ISC license ([LICENSE](LICENSE) or https://opensource.org/licenses/ISC)
+Licensed under ISC license ([LICENSE](LICENSE) or
+https://opensource.org/licenses/ISC)