update transfer commands

packages/docs/pages/users/shielded-accounts/masp-keys.mdx

@@ -4,13 +4,15 @@ import { Callout } from 'nextra-theme-docs'
 
 This section will detail the commands to generate spending keys, viewing keys and payment addresses with `namadaw`.  
 
-For an explanation of the different types of keys and addresses, see the [glossay](./glossary.mdx).
+For an explanation of the different types of keys and addresses, see the [glossary](./glossary.mdx).
 
 ### Generating a spending key and viewing key
 
-Create a new spending key with:
+The first step before interacting with the MASP is to create a spending key. A spending key is loosely analogous to the private key you may be familiar with 
+from [transparent accounts](../transparent-accounts.mdx), in the sense that it grants one the authority to spend tokens in the associated account (and must always be 
+kept secret). Create a new spending key with:
 ```bash copy
-namadaw gen --shielded --alias <your-spending-key-alias>
+namadaw gen --shielded --alias $SPENDING_KEY_ALIAS
 ```
 <Callout>
 This command will also generate a corresponding Viewing Key sharing
@@ -36,9 +38,10 @@ namadaw list --shielded --unsafe-show-secret --decrypt
 
 ### Generating a payment address
 
-Once you have created a spending key, it can be used to derive a payment address:
+Once you have created a spending key, it can be used to derive a payment address. A payment address begins with `znam` and is a public-facing address which you can 
+share when you wish to receive tokens.
 ```bash copy
-namadaw gen-payment-addr --alias <your-payment-address-alias> --key <your-spend-key-alias>
+namadaw gen-payment-addr --alias $PAYMENT_ADDRESS_ALIAS --key $SPENDING_KEY_ALIAS
 ```
 <Callout>
 It is possible (and recommended) to generate multiple payment addresses from the same spending key.
@@ -54,19 +57,20 @@ namadaw list --shielded
 
 You can recover an existing spending key from your mnemonic and add it to your wallet with:
 ```bash copy
-namadaw derive --alias <your-spend-key-alias> --shielded
+namadaw derive --alias $SPENDING_KEY_ALIAS --shielded
 ```
 
 ### Adding an existing key or payment address to your wallet
 
 If you know the raw value of a spending key, viewing key or payment address, you can add it to your wallet under an alias so you can more conveniently refer to it later.
 
 ```bash copy
-namadaw add --alias <choose-an-alias> --value <spending-key|viewing-key|payment-address>
+namadaw add --alias $ALIAS --value $HEX_VALUE
 ```
+where `$HEX_VALUE` is the hex value of a spending key, viewing key or payment address.
 
 ### Removing a key/address
 You can remove all keys/addresses associated with an alias from your wallet with:
 ```bash copy
-namadaw remove --alias <your-alias> --do-it
+namadaw remove --alias $ALIAS --do-it
 ```

packages/docs/pages/users/shielded-accounts/shielded-transfers.mdx

@@ -2,40 +2,42 @@ import { Callout } from 'nextra-theme-docs'
 
 # Shielded Transfers
 
-Once the user has a shielded balance, it can be transferred to a another shielded address. This is known as a __shielded transfer__.
+Once the user has a [shielded balance](./shielding.mdx), it can be transferred to a another shielded address. This is known as a __shielded transfer__.
 
 ## Making a shielded transfer
 
 Before making a shielded transfer, it is recommended to first sync the local shielded context:
 ```bash copy
-namadac shielded-sync --spending-keys <your-spend-key>
+namadac shielded-sync --spending-keys $SPENDING_KEY
 ```
 
 To make a shielded transfer, you must possess the relevant spending key. See the [glossary](./glossary.mdx) for
 an explanation on the types of keys and addresses used with the MASP.
 
+Use the `transfer` command to make a shielded transfer to a target shielded (`znam`) address by providing the spending key associated with the source shielded (`znam`) address:
+
 ```bash copy
 namadac transfer \
-  --source <your-spend-key> \
-  --target <destination-transparent-address> \
-  --token <token-address> \
-  --amount <amount-to-unshield> \
-  --gas-payer <your-implicit-account>
+  --source $SPENDING_KEY \
+  --target $PAYMENT_ADDRESS \
+  --token $TOKEN \
+  --amount $AMOUNT \
+  --gas-payer $IMPLICIT_ACCOUNT
 ```
 <Callout>
-Note: you must provide an implicit account you control containing funds for transcation fees.
+Note: you must provide an implicit account which you control containing funds for transcation fees.
 </Callout>
 
 
 ### Viewing your balance
 To view the up-to-date balance of your spending key (or viewing key), you must first run the `shielded-sync` command to
 sync the local shielded context with any MASP notes owned by your spending/viewing key:
 ```bash copy
-namadac shielded-sync --spending-keys <your-spend-key>
+namadac shielded-sync --spending-keys $SPENDING_KEY
 ```
 or
 ```bash copy
-namadac shielded-sync --viewing-keys <your-viewing-key>
+namadac shielded-sync --viewing-keys $VIEWING_KEY
 ```
 
 <Callout>
@@ -45,7 +47,8 @@ The first time you wish to check the balance of a spending/viewing key, you must
 
 After the sync has completed, check your balance with:
 ```bash copy
-namadac balance --owner <your-spend-or-viewing-key> --token <token address>
+namadac balance --owner $SPENDING_KEY --token $TOKEN
 ```
