Refine My Cloud Wallet documentation and migration steps

Author: includenull

docs/en/learn/getting-started/mycloudwallet/index.md

@@ -8,7 +8,7 @@ description: Learn about My Cloud Wallet, including passkeys, wallet migration,
 My Cloud Wallet is WAX's user-friendly wallet for signing in, managing digital assets, and using WAX-based apps. The latest version uses passkeys for sign-in and supports recovery with a 12-word mnemonic phrase.
 
 ::: info NOTE
-Cloud Wallet Mobile is currently no longer available.
+Cloud Wallet Mobile is no longer available.
 :::
 
 ## What is My Cloud Wallet?
@@ -43,10 +43,10 @@ If you used the legacy wallet, move to the new passkey-based wallet with the mig
 
 ### Account Management
 
-My Cloud Wallet lets you take full control, claiming your account with your own keys:
+Legacy account-claiming options are also available for users who want direct control of older accounts:
 
-- **[Soft Claim](/learn/getting-started/mycloudwallet/claim-account#soft-claim)**: Retain some control while keeping My Cloud Wallet integration
-- **[Hard Claim](/learn/getting-started/mycloudwallet/claim-account#hard-claim)**: Take full control of your account keys
+- **[Soft Claim](/learn/getting-started/mycloudwallet/claim-account#soft-claim)**: Keep My Cloud Wallet compatibility while moving an older account toward direct key control
+- **[Hard Claim](/learn/getting-started/mycloudwallet/claim-account#hard-claim)**: Fully take over an older account outside My Cloud Wallet custody
 
 ## Why Choose My Cloud Wallet?
 

docs/en/learn/getting-started/mycloudwallet/migration.md

@@ -15,15 +15,20 @@ Before starting the migration:
 - Use a supported browser and device for passkeys
 - Temporarily disable other password managers if they interfere with passkey prompts
 - Be ready to save recovery information securely before continuing
+- Do not close the migration window until the new wallet finishes setup
 
-Go to [mycloudwallet.com](https://www.mycloudwallet.com) and select **Migrate your account from legacy wallet**. The migration flow will send you to the legacy wallet at [legacy.mycloudwallet.com](https://legacy.mycloudwallet.com) to authenticate.
+Go to [mycloudwallet.com](https://www.mycloudwallet.com) and select **Migrate your account from legacy wallet**. The flow sends you to [legacy.mycloudwallet.com](https://legacy.mycloudwallet.com) to authenticate.
 
-After signing in to the legacy wallet, you will see two paths:
+![My Cloud Wallet sign-in screen with the legacy migration option](/assets/images/wax-cloud-wallet/mycloudwallet/migration/legacy-sign-in-migrate.png)
 
-- **Migrate account to new wallet**: Recommended for most users
-- **Advanced account claiming**: For users who want direct control of their keys through Soft Claim or Hard Claim
+After signing in to the legacy wallet, you will see two main options:
 
-For most users, choose **Migrate account to new wallet**.
+- **Use the New Cloud Wallet**: The standard migration path and the recommended choice for most users
+- **Take full control of your account**: Advanced claiming options for users who want direct key control in the legacy system
+
+For most users, choose **Use the New Cloud Wallet**.
+
+![Legacy wallet screen showing the recommended Use the New Cloud Wallet option](/assets/images/wax-cloud-wallet/mycloudwallet/migration/legacy-continue-options.png)
 
 ## Step 1: Create Your Passkey
 
@@ -36,94 +41,80 @@ You can create the passkey in one of two ways:
 
 If the browser shows the wrong password manager or the prompt fails, disable competing password managers and try again.
 
-## Step 2: Choose Your Migration Path
-
-After the passkey is set up, the wallet will ask how to migrate your account.
-
-Choose the path that matches your situation:
+![Passkey setup screen in My Cloud Wallet](/assets/images/wax-cloud-wallet/mycloudwallet/migration/setup-passkey.png)
 
-- **Claim & Migrate**: Use this if you never exported your private key from the legacy wallet
-- **Import account with private key**: Use this if you already exported your private key from the legacy wallet
+## Step 2: Continue to Migration
 
-## Path A: Claim and Migrate
+After the passkey is created, the migration UI continues into the guided legacy-account transfer flow. In the current app, most users do not choose between multiple migration sub-paths here.
 
-This is the most common path for users coming from the legacy wallet.
+Click **Continue to migration** to start the guided steps below.
 
-### 1. Back Up Your 12-Word Mnemonic Phrase
+## Step 3: Back Up Your 12-Word Mnemonic Phrase
 
 The wallet will generate a 12-word mnemonic phrase. This is your master recovery phrase.
 
 - Write it down in the correct order
 - Store it offline in a secure place
-- Do not save it in screenshots, notes apps, or cloud storage
+- Avoid screenshots or unsecured cloud storage
+
+The UI also lets you copy the phrase or download it as a `.txt` file, but offline storage is still the safest option.
 
 Select **Next** after you have stored it securely.
 
-### 2. Confirm the Mnemonic Phrase
+![Mnemonic backup screen in My Cloud Wallet](/assets/images/wax-cloud-wallet/mycloudwallet/migration/backup-mnemonic.png)
+
+## Step 4: Confirm the Mnemonic Phrase
 
 You will be asked to enter 3 of the 12 words to confirm your backup.
 
 - Enter each requested word in the correct numbered field
 - The confirmation button stays disabled until all required words are correct
 
-### 3. Save Your Owner and Active Keys
+![Mnemonic confirmation screen asking for 3 words](/assets/images/wax-cloud-wallet/mycloudwallet/migration/confirm-mnemonic.png)
 
-The migration flow also generates your blockchain keys:
+## Step 5: Review the Generated Owner and Active Public Keys
 
-- **Owner Key**
-- **Active Key**
+After mnemonic confirmation, the app derives the keys it needs for the claim flow from that mnemonic and shows the related public keys:
 
-Back up both before continuing. These are separate from your mnemonic phrase and should also be stored securely.
+- **Owner public key**
+- **Active public key**
 
-### 4. Approve the Connection Request
+These are useful for reference during the claim process, but your real recovery secret is the 12-word mnemonic phrase.
 
-A Cloud Wallet pop-up will appear asking you to approve a login request. Approve it so the new wallet can connect to your WAX account.
+![Review public keys screen in My Cloud Wallet](/assets/images/wax-cloud-wallet/mycloudwallet/migration/review-public-keys.png)
 
-### 5. Approve the Migration Transaction
+## Step 6: Approve the Legacy Claim Flow
 
-A second pop-up will appear for the on-chain migration transaction.
+The migration flow uses the legacy wallet session to claim the old account into the new passkey-based setup.
 
-- Review the request
-- Approve each transaction shown
-- Some accounts may require two approvals
+- Make sure you are signed in to the correct legacy wallet account
+- Start the claim step when prompted
+- Approve the legacy wallet transaction request
 
-### 6. Complete OTP Verification
+## Step 7: Complete OTP Verification
 
 The wallet may ask for verification codes:
 
-- If 2FA is not enabled, enter the email OTP
-- If 2FA is enabled, enter both the 2FA code and the email OTP
+- Email OTP is always required
+- If legacy-wallet 2FA is enabled, enter both the 2FA code and the email OTP
 
 If the email code does not arrive, use **Resend** and check your spam folder.
 
-### 7. Wait for Migration to Finish
+![OTP verification screen in My Cloud Wallet](/assets/images/wax-cloud-wallet/mycloudwallet/migration/otp-verification.png)
 
-The wallet will show a migration progress screen, then redirect you to the new dashboard.
+## Step 8: Wait for Wallet Creation to Finish
 
-When complete, your account name, balances, and assets should appear in the new wallet.
+After the claim succeeds, the new wallet creates your migrated wallet and passkey-backed encrypted package automatically. The app shows a countdown-based progress screen while this finishes.
 
-## Path B: Import with a Private Key
-
-Use this path only if you already exported your private key from the legacy wallet.
-
-### 1. Enter Your Private Key
-
-Paste your private key into the import form.
-
-- If the key is valid, the confirmation button becomes available
-- If the wallet says the key is invalid, re-check the key and try again
-
-### 2. Select the Accounts to Import
+When complete, your account name, balances, and assets should appear in the new wallet.
 
-The wallet will load all accounts associated with that key.
+![Migration progress screen while the wallet is being created](/assets/images/wax-cloud-wallet/mycloudwallet/migration/migration-in-progress.png)
 
-- Select the account or accounts you want to import
-- Use **Select All** if needed
-- Continue to the next step
+## If You Already Claimed in the Legacy Wallet
 
-### 3. Confirm the Import
+Some users already completed account claiming in the old system before setting up the new wallet.
 
-Review the list of selected accounts and confirm the import. The wallet will migrate the selected accounts and redirect you to the new dashboard.
+In that case, signing in to the new wallet can route you into passkey setup plus mnemonic import instead of rerunning the full guided migration above. The codebase also includes a private-key import route, but it is separate from the standard guided migration flow.
 
 ## After Migration
 
@@ -136,7 +127,7 @@ Once migration is complete, review the following:
 
 ## Advanced Path: Soft Claim and Hard Claim
 
-During migration, legacy users may also see advanced claiming options:
+The legacy wallet still exposes advanced claiming options:
 
 - **Soft Claim**: Keeps some My Cloud Wallet integration while giving you more key control
 - **Hard Claim**: Transfers full key ownership to you and removes My Cloud Wallet custody
@@ -148,6 +139,7 @@ These options are meant for advanced users. If you are unsure, use the standard
 - **Account already migrated**: Sign in directly at [mycloudwallet.com](https://www.mycloudwallet.com)
 - **Email already exists in the new wallet**: Try signing in to the new wallet first instead of restarting migration
 - **Passkey prompt does not appear**: Disable other password managers and retry
-- **Migration fails partway through**: Sign back in to the legacy wallet at [legacy.mycloudwallet.com](https://legacy.mycloudwallet.com) and resume from the migration banner
+- **Migration fails partway through**: Sign back in to the legacy wallet at [legacy.mycloudwallet.com](https://legacy.mycloudwallet.com) and resume from the legacy migration screen
+- **You already claimed in the legacy wallet**: Sign in to the new wallet again and follow the passkey setup or mnemonic-import flow it presents
 
 For more issue-specific fixes, see [Troubleshooting](/learn/getting-started/mycloudwallet/troubleshooting).

docs/en/learn/getting-started/mycloudwallet/troubleshooting.md

@@ -24,11 +24,9 @@ Try this:
 If the process did not finish:
 
 1. Sign back in to the legacy wallet at [legacy.mycloudwallet.com](https://legacy.mycloudwallet.com)
-2. Open the migration banner again
-3. Resume the migration flow
-4. Re-approve any login or transaction prompts that appear
-
-Your passkey and public key should update automatically when you restart the process.
+2. Open the **Use the New Cloud Wallet** migration flow again
+3. Resume the migration steps
+4. Re-approve any legacy-wallet prompts that appear
 
 ### I do not know whether my account already migrated
 
@@ -58,17 +56,17 @@ If another password manager appears first, disable it temporarily and retry.
 
 ### I lost access to the device that holds my passkey
 
-Use your 12-word mnemonic phrase to recover access and create a new passkey on another device.
+If you still have access on another trusted device, use **Settings > Devices > Add Device**.
 
-This same recovery flow can also be used to add a second device before you lose access to the first one.
+If you no longer have access to any existing passkey device, use your 12-word mnemonic phrase to add a new passkey with the recovery-credentials flow.
 
 ## Recovery Issues
 
 ### I did not save my 12-word mnemonic phrase
 
 The mnemonic phrase is the wallet's main recovery method. Without it, device recovery may not be possible.
 
-If you still have access to the wallet on an existing device, sign in there and review your recovery options before changing devices.
+If you still have access to the wallet on an existing device, sign in there and export the mnemonic from **Settings > Account Security > Export Mnemonic** before changing devices.
 
 ### I entered the mnemonic words and recovery is not working
 
@@ -126,12 +124,12 @@ The Vault only stays active while its session remains open and unlocked. If the
 
 ### I do not want to use the Vault
 
-You can disable the Vault in wallet settings and return to confirming each transaction individually.
+You cannot disable Vault-based signing as it is required for operation of the wallet.
 
 ## Security Reminders
 
 - Store your mnemonic phrase offline
-- Back up any generated Owner and Active keys if you are shown them during migration
+- Treat the mnemonic phrase as your main recovery secret
 - Do not share your passkey, mnemonic phrase, or private keys
 - Add a second recovery-ready device if you want stronger account resilience