handbook: replace README badges with npmx.dev badges

[nerdalytics]

Summary

The README currently uses shields.io and badgen for the version and license badges. These should be replaced with npmx.dev badges, which pull data from the same registry and link back to the npmx.dev package page (see #89).

This issue also covers the Socket.dev badge, which has two independent problems that cause it to display incorrect information.

Badge selection

npmx.dev provides ten badge types. Not all belong in a README header. The implementation should decide which subset to include and which style to use.

Available badges:

Badge	Shows
version	Current published version
license	License from package.json
size	Install size
downloads-year	Annual download count
dependencies	Dependency count
created	First publish date
updated	Last publish date
types	TypeScript types status
vulnerabilities	Known vulnerability count
deprecated	Deprecation status

Style options:

npmx.dev supports two rendering styles via the ?style=shieldsio query parameter. The default style uses rounded pill shapes with colored backgrounds. The shieldsio style matches the flat rectangular look common in most READMEs.

Socket.dev badge

Two separate problems affect the Socket badge.

1. Hardcoded version

The badge URL contains a hardcoded version (1000.3.0). Every version bump requires a manual README update, and this step is consistently missed. The badge currently points to 1000.3.0 while the package is at 1000.3.2.

Socket.dev does not appear to offer a versionless or /latest badge URL, so the version must be updated manually or via automation on each release.

2. npmjs.com caches badge images permanently

npmjs.com proxies all README images through its own CDN and caches the response from the first fetch. If Socket has not finished analyzing the package when npm first requests the badge, the "in progress" SVG gets cached indefinitely. There is no public mechanism to purge npm's image proxy cache.

This is visible today: the GitHub README shows the correct Socket score (74), while the npmjs.com README shows "in progress" for the same badge URL.

Root cause: Socket's badge endpoint does not set short-lived Cache-Control headers the way shields.io does (max-age=900). Once npm's proxy caches the initial response, it never re-fetches.

Possible mitigations:

• File a feature request with Socket.dev to set short cache TTLs on badge SVGs
• Delay adding the Socket badge until after analysis completes (requires a two-step publish or patch bump)
• Accept the stale state on npmjs.com and rely on the GitHub README for accurate display
• Automate a GitHub Action to purge GitHub's Camo cache after Socket analysis completes (does not help npmjs.com)

Scope

Replace

• README.md line 5 — badgen license badge → npmx.dev license badge
• README.md line 6 — shields.io version badge → npmx.dev version badge

Fix

• README.md line 7 — Socket badge with hardcoded version 1000.3.0

Decide

• Which npmx.dev badges to include beyond version and license
• Which badge style to use (default or shieldsio)
• How to handle the Socket.dev caching problem on npmjs.com