docs(reference): add rc command reference

docs/reference/rc/README.md

@@ -0,0 +1,67 @@
+# rc Command Reference
+
+This reference documents the operations exposed by `rc`, the RustFS S3-compatible command-line client. The structure follows the command-reference style used by MinIO `mc`: each operation describes its purpose, syntax, parameters, examples, and behavior, while keeping the examples specific to `rc`.
+
+`rc` supports both noun-first command groups and legacy command names. Prefer the noun-first groups for new scripts:
+
+| Operation | Preferred form | Legacy-compatible form |
+| --- | --- | --- |
+| Configure targets | [`rc alias`](alias.md) | none |
+| Bucket workflows | [`rc bucket`](bucket.md) | `rc ls`, `rc mb`, `rc rb`, `rc event`, `rc cors`, `rc version`, `rc anonymous`, `rc quota`, `rc ilm`, `rc replicate` |
+| Object workflows | [`rc object`](object.md) | `rc ls`, `rc cp`, `rc mv`, `rc rm`, `rc cat`, `rc head`, `rc stat`, `rc find`, `rc tree`, `rc share` |
+| Administrative workflows | [`rc admin`](admin.md) | none |
+| Streaming upload | [`rc pipe`](pipe.md) | none |
+| Difference reports | [`rc diff`](diff.md) | none |
+| Mirroring | [`rc mirror`](mirror.md) | none |
+| S3 Select | [`rc sql`](sql.md) | none |
+| Tags | [`rc tag`](tag.md) | none |
+| Shell completions | [`rc completions`](completions.md) | none |
+
+Legacy command pages remain documented for users migrating from MinIO `mc`-style workflows:
+
+- [`rc ls`](ls.md)
+- [`rc mb`](mb.md)
+- [`rc rb`](rb.md)
+- [`rc cat`](cat.md)
+- [`rc head`](head.md)
+- [`rc stat`](stat.md)
+- [`rc cp`](cp.md)
+- [`rc mv`](mv.md)
+- [`rc rm`](rm.md)
+- [`rc find`](find.md)
+- [`rc event`](event.md)
+- [`rc cors`](cors.md)
+- [`rc tree`](tree.md)
+- [`rc share`](share.md)
+- [`rc version`](version.md)
+- [`rc anonymous`](anonymous.md)
+- [`rc quota`](quota.md)
+- [`rc ilm`](ilm.md)
+- [`rc replicate`](replicate.md)
+
+## Path Format
+
+Remote paths use `ALIAS/BUCKET/KEY` form. An alias-only path such as `local/` refers to a configured S3-compatible service. A bucket path such as `local/photos` refers to a bucket. An object path such as `local/photos/2026/image.jpg` refers to a specific object key.
+
+## Output Modes
+
+Global options shown in command syntax use the same meaning everywhere:
+
+| Option | Description |
+| --- | --- |
+| `--format auto\|human\|json` | Select automatic, human-readable, or JSON output. |
+| `--json` | Emit JSON output where the command supports structured output. |
+| `--no-color` | Disable terminal colors. |
+| `--no-progress` | Disable progress bars. |
+| `-q, --quiet` | Suppress non-error output. |
+| `--debug` | Enable debug logging. |
+
+## Credentials
+
+Credentials are stored through aliases. Configure an alias before running remote operations:
+
+```bash
+rc alias set local http://localhost:9000 ACCESS_KEY SECRET_KEY
+```
+
+Do not put production credentials in examples, logs, issue descriptions, or screenshots.

docs/reference/rc/admin.md

