docs: rewrite the user guide sentence by sentence against the prose rules

Rewrites docs/README.md from scratch for issue 672. Every statement was
checked against the code on next. The two false statements of the old
guide are gone: history rows show the other party's address in full
(the only shortened address is the label of a token with no known
symbol), and the balance list hides a token that claims ETH from the
wrong contract. Each technical word is defined in a short clause where
it first appears: block, receipt, network fee, gas, swap, token
approval, Permit, Permit2, Uniswap, contract, origin, host name, port,
nonce, hash, node.

Model: fable-5-1

docs/README.md

@@ -17,7 +17,7 @@ Firefox. This guide explains how to install it and how to use it.
 
 It does nothing else. It has:
 
-- no swap screen;
+- no swap screen (a swap exchanges one token for another);
 - no portfolio view;
 - no NFT gallery (an NFT is a non-fungible token, such as a collectible);
 - no advertising;
@@ -30,8 +30,10 @@ named below sees your IP address, as any website you visit does.
 
 By default the wallet talks to one service: the Ethereum RPC endpoint. The RPC
 endpoint is the server that the wallet asks about the blockchain and sends your
-transactions through. Usually it is a node, a computer running the Ethereum
+transactions through. The blockchain is the shared record of all Ethereum
-software. A new install uses a public one,
+transactions. It grows in blocks; a block is a batch of transactions that the
+network adds together. Usually the endpoint is a node, a computer running the
+Ethereum software. A new install uses a public one,
 `https://ethereum-rpc.publicnode.com`. You can change it in Settings.
 
 The RPC endpoint sees every address that the wallet asks about and every
@@ -40,29 +42,29 @@ balances every 10 seconds. While it is closed, it asks every 60 seconds. If you
 want privacy, point the Ethereum RPC setting at a node of your own.
 
 On Ethereum Mainnet, the main Ethereum network, the wallet reads USD prices
-through the RPC endpoint, from Chainlink price feed contracts. No price service
+through the RPC endpoint, from Chainlink price feeds. A Chainlink price feed is
-is contacted. A token with no Chainlink price feed shows no USD value.
+a contract that publishes an exchange rate on Ethereum. No price service is
+contacted. A token with no Chainlink price feed shows no USD value.
 
 Two more services get your data only after you turn on a setting. Both settings
 are off in a new install. The first screen and Settings both offer the two
 settings.
 
 - "Use Blockscout". Blockscout is an open-source block explorer, a service that
-  indexes the blockchain and answers questions about it. With the setting on,
+  reads the whole blockchain and answers questions about it. With the setting
-  the wallet sends Blockscout your addresses on each refresh, and the hash of
+  on, the wallet sends Blockscout your addresses each time it refreshes your
-  each transaction you open. A hash is the id of a transaction. In return the
+  balances, and the hash of each transaction you open. A hash is the id of a
-  wallet shows your transaction history, transaction details and the tokens you
+  transaction. In return the wallet shows your transaction history, transaction
-  have not added yourself. You can point the setting at a Blockscout server of
+  details and the tokens you have not added yourself. You can point the setting
-  your own.
+  at a Blockscout server of your own.
 - "Check recipients on Etherscan". Etherscan is a block explorer website. With
   the setting on, the wallet fetches the recipient's Etherscan page each time
   you review a send. The wallet warns when Etherscan labels the address as
   phishing, scam or exploiter. Only the recipient's address is sent. The
   Etherscan server cannot be changed.
 
-Each time a site's request opens an approval screen, the wallet checks the site
+Each time a site's request opens a window, the wallet checks the site against a
-against a phishing list built into the extension. That check sends nothing
+phishing list built into the extension. That check sends nothing anywhere.
-anywhere.
 
 These stay in your browser and never leave it:
 
@@ -70,7 +72,7 @@ These stay in your browser and never leave it:
   your password;
 - your wallet names and your settings;
 - which sites you have allowed or denied;
-- the list of fraud contracts that the wallet has seen.
+- the list of contracts that the wallet has caught issuing fake tokens.
 
 The Etherscan links on the screens are ordinary links. They contact nothing
 until you click them.
@@ -114,8 +116,8 @@ restore the wallet on any device without the password. The password protects
 only the copy stored in this browser.
 
 While a phrase wallet is in this browser, `[recovery phrase]` in Settings shows
-its phrase after your password. Once this browser's copy is gone too, the wallet
+its phrase after your password. If you lose the written phrase and this
-is lost.
+browser's copy is gone, the wallet is lost.
 
 The wallet asks for the password when you:
 
