diff --git a/AGENTS.md b/AGENTS.md
index 2891cbcf..2ec98606 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -139,11 +139,22 @@ learning_ai_common_plat/
 - For LLM routing, prefer `@bytelyst/llm-router` as the source of truth; do not introduce parallel routing logic unless explicitly required
 - Commit messages: `type(scope): description` — types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`
 
+### .npmrc — NEVER edit directly in product repos
+
+**All `.npmrc` files are managed by a canonical template.** Never create or edit `.npmrc` in any product repo — use the sync tool instead.
+
+- **Template:** `scripts/npmrc.template` in this repo (learning_ai_common_plat)
+- **Sync:** `bash scripts/sync-npmrc.sh` — copies template to all 13 product repos
+- **Audit:** `bash scripts/check-npmrc-drift.sh` — detects drift (CI-ready, exits 1 on mismatch)
+- **Key config:** `@bytelyst:registry` uses `${GITEA_NPM_HOST:-localhost}:3300` SSH tunnel — never hardcode `gitea.bytelyst.com` (unreachable on corp network)
+- **If adding a new repo:** add it to the `REPOS` array in both `sync-npmrc.sh` and `check-npmrc-drift.sh`, then run sync
+
 ### MUST NOT do
 
 - Never use `console.log` in production code — use `req.log` or `app.log` in Fastify
 - Never use `any` type — use Zod inference or explicit types
 - Never hardcode secrets or API keys
+- Never hardcode `gitea.bytelyst.com` in `.npmrc` — use `${GITEA_NPM_HOST:-localhost}:3300` via the canonical template
 - Secret guardrails: Husky runs `scripts/secret-scan-staged.sh` (pre-commit) and `scripts/secret-scan-repo.sh` (pre-push). See `docs/WINDSURF/CODEX_SESSION_SUMMARY_AND_PLAYBOOK.md`.
 - Never commit real emulator keys or blob account keys in tracked files; keep placeholders in `.env.example`
 - Never modify tests to make them pass — fix the actual code