docs: add rofl machine info

docs: improve rofl proxy cli docs

docs: update rofl machine show section for clarity

fix: pr review suggestions

Author: uniyalabhishek

docs/rofl.md

@@ -227,10 +227,34 @@ offer:
 
 [ROFL marketplace]: https://github.com/oasisprotocol/oasis-sdk/blob/main/docs/rofl/features/marketplace.mdx
 
-## Top-up payment for the machine {#top-up}
+## Manage a deployed ROFL machine {#machine}
+
+Once a ROFL app is deployed, you can manage the machine it's running on using
+the `oasis rofl machine` subcommands.
+
+### Show machine information {#machine-show}
+
+To view details about a deployed machine, including its status, expiration,
+and any proxy URLs, run `oasis rofl machine show`:
+
+![code shell](../examples/rofl/machine-show.in.static)
+
+![code](../examples/rofl/machine-show.out.static)
+
+If you have published ports in your `compose.yaml`, the output will include
+a `Proxy` section with public URLs to access your services. For more details on
+how to configure the proxy and for troubleshooting, see the [ROFL Proxy]
+feature page.
+
+[ROFL Proxy]: https://github.com/oasisprotocol/oasis-sdk/blob/main/docs/rofl/features/proxy.mdx
+
+### Top-up payment for the machine {#machine-top-up}
 
 Run `rofl machine top-up` to extend the rental of the machine obtained from
-the [ROFL marketplace]. The rental is extended under the terms of the original
+the [ROFL marketplace]. You can check the current expiration date of your
+machine in the `Paid until` field from
+the [`oasis rofl machine show` output](#machine-show).
+The rental is extended under the terms of the original
 offer. Specify the extension period with [`--term`][term-flags] and
 [`--term-count`][term-flags] parameters.
 
@@ -240,6 +264,41 @@ offer. Specify the extension period with [`--term`][term-flags] and
 
 [term-flags]: #deploy
 
+### Show machine logs {#machine-logs}
+
+You can fetch logs from your running ROFL app using `oasis rofl machine logs`.
+
+![code shell](../examples/rofl/machine-logs.in.static)
+
+:::danger Logs are not encrypted!
+
+While only the app admin can access the logs, they are stored
+**unencrypted on the ROFL node**. In production, make sure
+you never print any confidential data to the standard or error outputs!
+
+:::
+
+### Restart a machine {#machine-restart}
+
+To restart a running machine, use `oasis rofl machine restart`.
+
+If you wish to clear the machine's persistent storage,
+pass the [`--wipe-storage`] flag.
+
+[`--wipe-storage`]: #machine-deploy
+
+### Stop a machine {#machine-stop}
+
+To stop a machine, use `oasis rofl machine stop`.
+To start it back again, use [`oasis rofl machine restart`].
+
+[`oasis rofl machine restart`]: #machine-restart
+
+### Remove a machine {#machine-remove}
+
+To cancel the rental and permanently remove a machine,
+including its persistent storage, use `oasis rofl machine remove`.
+
 ## Advanced
 
 ### Upgrade ROFL app dependencies {#upgrade}

examples/rofl/machine-logs.in.static

@@ -0,0 +1 @@
+oasis rofl machine logs

examples/rofl/machine-show.in.static

@@ -0,0 +1 @@
+oasis rofl machine show

examples/rofl/machine-show.out.static

@@ -0,0 +1,26 @@
+Name:       default
+Provider:   oasis1qp2ens0hsp7gh23wajxa4hpetkdek3swyyulyrmz
+ID:         000000000000025a
+Offer:      0000000000000001
+Status:     accepted
+Creator:    oasis1qzvxd8vjgp2y0tjx229420tva822mdk2wxpx0vws
+Admin:      oasis1qzvxd8vjgp2y0tjx229420tva822mdk2wxpx0vws
+Node ID:    DbeoxcRwDO4Wh8bwq5rAR7wzhiB+LeYn+y7lFSGAZ7I=
+Created at: 2025-08-25 10:00:00 +0000 UTC
+Updated at: 2025-08-25 10:00:10 +0000 UTC
+Paid until: 2025-08-26 10:00:00 +0000 UTC
+Proxy:
+  Domain: m602.test-proxy-b.rofl.app
+  Ports from compose file:
+    8080 (http-echo): https://p8080.m602.test-proxy-b.rofl.app
+Resources:
+  TEE:     Intel TDX
+  Memory:  4096 MiB
+  vCPUs:   2
+  Storage: 20000 MiB
+Deployment:
+  App ID: rofl1qrqw99h0f7az3hwt2cl7yeew3wtz0fxunu7luyfg
+  Metadata:
+    net.oasis.deployment.orc.ref: rofl.sh/0ba0712d-114c-4e39-ac8e-b28edffcada8:1747909776@sha256:77ff0dc76adf957a4a089cf7cb584aa7788fef027c7180ceb73a662ede87a217
+Commands:
+  <no queued commands>