Rewrite README.md and the other prose documents sentence by sentence, on Fable #672

New Issue

2026-10-22T20:16:29+02:00

clawbot commented

2026-10-22 20:16:29 +02:00

This repo's README.md is 33423 words on next (22 October).

sneak, 22 October (chat), after smallwebwaf's README turned out to fail sentence by sentence: "just file issues on the repos about it, and specify that it has to be fable, and make the issues detailed - include your rules. we're not doing this work today (except on smallwebwaf)". What went wrong there, and the rules below, are on sneak/project-management#39 (comment).

Not today. This waits until the fleet restarts (25 October at the earliest) and the repo's manager has room. It is not urgent, but it comes before this repo's next release-candidate tag.

Who. This must be done by Fable: a genius-bar session (--agent genius-bar --model fable --effort xhigh, on a worker account) that wrote none of the documents. Opus workers do not do this unit.

What.

Read README.md and every other prose document in the repo, such as SPEC.md, DESIGN.md and prose under docs/, sentence by sentence, as a newcomer would. Check each sentence against the rules below.
Rewrite each document that fails from scratch. The old text is only the reference for what a reader needs covered; do not edit it in place. Where the old text is unclear or disagrees with the code on next, the code decides what is true and the spec explains the intent. List any disagreement in the PR body; do not settle it silently.
A document that passes is left alone; say so on this issue.
Leave out anything the code does not do, and describe nothing that is not built.

The rules, sentence by sentence. A sentence fails when a newcomer cannot parse it on first reading. It always fails when it:

runs past about 30 words, or chains a list of things with commas where a bulleted list belongs;
stacks clauses so the verb or the subject arrives late, for example "refuses a client a blocklist you name lists";
paraphrases where a plain common name exists, for example "the bans that broken rate limits lead to" instead of rate-limit bans;
narrates the project's own history or plan (milestones, stages, build order, issue links) in a document meant for users;
puts an exception or rare edge case before the main rule, or anywhere in the opening.

Also:

one idea per sentence; subject and verb early;
a false statement fails too, but an inaccurate sentence is fixed by writing a correct short sentence, never by adding qualifiers;
the README leads with what the program is, what it is for and how to use it; every setting goes in a reference section after that; development and testing come last;
plain words, no coined terms, no jargon a newcomer would not know, and any technical word defined on first use;
every identifier, flag, environment variable, path, command and file name in backticks; no markdown tables; no superlatives or praise;
read every sentence once more before committing, and rewrite any you would have to read twice.

Definition of done.

Every prose document in the repo passes the rules above, read sentence by sentence.
Every statement matches the code on next.
One PR into next for each rewritten document. The last of them ends its title with (closes #N), N being this issue.
Each PR passes an independent pr-reviewer applying agents/pr-reviewer.md step 4 to every sentence, before it is squash-merged.
make fmt applied, and script/cibuild green on a fresh clone.

Model: opus-5-5

This repo's `README.md` is 33423 words on `next` (22 October). sneak, 22 October (chat), after smallwebwaf's README turned out to fail sentence by sentence: "just file issues on the repos about it, and specify that it has to be fable, and make the issues detailed - include your rules. we're not doing this work today (except on smallwebwaf)". What went wrong there, and the rules below, are on https://git.eeqj.de/sneak/project-management/issues/39#issuecomment-154280. **Not today.** This waits until the fleet restarts (25 October at the earliest) and the repo's manager has room. It is not urgent, but it comes before this repo's next release-candidate tag. **Who.** This must be done by Fable: a genius-bar session (`--agent genius-bar --model fable --effort xhigh`, on a worker account) that wrote none of the documents. Opus workers do not do this unit. **What.** 1. Read `README.md` and every other prose document in the repo, such as `SPEC.md`, `DESIGN.md` and prose under `docs/`, sentence by sentence, as a newcomer would. Check each sentence against the rules below. 2. Rewrite each document that fails from scratch. The old text is only the reference for what a reader needs covered; do not edit it in place. Where the old text is unclear or disagrees with the code on `next`, the code decides what is true and the spec explains the intent. List any disagreement in the PR body; do not settle it silently. 3. A document that passes is left alone; say so on this issue. 4. Leave out anything the code does not do, and describe nothing that is not built. **The rules, sentence by sentence.** A sentence fails when a newcomer cannot parse it on first reading. It always fails when it: - runs past about 30 words, or chains a list of things with commas where a bulleted list belongs; - stacks clauses so the verb or the subject arrives late, for example "refuses a client a blocklist you name lists"; - paraphrases where a plain common name exists, for example "the bans that broken rate limits lead to" instead of rate-limit bans; - narrates the project's own history or plan (milestones, stages, build order, issue links) in a document meant for users; - puts an exception or rare edge case before the main rule, or anywhere in the opening. Also: - one idea per sentence; subject and verb early; - a false statement fails too, but an inaccurate sentence is fixed by writing a correct short sentence, never by adding qualifiers; - the README leads with what the program is, what it is for and how to use it; every setting goes in a reference section after that; development and testing come last; - plain words, no coined terms, no jargon a newcomer would not know, and any technical word defined on first use; - every identifier, flag, environment variable, path, command and file name in backticks; no markdown tables; no superlatives or praise; - read every sentence once more before committing, and rewrite any you would have to read twice. **Definition of done.** - Every prose document in the repo passes the rules above, read sentence by sentence. - Every statement matches the code on `next`. - One PR into `next` for each rewritten document. The last of them ends its title with (closes #N), N being this issue. - Each PR passes an independent pr-reviewer applying `agents/pr-reviewer.md` step 4 to every sentence, before it is squash-merged. - `make fmt` applied, and `script/cibuild` green on a fresh clone. Model: opus-5-5

clawbot commented

2026-11-02 00:06:49 +01:00

Plan: a Fable session on claude2 that wrote none of the documents reads every prose document on next sentence by sentence against the rules in this issue, starting with README.md. It says on this issue which documents pass. Each one that fails is rewritten from scratch as its own PR into next, and each PR gets an independent review applying agents/pr-reviewer.md step 4 before it is squash-merged. RULES.md is sneak's: any change it needs is proposed on this issue, not made. Files copied from the shared prompts repo (REPO_POLICIES.md, the style guides) are not this repo's prose and are left alone. The paused PRs that touch README.md are not waited for; they rebase onto the new text when they resume.

Model: opus-5-5

Plan: a Fable session on claude2 that wrote none of the documents reads every prose document on `next` sentence by sentence against the rules in this issue, starting with `README.md`. It says on this issue which documents pass. Each one that fails is rewritten from scratch as its own PR into `next`, and each PR gets an independent review applying `agents/pr-reviewer.md` step 4 before it is squash-merged. `RULES.md` is sneak's: any change it needs is proposed on this issue, not made. Files copied from the shared prompts repo (`REPO_POLICIES.md`, the style guides) are not this repo's prose and are left alone. The paused PRs that touch `README.md` are not waited for; they rebase onto the new text when they resume. Model: opus-5-5

clawbot commented

2026-11-02 00:18:00 +01:00

RULES.md read against the code on next. Sentence by sentence the file passes. Eleven items no longer match the code. Proposed changes, for the owner to make:

External Communication, first item ("exactly three external services: configured RPC endpoint, CoinDesk price API, and Blockscout block-explorer API"). By default the code contacts the RPC endpoint and nothing else. USD prices come from Chainlink price feed contracts, read through that endpoint (src/shared/prices.js). Blockscout is contacted only while "Use Blockscout" is on. Etherscan is contacted only while "Check recipients on Etherscan" is on. There is no CoinDesk request. Proposed: four lines, one per fact above.
Secrets & Storage, "Password only required for signing operations". The password is also required to show a recovery phrase, to export a private key, and to delete a wallet on the DeleteWallet screen. Proposed: "Password required to sign, to show a recovery phrase, to export a private key, and to delete a wallet; the lost-password route and removing an address need none."
Build & Workflow, "Feature branches for all changes, merge to main when done". Branches are cut from next and merged to next; main receives one PR per milestone (TODO.md, Workflow). Proposed: "Feature branches from next, merged to next; next merges to main once per milestone."
DEBUG Mode, "DEBUG mode only enables: red banner + hardcoded test mnemonic". The build-time flag also raises the log level (isDebug() in src/shared/log.js) and adds the view id to the banner. Proposed: "DEBUG mode only enables: red banner with the view id, verbose logging, and the hardcoded test recovery phrase."
Language & Labeling, last item. script/check-censored allows the name in four places: the two provider flags in src/content/inpage.js, one token's on-chain name in src/shared/tokenList.js and script/lib/token-enrichment.json, and the upstream source named in script/vendor-blocklist. Proposed: list those four and point at script/check-censored.
Address Display, "Tokens with < 1,000 holders hidden from tx history and send selector". A token whose holder count is unknown is not hidden; only a reported count below 1,000 is (src/shared/holders.js). Proposed: "Tokens with a reported holder count below 1,000 hidden from tx history and send selector."
Cryptography, "All crypto goes through ethers or libsodium-wrappers-sumo". generateMnemonic() in src/shared/wallet.js draws its random bytes from the browser's crypto.getRandomValues(), and build.js and script/lib/package.js hash files with Node's crypto. Proposed: "Hashing, key derivation, signing and encryption go through ethers or libsodium-wrappers-sumo; a new recovery phrase draws its random bytes from crypto.getRandomValues()."
Cryptography, "No exceptions without an explicit code comment citing the Crypto Policy". The two uses outside the libraries named above carry no such comment. Proposed: add the comment at those places, or drop the item.
Transaction Decoding, "Decoders are self-contained modules in src/shared/". The ERC-20 decoder, decodeCalldata(), is in src/popup/views/approval.js; only the Uniswap decoder is in src/shared/uniswap.js. Proposed: "The Uniswap decoder is a self-contained module in src/shared/; ERC-20 calls are decoded in src/popup/views/approval.js."
Address Display, "Timestamps: ISO datetime + relative age, everywhere they appear". TransactionDetail shows both; a history row shows the age, with the datetime as its tooltip (src/popup/views/helpers.js). Proposed: "Timestamps: ISO datetime and relative age on TransactionDetail; relative age with the datetime as a tooltip in history rows."
Address Display, "Same data formatted identically across all screens". The balance lists and Home's ETH balance round amounts to four decimals; history rows and the authorization screens cut them (src/shared/amountDisplay.js). Proposed: "Each kind of value is written by one helper; amounts are rounded in balance lists and cut elsewhere."

Model: fable-5-1

`RULES.md` read against the code on `next`. Sentence by sentence the file passes. Eleven items no longer match the code. Proposed changes, for the owner to make: - External Communication, first item ("exactly three external services: configured RPC endpoint, CoinDesk price API, and Blockscout block-explorer API"). By default the code contacts the RPC endpoint and nothing else. USD prices come from Chainlink price feed contracts, read through that endpoint (`src/shared/prices.js`). Blockscout is contacted only while "Use Blockscout" is on. Etherscan is contacted only while "Check recipients on Etherscan" is on. There is no CoinDesk request. Proposed: four lines, one per fact above. - Secrets & Storage, "Password only required for signing operations". The password is also required to show a recovery phrase, to export a private key, and to delete a wallet on the DeleteWallet screen. Proposed: "Password required to sign, to show a recovery phrase, to export a private key, and to delete a wallet; the lost-password route and removing an address need none." - Build & Workflow, "Feature branches for all changes, merge to main when done". Branches are cut from `next` and merged to `next`; `main` receives one PR per milestone (`TODO.md`, Workflow). Proposed: "Feature branches from `next`, merged to `next`; `next` merges to `main` once per milestone." - DEBUG Mode, "DEBUG mode only enables: red banner + hardcoded test mnemonic". The build-time flag also raises the log level (`isDebug()` in `src/shared/log.js`) and adds the view id to the banner. Proposed: "DEBUG mode only enables: red banner with the view id, verbose logging, and the hardcoded test recovery phrase." - Language & Labeling, last item. `script/check-censored` allows the name in four places: the two provider flags in `src/content/inpage.js`, one token's on-chain name in `src/shared/tokenList.js` and `script/lib/token-enrichment.json`, and the upstream source named in `script/vendor-blocklist`. Proposed: list those four and point at `script/check-censored`. - Address Display, "Tokens with < 1,000 holders hidden from tx history and send selector". A token whose holder count is unknown is not hidden; only a reported count below 1,000 is (`src/shared/holders.js`). Proposed: "Tokens with a reported holder count below 1,000 hidden from tx history and send selector." - Cryptography, "All crypto goes through `ethers` or `libsodium-wrappers-sumo`". `generateMnemonic()` in `src/shared/wallet.js` draws its random bytes from the browser's `crypto.getRandomValues()`, and `build.js` and `script/lib/package.js` hash files with Node's `crypto`. Proposed: "Hashing, key derivation, signing and encryption go through `ethers` or `libsodium-wrappers-sumo`; a new recovery phrase draws its random bytes from `crypto.getRandomValues()`." - Cryptography, "No exceptions without an explicit code comment citing the Crypto Policy". The two uses outside the libraries named above carry no such comment. Proposed: add the comment at those places, or drop the item. - Transaction Decoding, "Decoders are self-contained modules in `src/shared/`". The ERC-20 decoder, `decodeCalldata()`, is in `src/popup/views/approval.js`; only the Uniswap decoder is in `src/shared/uniswap.js`. Proposed: "The Uniswap decoder is a self-contained module in `src/shared/`; ERC-20 calls are decoded in `src/popup/views/approval.js`." - Address Display, "Timestamps: ISO datetime + relative age, everywhere they appear". TransactionDetail shows both; a history row shows the age, with the datetime as its tooltip (`src/popup/views/helpers.js`). Proposed: "Timestamps: ISO datetime and relative age on TransactionDetail; relative age with the datetime as a tooltip in history rows." - Address Display, "Same data formatted identically across all screens". The balance lists and Home's ETH balance round amounts to four decimals; history rows and the authorization screens cut them (`src/shared/amountDisplay.js`). Proposed: "Each kind of value is written by one helper; amounts are rounded in balance lists and cut elsewhere." Model: fable-5-1

clawbot commented

2026-11-02 00:18:01 +01:00

Each prose document on next, read sentence by sentence against the rules in this issue:

README.md: fails. Sentences well past 30 words throughout; lists chained with commas; the opening narrates grievances about another wallet; project history and issue links in sections meant for users; markdown tables; development and test material comes before the design and before how to use it.
docs/README.md: fails. Two false statements: "The only exception is compact transaction list rows" (no screen truncates an address; history rows show the full counterparty address) and "a token claiming the symbol "ETH" is not filtered" from the balance list (it is, in src/shared/balances.js). Also sentences past 30 words and comma-chained lists in Why AutistMask Exists and Scam Protection, and a plan sentence in the FAQ.
docs/RELEASE.md: fails. Sentences past 30 words; "milestone PR" narration; step 6 describes distribution routes that are not built and links the open issue.
RULES.md: sneak's file; proposed changes are in the comment above.
REPO_POLICIES.md: copied from the shared prompts repo; left alone.
TODO.md: left alone, as the plan says.

Rewrites follow as one PR each: README.md first, then docs/README.md, then docs/RELEASE.md.

Model: fable-5-1

Each prose document on `next`, read sentence by sentence against the rules in this issue: - `README.md`: fails. Sentences well past 30 words throughout; lists chained with commas; the opening narrates grievances about another wallet; project history and issue links in sections meant for users; markdown tables; development and test material comes before the design and before how to use it. - `docs/README.md`: fails. Two false statements: "The only exception is compact transaction list rows" (no screen truncates an address; history rows show the full counterparty address) and "a token claiming the symbol "ETH" is not filtered" from the balance list (it is, in `src/shared/balances.js`). Also sentences past 30 words and comma-chained lists in Why AutistMask Exists and Scam Protection, and a plan sentence in the FAQ. - `docs/RELEASE.md`: fails. Sentences past 30 words; "milestone PR" narration; step 6 describes distribution routes that are not built and links the open issue. - `RULES.md`: sneak's file; proposed changes are in the comment above. - `REPO_POLICIES.md`: copied from the shared prompts repo; left alone. - `TODO.md`: left alone, as the plan says. Rewrites follow as one PR each: `README.md` first, then `docs/README.md`, then `docs/RELEASE.md`. Model: fable-5-1

clawbot referenced this issue

2026-11-02 00:44:10 +01:00

docs: rewrite README.md sentence by sentence against the prose rules #713

clawbot referenced this issue from a commit

2026-11-02 00:44:10 +01:00

docs: rewrite README.md sentence by sentence against the prose rules

clawbot referenced this issue from a commit

2026-11-02 01:45:02 +01:00

docs: rewrite README.md sentence by sentence against the prose rules

clawbot referenced this issue from a commit

2026-11-02 02:19:26 +01:00

docs: rework the README after review