This repo's README.md is 12391 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 12391 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
Scope.README.md only. REPO_POLICIES.md is copied from sneak/prompts and changes only there. TODO.md is the work log the repository workflow requires, not a document for users, so it stays as it is.
Who. One genius-bar session on Fable, on a worker account, that wrote none of the README. It starts once #223 is merged, so the README describes get, get-thumb, files and the thumbnail helper as they now are.
How. The session reads the README sentence by sentence against the rules in this issue, and checks every statement against the code on next. It then writes the README again from scratch, using the old text only as a list of what a reader needs. The sections REPO_POLICIES.md requires stay:
a first line naming the project, its purpose, its category, its licence and its author;
Getting Started, with a copy-pasteable block;
Entrypoints, opening with the Scripts to Rule Them All link;
Rationale, Design, TODO, License and Author.
Every place where the old text and the code disagree is listed in the PR body.
Gates. One PR into next, its title ending with (closes#219). An independent pr-reviewer applies step 4 of agents/pr-reviewer.md to every sentence before it is squash-merged. Before the release-candidate tag, a second fresh Fable session that wrote none of it reads the merged README whole and passes it against the same rules.
Model: opus-5-5
Plan.
**Scope.** `README.md` only. `REPO_POLICIES.md` is copied from sneak/prompts and changes only there. `TODO.md` is the work log the repository workflow requires, not a document for users, so it stays as it is.
**Who.** One genius-bar session on Fable, on a worker account, that wrote none of the README. It starts once https://git.eeqj.de/sneak/quak/issues/223 is merged, so the README describes `get`, `get-thumb`, `files` and the thumbnail helper as they now are.
**How.** The session reads the README sentence by sentence against the rules in this issue, and checks every statement against the code on `next`. It then writes the README again from scratch, using the old text only as a list of what a reader needs. The sections `REPO_POLICIES.md` requires stay:
- a first line naming the project, its purpose, its category, its licence and its author;
- Getting Started, with a copy-pasteable block;
- Entrypoints, opening with the Scripts to Rule Them All link;
- Rationale, Design, TODO, License and Author.
Every place where the old text and the code disagree is listed in the PR body.
**Gates.** One PR into `next`, its title ending with (closes #219). An independent pr-reviewer applies step 4 of `agents/pr-reviewer.md` to every sentence before it is squash-merged. Before the release-candidate tag, a second fresh Fable session that wrote none of it reads the merged README whole and passes it against the same rules.
Model: opus-5-5
clawbot
self-assigned this 2026-10-26 10:44:04 +01:00
README documents gate (next at b5fcbf4): FAIL. Five sentences fail, listed by section with the README line of each.
Keywords (line 750)
Sentence: "A file's score for a category is the cosine similarity of the file's embedding and the category's: a number from -1 to 1, higher the more alike the two embeddings are."
Problem: 31 words, two ideas, and the tail "higher the more alike" takes a second read.
Rewrite: "A file's score for a category is the cosine similarity of the file's embedding and the category's. That is a number from -1 to 1; the more alike the two embeddings are, the higher it is."
IDs (line 475)
Sentence: "Anything else, such as 0x10, 1e3 or -1, is refused before any request is sent. The command logs Invalid file ID: <arg> or Invalid collection ID: <arg> and exits 1."
Problem: false for -1. The option parser treats any argument that starts with - and is longer than one character as an option, so quak get -1 is refused with error: unknown option '-1'; the Invalid file ID line is never logged for it. bin/quak.ts sets nothing that changes this, and the repo's only -1 test (test/cli/commands.test.ts, "an ID given on the command line") calls the command function directly, bypassing the parser. Not executed here: the parser package is not vendored in a clone.
Rewrite: drop -1: "Anything else, such as 0x10 or 1e3, is refused before any request is sent."
The JSON beside each original (line 695)
Sentence: "mlData holds everything but that embedding."
Problem: the code drops the whole clip block, not only the embedding (src/backup.ts and src/metadata-backup.ts, const { clip: _clip, ...mlDataWithoutClip }). Ente's payload carries version and client in that block too, and test/cli/metadata-backup.test.ts asserts mlData has no clip key.
Rewrite: "mlData holds everything but the clip block, which holds that embedding."
Collection directories (line 779)
Sentence: "A name too long for a file name, which most file systems limit to 255 bytes, gets its ID added too."
Problem: true for a file's link, not for a collection directory. uniqueNames with withJSON (src/backup.ts) uses 250 bytes, so that <name>.json fits beside the directory; a collection name of 251 to 255 bytes gets its ID added although it fits a file name.
Rewrite: "A file name longer than 255 bytes, the limit on most file systems, gets its ID added too. So does a collection name longer than 250 bytes, which leaves room for .json."
failures.json (line 837)
Sentence: "lastTriedAt: when it was last tried, as a Unix time in milliseconds;"
Problem: the value is one timestamp per run, taken after the refresh and before any file is tried (src/backup.ts, const now = Date.now()), so every failure of a run carries the same instant, which on a large account is hours before the file's own attempt.
Rewrite: "lastTriedAt: the start of the run that last tried it, as a Unix time in milliseconds;"
Model: fable-5-1
README documents gate (`next` at `b5fcbf4`): FAIL. Five sentences fail, listed by section with the README line of each.
**Keywords** (line 750)
Sentence: "A file's score for a category is the cosine similarity of the file's embedding and the category's: a number from -1 to 1, higher the more alike the two embeddings are."
Problem: 31 words, two ideas, and the tail "higher the more alike" takes a second read.
Rewrite: "A file's score for a category is the cosine similarity of the file's embedding and the category's. That is a number from -1 to 1; the more alike the two embeddings are, the higher it is."
**IDs** (line 475)
Sentence: "Anything else, such as `0x10`, `1e3` or `-1`, is refused before any request is sent. The command logs `Invalid file ID: <arg>` or `Invalid collection ID: <arg>` and exits 1."
Problem: false for `-1`. The option parser treats any argument that starts with `-` and is longer than one character as an option, so `quak get -1` is refused with `error: unknown option '-1'`; the `Invalid file ID` line is never logged for it. `bin/quak.ts` sets nothing that changes this, and the repo's only `-1` test (`test/cli/commands.test.ts`, "an ID given on the command line") calls the command function directly, bypassing the parser. Not executed here: the parser package is not vendored in a clone.
Rewrite: drop `-1`: "Anything else, such as `0x10` or `1e3`, is refused before any request is sent."
**The JSON beside each original** (line 695)
Sentence: "`mlData` holds everything but that embedding."
Problem: the code drops the whole `clip` block, not only the embedding (`src/backup.ts` and `src/metadata-backup.ts`, `const { clip: _clip, ...mlDataWithoutClip }`). Ente's payload carries `version` and `client` in that block too, and `test/cli/metadata-backup.test.ts` asserts `mlData` has no `clip` key.
Rewrite: "`mlData` holds everything but the `clip` block, which holds that embedding."
**Collection directories** (line 779)
Sentence: "A name too long for a file name, which most file systems limit to 255 bytes, gets its ID added too."
Problem: true for a file's link, not for a collection directory. `uniqueNames` with `withJSON` (`src/backup.ts`) uses 250 bytes, so that `<name>.json` fits beside the directory; a collection name of 251 to 255 bytes gets its ID added although it fits a file name.
Rewrite: "A file name longer than 255 bytes, the limit on most file systems, gets its ID added too. So does a collection name longer than 250 bytes, which leaves room for `.json`."
**`failures.json`** (line 837)
Sentence: "`lastTriedAt`: when it was last tried, as a Unix time in milliseconds;"
Problem: the value is one timestamp per run, taken after the refresh and before any file is tried (`src/backup.ts`, `const now = Date.now()`), so every failure of a run carries the same instant, which on a large account is hours before the file's own attempt.
Rewrite: "`lastTriedAt`: the start of the run that last tried it, as a Unix time in milliseconds;"
Model: fable-5-1
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
This repo's
README.mdis 12391 words onnext(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.
README.mdand every other prose document in the repo, such asSPEC.md,DESIGN.mdand prose underdocs/, sentence by sentence, as a newcomer would. Check each sentence against the rules below.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.The rules, sentence by sentence. A sentence fails when a newcomer cannot parse it on first reading. It always fails when it:
Also:
Definition of done.
next.nextfor each rewritten document. The last of them ends its title with (closes #N), N being this issue.agents/pr-reviewer.mdstep 4 to every sentence, before it is squash-merged.make fmtapplied, andscript/cibuildgreen on a fresh clone.Model: opus-5-5
Plan.
Scope.
README.mdonly.REPO_POLICIES.mdis copied from sneak/prompts and changes only there.TODO.mdis the work log the repository workflow requires, not a document for users, so it stays as it is.Who. One genius-bar session on Fable, on a worker account, that wrote none of the README. It starts once #223 is merged, so the README describes
get,get-thumb,filesand the thumbnail helper as they now are.How. The session reads the README sentence by sentence against the rules in this issue, and checks every statement against the code on
next. It then writes the README again from scratch, using the old text only as a list of what a reader needs. The sectionsREPO_POLICIES.mdrequires stay:Every place where the old text and the code disagree is listed in the PR body.
Gates. One PR into
next, its title ending with (closes #219). An independent pr-reviewer applies step 4 ofagents/pr-reviewer.mdto every sentence before it is squash-merged. Before the release-candidate tag, a second fresh Fable session that wrote none of it reads the merged README whole and passes it against the same rules.Model: opus-5-5
README documents gate (
nextatb5fcbf4): FAIL. Five sentences fail, listed by section with the README line of each.Keywords (line 750)
Sentence: "A file's score for a category is the cosine similarity of the file's embedding and the category's: a number from -1 to 1, higher the more alike the two embeddings are."
Problem: 31 words, two ideas, and the tail "higher the more alike" takes a second read.
Rewrite: "A file's score for a category is the cosine similarity of the file's embedding and the category's. That is a number from -1 to 1; the more alike the two embeddings are, the higher it is."
IDs (line 475)
Sentence: "Anything else, such as
0x10,1e3or-1, is refused before any request is sent. The command logsInvalid file ID: <arg>orInvalid collection ID: <arg>and exits 1."Problem: false for
-1. The option parser treats any argument that starts with-and is longer than one character as an option, soquak get -1is refused witherror: unknown option '-1'; theInvalid file IDline is never logged for it.bin/quak.tssets nothing that changes this, and the repo's only-1test (test/cli/commands.test.ts, "an ID given on the command line") calls the command function directly, bypassing the parser. Not executed here: the parser package is not vendored in a clone.Rewrite: drop
-1: "Anything else, such as0x10or1e3, is refused before any request is sent."The JSON beside each original (line 695)
Sentence: "
mlDataholds everything but that embedding."Problem: the code drops the whole
clipblock, not only the embedding (src/backup.tsandsrc/metadata-backup.ts,const { clip: _clip, ...mlDataWithoutClip }). Ente's payload carriesversionandclientin that block too, andtest/cli/metadata-backup.test.tsassertsmlDatahas noclipkey.Rewrite: "
mlDataholds everything but theclipblock, which holds that embedding."Collection directories (line 779)
Sentence: "A name too long for a file name, which most file systems limit to 255 bytes, gets its ID added too."
Problem: true for a file's link, not for a collection directory.
uniqueNameswithwithJSON(src/backup.ts) uses 250 bytes, so that<name>.jsonfits beside the directory; a collection name of 251 to 255 bytes gets its ID added although it fits a file name.Rewrite: "A file name longer than 255 bytes, the limit on most file systems, gets its ID added too. So does a collection name longer than 250 bytes, which leaves room for
.json."failures.json(line 837)Sentence: "
lastTriedAt: when it was last tried, as a Unix time in milliseconds;"Problem: the value is one timestamp per run, taken after the refresh and before any file is tried (
src/backup.ts,const now = Date.now()), so every failure of a run carries the same instant, which on a large account is hours before the file's own attempt.Rewrite: "
lastTriedAt: the start of the run that last tried it, as a Unix time in milliseconds;"Model: fable-5-1