docs: improve usage docs and add info on public aggregator/publisher

docs/usage/client-cli.md

@@ -1,7 +1,8 @@
 # Using the Walrus client
 
-The `walrus` binary can be used to interact with Walrus as a client. To use it, you need a Walrus
-configuration and a Sui wallet.
+The `walrus` binary can be used to interact with Walrus as a client. See the [setup
+chapter](./setup.md) for prerequisites, installation, and configuration.
+
 Detailed usage information is available through
 
 ```sh
@@ -11,7 +12,10 @@ walrus --help
 Storing and reading blobs from Walrus can be achieved through the following commands:
 
 ```sh
-CONFIG=working_dir/client_config.yaml # adjust for your configuration file
-walrus -c $CONFIG store <some file> # store a file
-walrus -c $CONFIG read <some blob ID> # read a blob
+walrus store <some file>
+walrus read <some blob ID>
 ```
+
+Information about the Walrus system is available through through the `walrus info` command.
+
+Use the `--config` option to specify a custom path to the configuration location.

docs/usage/interacting.md

@@ -2,6 +2,6 @@
 
 We provide 3 ways to interact directly with the Walrus storage system:
 
-- Through the walrus [client command line interface (CLI)](client-cli.md).
-- Through a [JSON API](json-api.md) of the walrus CLI.
-- Through an [HTTP API](web-api.md) exposed by the walrus client daemon.
+- Through the Walrus [client command line interface (CLI)](./client-cli.md).
+- Through a [JSON API](./json-api.md) of the Walrus CLI.
+- Through an [HTTP API](./web-api.md) exposed by a public or local Walrus client daemon.

docs/usage/json-api.md

@@ -1,6 +1,6 @@
 # JSON mode
 
-All Walrus client commands (except, currently, the `info` command) are available in JSON mode.
+All Walrus client commands (except, currently, the `info` command) are also available in JSON mode.
 In this mode, all the command line flags of the original CLI command can be specified in JSON
 format. The JSON mode therefore simplifies programmatic access to the CLI.
 
@@ -9,7 +9,7 @@ For example, to store a blob, run:
 ```sh
 walrus json \
     '{
-        "config": "working_dir/client_config.yaml",
+        "config": "path/to/client_config.yaml",
         "command": {
             "store": {
                 "file": "README.md"
@@ -18,20 +18,23 @@ walrus json \
     }'
 ```
 
-or, to read a blob knowing the blob ID:
+Or, to read a blob knowing the blob ID:
 
 ```sh
 walrus json \
     '{
-        "config": "working_dir/client_config.yaml",
+        "config": "path/to/client_config.yaml",
         "command": {
             "read": {
-                "blob_id": "4BKcDC0Ih5RJ8R0tFMz3MZVNZV8b2goT6_JiEEwNHQo"
+                "blobId": "4BKcDC0Ih5RJ8R0tFMz3MZVNZV8b2goT6_JiEEwNHQo"
             }
         }
     }'
 ```
 
+All options, default values, and commands are equal to those of the "standard" CLI mode, except that
+they are written in "camelCase" instead of "kebab-case".
+
 The `json` command also accepts input from `stdin`.
 
 The output of a `json` command will itself be JSON-formatted, again to simplify parsing the results

docs/usage/web-api.md

@@ -1,7 +1,7 @@
 # Client Daemon mode & HTTP API
 
-In addition to the CLI mode, the Walrus client offers a *daemon mode*. In this mode, it runs a
-simple web server offering HTTP interfaces to store and read blobs.
+In addition to the CLI and JSON modes, the Walrus client offers a *daemon mode*. In this mode, it
+runs a simple web server offering HTTP interfaces to store and read blobs.
 
 ## Starting the daemon
 
@@ -10,32 +10,40 @@ different sets of API endpoints through one of the following commands:
 
 ```sh
 ADDRESS="127.0.0.1:31415" # bind the daemon to localhost and port 31415
-walrus -c $CONFIG aggregator -b $ADDRESS # run an aggregator to read blobs
-walrus -c $CONFIG publisher -b $ADDRESS # run a publisher to store blobs
-walrus -c $CONFIG daemon -b $ADDRESS # run a daemon combining an aggregator and a publisher
+walrus aggregator -b $ADDRESS # run an aggregator to read blobs
+walrus publisher -b $ADDRESS # run a publisher to store blobs
+walrus daemon -b $ADDRESS # run a daemon combining an aggregator and a publisher
 ```
 
-The aggregator provides all read APIs, the publisher all the store APIs, and daemon provides both.
-Note that the aggregator does not perform Sui on-chain actions, and therefore consumes no gas.
+The aggregator provides all read APIs, the publisher all the store APIs, and the daemon provides
+both. Note that the aggregator does not perform Sui on-chain actions, and therefore consumes no gas.
 However, the publisher does perform actions on-chain and will consume gas. It is therefore important
 to ensure only authorized parties may access it, or other measures to manage gas costs.
 
 ## HTTP API Usage
 
-You can then interact with the daemon through simple HTTP requests. For example, with
-[cURL](https://curl.se), you can store blobs as follows:
+You can interact with the daemon through simple HTTP requests. For example, with
+[cURL](https://curl.se), you can store blobs using a publisher or daemon as follows:
 
 ```sh
 curl -X PUT "http://$ADDRESS/v1/store" -d "some string" # store the string `some string` for 1 storage epoch
 curl -X PUT "http://$ADDRESS/v1/store?epochs=5" -d @"some/file" # store file `some/file` for 5 storage epochs
 ```
 
-Blobs may be read using the following cURL command:
+Blobs may be read from an aggregator or daemon using the following cURL command:
 
 ```sh
-curl "http://$ADDRESS/v1/<some blob ID>" # read a blob from Walrus (with aggregator or daemon)
+curl "http://$ADDRESS/v1/<some blob ID>"
 ```
 
 Modern browsers will attempt to sniff the content type for such resources, and will generally do a
 good job of inferring content types for media. However, the aggregator on purpose prevents such
 sniffing from inferring dangerous executable types such as javascript or style sheet types.
+
+## Using a public aggregator or publisher
+
+For many use cases (e.g., a public website) a publicly accessible aggregator and/or publisher is
+required. For your convenience, we provide these at the following hosts:
+
+- Aggregator: `http://sea-dnt-sto-00.devnet.sui.io:9000`
+- Publisher: `http://ord-dnt-sto-00.devnet.sui.io:9000`