chore: repo policy compliance sweep — test rerun, npx, frozen lockfile, docs (closes #166)

- script/test runs the suite quietly, then reruns it with --verbose on
  failure and always exits 1 (REPO_POLICIES.md conditional verbose rerun
  pattern). New package.json script test:verbose is the -v form of the
  existing jest --forceExit invocation.
- build.js calls node_modules/.bin/tailwindcss instead of npx, which
  would fetch from the registry unpinned if the binary were absent.
- make install uses --frozen-lockfile, so a stale yarn.lock fails the
  target instead of being silently rewritten.
- README Getting Started uses make setup (which also installs the
  pre-commit hook); the Makefile-only targets (install, hooks, build,
  build-debug, clean, dev) are now documented in Entrypoints.
- .dockerignore records why .git is deliberately not excluded.

README.md

@@ -287,10 +287,10 @@ on a different table knows exactly tf I am talking about.
 
 Every interactive element must visually indicate that it is clickable. Buttons
 use a visible border, padding, and a hover state (invert to white-on-black).
-Text that triggers an action (e.g. "Add additional wallet...") uses an
+Text that triggers an action (e.g. "Import private key") uses an underline. No
-underline. No invisible hit targets, no bare text that happens to have a click
+invisible hit targets, no bare text that happens to have a click handler. If it
-handler. If it does something when you click it, it must look like it does
+does something when you click it, it must look like it does something when you
-something when you click it.
+click it.
 
 #### Display Consistency
 
@@ -350,18 +350,12 @@ attack.
 
 The core hierarchy is **Wallets → Addresses**:
 
-- A **wallet** is one of three types:
+- A **wallet** is either:
-    - An **HD wallet** (`type: "hd"`, recovery phrase): generates multiple
+    - An **HD wallet** (recovery phrase): generates multiple addresses from a
-      addresses from a single 12/24 word recovery phrase using BIP-39/BIP-44
+      single 12/24 word recovery phrase using BIP-39/BIP-44 derivation. The user
-      derivation. The user can add more addresses with a "+" button.
+      can add more addresses with a "+" button.
-    - A **key wallet** (`type: "key"`, private key): a single address imported
+    - A **key wallet** (private key): a single address imported directly from a
-      directly from a private key. No "+" button since there is only one
+      private key. No "+" button since there is only one address.
-      address.
-    - An **xprv wallet** (`type: "xprv"`, extended private key): the same
-      multi-address behavior as an HD wallet, including the "+" button and the
-      address scan on import, but imported from an extended private key rather
-      than a recovery phrase. It therefore has no recovery phrase to display or
-      back up.
 - An **address** holds ETH and any user-added ERC-20 tokens.
 - The user can have multiple wallets, each with multiple addresses (HD) or a
   single address (key).
@@ -376,140 +370,95 @@ menus.
 
 ### Screen Map
 
-Navigation uses a stack model (like iOS): each forward action pushes the current
+Navigation uses a stack model (like iOS): each action pushes a screen onto the
-screen onto `state.viewStack`, and "Back" pops it (`pushCurrentView()` and
+stack, and "Back" pops it. The root screen is either Welcome (no wallets) or
-`goBack()` in `src/popup/views/helpers.js`). The root screen is either Welcome
+Home (has wallets). Screens are listed below with their elements and
-(no wallets) or Home (has wallets). Each screen below gives its view id in
+transitions.
-parentheses; the registry of view ids is the `VIEWS` array in
-`src/popup/views/helpers.js`, and the markup for a screen is the element with id
-`view-` plus that view id in `src/popup/index.html`.
 
-Three elements sit outside the screens and are present on all of them: the title
+#### Welcome
-bar ("AutistMask by @sneak" plus the Settings gear), the flash message line
-under it, and the red banner at the very top that appears on a debug build, when
-runtime debug mode is on, or when the active network is a testnet. They are not
-repeated in the element lists below.
 
-Closing and reopening the popup returns to the screen the user was last on only
+- **When**: No wallets exist yet.
-for the views listed in `RESTORABLE_VIEWS` (`src/popup/index.js`). Every other
+- **Elements**: "AutistMask" heading, brief intro text, "Add wallet" button.
-screen, including ExportPrivKey, falls back to Home.
-
-#### Welcome (`welcome`)
-
-- **When**: No wallets exist yet (`state.hasWallet` is false). This is the root
-  screen in that case.
-- **Elements**:
-    - "Welcome! To get started, add a wallet." text
-    - "Add wallet" button
 - **Transitions**:
     - "Add wallet" → **AddWallet**
 
-#### Home (`main`)
+#### Home
 
 - **When**: At least one wallet exists. This is the root screen.
 - **Elements**:
-    - Active address ETH balance (large) + USD value in parentheses
+    - Header: "AutistMask", Settings gear button
-    - "Total:" USD value across ETH and all tracked tokens of the active address
+    - Active address ETH balance (large) + USD value (inline parentheses)
+    - Total USD value across all tokens (small text)
     - Active address (color dot, full address, etherscan link, tap to copy)
-    - Send / Receive quick-action buttons, both acting on the active address
+    - Send / Receive quick-action buttons
     - ETH/USD price display
-    - Wallet list: each wallet shows its name (tap to rename inline) and a "+"
+    - Wallet list: each wallet shows name (tap to rename), "+" button (HD only),
-      button for HD and xprv wallets, then one block per address with "Address
+      and its addresses with color dots, balances, and `[info]` buttons
-      N" (bold when active), the ENS name if resolved, the full address, an
+    - Recent transactions across all addresses (merged, deduplicated, filtered)
-      `[info]` button, the address USD total, and a balance line for ETH and for
-      each tracked token
-    - "Recent Transactions": up to 25 transactions merged across every address
-      of every wallet, deduplicated by hash and filtered
     - "Add additional wallet..." link at bottom
 - **Transitions**:
-    - Tap address row → sets the active address and broadcasts
+    - Tap address row → sets active address (no screen change)
-      `AUTISTMASK_ACTIVE_CHANGED` (no screen change)
-    - Tap wallet name → inline rename field (no screen change)
-    - "+" on wallet → derives the next address inline (no screen change)
     - `[info]` on address → **AddressDetail**
-    - "Send" → **Send** (refuses with a flash message on a zero balance)
+    - "Send" → **Send** (selects active address)
     - "Receive" → **Receive** (shows active address QR)
-    - Tap home tx row → **TransactionDetail**
+    - "+" on wallet → derives next address inline
     - "Add additional wallet..." → **AddWallet**
     - Settings gear → **Settings** (toggles; tap again to return)
+    - Tap home tx row → **AddressDetail** (for the address involved)
 
-#### AddWallet (`add-wallet`)
+#### AddWallet
 
-- **When**: User wants to add a new wallet (from Welcome, Home, or Settings).
+- **When**: User wants to add a new wallet (from Home, Welcome, or Settings).
-  This one screen covers all three import modes; there is no separate import
-  screen.
 - **Elements**:
-    - "Back" button, "Add Wallet" heading
+    - "Add Wallet" heading, "Back" button
-    - Three tabs — "From Phrase" (`tab-mnemonic`), "From Key" (`tab-privkey`),
+    - Instruction text
-      "From xprv" (`tab-xprv`) — each showing its own form section:
+    - Die button `[die]` (generates random recovery phrase)
-        - **From Phrase**: instruction text, a die button that generates a
+    - Recovery phrase textarea
-          random recovery phrase, a recovery phrase textarea, and a backup
+    - Backup warning box (shown after die is clicked)
-          warning box that becomes visible once the die button has been used
+    - Password + confirm password inputs
-        - **From Key**: instruction text and a masked private key input
+    - "Add" button
-        - **From xprv**: instruction text and a masked extended private key
+    - "Have a private key instead?" link
-          input
+- **Transitions**:
-    - Password + confirm password inputs, with a hint line whose wording depends
+    - "Add" (valid phrase + password) → **Home**
-      on the selected tab
+    - "Back" → previous screen (Home or Welcome)
+    - "Have a private key instead?" → **ImportKey**
+
+#### ImportKey
+
+- **When**: User wants to import a single private key.
+- **Elements**:
+    - "Import Private Key" heading, "Back" button
+    - Instruction text
+    - Private key input (password-masked)
+    - Password + confirm password inputs
     - "Import" button
 - **Transitions**:
-    - "Import" with a valid entry and a matching password of at least 12
+    - "Import" (valid key + password) → **Home**
-      characters → creates the wallet, clears the navigation stack, and →
+    - "Back" → **AddWallet**
-      **Home**. The phrase and xprv modes then scan for further used addresses
-      and report the count as a flash message.
-    - "Import" with an invalid entry, a duplicate wallet or address, or a short
-      or mismatched password → flash message, no screen change
-    - "Back" → previous screen (Welcome, Home, or Settings)
 
-#### AddressDetail (`address`)
+#### AddressDetail
 
 - **When**: User tapped `[info]` on an address from Home.
 - **Elements**:
     - "Back" button
     - Blockie identicon (48px, centered)
     - Title: "Wallet Name — Address N"
-    - ENS name (if resolved, bold above the address)
+    - ENS name (if resolved, bold with color dot)
     - Full address (color dot, etherscan link, tap to copy)
     - USD total for address
     - Balance list: ETH + tracked ERC-20 tokens (4 decimal places, USD inline).
       Each balance row is clickable → **AddressToken**
-    - Send / Receive / + Token buttons and a "···" menu button
+    - Send / Receive / + Token buttons
-    - "···" dropdown containing a single "Export Private Key" entry
     - Transaction list (with ENS resolution for counterparties)
 - **Transitions**:
     - Tap balance row → **AddressToken** (for that token)
-    - "Send" → **Send** (refuses with a flash message on a zero balance)
+    - "Send" → **Send**
     - "Receive" → **Receive**
     - "+ Token" → **AddToken**
-    - "···" → "Export Private Key" → **ExportPrivKey**
     - Tap transaction row → **TransactionDetail**
-    - "Back" → previous screen (Home)
+    - "Back" → **Home**
 
-#### ExportPrivKey (`export-privkey`)
+#### AddressToken
-
-- **When**: User chose "Export Private Key" from the "···" menu on
-  AddressDetail. This screen discloses secret material.
-- **Elements**:
-    - "Back" button
-    - Blockie identicon (48px, centered)
-    - "Export Private Key" heading
-    - "Wallet Name — Address N" and the full address (etherscan link, tap to
-      copy)
-    - Warning that anyone holding the private key can transfer all funds from
-      the address
-    - Error line
-    - Password input and "Reveal" button, shown until the key is revealed
-    - The private key on a highlighted background, tap to copy, shown only after
-      the password has been accepted
-- **Transitions**:
-    - "Reveal" (correct password) → decrypts the wallet secret, derives this
-      address's key, hides the password input and shows the key (no screen
-      change)
-    - "Reveal" (wrong password) → "Wrong password." on the error line, nothing
-      revealed
-    - "Back" → clears the key and password from the DOM, then → previous screen
-      (AddressDetail)
-
-#### AddressToken (`address-token`)
 
 - **When**: User clicked a specific token balance on AddressDetail.
 - **Elements**:
