# Nova Onboarding — Autonomous Request Path (v1.16, REQ-182..184)

The v1.16 milestone implements the **request path** of the autonomous
onboarding flow (D-113). A consumer can submit an onboarding request
without contacting the platform team; the platform generates an
environment binding + (in a future milestone) provisions the AWS resources.

## The 3-step request path

### Step 1 — Submit an onboarding request (P18, REQ-182)

A consumer submits an onboarding request to the Nova platform Lambda:

```bash
# Via the Lambda Function URL (IAM auth):
curl -X POST "$NOVA_LAMBDA_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "onboard_consumer",
    "consumerRepo": "acdl/my-app",
    "requestedEnvironment": "dev",
    "ownerId": "team-x",
    "billingTag": "cost-center-x"
  }'
```

The Lambda validates the payload against
[`schemas/onboarding.schema.json`](../schemas/onboarding.schema.json),
then writes a `pending` row to the `nova-contracts` DynamoDB table
(D-119). No AWS resources are created by this action (D-113).

### Step 2 — Generate an environment binding (P19, REQ-183)

The platform (or the consumer locally) generates an environment binding
file from the request:

```bash
python3 core/onboarding.py --request '{
  "consumerRepo": "acdl/my-app",
  "requestedEnvironment": "qa",
  "ownerId": "team-x",
  "billingTag": "cost-center-x"
}' --out core/environments/qa.json
```

This produces a `<env>.json` from the `dev.json` template, filling in
the `ownerId` + `billingTag` + a description. The `account_id` is a
placeholder (`000000000000`) for the platform team to fill with the real
account. The generated file validates against
[`schemas/environment.schema.json`](../schemas/environment.schema.json).

### Step 3 — Cross-account role + ABAC tag grant (P20, REQ-184)

The platform authors the consumer deploy-role + `nova:owner` ABAC tag
grant via Terraform:

```bash
cd terraform/onboarding
terraform init -backend=false
terraform validate
NOVA_AWS_ACCOUNT_ID=123456789012 terraform plan \
  -var consumer_repo=acdl/my-app \
  -var owner_id=team-x
```

**Offline-proven only (D-114):** `terraform validate` + `terraform plan`
pass; **no live apply** in v1.16. The live apply (creating the real
cross-account role + OIDC trust) is deferred to a future feature
milestone (D-113).

## What is NOT automated (deferred)

- **Real AWS account/network/state provisioning** — the request path
  generates a binding file with a placeholder `account_id`; the actual
  AWS account creation + VPC + state backend is a future feature (D-113).
- **Live cross-account role apply** — the Terraform is offline-proven
  only (D-114); live apply is deferred.
- **OIDC trust policy** — the onboarding Terraform uses a placeholder
  OIDC provider; real OIDC federation is blocked on
  upstream forge OIDC support (carries forward from v1.1).

## See also

- [`schemas/onboarding.schema.json`](../schemas/onboarding.schema.json) — the request schema
- [`core/onboarding.py`](../core/onboarding.py) — the env-file generator
- [`terraform/onboarding/`](../terraform/onboarding/) — the role-grant Terraform
- [`core/environments/README.md`](../core/environments/README.md) — environment binding docs