@@ -0,0 +1,78 @@
+# rc admin
+
+## Purpose
+
+The `rc admin` operation manages RustFS or MinIO-compatible administrative APIs, including cluster information, healing, pools, expansion, decommissioning, rebalance workflows, IAM users, policies, groups, and service accounts.
+
+## Syntax
+
+```bash
+rc [GLOBAL OPTIONS] admin <COMMAND>
+rc admin info <cluster|server|disk> <ALIAS> [OPTIONS]
+rc admin heal <status|start|stop> <ALIAS> [OPTIONS]
+rc admin pool <list|status> <ALIAS> [POOL] [OPTIONS]
+rc admin expand <start|status|stop> <ALIAS>
+rc admin decommission <start|status|cancel> <ALIAS> <POOL> [OPTIONS]
+rc admin rebalance <start|status|stop> <ALIAS>
+rc admin user <ls|add|info|rm|enable|disable> ...
+rc admin policy <ls|create|info|rm|attach> ...
+rc admin group <ls|add|info|rm|enable|disable|add-members|rm-members> ...
+rc admin service-account <ls|create|info|rm> ...
+```
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `info` | Display cluster, server, or disk information. |
+| `heal` | Start, stop, or inspect healing operations. |
+| `pool` | List pools and inspect pool status. |
+| `expand` | Manage post-expansion data rebalancing. Alias: `scale`. |
+| `decommission` | Manage server pool decommissioning. Alias: `decom`. |
+| `rebalance` | Manage post-expansion rebalancing. |
+| `user` | Manage IAM users. |
+| `policy` | Manage IAM policies and attachments. |
+| `group` | Manage IAM groups and group membership. |
+| `service-account` | Manage service accounts. |
+
+## Examples
+
+Show cluster information:
+
+```bash
+rc admin info cluster local
+```
+
+Start a deep heal for a prefix:
+
+```bash
+rc admin heal start local --bucket logs --prefix 2026/ --scan-mode deep
+```
+
+Create a user and attach a policy:
+
+```bash
+rc admin user add local analyst STRONG_PASSWORD
+rc admin policy attach local readonly --user analyst
+```
+
+Create a service account with a policy file:
+
+```bash
+rc admin service-account create local SA_ACCESS_KEY SA_SECRET_KEY --policy ./policy.json
+```
+
+## Behavior
+
+Admin operations use the configured alias to create an admin client. The credentials behind the alias must have permissions for the requested administrative API. The command accepts aliases with or without a trailing slash.
+
+Global options shown in command syntax use the same meaning everywhere:
+
+| Option | Description |
+| --- | --- |
+| `--format auto\|human\|json` | Select automatic, human-readable, or JSON output. |
+| `--json` | Emit JSON output where the command supports structured output. |
+| `--no-color` | Disable terminal colors. |
+| `--no-progress` | Disable progress bars. |
+| `-q, --quiet` | Suppress non-error output. |
+| `--debug` | Enable debug logging. |

docs/reference/rc/alias.md

@@ -0,0 +1,77 @@
+# rc alias
+
+## Purpose
+
+The `rc alias` operation manages named S3-compatible service endpoints in the local `rc` configuration. Use aliases to avoid repeating endpoint URLs and credentials in every command.
+
+## Syntax
+
+```bash
+rc [GLOBAL OPTIONS] alias <COMMAND>
+rc [GLOBAL OPTIONS] alias set [OPTIONS] <NAME> <ENDPOINT> <ACCESS_KEY> <SECRET_KEY>
+rc [GLOBAL OPTIONS] alias list [-l|--long]
+rc [GLOBAL OPTIONS] alias remove <NAME>
+```
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `set` | Add a new alias or replace an existing alias. |
+| `list` | List configured aliases. |
+| `remove` | Remove an alias from local configuration. |
+
+## Parameters
+
+| Parameter | Description |
+| --- | --- |
+| `NAME` | Local alias name, such as `local`, `s3`, or `rustfs`. |
+| `ENDPOINT` | S3-compatible endpoint URL, such as `http://localhost:9000`. |
+| `ACCESS_KEY` | Access key ID for the endpoint. |
+| `SECRET_KEY` | Secret access key for the endpoint. |
+| `--region` | AWS region to associate with the alias. Defaults to `us-east-1`. |
+| `--signature` | Signature version, `v4` or `v2`. Defaults to `v4`. |
+| `--bucket-lookup` | Bucket lookup style: `auto`, `path`, or `dns`. Defaults to `auto`. |
+| `--insecure` | Allow insecure TLS connections for this alias. |
+| `-l, --long` | Show full alias details when listing aliases. |
+
+## Examples
+
+Configure a local RustFS or MinIO-compatible service:
+
+```bash
+rc alias set local http://localhost:9000 ACCESS_KEY SECRET_KEY
+```
+
+Configure AWS S3 with an explicit region:
+
+```bash
+rc alias set s3 https://s3.amazonaws.com ACCESS_KEY SECRET_KEY --region us-east-1
+```
+
+List aliases with endpoint details:
+
+```bash
+rc alias list --long
+```
+
+Remove an alias:
+
+```bash
+rc alias remove old-local
+```
+
+## Behavior
+
+`alias set` overwrites an existing alias with the same name. `alias list` does not print secret keys. Commands that need a remote service resolve the alias name before creating an S3 or admin client.
+
+Global options shown in command syntax use the same meaning everywhere:
+
+| Option | Description |
+| --- | --- |
+| `--format auto\|human\|json` | Select automatic, human-readable, or JSON output. |
+| `--json` | Emit JSON output where the command supports structured output. |
+| `--no-color` | Disable terminal colors. |
+| `--no-progress` | Disable progress bars. |
+| `-q, --quiet` | Suppress non-error output. |
+| `--debug` | Enable debug logging. |

docs/reference/rc/anonymous.md

