FAQ

Why should I trust a verdict?

Because each one shows its work and you can check it without asking us. A published verdict carries the version that was tested, the date a person verified it, the number of sources behind it, and a link to its page on the site where those sources are listed with the date each was read. The file itself is in the public repository under verdicts/, so the diff that changed an opinion is in the history.

That is the whole basis. There is no popularity signal, no download count, no scoring model.

What stops it going stale?

Two mechanisms. A verdict gets a hard expiry when it is published, at most 120 days out. And a job at 02:00 UTC re-reads the package registries and GitHub for every library a verdict points at; when the pick has moved a major version, or the repository is archived, or the expiry has passed, the verdict flips to recheck and is served with [RECHECK] in its first line until a person looks again.

A flagged verdict keeps answering. Hiding it would leave the agent with its training data, which is the thing being fixed.

What does an answer cost in tokens?

An answer is a dozen lines of plain text, not a document. The worked example on the repository front page is 577 characters across ten lines, roughly 150 tokens. That is the point of the format: an agent can call it before every dependency decision without the cost mattering.

Do you see my prompts or my code?

No, and not as a matter of policy: the tools never receive them. recommend takes a task description, traps takes a package name and a version. No argument in any schema is a file, no argument value is written anywhere, and the server reads no disk. What is kept per call is the tool name, the client name and version, whether the caller had a key, characters returned and latency. What is logged lists the fields.

Can I run it myself?

Yes for the server, with a caveat about the data. The code that answers a tool call is MIT licensed in the public repository, and it runs on Node 24 with Postgres and Redis. It ships with no corpus loader, so your copy starts empty and answers no verified verdict yet until you load your own. Self-hosting has the commands and the full list of what is not in the repository.

Am I locked in?

Removing Wellworn is deleting one entry from a config file. There is no SDK in your build, no import in your code, nothing written into your repository. The corpus is CC BY-SA 4.0, so the verdicts you rely on can be copied and kept.

Why not just use a documentation tool?

Different question. A documentation tool fetches the docs for a library you have already chosen. Wellworn answers which one to choose, what it breaks at the version in your lockfile, and what to avoid; the docs tool exists to hand the agent the official docs URL and llms.txt once that choice is made. The two sit next to each other in the same client.

How does a verdict get published?

A draft comes from a pull request against the public repository, from a submit_trap call, or from the request form. Nothing merges automatically: CI validates it against spec/verdict.schema.json, and it lands in a review queue. A reviewer sets verified_by, verified_at and version_tested at publish time, which is why an author cannot mark their own contribution verified. Publishing refuses a verdict that has no pick, and stamps the expiry. How verdicts are made walks the whole path.

Who are the reviewers today?

The Wellworn team. Review runs under a single reviewer identity right now, which is why every verdict prints by wellworn reviewer rather than a person's name. Named attribution for outside contributors is on the provenance line of the traps they submit, when they ask for it.

Can I run it in CI?

Yes. It is an HTTP endpoint, so a build step can call it the same way an editor does, and a key goes in as a repository secret. Use a key rather than the anonymous tier: the anonymous allowance is 60 calls a day per IP, and a hosted runner pool shares its addresses with every other customer on it, so the allowance can already be spent when your job starts.

Does it read my repository?

No. The server has no access to anything on your machine. The Claude Code plugin's hook comes closest, and what it does is parse package names out of the install command or the manifest edit locally, then ask for the traps on those names; the diff never leaves your machine, and the hook never blocks an edit.

A verdict is wrong. How do I dispute it?

Open a pull request against the file in verdicts/, or an issue on the repository if you would rather argue the point before writing it. Both land in the same queue a reviewer works through. For a breakage rather than a disagreement, submit_trap from inside your agent is faster and needs only a free key. Corrections that come with a source URL and the date you read it move quickest, because that is the same evidence a reviewer has to gather otherwise. Contributing has both routes.