diff --git a/AGENTS.md b/AGENTS.md
index cf6da7a..d81df3a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -178,6 +178,15 @@ learning_ai_notes/
 - All colors via `--nl-*` CSS custom properties from `@bytelyst/design-tokens` — never hardcode hex values
 - Every interactive element must have `aria-label` or visible text label
 
+
+### .npmrc — NEVER edit directly
+
+**`.npmrc` is managed by a canonical template in `learning_ai_common_plat`.** Never create or hand-edit `.npmrc` — it will drift.
+
+- **Template:** `../learning_ai_common_plat/scripts/npmrc.template`
+- **Sync:** `cd ../learning_ai_common_plat && bash scripts/sync-npmrc.sh`
+- **Key rule:** Never hardcode `gitea.bytelyst.com` — use `${GITEA_NPM_HOST:-localhost}:3300` (SSH tunnel on corp network)
+
 ### MUST NOT do
 
 - Never use `console.log` in production code — use `req.log` or `app.log` in Fastify