+(A viewing key can also be provided here instead of `$SPENDING_KEY`)  
 
 This will display the combined balance of all shielded addresses associated with that spending/viewing key.

packages/docs/pages/users/shielded-accounts/shielding.mdx

@@ -20,13 +20,21 @@ See [Shielded Key Management](./masp-keys.mdx) for details on how to do this.
 ### Derive a new shielded address (aka: payment address)
 You can (and should) derive multiple shielded addresses for the same spending key.
 
+### (If needed) submit `reveal-pk` transaction for sending address
+You can shield from either an [implicit](../transparent-accounts/implicit-accounts.mdx) or [established](../transparent-accounts/established-accounts.mdx) account. If 
+shielding from an implicit account, your account's public key must first be revealed on-chain. This only needs to be done once per account:
+```bash copy
+namadac reveal-pk --public-key $IMPLICIT_ACCOUNT_ALIAS
+```
+
 ### Send your shielding transfer
+Use the `shield` command to make a shielding transfer from a source transparent (`tnam`) address to a target shielded (`znam`) address:
 ```bash copy
-namadac transfer \
-  --source <your-transparent-address> \
-  --target <your-shielded-address> \
-  --token <token-address> \
-  --amount <amount-to-shield>
+namadac shield \
+  --source $TRANSPARENT_ACCOUNT \
+  --target $PAYMENT_ADDRESS \
+  --token $TOKEN \
+  --amount $AMOUNT
 ```
 
 </Steps>
@@ -35,11 +43,11 @@ namadac transfer \
 To view the up-to-date balance of your spending key (or viewing key), you must first run the `shielded-sync` command to
 sync the local shielded context with any MASP notes owned by your spending/viewing key:
 ```bash copy
-namadac shielded-sync --spending-keys <your-spend-key>
+namadac shielded-sync --spending-keys $SPENDING_KEY
 ```
 or
 ```bash copy
-namadac shielded-sync --viewing-keys <your-viewing-key>
+namadac shielded-sync --viewing-keys $VIEWING_KEY
 ```
 
 <Callout>
@@ -49,7 +57,8 @@ The first time you wish to check the balance of a spending/viewing key, you must
 
 After the sync has completed, check your balance with:
 ```bash copy
-namadac balance --owner <your-spend-or-viewing-key> --token <token address>
+namadac balance --owner $SPENDING_KEY --token $TOKEN
 ```
+(A viewing key can also be provided here instead of `$SPENDING_KEY`)  
 
 This will display the combined balance of all shielded addresses associated with that spending/viewing key.

packages/docs/pages/users/shielded-accounts/unshielding.mdx

@@ -10,21 +10,23 @@ Assets can also be sent directly from a shielded address through IBC -- see the
 
 Before making an unshielding transfer, it is recommended to first sync the local shielded context:
 ```bash copy
-namadac shielded-sync --spending-keys <your-spend-key>
+namadac shielded-sync --spending-keys $SPENDING_KEY
 ```
 
 To make an unshielding transfer, you must possess the relevant spending key. See the [glossary](./glossary.mdx) for
 an explanation on the types of keys and addresses used with the MASP.
 
+Use the `unshield` command to make an unshielding transfer to a target transparent (`tnam`) address by providing the spending key associated with a source shielded (`znam`) address:
+
 ```bash copy
-namadac transfer \
-  --source <your-spend-key> \
-  --target <destination-transparent-address> \
-  --token <token-address> \
-  --amount <amount-to-unshield> \
-  --gas-payer <your-implicit-account>
+namadac unshield \
+  --source $SPENDING_KEY \
+  --target $TRANSPARENT_ACCOUNT \
+  --token $TOKEN \
+  --amount $AMOUNT \
+  --gas-payer $IMPLICIT_ACCOUNT
 ```
 <Callout>
-Note: you must provide an implicit account you control containing funds for transcation fees. This does not have to be
+Note: you must provide an implicit account which you control containing funds for transcation fees. This does not have to be
 the same as the target.
 </Callout>

packages/docs/pages/users/transparent-accounts/send-and-receive-nam-tokens.mdx

@@ -16,13 +16,14 @@ Transfers to/from a `znam...` address (that is, to/from the [MASP](../shielded-a
 For help creating a new account, see the sections on [Generating an implicit account](../transparent-accounts/implicit-accounts.mdx) or [Using the file system wallet](../../users/wallet/file-system-wallet.mdx).
 </Callout>
 
-To submit a regular token transfer from your account to the `validator-1` address:
+To send a transparent transfer -- that is, a transfer from one transparent address to another -- we use the `transparent-transfer` command. Transparent transfers are so 
+named because all associated info (including sender, receiver, asset and amount) is publicly visible on-chain.
 
 ```shell copy
-namada client transfer \
-  --source <your address or alias> \
-  --target <destination address or alias> \
-  --token <token alias or address> \
+namada client transparent-transfer \
+  --source $SOURCE \
+  --target $TARGET \
+  --token $TOKEN \
   --amount 10
 ```
 
@@ -33,7 +34,7 @@ This command will attempt to find and use the key of the source address to sign
 To query token balances for a specific token and/or owner:
 
 ```shell copy
-namada client balance --token <token alias or address> --owner <account alias or address>
+namada client balance --token $TOKEN --owner $ACCOUNT
 ```
 
 <Callout type="info">