Merge branch 'main' into cursor/fix-cve-2026-44457-hono-sou-1070-6a4b

Author: brendan-kellam

CLAUDE.md

@@ -255,22 +255,36 @@ Images added to `.mdx` files in `docs/` should be wrapped in a `<Frame>` compone
 
 When fixing a CVE in a transitive dependency, prefer a real top-level upgrade over a forced `resolutions` override.
 
-1. **Trace the dependency chain** to find which top-level package in `package.json` brings in the vulnerable transitive dep:
+1. **Trace the dependency chain to a package in your own `package.json`.** Run:
 
    ```bash
    yarn why <vulnerable-package> --recursive
    ```
 
-2. **Prefer bumping the top-level dependency** to a version whose transitive tree no longer includes the vulnerable version. This is a real, supported upgrade and avoids forcing a version on a consumer that may not expect it.
+   "Top-level" means a package **literally listed in this repo's root or workspace `package.json`** under `dependencies`, `devDependencies`, or `peerDependencies` — not just any ancestor in the chain. If the chain is `vulnerable-pkg → mid-pkg → top-pkg`, do not stop at `mid-pkg`; keep walking until you reach `top-pkg`.
 
-3. **Fall back to a `resolutions` override** only if no top-level bump resolves it (no compatible version exists, or it would require a breaking major). Match the existing format in `package.json` and pin with `^`, not `>=`:
+2. **Check whether the existing ranges already allow a patched version.** Often the lockfile is just stale: every `^x.y.z` range in the chain still admits the patched version, but `yarn.lock` was written before that version existed. In that case, refresh the lockfile entry — no `package.json` change, no `resolutions` override:
+
+   ```bash
+   yarn up <intermediate-or-vulnerable-pkg>
+   # or, to refresh many at once:
+   yarn dedupe
+   ```
+
+   This is the lightest-weight fix: it doesn't force a version, it just bumps the lock to the latest version that satisfies the constraints already in the tree. Verify with `yarn why <vulnerable-package>` afterward — if every instance is now patched, you're done.
+
+3. **If a refresh isn't enough, bump the top-level dependency** to a version whose transitive tree no longer includes the vulnerable version. This is also a real, supported upgrade. Verify the upgrade actually removes the vulnerable version with `yarn why <vulnerable-package>` after running `yarn install`.
+
+4. **Fall back to a `resolutions` override** only if neither a refresh nor a top-level bump resolves it (no compatible version exists in the existing ranges, or a top-level upgrade would require a breaking major). Use the **qualified** form keyed to the existing source range (not a bare key, which overrides every requester unnecessarily), and pin with `^`, not `>=`:
 
    ```json
    "resolutions": {
-       "<pkg>@npm:<existing-range>": "^<patched>"
+       "<pkg>@npm:<existing-source-range>": "^<patched>"
    }
    ```
 
+   The `<existing-source-range>` is whatever range is currently requesting the vulnerable version (find it in `yarn.lock`, e.g. `^2.8.3`). Avoid the bare-key form `"<pkg>": "^x.y.z"`.
+
 ### Branch naming for CVE fixes
 
 Use a **package-keyed** branch name, not a CVE-keyed one: