fix: correct verify-build diagnostics and close its vacuous passes (closes #180)

The both-markers diagnostic claimed the debug branch was still live. It is
not: with the __BUILD_DEBUG__ define removed, the emitted bundle carries
`typeof __BUILD_DEBUG__<"u"?__BUILD_DEBUG__:!1`, and in extension context the
identifier is undeclared, so DEBUG evaluates to false at runtime. The message
now states what the check does prove -- DEBUG was not resolved at build time,
so the release/debug distinction is no longer enforced and which way the
unresolved fallback evaluates is an accident a refactor can flip -- and it
remains a hard failure. The other seven failure messages were reviewed and
none needed rewording.

has_marker no longer swallows grep's exit 2 with 2>/dev/null. Match and
no-match are answers about the emitted output; an unreadable file is not, and
is now reported as a permissions or I/O fault instead of as "the emitted
output changed shape". Both paths still fail hard. The manifest-membership
grep gets the same treatment in is_listed: an unreadable manifest is no longer
answered as "this file is not listed".

The unlisted-bundle scan no longer filters by extension, so the endsWith(".js")
test in build.js is the only place that assumption lives. A bundle emitted
under another extension previously escaped the manifest and the cross-check at
once; it now fails as unlisted. Both sites carry a comment naming the other.

That makes the scan the sole guard on build.js's filter, so its walk has to be
exhaustive rather than assumed to be. find's exit status was discarded twice
over -- the pipeline reported sort's status, and set -e does not fire on an
assignment from a successful pipeline -- so a subtree find could not descend
printed to stderr and was then silently omitted, and an unlisted marker-carrying
bundle inside a chmod 000 directory passed green. The status is now captured
and a non-zero find is a hard failure naming the unwalked tree; the sort moved
off the status-bearing pipeline. Symlinks are walked as well: a marker-carrying
bundle reachable under an unlisted path is a stale manifest whether the path is
a link or a file, and a link that cannot be read through fails closed via the
exit-2 path.

Also: the manifest must be readable and a listed bundle must be non-empty,
so a vacuous input fails loudly rather than reaching a marker check that
cannot prove anything.

README.md

@@ -346,17 +346,32 @@ The core hierarchy is **Wallets → Addresses**:
       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.
+- An **address** holds ETH and ERC-20 tokens.
 - The user can have multiple wallets, each with multiple addresses (HD) or a
   single address (key).
 
+Which tokens an address shows is decided by `fetchTokenBalances()` in
+`src/shared/balances.js`, from the Blockscout `token-balances` response, so
+tokens do appear without the user adding them. An ERC-20 is shown when its
+balance is nonzero and it is in the bundled top-250 token list, is tracked by
+the user, or has 1,000 or more holders; a token claiming a symbol from the
+bundled list from any other contract address is always dropped. That filter is
+unconditional — the "Hide tokens with fewer than 1,000 holders" setting governs
+the transaction history and the send-screen token selector, not this list.
+Tracked tokens with a zero balance are listed as well while "Show tracked tokens
+with zero balance" is on.
+
 #### Navigation
 
 The main view shows all addresses grouped by wallet, with ETH balances inline.
 The user taps an address to see its detail view (full address, balance, tokens,
-send/receive). Navigation is flat — every view has a "Back" or "Cancel" button
-that returns to the previous context. No deep nesting, no tabs, no hamburger
-menus.
+send/receive). Navigation is a stack: each forward action pushes the current
+screen, and every view has a "Back" or "Cancel" button that pops back to it (see
+the Screen Map below). There is no hamburger menu and no persistent tab bar; the
+Settings gear in the title bar is the only global control. Two screens carry an
+in-screen control beyond that: AddWallet uses three tabs to select the import
+mode, and AddressDetail keeps its one rarely-used action ("Export Private Key")
+behind a "···" menu.
 
 ### Screen Map
 
@@ -393,7 +408,7 @@ screen, including ExportPrivKey, falls back to Home.
 - **When**: At least one wallet exists. This is the root screen.
 - **Elements**:
     - Active address ETH balance (large) + USD value in parentheses
