# Veylant IA — Pilot Client Onboarding

Operational in **under one working day**.

## Prerequisites

| Tool | Version | Notes |
|---|---|---|
| `curl` | any | Standard on macOS/Linux |
| `python3` | 3.8+ | JSON parsing in scripts |
| Veylant IA proxy | running | `make dev` or production URL |
| Admin JWT | valid | Issued by Keycloak for the platform admin |

## Scripts

### `onboard-tenant.sh` — Full tenant provisioning

Provisions a new client tenant end-to-end:
1. Checks proxy health
2. Creates the tenant admin user
3. Seeds 4 routing policy templates (HR, Finance, Engineering, Catchall)
4. Configures rate limits
5. Prints a verification summary

```bash
# Make executable (once)
chmod +x onboard-tenant.sh import-users.sh

# Set required variables
export VEYLANT_URL=https://api.veylant.ai
export VEYLANT_ADMIN_TOKEN=<platform-admin-jwt>
export TENANT_ADMIN_EMAIL=admin@client.example

# Optional overrides
export TENANT_ADMIN_FIRST=Marie
export TENANT_ADMIN_LAST=Dupont
export RPM=2000
export BURST=400

./onboard-tenant.sh
```

### `import-users.sh` — Bulk user import from CSV

Imports a list of users from a CSV file. Idempotent — already-existing users (HTTP 409) are skipped without error.

```bash
export VEYLANT_URL=https://api.veylant.ai
export VEYLANT_ADMIN_TOKEN=<admin-jwt>

./import-users.sh sample-users.csv
```

### `sample-users.csv` — Example CSV format

```
email,first_name,last_name,department,role
alice.martin@corp.example,Alice,Martin,HR,user
bob.dupont@corp.example,Bob,Dupont,Finance,user
```

**Roles**: `admin`, `manager`, `user`, `auditor`

## Day-1 Checklist

- [ ] Run `onboard-tenant.sh` to provision the tenant
- [ ] Customize the CSV with real user data
- [ ] Run `import-users.sh` to bulk-import users
- [ ] Issue Keycloak JWTs for each user (via your IdP admin console)
- [ ] Share the [integration guide](../../docs/integration-guide.md) with developers
- [ ] Verify a test request: `curl -X POST $VEYLANT_URL/v1/chat/completions ...`
- [ ] Confirm audit logs appear: `GET /v1/admin/logs`

## Rate Limit Defaults

| Setting | Default | Override via |
|---|---|---|
| Requests/min | 1 000 | `RPM` env var |
| Burst | 200 | `BURST` env var |
| Per-user RPM | 200 | RPM ÷ 5 |
| Per-user burst | 40 | BURST ÷ 5 |

Limits can be adjusted at any time without restart via:
```bash
curl -X PUT $VEYLANT_URL/v1/admin/rate-limits/<tenant_id> \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"requests_per_min": 3000, "burst_size": 600, "is_enabled": true}'
```

## Troubleshooting

| Symptom | Check |
|---|---|
| `VEYLANT_URL` not set | Export the variable and retry |
| HTTP 401 on API calls | JWT may have expired — refresh via Keycloak |
| HTTP 403 | Token role is not `admin` — use the platform admin token |
| User creation fails (HTTP 500) | Check PostgreSQL is running: `make health` |
| PII not working | Ensure PII sidecar is up: `curl http://localhost:8091/healthz` |