diff --git a/docs/operations.md b/docs/operations.md
index f7f43f1..932ea2f 100644
--- a/docs/operations.md
+++ b/docs/operations.md
@@ -105,6 +105,34 @@ The token is loaded per-directory by `direnv` from `/Users/renaud/Projects/hal/.
 supabase projects list   # the row shows ● in the LINKED column when authed + visible
 ```
 
+**direnv does not fire in a non-interactive shell.** An agent, a script, a CI runner or anything
+driving `make deploy` without an interactive `cd` gets **no token at all** and falls through to
+the personal account — which fails with a 403 that reads like a permissions problem rather than a
+missing token. Source it explicitly first, exactly as Path B does:
+
+```bash
+source /Users/renaud/Projects/hal/.envrc
+```
+
+### CLI version prerequisite
+
+`supabase/functions/hal-mcp/deno.lock` is **lockfile version 5** (since `c19bec9`, June 2026).
+The Deno bundled in older CLI releases cannot read it, and the deploy dies *after* auth succeeds:
+
+```
+Error: Failed reading lockfile at '.../deno.lock'
+Caused by: Unsupported lockfile version '5'. Try upgrading Deno or recreating the lockfile
+```
+
+**Do not delete or regenerate `deno.lock` to work around this** — it pins the exact dependency
+versions that ship to production. Upgrade the CLI instead (2.72.7 → 2.109.1 fixed it on
+2026-07-25):
+
+```bash
+brew trust --formula supabase/tap/supabase   # Homebrew now refuses untrusted taps
+brew upgrade supabase
+```
+
 ### Pre-deploy check (non-negotiable)
 
 `supabase/functions/hal-mcp/index.ts` **must** end with:
@@ -123,6 +151,20 @@ an unauthenticated call must be rejected (401/400/405) by a live function. `make
 offline counterpart (deno type-check both edge functions + offline pytest) for pre-deploy sanity
 before ever reaching the live probe.
 
+⚠️ **`make test` does not run the `hal-mcp` unit tests, and neither does CI** (see #78). It
+type-checks. To actually exercise `index.test.ts` before a deploy — worth doing whenever the
+deploy carries a behavioural change:
+
+```bash
+cd supabase/functions/hal-mcp
+SUPABASE_URL="https://zgkvbjqlvebttbnkklpo.supabase.co" \
+SUPABASE_SECRET_KEYS='{"default":"test-admin"}' \
+deno test --allow-all index.test.ts        # ok | 63 passed | 0 failed
+```
+
+`SUPABASE_URL` must be the **real** project URL: four OAuth-metadata tests assert the exact
+`resource_metadata` value, so a placeholder fails those four while the other 59 pass.
+
 ### Path A — deploy from `main` (the normal case)
 
 ```bash