feat(billing): grant configurable AI gateway signup credit to new orgs

[nicacioliveira]

Summary

Every new org is granted a one-time Deco AI Gateway credit on creation, netting ~$25 with the gateway's existing $2 provision credit. The amount is a deployment default and can be overridden per-org by the control plane at org creation.

How the credit is granted

• The gateway's provisionKey only mints a key (+ a small $2 auto-grant); balance is separate. The server-to-server grant is POST /api/admin/credits (already used by the Stripe top-up webhook), idempotent per referenceId.
• New grantGatewaySignupCredit (billing/gateway-admin.ts) uses referenceId = signup-credit:<orgId> → a re-run of seedOrgDb or any retry is a no-op at the gateway, so no local "already granted" state is needed.
• Called fail-soft from seedOrgDb (own try/catch, only logs) — a grant error never fails org creation, mirroring the AI-key auto-provision path. Independent of the provision block.

Configurability

• Deployment default: DECO_AI_GATEWAY_SIGNUP_GRANT_CENTS (default 2300 = nets ~$25; 0 disables; capped at $1,000 via MAX_SIGNUP_GRANT_CENTS).
• Per-org override (control plane): ORGANIZATION_CREATE accepts optional initialCreditCents. It rides in org metadata; the afterCreate seed hook (the canonical creation boundary, covering the MCP tool and direct Better Auth calls) reads it via readInitialCreditCents, a defensive parser that handles metadata as object or JSON string and ignores out-of-range/garbage (→ falls back to the default).

Scope

Applies to every org only when the gateway admin is configured (gatewayAdminConfigured() = aiGatewayEnabled && aiGatewayAdminToken) — hosted deployments. Self-hosted can't reach the admin API and skip it.

Testing

• resolve-config.test.ts: default/override/0/non-numeric/cap for the new setting.
• initial-credit.test.ts: object vs JSON-string metadata, 0, out-of-range/garbage, cap boundary.
• bun run check (all workspaces) and bun run lint pass; bun run fmt applied; generate:tool-contracts re-run (tool-io.ts).
• The one failing test locally (billing-checkout.integration.test.ts) is a pre-existing Postgres-dependent integration test (no local DB), untouched by this PR.

Caveats

• Stacks on the gateway's own $2: I can't suppress the gateway (ai-site) auto-grant from Studio, so the default is 2300 to net ~$25. Change the env if the gateway's behavior changes.
• /api/admin/credits contract (field names, referenceId dedupe) is inferred from the existing creditGatewayTopUp consumer — the ai-site gateway repo isn't in this workspace. Worth a confirm from the gateway side before relying on exact idempotency semantics.

🤖 Generated with Claude Code

---

Summary by cubic

Grants new organizations a one-time Deco AI Gateway credit on creation, replacing the previous no-credit behavior. The amount is configurable via deployment default and per-org override.

Configuration

• DECO_AI_GATEWAY_SIGNUP_GRANT_CENTS sets the default (2300 cents, 0 disables, capped at $1,000).
• ORGANIZATION_CREATE accepts optional initialCreditCents to override per org.

Notes

• Grant is idempotent at the gateway via referenceId = signup-credit:<orgId>, so retries never double-grant.
• Fail-soft: a grant error is logged but never fails org creation.
• Only applies when the gateway admin is configured (hosted); self-hosted deployments skip it.
• Default is 2300 cents because the gateway's own $2 provision credit can't be suppressed; the admin API contract is inferred from the existing top-up consumer.

^{Written for commit 20c81de. Summary will update on new commits.}