ops: make deploy guards token + CLI version prerequisites

CLAUDE.md

@@ -77,13 +77,16 @@ files → a **partial** set. The remote ledger is the source of truth, stamped a
   with the same SQL.** Never one without the other. Two files sharing a timestamp = a
   hand-written-timestamp bug; always use `migration new`.
 - **MCP `execute_sql` is read/debug only — never DDL.**
-- **Edge function deploy**: `make deploy` (root `Makefile`) runs
-  `supabase functions deploy hal-mcp --no-verify-jwt` then `scripts/verify_deploy.sh`, which
+- **Edge function deploy**: `make deploy` (root `Makefile`) guards `SUPABASE_ACCESS_TOKEN` and
+  the `supabase` CLI version before deploying — see below — then runs
+  `supabase functions deploy hal-mcp --no-verify-jwt` and `scripts/verify_deploy.sh`, which
   probes the live function and exits non-zero if it does not answer. `--no-verify-jwt` is
-  required so the function does its own auth. Requires the CLI authenticated as
-  **`renaud@bluegreen.ai`** (org BluegReeno, owner of the project) via the per-repo `.envrc`
-  `SUPABASE_ACCESS_TOKEN`. The personal account (SecondBrain org) has no access → 403. Verify
-  with `supabase projects list` (the project shows ● when linked + visible). Offline checks:
+  required so the function does its own auth. Deploy requires the CLI authenticated as
+  **`renaud@bluegreen.ai`** (org BluegReeno, owner of the project); the personal account
+  (SecondBrain org) has no access → 403. `make deploy` sources the per-repo `.envrc`
+  `SUPABASE_ACCESS_TOKEN` automatically when unset (falls back to a named error, never a bare
+  403), and refuses to run below `MIN_SUPABASE_CLI` (kept in the `Makefile`). Verify auth with
+  `supabase projects list` (the project shows ● when linked + visible). Offline checks:
   `make test`.
 
 Full procedure (incl. deploying from an Archon worktree, and the OAuth vs `secret:hal_api_key`

Makefile

@@ -1,7 +1,23 @@
+MIN_SUPABASE_CLI := 2.109.1
+
 .PHONY: deploy verify test
 
-deploy:   ## deploy hal-mcp + verify it answers
-	supabase functions deploy hal-mcp --no-verify-jwt
+deploy:   ## deploy hal-mcp + verify it answers (guards CLI version + token first)
+	set -e; \
+	CLI_VERSION="$$(supabase --version)"; \
+	LOWEST="$$(printf '%s\n%s\n' "$(MIN_SUPABASE_CLI)" "$$CLI_VERSION" | sort -V | head -1)"; \
+	if [ "$$LOWEST" != "$(MIN_SUPABASE_CLI)" ]; then \
+		echo "supabase CLI $$CLI_VERSION < required $(MIN_SUPABASE_CLI) (deno.lock is lockfile v5, needs a newer CLI) — run: brew trust --formula supabase/tap/supabase && brew upgrade supabase" >&2; \
+		exit 1; \
+	fi; \
+	if [ -z "$$SUPABASE_ACCESS_TOKEN" ] && [ -f .envrc ]; then \
+		. ./.envrc; \
+	fi; \
+	if [ -z "$$SUPABASE_ACCESS_TOKEN" ]; then \
+		echo "SUPABASE_ACCESS_TOKEN unset and no .envrc to source — see docs/operations.md §2" >&2; \
+		exit 1; \
+	fi; \
+	supabase functions deploy hal-mcp --no-verify-jwt && \
 	./scripts/verify_deploy.sh
 
 verify:   ## probe the live hal-mcp function (no redeploy)

docs/operations.md

@@ -108,11 +108,14 @@ supabase projects list   # the row shows ● in the LINKED column when authed +
 **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:
+missing token.
 
-```bash
-source /Users/renaud/Projects/hal/.envrc
-```
+`make deploy` (Path A) guards this automatically: if `SUPABASE_ACCESS_TOKEN` is unset it sources
+`.envrc` from the repo root when present, and fails with a named error otherwise (see the `deploy`
+target in the root `Makefile`) — never a bare 403. An already-exported token is honoured as-is and
+`.envrc` is not required to exist. This does **not** help **Path B**: worktree deploys bypass `make
+deploy` entirely (they need `--workdir`/`--project-ref` flags the target doesn't pass), so there
+you still source the token by hand — see Path B below.
 
 ### CLI version prerequisite
 
@@ -126,7 +129,11 @@ Caused by: Unsupported lockfile version '5'. Try upgrading Deno or recreating th
 
 **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):
+2026-07-25).
+
+`make deploy` guards this too: it checks `supabase --version` against `MIN_SUPABASE_CLI` (kept in
+the `Makefile`, currently `2.109.1`) and stops *before* bundling if the CLI is too old, printing
+the exact remedy below. When you see it, run this and retry:
 
 ```bash
 brew trust --formula supabase/tap/supabase   # Homebrew now refuses untrusted taps