@@ -520,64 +469,49 @@ screen, including ExportPrivKey, falls back to Home.
     - USD total for this token
     - Single token balance line (4 decimal places)
     - Send / Receive buttons
-    - Token contract well (ERC-20 only): full contract address (tap to copy,
-      etherscan link) plus name, symbol, decimals, holder count and project
-      website where known
     - Token-filtered transaction list (only this token's transfers)
 - **Transitions**:
-    - "Send" → **Send** (token locked: the dropdown is replaced by a static
+    - "Send" → **Send** (token pre-selected and locked in dropdown)
-      symbol and contract address)
     - "Receive" → **Receive** (ERC-20 warning shown for non-ETH tokens)
     - Tap transaction row → **TransactionDetail**
-    - "Back" → previous screen (AddressDetail)
+    - "Back" → **AddressDetail**
 
-#### Send (`send`)
+#### Send
 
-- **When**: User wants to send ETH or a token, from Home, AddressDetail, or
+- **When**: User wants to send ETH or a token from this address.
-  AddressToken.
 - **Elements**:
-    - "Back" button, "Send" heading
+    - "Send" heading, "Back" button
     - From: address with color dot + etherscan link
     - What to send: token dropdown (or static display with contract address when
       locked from AddressToken)
-    - To: address or ENS name input, with an inline validation message
+    - To: address or ENS name input
     - Amount input with current balance display
-    - "Review" button, disabled until the recipient validates
+    - "Review" button
 - **Transitions**:
     - "Review" (valid inputs, ENS resolved) → **ConfirmTx**
-    - "Review" with an unresolvable ENS name or an invalid amount → flash
+    - "Back" → **AddressToken** (if came from token view) or **AddressDetail**
-      message, no screen change
-    - "Back" → previous screen (Home, AddressDetail, or AddressToken)
 
-#### ConfirmTx (`confirm-tx`)
+#### ConfirmTx
 
 - **When**: User reviewed send details and is ready to authorize.
 - **Elements**:
-    - "Back" button, "Confirm Transaction" heading
+    - "Confirm Transaction" heading, "Back" button
     - Type: "Native ETH transfer" or "ERC-20 token transfer (SYMBOL)"
     - Token contract: full address + etherscan link (ERC-20 only)
     - From: blockie + color dot + full address + etherscan link + wallet title
     - To: blockie + color dot + full address + etherscan link + ENS name
     - Amount: value + symbol (USD in parentheses)
     - Your balance: value + symbol (USD in parentheses)
-    - Estimated network fee: "Estimating..." then the ETH amount (USD in
+    - Estimated network fee: ETH amount (USD in parentheses), fetched async
-      parentheses) or "Unable to estimate", fetched async
+    - Warnings (scam address, self-send)
-    - Warnings: inline warnings from the local checks (scam address, self-send)
-      plus four reserved warning boxes made visible by the async checks —
-      recipient with no transaction history, recipient is a contract, burn
-      address, and an Etherscan phishing/scam label
     - Errors (insufficient balance)
-    - Password: an inline field on this screen, not a modal, with its own error
+    - "Send" button (disabled if errors)
-      line
-    - "Sign & Send" button (disabled if errors)
 - **Transitions**:
-    - "Sign & Send" (correct password) → broadcast tx → **WaitTx**
+    - "Send" → password modal → broadcast tx → **WaitTx**
-    - "Sign & Send" (correct password) → broadcast fails → **ErrorTx**
+    - "Send" → password modal → broadcast fails → **ErrorTx**
-    - "Sign & Send" (wrong password) → "Wrong password." on the password error
-      line, no screen change
     - "Back" → **Send**
 
-#### WaitTx (`wait-tx`)
+#### WaitTx
 
 - **When**: Transaction has been broadcast, waiting for on-chain confirmation.
 - **Elements**:
@@ -591,24 +525,20 @@ screen, including ExportPrivKey, falls back to Home.
     - Receipt found → **SuccessTx**
     - 60 seconds without confirmation → **ErrorTx** (timeout message)
 
-#### SuccessTx (`success-tx`)
+#### SuccessTx
 
 - **When**: Transaction confirmed on-chain.
 - **Elements**:
     - "Transaction Confirmed" heading
-    - Decoded action well (shown when the transaction carried recognized
-      calldata; the top-level Amount and To are hidden in that case)
     - Amount + symbol
     - To: color dot + full address + etherscan link
     - Block number
     - Transaction hash: full hash (tap to copy) + etherscan link
     - "Done" button
 - **Transitions**:
-    - "Done" in the approval popup → closes the popup window
+    - "Done" → **AddressToken** (if `selectedToken` set) or **AddressDetail**
-    - "Done" otherwise → resets the navigation stack, then → **AddressToken**
-      (if `selectedToken` set) or **AddressDetail**
 
-#### ErrorTx (`error-tx`)
+#### ErrorTx
 
 - **When**: Transaction broadcast failed, or timed out waiting for confirmation.
 - **Elements**:
@@ -620,28 +550,24 @@ screen, including ExportPrivKey, falls back to Home.
       full hash (tap to copy) + etherscan link
     - "Done" button
 - **Transitions**:
-    - "Done" in the approval popup → closes the popup window
+    - "Done" → **AddressToken** (if `selectedToken` set) or **AddressDetail**
-    - "Done" otherwise → resets the navigation stack, then → **AddressToken**
-      (if `selectedToken` set) or **AddressDetail**
 
-#### Receive (`receive`)
+#### Receive
 
-- **When**: User wants to receive funds at this address, from Home,
+- **When**: User wants to receive funds at this address.
-  AddressDetail, or AddressToken.
 - **Elements**:
-    - "Back" button, "Receive" heading
+    - "Receive" heading, "Back" button
     - Instruction text
     - QR code encoding the address
     - Full address (color dot, selectable, etherscan link)
     - "Copy address" button
     - ERC-20 warning (shown when navigating from AddressToken for non-ETH token)
 - **Transitions**:
-    - "Back" → previous screen (Home, AddressDetail, or AddressToken)
+    - "Back" → **AddressToken** (if `selectedToken` set) or **AddressDetail**
 
-#### TransactionDetail (`transaction`)
+#### TransactionDetail
 
-- **When**: User tapped a transaction row on Home, AddressDetail, or
+- **When**: User tapped a transaction row from AddressDetail or AddressToken.
-  AddressToken.
 - **Elements** (grouped into logical blocks using light well containers; field
   labels are self-explanatory so groups have no headings):
     - "Transaction" heading, "Back" button
@@ -666,182 +592,91 @@ screen, including ExportPrivKey, falls back to Home.
     - Raw data (shown when calldata is present): full calldata in monospace
       dashed border
 - **Transitions**:
-    - "Back" → previous screen (Home, AddressDetail, or AddressToken)
+    - "Back" → **AddressToken** (if `selectedToken` set) or **AddressDetail**
 
-#### AddToken (`add-token`)
+#### AddToken
 
-- **When**: User wants to track an ERC-20 token, reached from "+ Token" on
+- **When**: User wants to track an ERC-20 token on this address.
-  AddressDetail.
 - **Elements**:
-    - "Back" button, "Add Token" heading
+    - "Add Token" heading, "Back" button
     - Instruction text (find contract address on Etherscan)
     - Contract address input
-    - Status line ("Looking up token...", cleared or replaced on failure)
+    - Token info preview (name, symbol — fetched from contract)
-    - Common token quick-pick buttons (top 25 by market cap), which fill the
+    - Common token quick-pick buttons
-      contract address input
     - "Add" button
 - **Transitions**:
-    - "Add" (valid contract) → tracks the token, pops the stack, and re-renders
+    - "Add" (valid contract) → **AddressDetail**
-      **AddressDetail**
+    - "Back" → **AddressDetail**
-    - "Add" with a token already tracked, a scam-listed address, or a failed
-      contract lookup → flash message, no screen change
-    - "Back" → previous screen (AddressDetail)
 
-#### Settings (`settings`)
+#### Settings
 
-- **When**: User tapped the Settings gear.
+- **When**: User tapped Settings gear from Home.
 - **Elements**:
-    - "Back" button, "Settings" heading
+    - "Settings" heading, "Back" button
-    - Wallets: one row per wallet with its name (tap to rename inline) and an
+    - Wallets: "+ Add wallet" button
-      `[x]` delete button, plus a "+ Add wallet" button
+    - Display: "Show tracked tokens with zero balance" checkbox
-    - Tracked Tokens: one row per tracked token with an `[x]` remove button,
+    - Ethereum RPC: endpoint URL input + "Save" button
-      plus a "+ Add token" button
+    - Blockscout API: endpoint URL input + "Save" button
-    - Display: "Show tracked tokens with zero balance" checkbox and a Theme
-      selector (System / Light / Dark)
-    - Network: network selector (Ethereum Mainnet / Sepolia Testnet); switching
-      resets the RPC and Blockscout endpoints to that network's defaults
-    - Ethereum RPC: endpoint URL input + "Save" button (validated against
-      `eth_chainId` before being saved)
-    - Blockscout API: endpoint URL input + "Save" button (validated against
-      `/stats` before being saved)
     - Token Spam Protection:
         - "Hide tokens with fewer than 1,000 holders" checkbox
         - "Hide transactions from detected fraud contracts" checkbox
         - "Hide dust transactions below N gwei" checkbox + threshold input
-        - "UTC Timestamps" checkbox
     - Allowed Sites: list with remove buttons
     - Denied Sites: list with remove buttons
-    - About: project link, license, author, version, release date, and the
-      commit, which links to the commit in the repository
-    - Debug: hidden until revealed, then an "Enable debug mode" checkbox that
-      turns on the red banner and verbose logging
 - **Transitions**:
     - "+ Add wallet" → **AddWallet**
-    - "+ Add token" → **SettingsAddToken**
+    - "Back" (or Settings gear again) → **Home**
-    - `[x]` on a wallet → **DeleteWallet**
-    - Tap wallet name → inline rename field (no screen change)
-    - `[x]` on a tracked token or a site → removes it in place (no screen
-      change)
-    - Ten clicks on the version → reveals the Debug well (no screen change)
-    - "Back" (or Settings gear again) → previous screen (Home)
 
-#### DeleteWallet (`delete-wallet-confirm`)
+#### SiteApproval
 
-- **When**: User tapped the `[x]` next to a wallet in Settings.
+- **When**: A website requests wallet access via `eth_requestAccounts`. Opened
-- **Elements**:
+  in a separate popup by the background script.
-    - "Back" button, "Delete Wallet" heading
-    - Warning naming the wallet and stating that deletion is permanent and any
-      funds are unrecoverable without the recovery phrase
-    - Error line
-    - Password input
-    - "Confirm Delete" button
-- **Transitions**:
-    - "Confirm Delete" (correct password, other wallets remain) → deletes the
-      wallet and its site permissions, then → **Settings** with a "Wallet
-      deleted." flash message
-    - "Confirm Delete" (correct password, last wallet) → deletes the wallet,
-      clears the selection and the navigation stack, then → **Welcome**
-    - Either way, the active address moves only if it belonged to the deleted
-      wallet, and `AUTISTMASK_ACTIVE_CHANGED` is broadcast when it does
-      (`src/shared/walletDelete.js`)
-    - "Confirm Delete" (wrong password) → "Wrong password." on the error line,
-      nothing deleted
-    - "Back" → previous screen (Settings)
-
-#### SettingsAddToken (`settings-addtoken`)
-
-- **When**: User tapped "+ Add token" in Settings. Tokens added here are tracked
-  across every address, unlike AddToken which is reached from one address.
-- **Elements**:
-    - "Back" button, "Add Token" heading
-    - Instruction text
-    - "Top tokens:" quick-pick buttons (top 10 by market cap; already-tracked
-      tokens are disabled)
-    - "Or pick from top 100:" dropdown (already-tracked tokens are disabled) +
-      "Add selected" button
-    - "Or enter contract address:" input, a status line, and an "Add" button
-- **Transitions**:
-    - Any of the three add paths, on success → adds the token and shows an
-      "Added SYMBOL" flash message (no screen change)
-    - A duplicate, a scam-listed address, or a failed contract lookup → flash
-      message, no screen change
-    - "Back" → previous screen (Settings)
-
-#### SiteApproval (`approve-site`)
-
-- **When**: A website requests wallet access via `eth_requestAccounts` or
-  `wallet_requestPermissions` and is on neither the allowed nor the denied list.
-  The background script prefers the toolbar popup (`action.openPopup()`) and
-  falls back to a separate popup window (`src/background/index.js`,
-  `requestApproval()`).
 - **Elements**:
     - "Connection Request" heading
-    - Phishing warning banner (shown when the hostname is on the phishing
+    - Site hostname (bold)
-      blocklist)
-    - Site hostname (bold) + "wants to connect to your wallet"
     - Address that will be shared (color dot + full address + etherscan link)
     - "Remember my choice for this site" checkbox
     - "Allow" / "Deny" buttons
 - **Transitions**:
-    - "Allow" / "Deny" → closes popup (returns result to background script; the
+    - "Allow" / "Deny" → closes popup (returns result to background script)
-      choice is persisted to the allowed or denied list when "Remember" is
-      checked)
-    - Popup closed without answering → treated as a denial
 
-#### TxApproval (`approve-tx`)
+#### TxApproval
 
 - **When**: A connected website requests a transaction via
-  `eth_sendTransaction`. Always opened in a separate popup window by the
+  `eth_sendTransaction`. Opened via the toolbar popup by the background script.
-  background script (`windows.create()`), because the request is triggered
-  programmatically rather than by a user gesture.
 - **Elements**:
     - "Transaction Request" heading
-    - Phishing warning banner (shown when the hostname is on the phishing
-      blocklist)
     - Site hostname (bold) + "wants to send a transaction"
     - Decoded action (if calldata is recognized): action name, token details,
       amounts, steps, deadline (see Transaction Decoding)
     - From: color dot + full address + etherscan link
-    - Contract: color dot + full address + etherscan link (or "contract
+    - To/Contract: color dot + full address + etherscan link (or "contract
       creation"), token symbol label if known
-    - Value: amount in ETH (4 decimal places, USD in parentheses)
+    - Value: amount in ETH (4 decimal places)
     - Raw data: full calldata displayed inline (shown if present)
-    - Password input and an error line
+    - Password input
     - "Confirm" / "Reject" buttons
 - **Transitions**:
-    - "Confirm" (correct password) → decrypts and signs in the popup, hands the
+    - "Confirm" (with password) → closes popup (returns result to background)
-      signed transaction to the background to broadcast, then → **WaitTx** in
-      the same popup window
-    - "Confirm" (wrong password) → error line, no screen change
     - "Reject" → closes popup (returns rejection to background)
-    - Popup window closed without answering → the request is rejected with
-      EIP-1193 code 4001
 
-#### SignApproval (`approve-sign`)
+#### SignApproval
 
 - **When**: A connected website requests a message signature via
-  `personal_sign`, `eth_sign`, or `eth_signTypedData_v4`. Opened the same way as
+  `personal_sign`, `eth_sign`, or `eth_signTypedData_v4`. Opened via the toolbar
-  TxApproval, in a separate popup window.
+  popup by the background script.
 - **Elements**:
     - "Signature Request" heading
-    - Phishing warning banner (shown when the hostname is on the phishing
-      blocklist)
     - Site hostname (bold) + "wants you to sign a message"
-    - Danger warning box (shown for `eth_sign`, which signs a raw hash)
     - Type: "Personal message" or "Typed data (EIP-712)"
     - From: color dot + full address + etherscan link
     - Message: decoded UTF-8 text (personal_sign) or formatted domain/type/
       message fields (EIP-712 typed data)
-    - Password input and an error line
+    - Password input
     - "Sign" / "Reject" buttons
 - **Transitions**:
-    - "Sign" (correct password) → signs locally → closes popup (returns
+    - "Sign" (with password) → signs locally → closes popup (returns signature)
-      signature)
-    - "Sign" (wrong password, or a signing failure) → error line, no screen
-      change
     - "Reject" → closes popup (returns rejection to background)
-    - Popup window closed without answering → the request is rejected with
-      EIP-1193 code 4001
 
 ### External Services
 
@@ -996,7 +831,6 @@ hardcoded test phrase.
 - Create new HD wallet (generates 12-word recovery phrase)
 - Import HD wallet from existing 12 or 24 word recovery phrase
 - Import single-address wallet from private key
-- Import multi-address wallet from an extended private key (`xprv`)
 - Add multiple addresses within an HD wallet
 - Manage multiple wallets simultaneously
 - View ETH balance per address
@@ -1168,7 +1002,7 @@ Currently supported:
 
 ### Transactions
 
-- [x] Gas estimation and fee display before confirming
+- [ ] Gas estimation and fee display before confirming
 
 ### Testing
 

TODO.md

@@ -48,12 +48,6 @@ undefined identifiers, which is how
   Tailwind binary instead of `npx`, `--frozen-lockfile` on `make install`, and
   the Makefile-only targets documented in the README
   ([#166](https://git.eeqj.de/sneak/AutistMask/issues/166)).
-- 2026-08-11: README Screen Map rebuilt from the code — every screen, element
-  and transition re-verified against `src/popup/`
-  ([#164](https://git.eeqj.de/sneak/AutistMask/issues/164)).
-- 2026-08-11: `docs/README.md` rewritten against the code: no competitor names,
-  all five network destinations documented, password/Settings/Add Wallet
-  sections corrected ([#163](https://git.eeqj.de/sneak/AutistMask/issues/163)).
 - 2026-08-11: Wallet deletion repairs its own state — `hasWallet` follows the
   remaining wallets, the selection only moves when it was deleted, and the
   active-address change is broadcast to connected sites

docs/README.md

@@ -6,10 +6,10 @@ and ERC-20 tokens, and connects to web3 sites. Nothing else.
 
 ## Why AutistMask Exists
 
-The most popular browser-based EVM wallet has become bloated with swap UIs,
+MetaMask has become bloated with swap UIs, portfolio dashboards, analytics,
-portfolio dashboards, analytics, tracking, and advertisements. It is no longer a
+tracking, and advertisements. It is no longer a simple wallet. Most alternatives
-simple wallet. The common alternatives only support Chromium browsers, leaving
+(Rabby, Rainbow, etc.) only support Chromium browsers, leaving Firefox users
-Firefox users without a usable option.
+without a usable option.
 
 AutistMask exists because a wallet should be a wallet. You should be able to see
 your balances, send tokens, receive tokens, and connect to sites. That is all a
@@ -27,10 +27,9 @@ analytics, use a portfolio tracker. The wallet is not the place for any of that.
 
 - **Encrypt your recovery phrase and private keys at rest.** Your secrets are
   encrypted on disk using Argon2id key derivation and XSalsa20-Poly1305
-  authenticated encryption (via libsodium). Your password is required whenever a
+  authenticated encryption (via libsodium). Your password is required only when
-  secret has to be decrypted: signing a transaction, signing a message or typed
+  signing a transaction. Viewing balances and addresses never requires a
-  data, exporting a private key, and deleting a wallet. Viewing balances and
+  password.
-  addresses never requires a password.
 
 - **Let you choose your own RPC endpoint.** The default is a public Ethereum
   RPC, but you can point it at your own node or any provider you trust. No
@@ -57,25 +56,23 @@ analytics, use a portfolio tracker. The wallet is not the place for any of that.
 
 - **No NFT galleries or portfolio views.** This is a wallet, not a dashboard.
 
-- **No third-party token list APIs.** Token balances come from the same block
+- **No token auto-discovery.** AutistMask does not scan the blockchain for
-  explorer you configure for transaction history, and the extension ships its
+  tokens you might hold. You add tokens manually by contract address. This
-  own hardcoded list of top ERC-20 contract addresses for symbol-spoofing
+  prevents scam tokens from appearing in your wallet uninvited.
-  detection. Any token you want tracked across all your addresses, you add
-  yourself by contract address.
 
-- **No backend servers operated by the developer.** Nothing is sent to any
+- **No phishing blocklists from third parties.** AutistMask does not phone home
-  server run by AutistMask. Every network destination is listed below.
+  to check URLs against a remote blocklist. It does maintain a local list of
+  known scam addresses, but this is shipped with the extension, not fetched from
+  a server.
 
 ## How It Works
 
 AutistMask is a browser extension that runs entirely in your browser. It does
-not have a backend server. It communicates with five external destinations:
+not have a backend server. It communicates with three external services:
-three you configure yourself, and two fixed ones used for scam detection.
 
 ### External Services
 
-**Ethereum JSON-RPC endpoint** (default: `ethereum-rpc.publicnode.com`;
+**Ethereum JSON-RPC endpoint** (default: `ethereum-rpc.publicnode.com`)
-`ethereum-sepolia-rpc.publicnode.com` on Sepolia)
 
 This is how AutistMask talks to the Ethereum network. Every wallet needs an
 Ethereum node to check balances, estimate gas, broadcast transactions, and
@@ -83,73 +80,27 @@ verify confirmations. The default is a free public RPC endpoint. You can change
 this in Settings to any Ethereum JSON-RPC endpoint, including your own local
 node.
 
-When it is contacted: on every balance refresh (every 10 seconds while the popup
-is open, every 60 seconds in the background), when you type an ENS name into the
-Send screen, when a send is prepared and broadcast, while a pending transaction
-is polled for its receipt, and for the reverse ENS lookups used to label
-addresses (cached for 12 hours).
-
 What gets sent: standard Ethereum JSON-RPC requests (balance queries,
-transaction broadcasts, gas estimates, ENS lookups, contract-code checks). Your
+transaction broadcasts, gas estimates, ENS lookups). Your addresses are
-addresses are necessarily visible to the RPC provider when querying balances.
+necessarily visible to the RPC provider when querying balances.
 
-**Blockscout API** (default: `eth.blockscout.com/api/v2`;
+**Blockscout API** (default: `eth.blockscout.com/api/v2`)
-`eth-sepolia.blockscout.com/api/v2` on Sepolia)
 
 Used to fetch token balances and transaction history. Blockscout is an
 open-source blockchain explorer. AutistMask queries it for your ERC-20 token
-balances (including the holder counts used for spam filtering) and your recent
+balances and recent transactions. You can change this in Settings to a
-transactions and token transfers. You can change this in Settings to a
 self-hosted Blockscout instance.
 
-When it is contacted: on every balance refresh, and whenever a screen showing
-transaction history is opened.
-
 What gets sent: your Ethereum addresses (to look up balances and transactions).
 
 **CoinDesk CADLI price API** (`data-api.coindesk.com`)
 
-Used to fetch current USD prices for ETH and the top 25 tokens. Prices are
+Used to fetch current USD prices for ETH and ERC-20 tokens. Prices are cached
-cached for 5 minutes. No API key is required. This endpoint is not
+for 5 minutes. No API key is required. No user data is sent -- only a list of
-user-configurable, and it is not contacted at all while you are on a testnet,
+token symbols (e.g. "ETH", "USDC") to get their prices.
-where no USD values are shown.
 
-When it is contacted: while the popup is open, at most once every 5 minutes.
+What gets sent: token symbol names. No addresses, no balances, no identifying
-
+information.
-What gets sent: token symbol names (e.g. "ETH", "USDC"). No addresses, no
-balances, no identifying information. As with any request, CoinDesk sees your IP
-address.
-
-**Phishing domain blocklist** (`raw.githubusercontent.com`)
-
-A community-maintained list of phishing domains, used to warn you when a site
-that asks to connect, or to have a transaction or signature approved, is a known
-scam. A copy is bundled into the extension at build time, so the protection
-works before any network request happens. At runtime the extension fetches the
-live list to pick up newly added domains, keeping only the entries not already
-in the bundled copy (persisted locally if under 256 KiB). This endpoint is not
-user-configurable.
-
-When it is contacted: once when the background script starts, and every 24 hours
-after that. It is a plain download of a public file — nothing about you is sent,
-but the host sees your IP address. If the fetch fails, the bundled copy is still
-used.
-
-**Etherscan address labels** (`etherscan.io`; `sepolia.etherscan.io` on Sepolia)
-
-When you review a send, AutistMask fetches the recipient's public Etherscan
-address page and looks for a "Fake_Phishing"/"Phish/Hack" label or a scam
-warning, and shows a red warning if it finds one. This is a plain page fetch
-with no API key, made by your browser. It is best-effort: if it fails, it is
-silently ignored. This endpoint is not user-configurable.
-
-When it is contacted: each time you reach the send confirmation screen.
-
-What gets sent: the recipient address you are about to send to, and your IP
-address. Your own addresses are not sent.
-
-Etherscan links shown elsewhere in the UI (on addresses, transactions, and token
-contracts) are ordinary links. They contact nothing until you click them.
 
 ### What Stays Local
 
@@ -172,11 +123,8 @@ word recovery phrase can restore your wallet on any device without your
 password. The password only protects the copy stored in this browser. If you
 lose your recovery phrase, your password cannot help you recover it.
 
-Your password is requested whenever an encrypted secret must be decrypted: when
+Your password is only requested when you send a transaction. Viewing balances,
-you send a transaction, when a site asks you to sign a message or typed data,
+receiving funds, and browsing transaction history never require your password.
-when you export an address's private key, and when you delete a wallet. Viewing
-balances, receiving funds, and browsing transaction history never require your
-password.
 
 ## Installation
 
@@ -199,46 +147,34 @@ password.
 ### Creating a New Wallet
 
 1. Click the AutistMask icon in your browser toolbar.
-2. Click "Add wallet" (on first use), or open Settings and click "+ Add wallet".
+2. Click "Add wallet".
-3. On the "From Phrase" tab, click the die button to generate a random 12-word
+3. Click the die button to generate a random 12-word recovery phrase.
-   recovery phrase.
 4. **Write down the recovery phrase and store it safely.** Anyone with these
    words can take your funds. If you lose them, your wallet is gone. AutistMask
    cannot recover them for you.
-5. Choose a password and confirm it. This encrypts your recovery phrase on this
+5. Choose a password. This encrypts your recovery phrase on this device.
-   device.
+6. Click "Add".
-6. Click "Import".
 
 ### Importing an Existing Wallet
 
-The Add Wallet screen has three tabs:
+**From a recovery phrase:** Follow the same steps as creating a wallet, but
+paste your existing 12 or 24 word recovery phrase instead of generating a new
+one. AutistMask uses the same derivation path as MetaMask (`m/44'/60'/0'/0`), so
+your addresses will match.
 
-**From Phrase:** Paste your existing 12 or 24 word recovery phrase instead of
+**From a private key:** On the Add Wallet screen, click "Have a private key
-generating a new one. AutistMask uses the standard BIP-44 Ethereum derivation
+instead?" and paste your private key. This creates a single-address wallet.
-path (`m/44'/60'/0'/0`), which is what other wallets use by default, so your
-addresses will match and your phrase stays portable in both directions.
-
-**From Key:** Paste a single private key. This creates a single-address wallet.
-
-**From xprv:** Paste an extended private key. This imports the HD wallet and
-scans for used addresses.
-
-All three tabs ask for the same password fields, and the "Import" button
-finishes the job.
 
 ### Adding More Addresses
 
-HD wallets (created from a recovery phrase or an xprv) can derive multiple
+HD wallets (created from a recovery phrase) can derive multiple addresses. On
-addresses. On the home screen, click the "+" button next to a wallet name to add
+the home screen, click the "+" button next to a wallet name to add the next
-the next address. These are deterministic -- the same recovery phrase will
+address. These are deterministic -- the same recovery phrase will always produce
-always produce the same sequence of addresses.
+the same sequence of addresses.
 
 ### Adding ERC-20 Tokens
 
-Tokens you hold show up automatically only if they are in the extension's
+AutistMask does not auto-discover tokens. To track a token:
-bundled list of well-known tokens or have at least 1,000 holders; everything
-else is treated as spam and hidden. To track a token explicitly (which also
-shows it at zero balance), add it by contract address:
 
 1. Go to an address detail view (click `[info]` on any address).
 2. Click "+ Token".
@@ -247,13 +183,12 @@ shows it at zero balance), add it by contract address:
 4. Click "Add".
 
 The token balance will appear on the address detail screen and on the home
-screen. Tokens can also be added from Settings, under "Tracked Tokens".
+screen.
 
 ## Sending
 
 1. Click "Send" from the home screen or an address detail view.
-2. Select what to send (ETH, or any ERC-20 token with a balance on this address
+2. Select what to send (ETH or any tracked ERC-20 token).
-   that survives the spam filters).
 3. Enter the recipient address or ENS name (e.g. `vitalik.eth`).
 4. Enter the amount.
 5. Click "Review" to see the confirmation screen.
@@ -266,14 +201,11 @@ The confirmation screen shows:
 - **Amount** with USD estimate
 - **Your current balance** with USD estimate
 - **Estimated network fee** in ETH with USD estimate
-- **Warnings** if the recipient is a contract, a burn address, one of your own
-  addresses, on the bundled scam-address list, or labelled as a phisher on
-  Etherscan
 
-After reviewing, enter your password and click "Sign & Send". The transaction
+After reviewing, click "Send" and enter your password. The transaction will be
-will be broadcast to the network and you will see a waiting screen with a timer.
+broadcast to the network and you will see a waiting screen with a timer. Once
-Once confirmed (or after 60 seconds), you will see either a success or error
+confirmed (or after 60 seconds), you will see either a success or error screen
-screen with the transaction hash and an Etherscan link.
+with the transaction hash and an Etherscan link.
 
 ### Sending a Specific Token
 
@@ -287,10 +219,10 @@ cannot accidentally switch to a different one.
 1. Click "Receive" from the home screen or an address detail view.
 2. Share the QR code or copy the address using the "Copy address" button.
 
-When receiving ERC-20 tokens, make sure the sender is sending on the network you
+When receiving ERC-20 tokens, make sure the sender is sending on the Ethereum
-are using. AutistMask supports Ethereum mainnet and the Sepolia testnet. Tokens
+network. AutistMask is an Ethereum mainnet wallet. Tokens sent on other networks
-sent on other networks (Polygon, Arbitrum, BSC, etc.) to the same address will
+(Polygon, Arbitrum, BSC, etc.) to the same address will not appear and may be
-not appear and may be permanently lost.
+permanently lost.
 
 ## Connecting to Web3 Sites
 
@@ -305,12 +237,7 @@ pages. When a site requests access to your wallet:
 
 When a connected site requests a transaction, a separate approval popup appears
 showing the transaction details (from, to, value, data). You must enter your
-password and click "Confirm" to authorize it. Message and typed-data signature
+password and click "Confirm" to authorize it.
-requests work the same way, with a "Sign" button, and also require your
-password.
-
-If the requesting site's domain is on the phishing blocklist, all three approval
-screens show a red phishing warning before you decide.
 
 You can manage site permissions in Settings. Allowed and denied sites can be
 individually removed to reset their permissions.
@@ -320,16 +247,15 @@ individually removed to reset their permissions.
 AutistMask includes several defenses against common Ethereum scams, all enabled
 by default:
 
-**Known token symbol verification.** AutistMask ships a list of roughly 500
+**Known token symbol verification.** AutistMask ships a list of ~250 legitimate
-legitimate ERC-20 tokens with their contract addresses. If a transaction or
+ERC-20 tokens with their contract addresses. If a transaction claims to involve
-balance claims to involve a known symbol (like "ETH" or "USDT") but comes from
+a known symbol (like "ETH" or "USDT") but comes from an unrecognized contract,
-an unrecognized contract, it is identified as a spoof and hidden.
+it is identified as a spoof and hidden.
 
 **Low-holder token filtering.** Tokens with fewer than 1,000 holders are hidden
-from transaction history and the send token list, and are left out of your
+from transaction history and the send token list. Legitimate tokens have
-balances unless they are on the bundled known-token list or you added them
+substantial holder counts; scam tokens deployed for address poisoning typically
-yourself. Legitimate tokens have substantial holder counts; scam tokens deployed
+have zero.
-for address poisoning typically have zero.
 
 **Fraud contract blocklist.** When AutistMask detects a fraudulent transfer, it
 adds the contract address to a local blocklist. Future transactions from that
@@ -340,47 +266,31 @@ ETH by default) are hidden. Scammers send dust from look-alike addresses to
 plant them in your transaction history. The threshold is configurable in
 Settings.
 
-**Scam address list.** A list of known fraud, drainer, and phishing addresses is
+All of these filters can be individually disabled in Settings if you prefer to
-shipped with the extension. Sending to one of them raises a warning on the
-confirmation screen. It contains only addresses involved in fraud -- it is not a
-sanctions list.
-
-**Phishing domain warnings.** Sites asking to connect or to have something
-approved are checked against the phishing domain blocklist described under
-External Services, and flagged with a red banner if they match.
-
-The first four filters can be individually disabled in Settings if you prefer to
 see everything unfiltered.
 
 ## Settings
 
 Click the gear icon on the home screen to access settings:
 
-- **Wallets**: Your wallets, and "+ Add wallet".
+- **Wallets**: Add a new wallet.
-- **Tracked Tokens**: The ERC-20 tokens tracked across all addresses, and "+ Add
+- **Display**: Toggle whether tracked tokens with zero balance are shown.
-  token".
-- **Display**: Toggle whether tracked tokens with zero balance are shown, and
-  choose the theme (System, Light, or Dark).
-- **Network**: Switch between Ethereum Mainnet and Sepolia Testnet. Switching
-  resets the RPC and Blockscout endpoints to that network's defaults.
 - **Ethereum RPC**: Change the Ethereum node endpoint. Default is a public RPC.
   You can use your own node for maximum privacy.
 - **Blockscout API**: Change the Blockscout instance used for token balances and
   transaction history. You can use a self-hosted instance.
-- **Token Spam Protection**: Toggle individual scam filters, set the dust
+- **Token Spam Protection**: Toggle individual scam filters and set the dust
-  transaction threshold, and switch timestamps to UTC.
+  transaction threshold.
 - **Allowed Sites / Denied Sites**: View and manage web3 site permissions.
-- **About**: License, author, version, release date, and a link to the commit
-  this build came from.
 
 ## Frequently Asked Questions
 
-**Can I use AutistMask alongside another wallet?**
+**Is AutistMask compatible with MetaMask?**
 
-Yes. AutistMask uses the standard `m/44'/60'/0'/0` derivation path, so importing
+Yes. AutistMask uses the same derivation path (`m/44'/60'/0'/0`) as MetaMask. If
-the same recovery phrase gives you the same addresses as any other wallet using
+you import the same recovery phrase, you will get the same addresses. You can
-that path. Two wallet extensions can be installed side by side, though only one
+use both wallets side by side, though only one can be the active
-can be the active `window.ethereum` provider at a time.
+`window.ethereum` provider at a time.
 
 **Can I use AutistMask with a hardware wallet?**
 
@@ -388,9 +298,8 @@ Not yet. Hardware wallet support may be added in the future.
 
 **Does AutistMask support networks other than Ethereum mainnet?**
 
-Ethereum mainnet and the Sepolia testnet, selectable in Settings. No other
+Not currently. AutistMask is Ethereum mainnet only. Multi-chain support may be
-networks are supported today. On Sepolia, USD values are not shown, because
+added in the future.
-testnet tokens have no market value.
 
 **Where is my data stored?**
 
@@ -403,7 +312,7 @@ to any server operated by AutistMask.
 
 Your data is deleted. Make sure you have your recovery phrase backed up before
 uninstalling. With your recovery phrase, you can restore your wallet in
-AutistMask or any other wallet that uses the standard derivation path.
+AutistMask or any other compatible wallet (MetaMask, etc.) at any time.
 
 **What happens if a transaction times out?**