docs: document npm overrides + standardize npm registry

.npmrc

@@ -0,0 +1,4 @@
+# Use the canonical npm registry. registry.npmmirror.com's advisory endpoint
+# returns NOT_IMPLEMENTED, which breaks `npm audit`; pinning here also keeps
+# package-lock.json from drifting to mixed registries. See docs/dependencies.md.
+registry=https://registry.npmjs.org/

AGENTS.md

@@ -0,0 +1,15 @@
+# Agent & contributor notes
+
+Operational guidance for humans and coding agents working in this repo.
+
+## Dependencies / npm
+
+- **Registry:** npmjs, pinned in `.npmrc`. Do not switch to
+  `registry.npmmirror.com` or commit a lockfile that resolves from it — its
+  advisory endpoint returns `NOT_IMPLEMENTED`, so `npm audit` silently can't run.
+- **The `overrides` in `package.json` are intentional security pins** for
+  `@cursor/sdk`'s transitive deps (`tar`, `undici`, `@tootallnate/once`) — there
+  is no upstream `@cursor/sdk` fix yet. Do not remove or loosen them, and do not
+  regenerate the lockfile against another registry. Rationale, verification, and
+  removal conditions live in `docs/dependencies.md` (removal tracked in #5).
+- **Auditing:** `npm audit --audit-level=moderate` (npmjs registry required).

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

docs/dependencies.md

@@ -0,0 +1,45 @@
+# Dependency notes
+
+## npm `overrides` (security pins)
+
+`@cursor/sdk@1.0.18` pulls transitive dependencies with `npm audit` findings and
+has no upstream fix yet, so `package.json` pins patched versions via `overrides`:
+
+| Override | Pinned | Consumer (chain) | Scope / why safe | Remove when |
+|----------|--------|------------------|------------------|-------------|
+| `tar` | `^7.5.10` | `sqlite3 → node-gyp@8 / cacache` | **install-time only** — not in the runtime path; used to build sqlite3's native addon | `@cursor/sdk` updates `sqlite3`/`node-gyp` past `tar` 6 |
+| `undici` | `^6.24.0` | `@connectrpc/connect-node@1.7.0` | runtime-inert on Node ≥18 (see below) | connect-node / `@cursor/sdk` ship `undici` ≥6 |
+| `@tootallnate/once` | `^2.0.1` | optional install tooling (`http-proxy-agent`) | optional, install-time | transitive bump |
+
+**Verified (2026-06):** a clean `npm ci` on **Node 26** — which has no `sqlite3`
+prebuilt, so it forces the native source build that actually exercises `tar` —
+succeeds with `tar@7` building the addon; `npm audit --audit-level=moderate`
+(against npmjs) → **0 vulnerabilities**.
+
+### Why `undici` 5→6 is runtime-safe
+`@connectrpc/connect-node@1.7.0`'s only use of `undici` is a `Headers` polyfill
+gated behind `node < 18`:
+
+```js
+const undici_1 = require("undici");
+if (major < 18) {
+  if (typeof globalThis.Headers === "undefined") globalThis.Headers = undici_1.Headers;
+}
+```
+
+This repo requires Node ≥22, so that branch never runs (the global `fetch` /
+`Headers` are used). `undici@6` imports cleanly on Node ≥18.17, and nothing else
+consumes it — so the major bump is inert at runtime here.
+
+### Do not
+- Delete or loosen these overrides (re-introduces the audit findings).
+- Regenerate `package-lock.json` against `registry.npmmirror.com`.
+
+Removal is tracked in #5.
+
+## Registry
+
+Installs and audits use `registry.npmjs.org`, pinned in `.npmrc`.
+`registry.npmmirror.com`'s advisory endpoint returns `NOT_IMPLEMENTED`, so
+`npm audit` cannot run against it. The lockfile should resolve from this single
+registry; if entries drift, run `npm install` with the npmjs registry to converge.