-    - "Total:" USD value across ETH and all tracked tokens of the active address
+    - "Total:" USD value across ETH and every token shown for the active address
     - Active address (color dot, full address, etherscan link, tap to copy)
     - Send / Receive quick-action buttons, both acting on the active address
     - ETH/USD price display
@@ -401,7 +416,7 @@ screen, including ExportPrivKey, falls back to Home.
       button for HD and xprv wallets, then one block per address with "Address
       N" (bold when active), the ENS name if resolved, the full address, an
       `[info]` button, the address USD total, and a balance line for ETH and for
-      each tracked token
+      each token shown for that address
     - "Recent Transactions": up to 25 transactions merged across every address
       of every wallet, deduplicated by hash and filtered
     - "Add additional wallet..." link at bottom
@@ -454,8 +469,8 @@ screen, including ExportPrivKey, falls back to Home.
     - ENS name (if resolved, bold above the address)
     - 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**
+    - Balance list: ETH + the ERC-20 tokens shown for this address (4 decimal
+      places, USD inline). Each balance row is clickable → **AddressToken**
     - Send / Receive / + Token buttons and a "···" menu button
     - "···" dropdown containing a single "Export Private Key" entry
     - Transaction list (with ENS resolution for counterparties)
@@ -861,7 +876,7 @@ communicates with three external services to function as a wallet:
 What the extension does NOT do:
 
 - No analytics or telemetry services
-- No token list APIs (user adds tokens manually by contract address)
+- No token list APIs (the top-250 token list is bundled at build time)
 - No Infura/Alchemy dependency (any JSON-RPC endpoint works)
 - No backend servers operated by the developer
 
@@ -984,7 +999,8 @@ hardcoded test phrase.
 - Add multiple addresses within an HD wallet
 - Manage multiple wallets simultaneously
 - View ETH balance per address
-- View ERC-20 token balances (user adds token by contract address)
+- View ERC-20 token balances (bundled top-250 tokens, tokens with 1,000 or more
+  holders, and tokens the user adds by contract address)
 - Send ETH to an address
 - Send ERC-20 tokens to an address
 - Receive ETH/tokens (display address, copy to clipboard, QR code)
@@ -1130,7 +1146,8 @@ Currently supported:
 - Built in token swaps (use a DEX in the browser)
 - Analytics, telemetry, or tracking of any kind
 - Advertisements or promotions
-- Obscure token list auto-discovery (user adds tokens manually)
+- Obscure token list auto-discovery — nothing outside the bundled list, the
+  1,000-holder floor, and the tokens the user added by contract address
     - We detect common/popular ERC20s in the basic case
 - Fiat on/off ramps
 - Extensive transaction decoding/parsing
@@ -1188,13 +1205,17 @@ covered by the GPL-3.0 license above. These files, their copyright holders, and
 their licenses are:
 
 | File                                                       | Source                                                                                                    | Copyright                         | License                                                        |
-| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | -------------------------------------------------------------- |
-| `src/shared/phishingBlocklist.json`                        | [eth-phishing-detect](https://github.com/AugurProject/eth-phishing-detect) community-maintained phishing domain blocklist | Copyright (c) 2018 kumavis        | [DBAD (Don't Be a Dick)](https://github.com/philsturgeon/dbad) |
+| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------- | -------------------------------------------------------------- |
+| `src/shared/phishingBlocklist.json`                        | `eth-phishing-detect` community-maintained phishing domain blocklist, vendored from its `src/config.json` | Copyright (c) 2018 kumavis        | [DBAD (Don't Be a Dick)](https://github.com/philsturgeon/dbad) |
 | `src/shared/scamlist.js` (address data from MyEtherWallet) | [ethereum-lists](https://github.com/MyEtherWallet/ethereum-lists) `addresses-darklist.json`               | Copyright (c) 2020 MyEtherWallet  | MIT                                                            |
 | `src/shared/scamlist.js` (address data from EtherScamDB)   | [EtherScamDB](https://github.com/MrLuit/EtherScamDB) `scams.yaml`                                         | Copyright (c) 2018 Luit Hollander | MIT                                                            |
 
 The full license texts for these third-party files are included in the
-[LICENSE](LICENSE) file.
+[LICENSE](LICENSE) file. The `eth-phishing-detect` row carries no repository
+link because the upstream is hosted under a competitor's organization name,
+which project policy keeps out of code and documentation; the vendored copy and
+the runtime refresh both come from that upstream, whose URL is the
+`BLOCKLIST_URL` constant in `src/shared/phishingDomains.js`.
 
 ## Author
 

TODO.md

@@ -44,6 +44,15 @@ undefined identifiers, which is how
 
 # Completed Steps
 
+- 2026-08-11: `script/verify-build` diagnostics corrected: the both-markers
+  message now states what is and is not proven, an unreadable bundle is
+  diagnosed as an I/O fault rather than as changed output, the `*.js` assumption
+  lives only in `build.js`, and the unlisted-bundle scan hard-fails when it
+  cannot enumerate `dist/`
+  ([#180](https://git.eeqj.de/sneak/AutistMask/issues/180)).
+- 2026-08-11: Three `README.md` claims corrected against the code — blocklist
+  attribution, token-display rule, navigation model
+  ([#213](https://git.eeqj.de/sneak/AutistMask/issues/213)).
 - 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)).

build.js

@@ -29,6 +29,12 @@ function repoRelative(p) {
 // reports every input that contributed to an output in the metafile, which is
 // the authoritative answer to "is constants.js in this bundle" — unlike
 // searching the minified text, it does not depend on what survived minification.
+//
+// The ".js" filter below is the only place that assumption lives:
+// script/verify-build searches every file and symlink under dist/ for a
+// marker, without filtering by extension, and hard-fails if it cannot walk the
+// whole tree, so a bundle emitted under some other extension fails there as
+// unlisted rather than escaping both checks at once.
 function outputsContainingAuditedModule(metafile) {
     return Object.entries(metafile.outputs)
         .filter(([outFile, info]) => {

script/verify-build

@@ -34,16 +34,51 @@ fail() {
     exit 1
 }
 
+# Is the literal $1 present in the file $2? Match (grep exit 0) and no-match
+# (exit 1) are answers about the emitted output. Anything else (exit 2: the
+# file could not be read) is not an answer at all, and must not be reported as
+# "no marker" — that would blame the bundle for a permissions or I/O fault.
 has_marker() {
-    grep -q -F "$1" "$2" 2>/dev/null
+    _hm_status=0
+    grep -q -F -e "$1" -- "$2" || _hm_status=$?
+    case "$_hm_status" in
+    0) return 0 ;;
+    1) return 1 ;;
+    *)
+        fail "grep exited $_hm_status reading $2, so the file could not be
+    searched and its DEBUG state was not checked at all. That is a permissions
+    or I/O fault on the artifact, not a change in the emitted output. Refusing
+    to report success."
+        ;;
+    esac
+}
+
+# Does the manifest list the path $1, as a whole line? Same discipline as
+# has_marker: exit 0 and 1 are answers about the manifest, exit 2 means the
+# manifest could not be read and is not an answer at all. Without this, an
+# unreadable manifest reads as "this file is not listed" and every emitted
+# bundle gets reported as an unlisted one.
+is_listed() {
+    _il_status=0
+    grep -q -x -F -e "$1" -- "$MANIFEST" || _il_status=$?
+    case "$_il_status" in
+    0) return 0 ;;
+    1) return 1 ;;
+    *)
+        fail "grep exited $_il_status reading $MANIFEST, so it could not be
+    searched and nothing was established about which bundles it lists. That is
+    a permissions or I/O fault on the manifest, not a stale manifest. Refusing
+    to report success."
+        ;;
+    esac
 }
 
 # Read one bundle's DEBUG state into MARKER. Exactly one marker must be
 # present. Both means the ternary in constants.js was never folded, which is
 # what happens when the __BUILD_DEBUG__ define goes missing from build.js:
-# DEBUG stops being known at build time and the debug branch is live again.
-# Neither means we are reading output we do not understand. Both are hard
-# failures; neither is ever treated as absence of a problem.
+# DEBUG stops being known at build time. Neither means we are reading output
+# we do not understand. Both are hard failures; neither is ever treated as
+# absence of a problem.
 read_marker() {
     _file="$1"
     _on=no
@@ -52,9 +87,14 @@ read_marker() {
     if has_marker "$MARKER_OFF" "$_file"; then _off=yes; fi
 
     if [ "$_on" = yes ] && [ "$_off" = yes ]; then
-        fail "$_file carries both debug markers, so the build-time DEBUG value
-    was never resolved and the debug branch is still live. Check that build.js
-    still defines __BUILD_DEBUG__."
+        fail "$_file carries both debug markers, so DEBUG was not resolved at
+    build time: the ternary in src/shared/constants.js survived into the
+    emitted output. This does not mean the debug branch is live in this
+    artifact: an unresolved __BUILD_DEBUG__ is undeclared in extension
+    context, so DEBUG evaluates to false at runtime. It does mean the
+    release/debug distinction is no longer enforced at build time, and which
+    way that fallback happens to evaluate is then an accident a refactor can
+    flip. Check that build.js still defines __BUILD_DEBUG__."
     fi
     if [ "$_on" = no ] && [ "$_off" = no ]; then
         fail "$_file carries no debug marker, so its DEBUG state cannot be
@@ -70,13 +110,43 @@ read_marker() {
 }
 
 # The manifest says which bundles must carry a marker. This says no other
-# emitted bundle may carry one, which catches a manifest that has gone stale
+# emitted file may carry one, which catches a manifest that has gone stale
 # or short rather than trusting whatever it happens to list.
+#
+# Deliberately unfiltered by extension. build.js selects manifest entries with
+# an endsWith(".js") test; repeating that literal here would mean a bundle
+# emitted under some other extension escaped the manifest AND this check at
+# once, which is the correlated blind spot the two-source design exists to
+# avoid. Every file under dist/ is searched, so build.js's filter is the only
+# place the assumption lives and this check is what catches it being wrong.
+#
+# That claim only holds if the walk is exhaustive, so two things are enforced
+# here rather than assumed:
+#
+#   - find's exit status is checked. A subtree it cannot descend is reported on
+#     stderr and then simply missing from the listing, so an unchecked status
+#     turns "could not look" into "nothing was there" — the same conflation
+#     has_marker exists to prevent. The status cannot be read off a pipeline
+#     ending in sort, so the sort is a separate step.
+#   - symlinks are walked too (-type l), not skipped. A marker-carrying bundle
+#     reachable under an unlisted path in dist/ is a stale manifest whether the
+#     path is a link or a file, and grep reads through the link. A link that
+#     cannot be read through — dangling, or pointing at a directory — fails
+#     hard via has_marker's exit-2 path, which is the fail-closed answer: the
+#     build emits neither, so their DEBUG state is unproven, not fine.
 check_unlisted_bundles() {
-    _listing="$(find dist -type f -name '*.js' | sort)"
+    _find_status=0
+    _listing="$(find dist \( -type f -o -type l \) -print)" || _find_status=$?
+    [ "$_find_status" -eq 0 ] ||
+        fail "find exited $_find_status enumerating dist/, so part of the tree
+    was never walked and nothing was established about the files in it. Any
+    unlisted bundle there went unchecked. That is a permissions or I/O fault on
+    the artifact, not a stale manifest. Refusing to report success."
+    _listing="$(printf '%s\n' "$_listing" | sort)"
+
     while read -r _file; do
         [ -n "$_file" ] || continue
-        if grep -q -x -F "$_file" "$MANIFEST"; then
+        if is_listed "$_file"; then
             continue
         fi
         if has_marker "$MARKER_ON" "$_file" ||
@@ -113,12 +183,18 @@ main() {
         fail "$MANIFEST is empty, so no emitted bundle was found to contain
     src/shared/constants.js. That is never correct, so it is a failure and not
     a pass."
+    [ -r "$MANIFEST" ] ||
+        fail "$MANIFEST is not readable, so nothing was inspected. That is a
+    permissions or I/O fault, not a pass."
 
     count=0
     while read -r file; do
         [ -n "$file" ] || continue
         [ -f "$file" ] ||
             fail "$MANIFEST lists $file, which does not exist."
+        [ -s "$file" ] ||
+            fail "$MANIFEST lists $file, which is empty. An empty bundle
+    carries no marker and proves nothing, so this is a failure and not a pass."
         read_marker "$file"
         [ "$MARKER" = "$expected" ] ||
             fail "$file is $MARKER but this build expects $expected."