docs: update usage docs

Author: vjeeva

docs/usage.md

@@ -21,8 +21,8 @@ $ belt [OPTIONS] COMMAND [ARGS]...
 * `dst-dsn`: Print a dsn to stdout that you can use to...
 * `check-pkeys`: Print out lists of tables with and without...
 * `check-connectivity`: Returns exit code 0 if pgbelt can connect...
-* `revoke-logins`: Discovers all users in the db who can log...
-* `restore-logins`: Grant permission to log in for any user...
+* `revoke-logins`: Discovers all users who can log in and...
+* `restore-logins`: Discovers all roles that currently have...
 * `precheck`: Report whether your source database meets...
 * `reset`: Reset an in-progress migration before...
 * `dump-schema`: Dumps and sanitizes the schema from the...
@@ -40,6 +40,7 @@ $ belt [OPTIONS] COMMAND [ARGS]...
 * `analyze`: Run ANALYZE in the destination database.
 * `validate-data`: Compares data in the source and target...
 * `sync`: Sync and validate all data that is not...
+* `diff-sequences`: Compare source and destination sequence...
 * `teardown-back-replication`: Stops pglogical replication from the...
 * `teardown-forward-replication`: Stops pglogical replication from the...
 * `teardown`: Removes all pglogical configuration from...
@@ -188,10 +189,8 @@ $ belt check-connectivity [OPTIONS] DC [DB]
 
 ## `belt revoke-logins`
 
-Discovers all users in the db who can log in, saves them in the config file,
-then revokes their permission to log in. Use this command to ensure that all
-writes to the source database have been stopped before syncing sequence values
-and tables without primary keys.
+Discovers all users who can log in and revokes their permission.
+Stateless — queries pg_roles each time rather than caching a user list.
 
 Always excludes built-in service accounts (pglogical, rdsadmin, monitoring, etc.).
 Use --exclude-user to exclude additional specific usernames.
@@ -225,10 +224,11 @@ $ belt revoke-logins [OPTIONS] DC [DB]
 
 ## `belt restore-logins`
 
-Grant permission to log in for any user present in the config file. The user
-must already have a password. This will not generate or modify existing
-passwords for users.
+Discovers all roles that currently have NOLOGIN and re-enables login for
+them, excluding built-in service accounts and any roles specified via
+--exclude-user / --exclude-pattern.
 
+This is stateless — it does not rely on a previously saved user list.
 Intended to be used after revoke-logins in case a rollback is required.
 
 
@@ -250,6 +250,8 @@ $ belt restore-logins [OPTIONS] DC [DB]
 **Options**:
 
 * `--json`: Output structured JSON instead of human-readable tables.
+* `-e, --exclude-user TEXT`: Additional usernames to exclude from restoration (can be repeated).
+* `-p, --exclude-pattern TEXT`: SQL LIKE patterns to exclude usernames (e.g. '%%myapp%%'). Can be repeated.
 * `--help`: Show this message and exit.
 
 ## `belt precheck`
@@ -299,6 +301,12 @@ This command:
 Note: sequence values are intentionally left unchanged. They only need to be
 synchronized after cutover by running sync-sequences.
 
+WARNING: --force skips the safety check that prevents resetting when the
+destination is the same size or larger than the source. This is intended for
+post-migration resets where SRC and DST are identical. Using --force on a
+live migration where DST is genuinely the primary copy will result in
+irreversible data loss.
+
 
 Requires both src and dst to be not null in the config file.
 
@@ -318,6 +326,7 @@ $ belt reset [OPTIONS] DC [DB]
 **Options**:
 
 * `--json`: Output structured JSON instead of human-readable tables.
+* `--force`: Skip the dataset-size failsafe that normally prevents reset when DST >= SRC. Use ONLY after a completed migration when you are certain the destination database should be wiped and all its up-to-date data discarded.
 * `--help`: Show this message and exit.
 
 ## `belt dump-schema`
@@ -778,6 +787,42 @@ $ belt sync [OPTIONS] DC [DB]
 * `--no-schema / --no-no-schema`: [default: no-no-schema]
 * `--help`: Show this message and exit.
 
+## `belt diff-sequences`
+
+Compare source and destination sequence last_value for each targeted sequence.
+
+Uses the **root** database user on both source and destination (same as
+``diff-schemas``), not the pglogical user.
+
+Destination values are highlighted green when they are greater than or equal to
+source, and red otherwise.
+
+Requires both src and dst to be not null in the config file.
+
+If the db name is not given, runs for every database in the datacenter (same
+pattern as ``diff-schemas``).
+
+
+Requires both src and dst to be not null in the config file.
+
+If the db name is not given run on all dbs in the dc.
+
+**Usage**:
+
+```console
+$ belt diff-sequences [OPTIONS] DC [DB]
+```
+
+**Arguments**:
+
+* `DC`: [required]
+* `[DB]`
+
+**Options**:
+
+* `--json`: Output structured JSON instead of human-readable tables.
+* `--help`: Show this message and exit.
+
 ## `belt teardown-back-replication`
 
 Stops pglogical replication from the destination database to the source.