feat(cli): envelope-first plan-gate upgrade hints

[pamelachia]

Paid-feature denials now read the management API's entitlement_required error envelope straight off the failed response and print the upgrade hint with zero extra API calls. Previously the suggest path made 2 extra round-trips (project lookup + entitlements) per gated failure, and only 9 commands were wired at all.

Changed:

• Wired commands stop making extra API calls on denial: the shared suggest functions (Go plan_gate.go, TS legacy-upgrade-suggest.ts) parse { error: { code: "entitlement_required", feature, upgrade_url } } first; the entitlements round-trip stays as the fallback for gates that do not emit the envelope yet (v1 SSO carries no server-side gate at all).
• domains create/get/activate/reverify and vanity-subdomains get newly show the hint: envelope-only, no fallback, because the custom_domain entitlement key is plan-level while the gate is a per-project add-on, so the old round-trip would tell Free orgs to upgrade on unrelated 404s.
• cli_upgrade_suggested reports the server-authoritative feature: feature_key comes from the envelope (fixes a branching_persistent denial being logged as branching_limit); org_slug is parsed from upgrade_url.
• Go mirror kept 1:1 per the legacy-shell parity doctrine; AGENTS.md telemetry table and the affected SIDE_EFFECTS.md files updated to match.

Note: the envelope's upgrade_url is server-built and printed without a host check. This trusts the management API host the same way every authenticated call already does; a host allowlist would silently suppress valid hints on profiles whose dashboard URL differs from the CLI default.

To test

Requires a Free-org project ref (to hit the gates).

Tested locally against prod (bun src/legacy/main.ts, Free org):

• domains get --project-ref <free-ref> --agent no prints "Upgrade your plan: .../org//billing" on stderr; --debug shows exactly one HTTP request, no project/entitlements lookups
• vanity-subdomains get shows the same hint via the decorated server gate (since the develop merge bringing in fix(cli): gate vanity-subdomains and network-restrictions behind --experimental (CLI-1972) #5945, this command additionally needs --experimental or SUPABASE_EXPERIMENTAL=1 to get past the experimental gate)
• Plain 4xx without the envelope on the newly wired commands produces no hint (integration tests pin the false-positive guard)
• Envelope-less denials on previously wired commands still run the entitlements fallback unchanged

Before / after

domains get --project-ref <free-ref> --agent no on the same Free-org project, stderr verbatim (ref and org slug redacted). Before is the merge-base with develop (3ad3b875), after is this branch.

Before, the envelope is already in the raw error JSON but nothing reads it, so no hint:

unexpected get hostname status 400: {"message":"Custom domains require the Custom Domain add-on, available on the Pro plan and above.","error":{"code":"entitlement_required","feature":"custom_domain","upgrade_url":"https://supabase.com/dashboard/org/<slug>/billing"}}
Try rerunning the command with --debug to troubleshoot the error.

After, the hint prints first, still exactly one HTTP request (--debug shows only the /custom-hostname GET):

Your organization does not have access to this feature. Upgrade your plan: https://supabase.com/dashboard/org/<slug>/billing
unexpected get hostname status 400: {"message":"Custom domains require the Custom Domain add-on, available on the Pro plan and above.","error":{"code":"entitlement_required","feature":"custom_domain","upgrade_url":"https://supabase.com/dashboard/org/<slug>/billing"}}
Try rerunning the command with --debug to troubleshoot the error.

Linear

• fixes GROWTH-958

[github-actions]

Supabase CLI preview

npx --yes https://pkg.pr.new/supabase/cli/supabase@821b821048c8c3cfc7c35549423d0acc1af96773

Preview package for commit 821b821.

[pamelachia]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. 🎉

Reviewed commit: 821b821048

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".