docs(agents): three deploy gaps observed during M10/M11 ramp

AGENTS.md

@@ -127,6 +127,24 @@ Tracked here so a future agent can pick up without re-discovering. All are pre-l
 
 4. **Production cron config for reservation reminders.** Migration `0011_m9_reminder_loop.sql` ships the `cron.schedule(...)` call but it only runs when `pg_cron` is installed (gated by `to_regnamespace('cron')`). To activate in cloud Supabase: enable `pg_cron` + `pg_net` extensions in the Dashboard, then `alter database postgres set app.functions_url = '<project-functions-url>'` and `alter database postgres set app.service_role_key = '<service-role-jwt>'`, then re-apply the migration so the schedule INSERT runs against the now-present `cron` schema. Until that's done in cloud, reminder SMS won't fire — the Edge Function works, the cron just never invokes it.
 
-5. **Deploy workflow doesn't push migrations to cloud.** `.github/workflows/deploy.yml` ships admin + kitchen + Edge Functions but does NOT run `pnpm supabase db push --linked`. M10 (PR #14) merged with migration `0012_m10_knowledge_rpcs.sql` and the new Edge Function code went live, but the `knowledge_replace_chunks` and `knowledge_lookup` RPCs never landed in cloud — discovered when `knowledge_reindex` returned a generic 500 (OpenAI embed succeeded; the RPC call hit "function does not exist"). For now, manually run `pnpm supabase db push --linked` after merging any PR that adds a file under `supabase/migrations/`. Verify via Supabase SQL editor: `select proname from pg_proc where proname = '<new-fn-name>';`. Documented in [developer/m8-runbook.md](developer/m8-runbook.md) "Deployment + rollback" callout.
+5. **Local CLI deploy paths silently differ from CI — three gaps observed during M10/M11 launch validation (May 4, 2026).** The CI workflow `.github/workflows/deploy.yml` is the *only* deploy path that's correct today. Local `pnpm deploy:*` commands and direct `supabase` CLI invocations all default to behaviors that break production. All three observed in a single afternoon while bringing M10's KB into cloud:
 
-   **Fix to land in M12 or M13:** add a `db push` job to `deploy.yml`, gated on either a manual workflow_dispatch with `confirm_migrations: yes` or a label on the PR (`migrate-on-merge`). Do NOT auto-push migrations on every commit — destructive migrations need a human gate. The cleanest design: separate workflow `migrate.yml` triggered manually with the target environment selector, like the deploy workflow already does for `target: all/admin/kitchen/functions`.
+   **5a. `db push` not in deploy workflow.** CI ships admin + kitchen + Edge Functions but doesn't run `pnpm supabase db push --linked`. M10's migration `0012_m10_knowledge_rpcs.sql` merged and the new Edge Function code went live, but the `knowledge_replace_chunks` and `knowledge_lookup` RPCs never landed in cloud — discovered when `knowledge_reindex` returned a generic 500 (OpenAI embed succeeded; the RPC call hit "function does not exist"). **Today's manual fix:** run `pnpm supabase db push --linked` after merging any PR that adds a file under `supabase/migrations/`. Verify via Supabase SQL editor: `select proname from pg_proc where proname = '<new-fn-name>';`.
+
+   **5b. `supabase functions deploy <name>` defaults to `verify_jwt=true`.** The Supabase CLI requires `--no-verify-jwt` to deploy with the Kong-level JWT check disabled. CI knows this (`.github/workflows/deploy.yml`'s functions step explicitly passes `--no-verify-jwt`); operators running the CLI by hand do not. Re-deploying any single function from a local shell with the default flags re-enables JWT verification and breaks Vapi-reachable functions immediately (Vapi has no `apikey` or `Authorization` header on its `assistant-request` POST). **Today's manual fix:** always pass `--no-verify-jwt` when running `pnpm supabase functions deploy <name>` against cloud. Re-bulk-deploying via `pnpm supabase functions deploy --no-verify-jwt --project-ref <ref>` corrects the state.
+
+   **5c. `pnpm deploy:admin` (and `:kitchen`) silently fall back to Vite dev defaults when `VITE_SUPABASE_URL` and `VITE_SUPABASE_ANON_KEY` aren't in the shell.** Vite embeds those values into the browser bundle at build time. CI injects them from GitHub Actions secrets pointing at cloud; a local `pnpm deploy:admin` without them produces a bundle pointing at `http://127.0.0.1:54321` (Vite dev fallback). The build succeeds, deploy succeeds, the deployed app is unreachable from real browsers. **Today's manual fix:** prepend the cloud env vars when running locally:
+
+   ```bash
+   VITE_SUPABASE_URL=https://klzznfagrtormretqsgb.supabase.co \
+   VITE_SUPABASE_ANON_KEY='<cloud anon key>' \
+   pnpm deploy:admin
+   ```
+
+   Better yet, trigger the CI workflow (`gh workflow run Deploy --ref main -f target=admin`) so secrets come from GitHub Actions.
+
+   **Fixes to land in M12 or M13** (a single workflow refactor addresses all three):
+   - Add a separate `migrate.yml` workflow gated on a `migrate-on-merge` PR label or a `workflow_dispatch` with `confirm_migrations: yes`. Don't auto-push migrations on every commit — destructive migrations need a human gate.
+   - Add a `pnpm cloud:deploy` wrapper script that fails loudly if `VITE_SUPABASE_URL` / `VITE_SUPABASE_ANON_KEY` / `--no-verify-jwt`-equivalents are missing, so operators get a clear error instead of a silently-broken deploy. Or remove `pnpm deploy:*` from the package scripts entirely and force operators through CI.
+
+   Documented in [developer/m8-runbook.md](developer/m8-runbook.md) "Deployment + rollback" callout (5a only as of writing — extend to cover 5b and 5c when the runbook gets its next pass).