@@ -0,0 +1,50 @@
+# rc anonymous
+
+## Purpose
+
+`rc anonymous` manages anonymous bucket or prefix access. It is a legacy-compatible command; prefer `rc bucket anonymous` for new scripts.
+
+## Syntax
+
+```bash
+rc [GLOBAL OPTIONS] anonymous <COMMAND>
+rc anonymous set <private|public|download|upload> <PATH>
+rc anonymous set-json <FILE> <PATH>
+rc anonymous get <PATH>
+rc anonymous get-json <PATH>
+rc anonymous list <PATH>
+rc anonymous links [-r|--recursive] <PATH>
+```
+
+## Parameters
+
+| Parameter | Description |
+| --- | --- |
+| `PATH` | Bucket or prefix path, `ALIAS/BUCKET[/PREFIX]`. |
+| `PERMISSION` | One of `private`, `public`, `download`, or `upload`. |
+| `FILE` | Policy JSON file for `set-json`. |
+| `-r, --recursive` | Recursively list public links. |
+
+## Examples
+
+```bash
+rc bucket anonymous set download local/public/reports
+rc anonymous get local/public/reports
+rc anonymous links local/public/reports --recursive
+rc anonymous set private local/public
+```
+
+## Behavior
+
+Setting prefix-level anonymous access replaces the bucket policy document with statements generated for the target prefix. Setting `private` is bucket-level because it clears the anonymous policy.
+
+Global options shown in command syntax use the same meaning everywhere:
+
+| Option | Description |
+| --- | --- |
+| `--format auto\|human\|json` | Select automatic, human-readable, or JSON output. |
+| `--json` | Emit JSON output where the command supports structured output. |
+| `--no-color` | Disable terminal colors. |
+| `--no-progress` | Disable progress bars. |
+| `-q, --quiet` | Suppress non-error output. |
+| `--debug` | Enable debug logging. |

docs/reference/rc/bucket.md

@@ -0,0 +1,97 @@
+# rc bucket
+
+## Purpose
+
+The `rc bucket` operation is the preferred noun-first entry point for bucket-oriented workflows. It groups bucket listing, creation, deletion, notification, CORS, versioning, quota, anonymous access, lifecycle, and replication operations under one command family.
+
+## Syntax
+
+```bash
+rc [GLOBAL OPTIONS] bucket <COMMAND>
+rc bucket list [OPTIONS] <PATH>
+rc bucket create [OPTIONS] <ALIAS/BUCKET>
+rc bucket remove [OPTIONS] <ALIAS/BUCKET>
+rc bucket event <add|list|remove> ...
+rc bucket cors <list|set|remove> ...
+rc bucket version <enable|suspend|info|list> ...
+rc bucket quota <set|info|clear> ...
+rc bucket anonymous <set|set-json|get|get-json|list|links> ...
+rc bucket lifecycle <rule|tier|restore> ...
+rc bucket replication <add|update|list|status|remove|export|import> ...
+```
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `list` | List buckets for an alias or list objects under a bucket path. |
+| `create` | Create a bucket. |
+| `remove` | Remove a bucket. |
+| `event` | Manage bucket notification rules. |
+| `cors` | Manage bucket CORS rules. |
+| `version` | Manage bucket versioning and object versions. |
+| `quota` | Manage bucket quota. |
+| `anonymous` | Manage anonymous bucket or prefix access. |
+| `lifecycle` | Manage lifecycle rules, remote tiers, and object restore requests. |
+| `replication` | Manage bucket replication rules and replication status. |
+
+## Parameters
+
+| Parameter | Description |
+| --- | --- |
+| `PATH` | `ALIAS/`, `ALIAS/BUCKET`, or `ALIAS/BUCKET/PREFIX`. |
+| `--recursive` | Recursively list objects for `bucket list`. |
+| `--versions` | Include object versions when listing supported versioned buckets. |
+| `--summarize` | Show totals only for list output. |
+| `--ignore-existing` | Do not fail if the bucket already exists when creating it. |
+| `--with-versioning` | Enable versioning when creating the bucket. |
+| `--with-lock` | Enable object lock when creating the bucket. |
+| `--force` | Force destructive or capability-gated operations where supported. |
+| `--dangerous` | Remove a bucket even when incomplete multipart uploads exist. |
+
+## Examples
+
+List buckets for an alias:
+
+```bash
+rc bucket list local/
+```
+
+Create a versioned bucket with object lock:
+
+```bash
+rc bucket create local/archive --with-versioning --with-lock
+```
+
+List notification rules:
+
+```bash
+rc bucket event list local/archive
+```
+
+Set CORS from an XML or JSON file:
+
+```bash
+rc bucket cors set local/archive cors.xml
+```
+
+Check replication status:
+
+```bash
+rc bucket replication status local/archive
+```
+
+## Behavior
+
+Prefer `rc bucket ...` for new scripts. Legacy commands such as `rc mb`, `rc rb`, `rc event`, `rc cors`, `rc version`, `rc anonymous`, `rc quota`, `rc ilm`, and `rc replicate` remain available and delegate to the same implementations.
+
+Global options shown in command syntax use the same meaning everywhere:
+
+| Option | Description |
+| --- | --- |
+| `--format auto\|human\|json` | Select automatic, human-readable, or JSON output. |
+| `--json` | Emit JSON output where the command supports structured output. |
+| `--no-color` | Disable terminal colors. |
+| `--no-progress` | Disable progress bars. |
+| `-q, --quiet` | Suppress non-error output. |
+| `--debug` | Enable debug logging. |