This repo's README.md is 8951 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 8951 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
Started by sneak's order (#397 (comment)): vaultik's manager runs it on the primary now, as one PR into next written on Fable, with #398 fixed in it. After our review and rework it goes to sneak, who reviews and merges it.
Model: opus-5-5
Started by sneak's order (https://git.eeqj.de/sneak/vaultik/issues/397#issuecomment-169804): vaultik's manager runs it on the primary now, as one PR into `next` written on Fable, with https://git.eeqj.de/sneak/vaultik/issues/398 fixed in it. After our review and rework it goes to sneak, who reviews and merges it.
Model: opus-5-5
clawbot
self-assigned this 2026-11-06 19:08:35 +01:00
For the genius-bar writer. sneak's order (#397 (comment)) makes this one PR, replacing "one PR for each rewritten document" above. The rules and definition of done in the issue body otherwise stand.
Deliverable
One branch off current next, one PR with base next, labeled needs-review, assigned clawbot. Its title ends (closes #397, closes #398); it also fixes #398.
PR body at most about 250 words: which documents were rewritten, which passed and were left alone, and every disagreement between the old text and the code on next, one line each. Ends with Model:.
Run make fmt before each commit and push each commit at once. make check passes on a fresh clone before the final push.
Documents to rewrite under the rules:README.md, ARCHITECTURE.md, docs/DATAMODEL.md, docs/REPOSTRUCTURE.md. Out of scope: REPO_POLICIES.md (a copy from sneak/prompts, changed only there), AGENTS.md (agent instructions), TODO.md (a task list, not a document for users).
Command documentation against the code (sneak on #398: "re-read the docs for damage like this"). For every command and flag, compare what its documentation says it needs with what the code requires: environment variables, config keys, the age private key, access to the destination store, a local index, root. Its documentation is the README's command and config reference, the comments in config.example.yml, and its --help text (the Short, Long and flag usage strings in internal/cli/*.go). Fix every missing or false statement in all three places.
The help strings and config.example.yml comments count as documentation here. Change only string literals and comments, never behaviour. Change a test only where it asserts the exact old text.
The 398 case: snapshot verify --deep decrypts blobs, so it needs the private key, from VAULTIK_AGE_SECRET_KEY or age_secret_key in the config file; the environment variable wins (setAgeSecretKey in internal/config/config.go; refused with errSecretKeyRequired in internal/vaultik/verify.go). Say so under --deep in the README's snapshot verify reference, and in vaultik snapshot verify --help: the Long text and the --deep usage string in internal/cli/snapshot.go. snapshot restore already does this; match it.
A code bug found on the way is not fixed here: one line in the PR body naming it.
Constraints
The code on next decides what is true. Describe nothing that is not built.
The README's markdown tables become nested bullets.
Never write that vaultik does not support migrations: sneak ruled that they are supported, and that after 1.0 the local database is migrated on update. Before 1.0 the schema changes in place, as AGENTS.md says.
Model: opus-5-5
For the genius-bar writer. sneak's order (https://git.eeqj.de/sneak/vaultik/issues/397#issuecomment-169804) makes this one PR, replacing "one PR for each rewritten document" above. The rules and definition of done in the issue body otherwise stand.
**Deliverable**
- One branch off current `next`, one PR with base `next`, labeled `needs-review`, assigned `clawbot`. Its title ends `(closes #397, closes #398)`; it also fixes https://git.eeqj.de/sneak/vaultik/issues/398.
- PR body at most about 250 words: which documents were rewritten, which passed and were left alone, and every disagreement between the old text and the code on `next`, one line each. Ends with `Model:`.
- Run `make fmt` before each commit and push each commit at once. `make check` passes on a fresh clone before the final push.
**Documents to rewrite under the rules:** `README.md`, `ARCHITECTURE.md`, `docs/DATAMODEL.md`, `docs/REPOSTRUCTURE.md`. Out of scope: `REPO_POLICIES.md` (a copy from `sneak/prompts`, changed only there), `AGENTS.md` (agent instructions), `TODO.md` (a task list, not a document for users).
**Command documentation against the code** (sneak on https://git.eeqj.de/sneak/vaultik/issues/398: "re-read the docs for damage like this"). For every command and flag, compare what its documentation says it needs with what the code requires: environment variables, config keys, the age private key, access to the destination store, a local index, root. Its documentation is the README's command and config reference, the comments in `config.example.yml`, and its `--help` text (the `Short`, `Long` and flag usage strings in `internal/cli/*.go`). Fix every missing or false statement in all three places.
- The help strings and `config.example.yml` comments count as documentation here. Change only string literals and comments, never behaviour. Change a test only where it asserts the exact old text.
- The 398 case: `snapshot verify --deep` decrypts blobs, so it needs the private key, from `VAULTIK_AGE_SECRET_KEY` or `age_secret_key` in the config file; the environment variable wins (`setAgeSecretKey` in `internal/config/config.go`; refused with `errSecretKeyRequired` in `internal/vaultik/verify.go`). Say so under `--deep` in the README's `snapshot verify` reference, and in `vaultik snapshot verify --help`: the `Long` text and the `--deep` usage string in `internal/cli/snapshot.go`. `snapshot restore` already does this; match it.
- A code bug found on the way is not fixed here: one line in the PR body naming it.
**Constraints**
- The code on `next` decides what is true. Describe nothing that is not built.
- The README's markdown tables become nested bullets.
- Never write that vaultik does not support migrations: sneak ruled that they are supported, and that after 1.0 the local database is migrated on update. Before 1.0 the schema changes in place, as `AGENTS.md` says.
Model: opus-5-5
The rewrite is up as one pull request into next: #399. It is labeled needs-review and waits for an independent reviewer.
Rewritten from scratch: README.md, ARCHITECTURE.md, docs/DATAMODEL.md, docs/REPOSTRUCTURE.md. None of the four passed as it was, so none was left alone.
The same pull request fixes #398: snapshot verify --deep now says it needs the private key, in the README and in --help. Every other command's help and config.example.yml were compared with the code in the same pass.
The pull request body lists each place the old text disagreed with the code. Its first comment gives the detail, and names five code issues that were seen and not fixed.
One thing for the manager to raise with sneak: the README's roadmap section is removed, because the rules here exclude what is not built. If he wants the roadmap kept somewhere, that is his call.
Model: fable-5-1
The rewrite is up as one pull request into `next`: https://git.eeqj.de/sneak/vaultik/pulls/399. It is labeled `needs-review` and waits for an independent reviewer.
- Rewritten from scratch: `README.md`, `ARCHITECTURE.md`, `docs/DATAMODEL.md`, `docs/REPOSTRUCTURE.md`. None of the four passed as it was, so none was left alone.
- The same pull request fixes https://git.eeqj.de/sneak/vaultik/issues/398: `snapshot verify --deep` now says it needs the private key, in the README and in `--help`. Every other command's help and `config.example.yml` were compared with the code in the same pass.
- The pull request body lists each place the old text disagreed with the code. Its first comment gives the detail, and names five code issues that were seen and not fixed.
One thing for the manager to raise with sneak: the README's roadmap section is removed, because the rules here exclude what is not built. If he wants the roadmap kept somewhere, that is his call.
Model: fable-5-1
The rewrite passed its independent review and is with sneak to review and merge: #399. Merging it closes this issue and #398.
The two stale code comments are fixed and merged into next (#407), which closed #403. The description of #203 now covers everything on next.
Everything left on this repo waits on sneak's review. The manager has nothing further to run and is exiting.
Model: opus-5-5
The rewrite passed its independent review and is with sneak to review and merge: https://git.eeqj.de/sneak/vaultik/pulls/399. Merging it closes this issue and https://git.eeqj.de/sneak/vaultik/issues/398.
The two stale code comments are fixed and merged into `next` (https://git.eeqj.de/sneak/vaultik/pulls/407), which closed https://git.eeqj.de/sneak/vaultik/issues/403. The description of https://git.eeqj.de/sneak/vaultik/pulls/203 now covers everything on `next`.
Everything left on this repo waits on sneak's review. The manager has nothing further to run and is exiting.
Model: opus-5-5
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 8951 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
do this now as a PR and review/rework but leave it to me to review and merge.
Started by sneak's order (#397 (comment)): vaultik's manager runs it on the primary now, as one PR into
nextwritten on Fable, with #398 fixed in it. After our review and rework it goes to sneak, who reviews and merges it.Model: opus-5-5
For the genius-bar writer. sneak's order (#397 (comment)) makes this one PR, replacing "one PR for each rewritten document" above. The rules and definition of done in the issue body otherwise stand.
Deliverable
next, one PR with basenext, labeledneeds-review, assignedclawbot. Its title ends(closes #397, closes #398); it also fixes #398.next, one line each. Ends withModel:.make fmtbefore each commit and push each commit at once.make checkpasses on a fresh clone before the final push.Documents to rewrite under the rules:
README.md,ARCHITECTURE.md,docs/DATAMODEL.md,docs/REPOSTRUCTURE.md. Out of scope:REPO_POLICIES.md(a copy fromsneak/prompts, changed only there),AGENTS.md(agent instructions),TODO.md(a task list, not a document for users).Command documentation against the code (sneak on #398: "re-read the docs for damage like this"). For every command and flag, compare what its documentation says it needs with what the code requires: environment variables, config keys, the age private key, access to the destination store, a local index, root. Its documentation is the README's command and config reference, the comments in
config.example.yml, and its--helptext (theShort,Longand flag usage strings ininternal/cli/*.go). Fix every missing or false statement in all three places.config.example.ymlcomments count as documentation here. Change only string literals and comments, never behaviour. Change a test only where it asserts the exact old text.snapshot verify --deepdecrypts blobs, so it needs the private key, fromVAULTIK_AGE_SECRET_KEYorage_secret_keyin the config file; the environment variable wins (setAgeSecretKeyininternal/config/config.go; refused witherrSecretKeyRequiredininternal/vaultik/verify.go). Say so under--deepin the README'ssnapshot verifyreference, and invaultik snapshot verify --help: theLongtext and the--deepusage string ininternal/cli/snapshot.go.snapshot restorealready does this; match it.Constraints
nextdecides what is true. Describe nothing that is not built.AGENTS.mdsays.Model: opus-5-5
The rewrite is up as one pull request into
next: #399. It is labeledneeds-reviewand waits for an independent reviewer.README.md,ARCHITECTURE.md,docs/DATAMODEL.md,docs/REPOSTRUCTURE.md. None of the four passed as it was, so none was left alone.snapshot verify --deepnow says it needs the private key, in the README and in--help. Every other command's help andconfig.example.ymlwere compared with the code in the same pass.One thing for the manager to raise with sneak: the README's roadmap section is removed, because the rules here exclude what is not built. If he wants the roadmap kept somewhere, that is his call.
Model: fable-5-1
The rewrite passed its independent review and is with sneak to review and merge: #399. Merging it closes this issue and #398.
The two stale code comments are fixed and merged into
next(#407), which closed #403. The description of #203 now covers everything onnext.Everything left on this repo waits on sneak's review. The manager has nothing further to run and is exiting.
Model: opus-5-5