docs(walrus-sites): add 'deploy' command docs

docs/book/walrus-sites/commands.md

@@ -7,18 +7,119 @@ In general, the `--help` flag is your friend, you can add it to get further deta
 CLI (`site-builder --help`) or individual commands (e.g. `site-builder update --help`).
 ```
 
+## `deploy`
+
+The `deploy` command is the primary and recommended command for managing your Walrus Site on Sui.
+The command takes a directory as input and creates a new Walrus Site from the
+resources contained within, and on subsequent calls, it updates the existing site.
+
+### Behavior
+
+The deploy command determines whether to publish a new site or update an existing one by looking for
+a Site Object ID. It finds the ID with the following priority:
+
+- An ID provided directly via the --object-id <OBJECT_ID> command-line flag.
+- An ID found in the object_id field of the ws-resources.json file.
+- If no ID is found by either method, deploy will publish a new site.
+
+When a new site is published, its object_id is automatically saved back to ws-resources.json,
+streamlining future updates.
+
+### Usage
+
+As shown by the command's help information, the typical usage is:
+
+``` sh
+site-builder deploy [OPTIONS] --epochs <EPOCHS> <DIRECTORY>
+```
+
+The `deploy` command determines whether to publish or update based on the presence of an `object_id`
+field in the `ws-resources.json` file. [specifying headers and routing](./routing.md).
+
+```admonish info
+The `object_id` field is automatically set by the `deploy`
+command, when deploying a new site, so there is no need for manually tracking the Site's Object ID.
+```
+
+```admonish note
+The wallet you are using to update an existing Site must be the *owner* of the Walrus Site object to be able
+to update it.
+```
+
+The `--epochs` flag specifies the number of epochs for which the site's resources will be stored
+on Walrus (e.g., 10). You can also use max to store for the maximum allowed duration.
+
+```admonish warning
+The `--epochs` flag is required & it's value must be greater than 0.
+```
+
+```admonish danger title="Epoch duration on Walrus"
+On Walrus Testnet, the epoch duration is **one day**.
+On Walrus Mainnet, the epoch duration is **fourteen days**.
+Therefore, consider storing your site for a large number of epochs
+if you want to make it available for the following months!
+The maximum duration is set to 53 epochs.
+```
+
+If you are just uploading raw files without an `index.html`, you may want to use the
+`--list-directory` flag, which will automatically create an index page to browse the files. See for
+example <https://bin.wal.app>.
+
+### Migrating from `publish`/`update`
+
+If you have a site that was previously managed with the `publish` and `update` commands, you can
+easily switch to the `deploy` command using one of the following methods:
+
+- **Recommended**: Use the `--object-id` cli flag
+Simply run the `deploy` command and provide your existing Site's Object ID via the `--object-id` flag:
+
+```sh
+site-builder deploy --object-id <YOUR_EXISTING_SITE_ID> --epochs <NUMBER> ./path/to/your/site
+```
+
+On success, this will update your site and automatically create (or update if already existing) a
+`ws-resources.json` file with the Site's Object ID saved in the `object_id` field.
+Future deployments will then be as simple as:
+
+```sh
+site-builder deploy --epochs <NUMBER> ./path/to/your/site
+```
+
+- Manual `ws-resources.json` setup.
+You can manually create or update a `ws-resources.json` file in your site's root directory and add
+the `object_id` field with your existing site's Object ID.
+
+```json
+{
+  "object_id": "0x123...abc"
+}
+```
+
+Then, you can simply run:
+
+```sh
+site-builder deploy --epochs <NUMBER> ./path/to/your/site
+```
+
 ## `publish`
 
+```admonish note
+The `deploy` command is the new standard for publishing and updating your Walrus Sites.
+Users are encouraged to migrate to the `deploy` command for a simpler and more robust experience.
+```
+
 The `publish` command, as described in the [previous section](./tutorial-publish.md), publishes a
 new site on Sui. The command takes a directory as input and creates a new Walrus Site from the
 resources contained within.
 
 The `--epochs` flag allows you to specify for how long the site data will be stored on Walrus.
 
-```admonish danger title="Epoch duration on Walrus Testnet"
-On Walrus Testnet, the epoch duration is **two days**. Therefore, consider storing your site for a
-large number of epochs if you want to make it available for the following months! The maximum
-duration is set to 183 epochs (corresponding to one year).
+```admonish danger title="Epoch duration on Walrus"
+On Walrus Testnet, the epoch duration is **one day**.
+On Walrus Mainnet, the epoch duration is **fourteen days**.
+Therefore, consider storing your site for a large number of epochs
+if you want to make it available for the following months!
+The maximum duration is set to 53 epochs.
 ```
 
 If you are just uploading raw files without an `index.html`, you may want to use the
@@ -30,6 +131,11 @@ file. To know more, see the section on [specifying headers and routing](./routin
 
 ## `update`
 
+```admonish note
+The `deploy` command is the new standard for publishing and updating your Walrus Sites.
+Users are encouraged to migrate to the `deploy` command for a simpler and more robust experience.
+```
+
 This command is the equivalent of `publish`, but for updating an existing site. It takes the same
 arguments, with the addition of the Sui object ID of the site to update.
 

docs/book/walrus-sites/routing.md

@@ -13,7 +13,7 @@ site's resources (in other words, the file is not part of the resulting Walrus S
 served by the portal).
 
 If you don't want to use this default location, you can specify the path to the configuration file
-with the `--ws-resources` flag when running the `publish` or `update` commands.
+with the `--ws-resources` flag when running the `deploy`, `publish` or `update` commands.
 
 The file is JSON-formatted, and looks like the following:
 
@@ -37,12 +37,18 @@ The file is JSON-formatted, and looks like the following:
       "project_url": "https://github.com/MystenLabs/walrus-sites/",
       "creator": "MystenLabs"
   },
+  "site_name": "My Walrus Site",
+  "object_id": "0xe674c144119a37a0ed9cef26a962c3fdfbdbfd86a3b3db562ee81d5542a4eccf",
   "ignore": ["/private/*", "/secret.txt", "/images/tmp/*"]
 }
 ```
 
-We now describe in detail four sections of the configuration file: `headers`, `routes`,
-`metadata`, and the `ignore` section.
+```admonish note
+The `ws-resources.json` file, expects the field names to be in `snake_case`
+```
+
+We now describe in detail six sections of the configuration file: `headers`, `routes`,
+`metadata`, `site_name`, `object_id` and the `ignore` section.
 
 ## Specifying HTTP response headers
 
@@ -160,6 +166,34 @@ example you can place a link to your sites favicon.
 - `project_url`: If your site is open-source, add a link to your site's GitHub repository.
 - `creator`: Add the name of your company, group, or individual creator of your site.
 
+## Site Name (`site_name`)
+
+You can set a Name for your Walrus Site, via the optional `site_name` field in your
+`ws-resources.json` file.
+
+```admonish note
+In case you have also provided a Site Name via the `--site-name` cli flag, the cli flag
+will take priority over the `site_name` field in the `ws-resources.json`, which will be
+overwritten.
+```
+
+```admonish note
+If a Site Name is not provided at all (neither through the `--site-name` cli flag, nor
+through the `site_name` field in `ws-resources.json`), then a default name will be used.
+```
+
+## Site Object ID (`object_id`)
+
+The optional `object_id` field in your `ws-resources.json` file stores the Sui Object ID of your
+deployed Walrus Site.
+
+**Role in Deployment:**
+
+The `site-builder deploy` command primarily uses this field to identify an existing site for updates.
+If a valid `object_id` is present, `deploy` will target that site for modifications.
+If this field is missing (and no `--object-id` CLI flag is used), `deploy` will publish a new site.
+If successful, then the command automatically populates this `object_id` field in your `ws-resources.json`.
+
 ## Ignoring files from being uploaded
 
 You can use the optional `ignore` field to exclude certain files or folders from being published.

docs/book/walrus-sites/tutorial-publish.md

@@ -26,12 +26,12 @@ Since we have placed the `walrus` and `site-builder` binaries and configuration
 locations, publishing the `./walrus-snake` site is as simple as calling the publishing command:
 
 ``` sh
-site-builder publish ./walrus-snake --epochs 1
+site-builder deploy ./walrus-snake --epochs 1
 ```
 
 ``` admonish tip
 Depending on the network, the duration of an epoch may vary. Currently on Walrus Testnet, the
-duration of an epoch is two days. On Mainnet, the duration of an epoch is two weeks.
+duration of an epoch is one day. On Mainnet, the duration of an epoch is two weeks.
 ```
 
 The end of the output should look like the following:
@@ -60,6 +60,7 @@ This output tells you that, for each file in the folder, a new Walrus blob was c
 respective blob ID. Further, it prints the object ID of the Walrus Site object on Sui (so you can
 have a look in the explorer and use it to set the SuiNS name) and, finally, the URL at which you can
 browse the site.
+The deploy command will also save this new Site Object ID to the ws-resources.json
 
 Note here that we are implicitly using the default `sites-config.yaml` as the config for the site
 builder that we set up previously on the [installation section](./tutorial-install.md). The
@@ -76,12 +77,12 @@ Let's say now you want to update the content of the site, for example by changin
 
 First, make this edit on in the `./walrus-snake/index.html` file.
 
-Then, you can update the existing site by running the `update` command, providing the directory
-where to find the updated files (still `./walrus-snake`) and the object ID of the existing site
-(`0x407a3081...`):
+Then, you can update the existing site by running the `deploy` command again. The deploy command will
+use the Site Object ID stored in ws-resources.json (from the initial deployment) to identify which site
+to update. You do not need to specify the object ID manually:
 
 ``` sh
-site-builder update --epochs 1 ./walrus-snake 0xe674c14...
+site-builder deploy --epochs 1 ./walrus-snake
 ```
 
 The output this time should be:
@@ -102,8 +103,8 @@ To browse the site, you have the following options:
            Finally, browse it with: https://example-domain.wal.app
 ```
 
-Compared to the `publish` action, we can see that now the only actions performed were to delete the
-old `index.html`, and update it with the newer one.
+Compared to the when the site was first published, we can see that now the only actions performed
+were to delete the old `index.html`, and update it with the newer one.
 
 Browsing to the provided URL should reflect the change. You've updated the site!