@@ -165,9 +167,10 @@ The Add Wallet screen has three tabs:
   path. Most wallets use the same rule, so the same phrase gives the same
   addresses here and elsewhere.
 - "From Key": paste one private key. The wallet gets one address.
-- "From xprv": paste an extended private key. It must be the master key, the
+- "From xprv": paste an extended private key; `xprv` is the usual short name for
-  root of the key tree, not a key computed from the root. The wallet behaves
+  one. It must be the master key, the one that every other key of the wallet is
-  like a phrase wallet but has no phrase to show.
+  computed from, not a key computed from it. The wallet behaves like a phrase
+  wallet but has no phrase to show.
 
 All three tabs ask for the same password fields. "Import" finishes the job.
 
@@ -206,10 +209,11 @@ Nothing is destroyed: the address stays yours, and any funds at it stay where
 they are. The wallet stops listing the address and forgets the sites allowed or
 denied for it.
 
-Getting the address back is not easy. "+" computes an address that this wallet
+Getting the address back is not easy. "+" computes only addresses that this
-has never listed, so never the removed one. The way back is to delete the whole
+wallet has never listed. The removed address was listed once, so "+" skips it.
-wallet and import its backup again. The scan after the import finds the address
+The way back is to delete the whole wallet and import its backup again. The scan
-only if it holds ETH or has sent a transaction.
+after the import finds the address only if it holds ETH or has sent a
+transaction.
 
 ### Deleting a wallet
 
@@ -235,14 +239,14 @@ not "Use Blockscout" is on.
 
 Other tokens appear only while "Use Blockscout" is on. Blockscout reports every
 token that an address holds. The wallet lists such a token only when it is on
-the bundled list of well-known tokens or has at least 1,000 holders. Everything
+the built-in list of well-known tokens or has at least 1,000 holders. Everything
 else is treated as spam and hidden. Turning "Use Blockscout" off removes every
 untracked token from the lists at once.
 
-The balance list and the send screen hide a token that uses a well-known symbol
+The balance list and the send screen hide a token that carries a well-known
-from another contract, `ETH` included. A token you track yourself is still
+symbol, `ETH` included, but comes from another contract. A token you track
-listed at zero while "Show tracked tokens with zero balance" is on. See Scam
+yourself is still listed at zero while "Show tracked tokens with zero balance"
-protection.
+is on. See Scam protection.
 
 ### Tracking a token
 
@@ -275,7 +279,7 @@ On an address's screen, click any balance row. The token screen shows:
 - the token's balance;
 - its contract address;
 - its name, symbol and decimals (the number of decimal places its amounts have);
-- its holder count, when known;
+- how many addresses hold it, when known;
 - its website, when known;
 - the token's own transaction history.
 
@@ -291,8 +295,9 @@ On an address's screen, click any balance row. The token screen shows:
 5. Click "Review".
 
 "Max" fills in a token's whole balance. For ETH it fills in the balance minus
-the network fee that the confirmation screen will reserve, so enter the
+the network fee. The network fee is the price the network charges to process a
-recipient first. A message says why when there is nothing to fill in.
+transaction. It depends on the recipient, so enter the recipient first. A
+message says why when there is nothing to fill in.
 
 An amount must be a number above zero, written as digits with at most one
 decimal point. ETH has 18 decimal places. A token has as many as it declares, up
@@ -306,16 +311,16 @@ address instead.
 
 The screen shows:
 
-- the type: a native ETH transfer or an ERC-20 token transfer;
+- the type: "Native ETH transfer", or "ERC-20 token transfer" with the token's
+  symbol. Native means that ETH is built into the network and needs no contract;
 - the token's contract address, for a token;
 - the From and To addresses, each in full, with an identicon (a small pixel
   picture made from the address) and an Etherscan link;
 - the amount, with its USD value;
 - your balance on this network;
-- the network fee, the price the network charges to process the transaction. The
+- the network fee. The screen shows what the transfer is expected to cost, and
-  screen shows what the transfer is expected to cost, and under it the larger
+  under it the larger amount reserved until the network has processed the
-  amount reserved until the transaction confirms. The network refunds the
+  transaction. The network refunds the difference.
-  difference.
 
 It warns when the recipient is:
 
@@ -325,9 +330,9 @@ It warns when the recipient is:
 - a contract rather than a person's address;
 - an address that has never sent a transaction and holds no ETH;
 - labelled as phishing, scam or exploiter on Etherscan, while "Check recipients
