## ADDED Requirements

### Requirement: Tenants are assigned to a tier with defined rate limits
The system SHALL maintain a `tenant_tiers` table linking each tenant to a tier (`free`, `pro`, `enterprise`) with associated limits: max agents, max API calls per day, and max token issuances per day. Tier configuration SHALL be defined in a `TIER_CONFIG` constant (not in the database) to enable zero-latency enforcement.

Tier defaults:
- `free`: 10 agents, 1,000 API calls/day, 1,000 token issuances/day
- `pro`: 100 agents, 50,000 API calls/day, 50,000 token issuances/day
- `enterprise`: unlimited (no enforcement)

#### Scenario: New tenant defaults to free tier
- **WHEN** a new tenant is created via `POST /api/tenants`
- **THEN** a `tenant_tiers` row SHALL be created with `tier=free`

#### Scenario: Enterprise tier bypasses all rate limits
- **WHEN** a tenant on the `enterprise` tier makes any API call
- **THEN** no rate limit check SHALL be applied for that tenant

### Requirement: API calls are rate-limited per tenant tier
The system SHALL enforce daily API call limits per tenant using Redis keys `rate:tier:calls:<tenant_id>` with a TTL aligned to UTC midnight. When a tenant exceeds their daily call limit, subsequent requests SHALL be rejected.

#### Scenario: Tenant within call limit proceeds normally
- **WHEN** a tenant on the `free` tier has made fewer than 1,000 API calls today
- **THEN** the request SHALL proceed and the counter SHALL be incremented

#### Scenario: Tenant exceeding daily call limit is rejected
- **WHEN** a tenant on the `free` tier has made 1,000 or more API calls today
- **THEN** any further API request SHALL return HTTP 429 with `Retry-After` header set to seconds until UTC midnight

#### Scenario: Rate limit headers are present on all responses
- **WHEN** any authenticated API request is made
- **THEN** the response SHALL include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers reflecting the tenant's daily call allowance

### Requirement: Agent count is enforced per tenant tier
The system SHALL prevent tenants from creating more agents than their tier allows. The check SHALL occur at agent creation time.

#### Scenario: Tenant at agent limit cannot create new agent
- **WHEN** a `free` tier tenant already has 10 agents and calls `POST /api/agents`
- **THEN** the response SHALL be HTTP 429 with an error message indicating the agent limit and a link to upgrade

#### Scenario: Tenant below agent limit can create agents
- **WHEN** a `free` tier tenant has fewer than 10 agents and calls `POST /api/agents`
- **THEN** the request SHALL proceed normally

### Requirement: Tier enforcement can be toggled via feature flag
The system SHALL respect a `TIER_ENFORCEMENT` environment variable (default: `true`). When `TIER_ENFORCEMENT=false`, all tier limit checks SHALL be bypassed and requests SHALL proceed as if on the `enterprise` tier. Rate limit headers SHALL still be present but reflect unlimited limits.

#### Scenario: Tier enforcement disabled allows all requests
- **WHEN** `TIER_ENFORCEMENT=false` and a `free` tier tenant has exceeded their daily limit
- **THEN** the request SHALL succeed with HTTP 200 (no 429 returned)

### Requirement: Tenant can self-service upgrade their tier
The system SHALL expose `POST /api/tiers/upgrade` allowing an authenticated tenant admin to request an upgrade to a higher tier. The endpoint SHALL validate the target tier is higher than the current tier and initiate a Stripe checkout session for the new tier's price. On successful payment webhook, the `tenant_tiers` row SHALL be updated.

#### Scenario: Successful tier upgrade initiation
- **WHEN** a `free` tier tenant calls `POST /api/tiers/upgrade` with `{ "target_tier": "pro" }`
- **THEN** the response SHALL be HTTP 200 with a Stripe checkout URL

#### Scenario: Downgrade attempt is rejected
- **WHEN** a `pro` tier tenant calls `POST /api/tiers/upgrade` with `{ "target_tier": "free" }`
- **THEN** the response SHALL be HTTP 400 with an error indicating downgrades require support

#### Scenario: Stripe webhook updates tier on payment success
- **WHEN** Stripe sends a `checkout.session.completed` event for a tier upgrade
- **THEN** the tenant's `tier` SHALL be updated to the purchased tier within 5 seconds

### Requirement: Tenant can view their current tier and usage
The system SHALL expose `GET /api/tiers/status` returning the tenant's current tier, daily limits, current usage counts (calls today, tokens today, agent count), and time until daily limit reset.

#### Scenario: Tier status returns current usage
- **WHEN** an authenticated tenant admin calls `GET /api/tiers/status`
- **THEN** the response SHALL be HTTP 200 with tier name, limits, and live usage counters