diff --git a/.husky/pre-commit b/.husky/pre-commit
index 942f0858..b0d5ff53 100644
--- a/.husky/pre-commit
+++ b/.husky/pre-commit
@@ -14,8 +14,15 @@ if grep -E '"resolved": "https?://' package-lock.json | grep -v registry.npmjs.o
   exit 1
 fi
 
+# Capture staged files so we only re-stage what the user intended to commit
+# (avoids sweeping unrelated WIP into the commit)
+STAGED=$(git diff --name-only --cached)
+
 npm run build:all
 npm run prettier:fix
 
-# Stage any files reformatted by prettier (generated files, source, docs, etc.)
-git diff --name-only --diff-filter=M | xargs -r git add
+# Re-stage originally-staged files (prettier may have reformatted them)
+echo "$STAGED" | xargs -r git add
+
+# Also stage generated files (regenerated by build:all from spec.types.ts)
+git add src/generated/
diff --git a/.npmrc b/.npmrc
new file mode 100644
index 00000000..214c29d1
--- /dev/null
+++ b/.npmrc
@@ -0,0 +1 @@
+registry=https://registry.npmjs.org/
diff --git a/AGENTS.md b/AGENTS.md
index 41997da1..6bfc8cdd 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -39,7 +39,10 @@ npm test
 # Check JSDoc comment syntax and `{@link}` references
 npm exec typedoc -- --treatValidationWarningsAsErrors --emit none
 
-# Regenerate package-lock.json (especially on setups w/ custom npm registry)
+# Regenerate package-lock.json
+# Note: repo .npmrc pins registry to npmjs.org, so a plain `npm i` is safe even
+# if your global npm config points elsewhere. The Docker step below is optional
+# — it locks linux-amd64 optionalDependencies (sharp, rollup, bun) for CI.
 rm -fR  package-lock.json node_modules && \
   docker run  --rm -it --platform linux/amd64 -v $PWD:/src:rw -w /src node:latest npm i && \
   rm -fR node_modules && \