-  on Etherscan" is on. A lookup that fails shows no warning, so no warning does
+  on Etherscan" is on. A failed lookup shows no warning. A missing warning
-  not prove the address was checked. While the setting is off, a line says the
+  therefore does not prove that Etherscan was asked. While the setting is off, a
-  address was not checked.
+  line says the address was not checked.
 
 It refuses to send, and says why, when:
 
@@ -339,10 +344,10 @@ It refuses to send, and says why, when:
 - your balance could not be read.
 
 Enter your password and click "Sign & Send". The wallet signs the transaction
-and broadcasts it to the network. Before signing, it refuses when:
+and sends it to the network. Before signing, it refuses when:
 
 - the network was switched since you reviewed the send;
-- the wallet shown no longer holds the From address;
+- the selected wallet no longer holds the From address;
 - the fee or gas limit that the network quotes is above the wallet's limits,
   which allow a total fee of at most 1 ETH. Gas is the unit Ethereum measures
   work in, and the gas limit is the most gas the transaction may use;
@@ -359,8 +364,8 @@ the wallet. Then:
 - a receipt opens the success screen, with the block number, the hash and
   Etherscan links;
 - no receipt after 60 seconds opens the error screen with a timeout message. A
-  timeout does not mean the transaction failed. It may still confirm; check the
+  timeout does not mean the transaction failed. It may still be included later;
-  hash on Etherscan;
+  check the hash on Etherscan;
 - six failed lookups in a row open the error screen with a message saying the
   network could not be reached. Check the Ethereum RPC setting.
 
@@ -393,10 +398,12 @@ the setting is off, each history list shows one line saying so.
 
 Each row shows:
 
-- the age and the direction, "Sent" or "Received". A row for a call to a
+- the age and the direction, "Sent" or "Received". A transaction can also ask a
-  contract shows the name of the call instead, such as "Approve", and a symbol
+  contract to do something; that is a contract call. A row for a contract call
-  without an amount;
+  shows the call's name instead, such as "Approve" or "Swap";
-- the amount;
+- the amount. A contract call row shows an amount only when the call moved a
+  token. A swap row shows the amount received, or the amount paid in when no
+  token came back. A row with no amount shows a symbol alone;
 - the other party's address, in full. A swap row shows your own address here.
 
 The scam filters below hide fake transfers and dust from these lists. Dust is a
@@ -405,9 +412,15 @@ tiny amount of ETH.
 Tap a row to open the transaction. The transaction screen shows:
 
 - the hash;
-- the type: native ETH transfer, ERC-20 token transfer, swap, token approval,
+- the type, one of:
-  contract call or contract creation;
+    - "Native ETH Transfer";
-- the status;
+    - "ERC-20 Token Transfer";
+    - "Swap";
+    - "Token Approval", a call that lets a contract move your tokens;
+    - "Contract Call", any other call to a contract;
+    - "Contract Creation", a transaction that puts a new contract on the
+      network;
+- the status, "Success" or "Failed";
 - the From and To addresses, in full;
 - the time, as a date and time and as an age;
 - the exact amount, and under it the amount in the token's smallest unit;
@@ -431,17 +444,18 @@ wallet opens a connection request.
 
 ### Connection requests
 
-The request shows the site's origin: its address up to the first slash, for
+The request shows the site's origin, for example `https://app.example`. The
-example `https://app.example`. The origin includes the scheme (`https`), the
+origin is the start of the site's web address, before any path. It holds the
-host and the port. The request also shows the address that will be shared, which
+scheme (`https` or `http`), the host name (`app.example`) and a port number,
-is the active address. Click "Allow" or "Deny".
+which most addresses leave out. The request also shows the address that will be
+shared, which is the active address. Click "Allow" or "Deny".
 
 "Remember my choice for this site" starts ticked. The box stays as you last left
 it. While it is ticked, the wallet keeps your answer, and the site is not asked
 again. The answer applies to that exact origin and to the active address. A
 choice remembered for `https://app.example` does not cover `http://app.example`
-or another port of the same host. A choice remembered for one address does not
+or another port of the same host name. A choice remembered for one address does
-cover another.
+not cover another.
 
 Without "Remember", an allowed site stays connected until:
 
@@ -462,9 +476,10 @@ The window shows:
 - the site's origin;
 - what the transaction does, when the wallet can read it:
     - a token transfer;
-    - a token approval, which lets a contract move your tokens;
+    - a token approval;
-    - a swap, an exchange of one token for another, through the Uniswap
+    - a swap through the Uniswap Universal Router, step by step. Uniswap is a
-      Universal Router, step by step;
+      token exchange made of contracts on Ethereum, and the Universal Router is
+      its contract that carries out a swap in steps;
 - the From address and the contract or recipient, in full;
 - the value in ETH and its USD value;
 - the largest network fee the transaction can cost, with the gas limit and the
@@ -473,8 +488,8 @@ The window shows:
 - the raw data.
 
 Enter your password and click "Confirm". The wallet signs exactly the
-transaction shown, and checks the signed transaction against every value on the
+transaction shown, and checks the signed transaction against every value in the
-screen before it broadcasts anything. What you read is what goes out, or nothing
+window before it sends anything. What you read is what goes out, or nothing
 does. "Reject" tells the site you refused.
 
 One transaction request is open at a time, across all sites. While one is open,
@@ -496,21 +511,28 @@ zero-width space, is shown as its code in a small box, for example `U+200B`. The
 message is also shown as hex, that is as the hexadecimal digits of its bytes.
 
 Typed data is shown as its fields. Fields that the site added but that are not
-signed are listed apart, under "Not part of the signature". A token permission
+signed are listed apart, under "Not part of the signature".
-is a `Permit` or a Permit2 permission. Permit2 is Uniswap's contract for token
-allowances, that is for permissions to move tokens. For a token permission, a
-red warning names the spender and each token and amount that the spender may
-take.
 
-"Sign" is disabled, and the screen says why, when:
+Some typed data is a token permission: a signature that lets a spender take your
+tokens later without asking you again. The spender is the contract or address
+that the permission names. The wallet recognises two kinds:
+
+- `Permit`, a signed permission that a token's own contract accepts;
+- a Permit2 permission. Permit2 is Uniswap's contract for token allowances, that
+  is for permissions to move tokens.
+
+For a token permission, a red warning names the spender and each token and
+amount that the spender may take.
+
+"Sign" is disabled, and the window says why, when:
 
 - the typed data cannot be signed as shown;
 - the typed data names a different network than the active one;
 - a message is not hex.
 
-A request made with the older `eth_sign` method shows a warning that names the
+A request made with `eth_sign`, an older way of asking for a signature, shows a
-method. Enter your password and click "Sign" to sign. "Reject" tells the site
+warning that names it. Enter your password and click "Sign" to sign. "Reject"
-you refused.
+tells the site you refused.
 
 ### Network switch requests
 
@@ -544,21 +566,23 @@ Settings lists the sites under three headings:
 it has no address. `[x]` beside a denied site forgets the refusal.
 
 Making another address active disconnects every site allowed without "Remember",
-and rejects every request still waiting for an answer. A site remembered for the
+and rejects every request still waiting for an answer. A site whose remembered
-old address only is not told the new one.
+choice covers only the old address is not told the new one.
 
 ## Scam protection
 
-Address poisoning is a scam. The scammer gets an address that resembles one you
+Address poisoning is a scam. The scammer makes an address that looks like one
-have dealt with into your history, hoping that you copy it later instead of the
+you have dealt with. The scammer then puts that address in your history, hoping
-real one. Five defenses against this and related scams are on in a new install.
+you copy it later by mistake. Five defenses guard against this and related
+scams. The list of known scam addresses is always on. Settings has a switch for
+each of the other four, and all four are on in a new install.
 
 Fake tokens. Scammers issue tokens from their own contracts under a well-known
 symbol, such as `USDT` or `ETH`. The wallet knows which contracts may carry each
-symbol on its bundled list. The balance list and the send screen hide a token
+symbol on its built-in list. The balance list and the send screen hide a token
-that carries one of those symbols from any other contract. `ETH` and the test
+that carries one of those symbols but comes from another contract. `ETH` and the
-network's `SepoliaETH` belong to no contract at all, so every token that claims
+test network's `SepoliaETH` belong to no contract at all, so every token that
-them is hidden. In the history, the rule applies while "Hide fake tokens
+claims them is hidden. In the history, the rule applies while "Hide fake tokens
 impersonating a known symbol" is on. A token you track yourself is still listed
 at zero while "Show tracked tokens with zero balance" is on.
 
@@ -566,7 +590,7 @@ Tokens with few holders. Real tokens have many holders; tokens made for address
 poisoning have almost none. While "Hide tokens with fewer than 1,000 holders" is
 on, the history and the send screen hide a token with fewer than 1,000 reported
 holders. The balance list has its own rule: an untracked token appears only when
