wip: guide: improve web section documentation (#18)

guide: improve web section documentation

pages/pcli.md

@@ -2,9 +2,9 @@
 
 This section describes how to use `pcli`, the command line client for Penumbra:
 
-- [Installation](./pcli/install.md) describes how to compile and run `pcli`;
-- [Generating a Wallet](./pcli/wallet.md) describes how to generate a wallet;
-- [Viewing Balances](./pcli/balance.md) describes how to view balances;
+- [Installation](./pcli/install.md) describes how to compile and run `pcli`.
+- [Generating a Wallet](./pcli/wallet.md) describes how to generate a wallet.
+- [Viewing Balances](./pcli/balance.md) describes how to view balances.
 - [Sending Transactions](./pcli/transaction.md) describes how to send funds.
 
 Penumbra is a private blockchain, so the public chain state does not reveal any
@@ -17,8 +17,3 @@ Thank you for helping us test the Penumbra network! If you have any feedback, pl
 the `#general` channel on our [Discord](https://discord.gg/hKvkrqa3zC). We would love to know about bugs, crashes,
 confusing error messages, or any of the many other things that inevitably won't quite work yet. Have
 fun! :)
-
-### Diagnostics and Warnings
-
-By default, `pcli` prints a warning message to the terminal, to be sure that people understand that this is _unstable, unfinished, pre-release software_.
-To disable this warning, export the `PCLI_UNLEASH_DANGER` environment variable.

pages/web.md

@@ -1,63 +1,11 @@
 # Using Penumbra on the web
 
-This section describes how to use the Penumbra Wallet web extension, a GUI client for Penumbra.
-
-Currently, the web extension only supports a subset of functionality of the
-command-line client, [`pcli`](./pcli.md).
-
-## Installing the extension
-
-The Penumbra Wallet web extension only supports the Google Chrome browser.
-You must run Chrome in order to follow the instructions below.
-
-1. Visit the Web Store page for the [Prax Wallet](https://chromewebstore.google.com/detail/prax-wallet/lkpmkhpnhknhmibgnmmhdhgdilepfghe),
-   and click **Add to Chrome** to install it.
-2. Navigate to the dApp website for the extension: [https://app.testnet.penumbra.zone/](https://app.testnet.penumbra.zone/),
-   or [self-host your own frontend](./tutorials/running-frontend.md) and click **Connect** in the top-right corner.
-3. Click **Get started** to proceed with wallet configuration.
-
-## Generating a wallet
-
-You'll be offered to import a pre-existing wallet. If you don't already have one, choose **Create a new wallet**.
-During the guided tutorial, you'll need to set a passphrase to protect your wallet. The passphrase
-is *not* the same as the recovery phrase. The passphrase is used to restrict access to the web wallet
-on your computer. The recovery phrase can be used to import your wallet on a fresh installation, or
-on a different machine. Make sure to store both the passphrase and the recovery phrase
-securely, for example in a password manager.
-
-Re-enter portions of the recovery phrase when prompted, to confirm that you've saved it properly.
-Then you'll be taken to a screen that shows an initial synchronization process with the selected network:
-
-<!--
-Do we want to maintain screenshots inside the web extension docs?
-The image files will become out of data quickly, requiring maintenance, and bloat the repo.
--->
-
-<picture>
-  <source srcset="images/web-extension-sync-progress.png" media="(prefers-color-scheme: dark)" />
-  <img src="images/web-extension-sync-progress.png" />
-</picture>
-
-## Creating transactions
-
-Now that you've got the web wallet configured, let's use it to send a
-transaction.  Navigate to the dApp website:
-[https://app.testnet.penumbra.zone/](https://app.testnet.penumbra.zone/) and
-click **Connect**, then authorize the extension to work with the site. After
-doing so, you'll see buttons for actions such as **Receive**, **Send**, and
-**Exchange**.
-
-## Updating to a new version of the extension
-
-The extension should be automatically updated every time a new version is released.
-You can view the latest version of the extension on the [Prax Wallet] page at the
-Chrome Web Store. To force a check for updates:
-
-1. Click the three-dot icon in the top right corner of the browser.
-2. From the drop-down menu, choose **Extensions -> Manage Extensions**.
-3. Select **Update** on the top panel.
-
-After updating the extension manually, it may be helpful to clear the local cache,
-as described above.
-
-[Prax Wallet]: https://chromewebstore.google.com/detail/prax-wallet/lkpmkhpnhknhmibgnmmhdhgdilepfghe
+This section describes how to use the [Prax Wallet](https://chromewebstore.google.com/detail/prax-wallet/lkpmkhpnhknhmibgnmmhdhgdilepfghe) web extension, a GUI client for Penumbra.
+
+- [Prax Wallet](./web/prax.md) describes how to use Prax to generate a wallet.
+- [Viewing Balances](./web/balances.md) describes how to view balances.
+- [Shielding Funds](./web/ibc-transfers.md) describes how to shield transactions via IBC transfers.
+- [Sending Funds](./web/send.md) describes how to send funds.
+- [Swapping Tokens](./web/swap.md) describes how to perform token swaps.
+- [Staking](./web/stake.md) describes how to stake tokens.
+- [Governance](./web/vote.md) describes how to participate in governance.

pages/web/balances.mdx

@@ -1 +1,4 @@
 # Viewing Balances
+
+To view your balance, simply navigate to the `Assets` tab in the frontend site you are using. The balance of your wallet will be displayed there, separated by asset type. 
+Here you may also toggle into a `Transactions` view, which will allow you to see the connected wallet's transaction history, and dive into their transaction details.

pages/web/ibc-transfers.mdx

@@ -1 +1,6 @@
 # Shielding Funds
+
+To shield funds originating on other chains, you can use the IBC transfer feature in the Prax Wallet, found under the `Shield Funds` tab.
+This feature allows you to send tokens from other chains into Penumbra's shielded pool, where they will benefit from Penumbra's enhanced privacy and become available to use on the DEX.
+For incoming transfers to the shielded pool, you must connect a wallet from a counterparty chain to the Prax Wallet, and then initiate the transfer from the counterparty chain's wallet.
+To unshield funds, you can use the `Shield Funds` tab to send tokens from Penumbra to another chain, by selecting a counterparty chain and destination address and clicking `Unshield Assets`.

pages/web/prax.mdx

@@ -1 +1,54 @@
-# Prax wallet
+# Prax Wallet
+
+This section describes how to use the Prax Wallet web extension, an official GUI client for Penumbra.
+
+Currently, the web extension only supports a subset of functionality of the
+command-line client, [`pcli`](./pcli.md).
+
+## Installing the extension
+
+The Penumbra Wallet web extension only supports the Google Chrome browser.
+You must run Chrome in order to follow the instructions below.
+
+Visit the Web Store page to download the [Prax Wallet](https://chromewebstore.google.com/detail/prax-wallet/lkpmkhpnhknhmibgnmmhdhgdilepfghe), and click **Add to Chrome** to install it.
+
+## Generating a wallet
+
+When you first open the extension, you'll be offered to import a pre-existing wallet. If you don't already have one, choose **Create a new wallet**.
+During the guided tutorial, you'll need to set a passphrase to protect your wallet. The passphrase
+is *not* the same as the recovery phrase. The passphrase is used to restrict access to the web wallet
+on your computer. The recovery phrase can be used to import your wallet on a fresh installation, or
+on a different machine. Make sure to store both the passphrase and the recovery phrase
+securely, for example in a password manager.
+
+Re-enter portions of the recovery phrase when prompted, to confirm that you've saved it properly.
+
+## Select your preferred RPC endpoint
+
+Once you import or generate a wallet, you will be prompted to select an RPC endpoint, which is the URL the extension uses to sync with the network. 
+These are hosted by the community (including yourself, if you like), and those provided in the UI are typically offered by known validators.
+You may also provide your own custom endpoint, whether that is a community provider not provided as a default option, or hosted on a node you run yourself.
+
+## Select your preferred frontend app
+
+The extension will prompt you to select a frontend app to use with the wallet. This is a web interface that you will use to interact with the blockchain.
+The provided options are community-hosted frontends, and you may also provide your own custom frontend URL.
+Connecting a frontend to your wallet grants the frontend provider a full viewing key for your wallet in order to decrypt and display relevant information, such as your wallet balance. 
+*This means that the front-end provider has read access (only) to your wallet and all of its activity.* This is necessary for the encrypted data on-chain to be parsed and rendered in a human-readable format.
+However, this means that you should only connect to frontend providers that you trust, because they can see any actions taken by the connected wallet by using the provided full viewing key.
+If you desire greater privacy than this provides, you can always run your own frontend, or utilize the command-line client, [`pcli`](./pcli.md), to interact with the blockchain directly.
+
+## Updating to a new version of the extension
+
+The extension should be automatically updated every time a new version is released.
+You can view the latest version of the extension on the [Prax Wallet] page at the
+Chrome Web Store. To force a check for updates:
+
+1. Click the three-dot icon in the top right corner of the browser.
+2. From the drop-down menu, choose **Extensions -> Manage Extensions**.
+3. Select **Update** on the top panel.
+
+After updating the extension manually, it may be helpful to clear the local cache,
+as described above.
+
+[Prax Wallet]: https://chromewebstore.google.com/detail/prax-wallet/lkpmkhpnhknhmibgnmmhdhgdilepfghe

pages/web/send.mdx

@@ -1 +1 @@
-# Sending Funds
+# Sending Funds