Contracts & capacity

Operators use contracts to define each organization's entitlement: its plan, monthly allowance, and capacity. This is the ceiling within which org admins set their own budgets.

Contracts are the commercial source of truth. When a customer upgrades, renews, or enters a trial, operators update the contract in the Console — org admins then allocate that entitlement internally via budget policies.

Contracts

A contract captures an organization's commercial agreement:

Field	Description
`kind`	`trial`, `enterprise`, or `internal`
`supportTier`	`community`, `standard`, `priority`, or `dedicated`
`startsAt`	Contract effective date (ISO timestamp)
`endsAt`	Optional expiration
`renewalAt`	Optional renewal reminder date
`limits`	Numeric caps — see below

The included monthly allowance powers the Included bucket on the org's Usage page.

Limit fields

Limit	Governs
`monthlyUsd`	Top-level spend ceiling for the org
`monthlyAgentRuns`	Maximum monthly cloud agent runs
`concurrentAgentRuns`	Maximum concurrent cloud agent runs
`sentinelLicenses`	Sentinel product seats
`cloudAgentLicenses`	Cloud agent seats
Additional limits	`seats`, `teams`, `projects`, `designLicenses`, `monthlyTokens`

Capacity

Capacity grants control how much an organization can consume. Operators adjust capacity when agreements change — mid-contract upgrades, trial extensions, or enterprise true-ups.

Concept	Set by	Governs
Contract / capacity	Operator (Console)	What the org is entitled to
Budget policy	Org admin (Dashboard)	Internal spend within that entitlement

Provisioning API limit fields

The platform API (PATCH /api/provisioning/contracts on api.4rged.ai) accepts these contract.limits keys:

Limit key	Governs
`monthlyUsd`	Top-level monthly spend ceiling (powers the Included bucket)
`monthlyTokens`	Token allowance when token caps apply
`monthlyAgentRuns`	Monthly cloud agent run cap
`concurrentAgentRuns`	Concurrent run cap
`sentinelLicenses`	Sentinel seats
`designLicenses`	Design product seats
`cloudAgentLicenses`	Cloud agent seats
`seats`, `teams`, `projects`	Org structure caps

Every update requires organizationId, a full contract object, and a non-empty reason string recorded in the audit log. Optional overrideReason documents break-glass or exceptional changes.

Console UI vs API

Operators can update capacity from Console → Contracts or via the provisioning API. The Console proxies to platform-api — the same validation runs in both paths. After a change, ask the org admin to refresh Usage and confirm the Included bucket reflects the new monthlyUsd limit.

Note

Changing capacity takes effect for the organization immediately and is reflected in their usage view. Always provide a reason when updating — it is recorded in the audit log.

Operator procedure: update contract capacity

Open the client in Console
Navigate to Clients → select the organization → Contract tab.
Review current usage
Compare current month consumption on the org's Usage page against existing limits. Note whether the change is an upgrade, downgrade, or correction.
Apply the update
Set new limit values, contract kind, support tier, and dates. Enter a clear reason (for example, "Q3 enterprise renewal — increased allowance to 500 USD").
Confirm in dashboard
Ask the org admin to refresh Usage and verify the Included bucket and any license counts updated.
Document externally
Match the Console change to your CRM or billing record so finance and support stay aligned.

Update via provisioning API

Platform operators can update contract capacity through the platform API:

curl -X PATCH "https://api.4rged.ai/api/provisioning/contracts" \
  -H "Authorization: Bearer <platform-operator-session>" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "org_abc123",
    "reason": "Enterprise renewal — increased monthly allowance",
    "contract": {
      "kind": "enterprise",
      "supportTier": "priority",
      "startsAt": "2026-01-01T00:00:00.000Z",
      "endsAt": "2026-12-31T23:59:59.000Z",
      "limits": {
        "monthlyUsd": 500,
        "sentinelLicenses": 10
      }
    }
  }'

List the contract directory:

curl "https://api.4rged.ai/api/provisioning/contracts" \
  -H "Authorization: Bearer <platform-operator-session>"

Trial to enterprise transition

Phase	Operator action	Customer action
Trial start	Set `kind: trial`, low allowance, `endsAt` in 14–30 days	Connect GitHub, run smoke cloud agent
Trial mid-point	Review usage in Console; extend `endsAt` if needed	Internal budget policy optional
Conversion	Set `kind: enterprise`, raise limits, clear or extend `endsAt`	Set team budgets within new ceiling
Renewal	Update `renewalAt`, adjust limits for true-up	No action if within new entitlement

Downgrades

Lowering monthlyAllowanceUsd below current month consumption does not retroactively cancel runs in progress. Coordinate with the customer before downgrading mid-cycle.

Governance

Audit trail for capacity changes.

Usage & budgets

How org admins allocate entitlement internally.

Console overview

Full operator surface map.