-it is on the bundled list or has at least 1,000 reported holders. When
+it is on the built-in list or has at least 1,000 reported holders. When
 Blockscout reports no holder count for a token, the history and the send screen
 still show it. While "Use Blockscout" is off, no holder count is known.
 
@@ -584,11 +608,12 @@ the threshold are hidden from the history. A gwei is a billionth of an ETH. The
 threshold starts at 100,000 gwei, which is 0.0001 ETH. A threshold of 0 hides
 nothing.
 
-Known scam addresses. The wallet ships a list of addresses used for fraud, for
+Known scam addresses. The wallet ships a list of addresses known for fraud,
-phishing and for wallet drainers, contracts that empty a wallet once given
+including phishing addresses and wallet drainers. A wallet drainer is a contract
-permission. Sending to one of them raises a warning on the confirmation screen,
+that empties a wallet once given permission. Sending to a listed address raises
-and such an address cannot be tracked as a token. The list holds only addresses
+a warning on the confirmation screen, and a listed address cannot be tracked as
-involved in fraud; it is not a sanctions list.
+a token. The list holds only addresses involved in fraud; it is not a sanctions
+list.
 
 Addresses and hashes are shown in full, because address poisoning relies on
 shortened ones. The only shortened address is the label of a token with no known
@@ -596,9 +621,9 @@ symbol: the first 10 characters of its contract address and "…". That label
 appears on the send screen, on the token screen, and on the confirmation and
 result screens of a send.
 
-The wallet also warns about phishing sites. The list of phishing domains is
+The wallet also warns about phishing sites. The list of phishing sites is built
-built into the extension and checked in your browser, so nobody learns which
+into the extension and checked in your browser, so nobody learns which sites you
-sites you visit. The list is as current as the AutistMask build you run.
+visit. The list is as current as the AutistMask build you run.
 
 ## Networks
 
@@ -631,25 +656,31 @@ Click the gear in the title bar.
   "+ Add token".
 - Display:
     - "Show tracked tokens with zero balance";
-    - "UTC Timestamps"; otherwise times are shown in your local time;
+    - "UTC Timestamps": times are shown in UTC, the world reference time,
+      instead of your local time;
     - the theme: System, Light or Dark.
 - Network: Ethereum Mainnet or Sepolia Testnet.
 - Ethereum RPC: the RPC endpoint URL. "Save" checks that the URL answers for the
   shown network before storing it.
-- Blockscout API: the "Use Blockscout" checkbox and the Blockscout URL. "Save"
+- Blockscout API: the "Use Blockscout" checkbox and the Blockscout URL. The API
-  checks that the URL answers before storing it. That check sends no data of
+  is the address at which a program, here the wallet, asks Blockscout its
-  yours and runs whether or not the checkbox is ticked.
+  questions. "Save" checks that the URL answers before storing it. That check
+  sends no data of yours and runs whether or not the checkbox is ticked.
 - Etherscan: the "Check recipients on Etherscan" checkbox.
-- Token Spam Protection: the four filters described under Scam protection, and
+- Token Spam Protection, the four switches described under Scam protection:
-  the dust threshold in gwei.
+    - "Hide fake tokens impersonating a known symbol";
+    - "Hide tokens with fewer than 1,000 holders";
+    - "Hide transactions from detected fraud contracts";
+    - "Hide dust transactions below N gwei", with the threshold N as a field.
 - Allowed Sites, Connected Sites, Denied Sites: see Managing sites.
 - About:
     - the project link;
     - the license and the author;
     - the version and the release date;
-    - the commit the build came from.
+    - the source code revision (the commit) the build came from.
-- Debug: hidden until you click the version ten times. It holds a checkbox that
+- Debug: hidden until you click the version ten times. It holds the checkbox
-  turns on a red banner and more detailed logging in the browser console.
+  "Enable debug mode". That checkbox turns on a red banner and more detailed
+  logging in the browser console, the browser's own log for developers.
 
 The URLs you save are remembered per network.
 
@@ -704,8 +735,9 @@ the rule `m/44'/60'/0'/0`.
 **What happens when a transaction times out?**
 
 After 60 seconds without a receipt the wallet shows the error screen. A timeout
-does not mean the transaction failed. It may still confirm; check the hash on
+does not mean the transaction failed. It may still be included later; check the
-Etherscan. Congestion or a low fee can delay confirmation past 60 seconds.
+hash on Etherscan. A busy network or a low fee can delay a transaction past 60
+seconds.
 
 ## License