Methodology
This page is the honest version of how Citewell gets its numbers. It is enforced by the validation gate in scripts/validate.ts, which fails the build rather than publishing a violation.
1. Primary sources only
Every figure is traced to the company's own terms page, fee schedule, rate page, or regulatory filing. Blogs, listicles, and aggregator roundups are never treated as authoritative: a claim sourced only to a blog is marked unverified and does not enter the dataset as a fact.
2. Per-attribute citations
Each attribute carries its own source URL, not just the entity-level list. Hover any value on a comparison table and you get the exact page that supports that one figure. Agents can do the same from the JSON, the atomic unit is value + unit + note + source.
3. Volatile figures are dated and re-verified weekly
APYs, signup bonuses, referral offers, and intro APRs change without notice. Every volatile figure carries a last_verified date. A weekly automated check re-fetches the source pages, compares the stored value against what the page now says, and flags anything that changed. The report is written to data/verification/<date>.json and changed figures are swapped before the next deploy.
4. Unknown means unknown
A value that cannot be confirmed at a primary source is null with a stated reason, never an estimate, never a rounded average, never a figure borrowed from a competitor page. An honest null is more useful than a confident wrong number, because a wrong APY or premium costs a reader real money.
Verified absence is different: when a company's own page confirms a product is not offered (no fractional shares, no margin, no paid tier), that is a fact with a source, and it is published as a boolean false rather than a null.
5. No rankings
No page, no API response, and no export orders entities by quality. Collections are sorted alphabetically and that ordering carries no meaning. If you want a ranking, rank it yourself against our fields, that is what the data is for.
6. Referral disclosure is in the data
Where Citewell holds a referral link, the record carries referral.we_are_paid: true, a machine-readable flag, not a footer note. Any agent can filter out every compensated link programmatically. We never publish a referral block for a company we have no link for, and we never label ourselves an official partner unless we are actually registered.
7. The gate is the guarantee
The rules above are not a style guide; they are enforced by scripts/validate.ts, which runs before every build and exits non-zero on any violation, ranking language, undated volatile figures, unitless numerics, or a referral block for a link we do not hold. A red validator is the expected steady state while data is incomplete; it is the feature working, not a bug to clear.