# Region-aware API routing

## Problem

TilliT now serves tenants from regional API gateways. A call that used to hit
`https://{tenant}.tillit.cloud/api/...` must now hit `/eu/api/...` or
`/us/api/...` depending on where the tenant lives. `tllt configure` doesn't ask
for a region, and `apiClient` doesn't inject one, so every CLI call lands on the
wrong path against a region-aware deployment.

## Goal

1. Capture an explicit tenant region (`eu` | `us` | `au`) at `tllt configure` time.
2. Persist it on the connection profile.
3. Prefix every API request with `/{region}` so `prefixUrl` becomes
   `${baseUrl}/{region}/api[...]`.

Region selection is **required for all environments** (prod, stage, sandbox,
dev, enterprise). There is **no default**: the user picks at configure time.
Existing profiles without a region must re-run `tllt configure`.

## Out of scope

- Domain-level changes (e.g. `tillit-us.cloud`). All regions share the existing
  per-environment domains; only the URL path differs.
- Region prefix on static asset paths (`/assets/data/schema`). Those are served
  by the app, not the regional gateway, so `fetchAsset` keeps the current path.
- Migrating existing saved profiles automatically. Migration is manual:
  re-run `tllt configure`, prompted by a clear error from `resolveProfile`.
- Region in the profile name. Tenants only exist in one region per environment,
  so `{tenant}-{environment}` stays collision-free.

## Design

### Profile shape

`lib/config.js` gains:

```js
export const REGIONS = ['eu', 'us', 'au'];
```

A saved profile becomes:

```json
{
  "tenant": "client1",
  "environment": "prod",
  "region": "eu",
  "baseUrl": "https://client1.tillit.cloud",
  "auth": { "method": "basic", "username": "...", "password": "..." }
}
```

`resolveProfile` validates that `region` is set and is one of `REGIONS`. If
missing, it throws:

> Profile "client1-prod" is missing a region. Re-run `tllt configure --profile client1-prod` (or pass `--region eu|us|au`).

Legacy `.env` profiles also lack a region, so they hit the same error and must
be re-bootstrapped via `tllt configure`. That is acceptable — the legacy path
already warns it is deprecated.

### Configure flow

`tllt configure` (alias `init`) gains:

- A new CLI flag: `--region <eu|us>`.
- A new interactive prompt placed immediately after the `environment` prompt:

  ```
  ? Region
    > eu
      us
  ```

- Validation in `canRunNonInteractive` (region must be present) and
  `validateNonInteractive` (region must be in `REGIONS`). In `--json` mode a
  missing or invalid `--region` produces the same hard error pattern as
  `--tenant` / `--environment` today.
- `region` is written to the profile alongside `tenant` / `environment`.

The smoke test (`testConnection`) needs no changes — it goes through
`apiClient`, which now layers the region in.

### API client routing

`lib/client.js` changes the `prefixUrl` line in `apiClient`:

```js
// before
prefixUrl: `${baseUrl}${api.prefix}`,
// after
prefixUrl: `${baseUrl}/${profile.region}${api.prefix}`,
```

So:

- DO → `${baseUrl}/eu/api`
- Scheduler → `${baseUrl}/eu/api/scheduler`

`fetchAsset` is unchanged — assets stay at `${baseUrl}/assets/...`.

`lib/apis.js` is unchanged. The API descriptors stay region-agnostic; the
region is a connection-level concern, layered in at client construction.

## Risks / edge cases

- **Existing CI / scripts**: any pipeline that calls `tllt configure` with
  flags will fail until `--region` is added. Documented in the error message.
- **`--base-url` override**: still respected. If a user passes `--base-url`
  that already contains a region (`https://x.tillit.cloud/eu`), the client
  will double-prefix. Document in `--base-url` help that the override should
  be a host-only URL, no path. Same constraint as today; no new pitfall.
- **Asset assumption**: if the static asset path turns out to live behind the
  regional gateway too, the fix is a one-line change in `fetchAsset` to also
  prepend `/${profile.region}`. Cheap to revisit.

## Touched files

- `lib/config.js` — `REGIONS` export, `resolveProfile` validation.
- `configure.js` — `--region` flag, prompt, validation.
- `lib/client.js` — `apiClient` prefixUrl.
- `tllt.js` — register `--region` on the `configure` command.
- `docs/commands.md`, `docs/authentication.md`, `AGENTS.md` — mention the new
  required flag / prompt.

## Verification

1. `tllt configure --tenant t --environment dev --region eu --auth basic ...`
   succeeds; saved profile has `region: 'eu'`.
2. Same command without `--region` and with `--json` exits non-zero with the
   "required flag" error.
3. Interactive `tllt configure` prompts for region after environment.
4. `tllt import --profile t-dev` hits `${baseUrl}/eu/api/core/sites`
   (verified via a network trace or by inspecting `got` debug logs).
5. Loading a config saved before this change throws the re-configure error.