Address review feedback

Author: thossain-nv

docs/configuration/tenant-management-keycloak.md

@@ -202,11 +202,16 @@ Two `nicocli` flag defaults do not match a `setup.sh` deployment and have to be
 `--keycloak-realm` defaults to `nico-dev` and `--client-id` defaults to `nico-api`, both of
 which are Kustomize dev values.
 
+`--keycloak-url`, `--keycloak-realm`, and `--client-id` are global flags, so they go before
+`login`. Only `--client-secret`, `--username`, and `--password` belong to the subcommand.
+Putting a global flag after `login` fails with `flag provided but not defined`.
+
 ```bash
-nicocli login \
+nicocli \
   --keycloak-url http://keycloak.nico-rest:8082 \
   --keycloak-realm nico \
   --client-id nico-rest \
+  login \
   --client-secret nico-local-secret \
   --username tenant-admin@acme-corp.example
 ```

docs/configuration/tenant_management.md

@@ -100,7 +100,7 @@ $ nicocli tenant current
 | `id` | UUID identifier for the tenant, used in all subsequent API calls |
 | `org` | Organization name (matches your config `api.org`) |
 | `orgDisplayName` | Human-readable name pulled from the IdP's org metadata |
-| `capabilities.targetedInstanceCreation` | **Deprecated, removal scheduled for October 1, 2026.** A read-only aggregate across the tenant's `Ready` tenant accounts, not a setting on the tenant. It is `true` only when every such account enables the capability and no site override disables it, and it is always `false` on embedded `tenantSummary` objects. A Provider Admin configures the capability per tenant account, and optionally per site. See [Granting Targeted Instance Creation](#granting-targeted-instance-creation). |
+| `capabilities.targetedInstanceCreation` | **Deprecated, removal scheduled for October 1, 2026.** A read-only aggregate across the tenant's `Ready` tenant accounts, not a setting on the tenant. It is `true` only when every such account enables the capability and no site override disables it, and it is absent rather than `false` when disabled: the field is omitted, and on the `tenantSummary` objects embedded in other resources `capabilities` is always `{}`. A Provider Admin configures the capability per tenant account, and optionally per site. See [Granting Targeted Instance Creation](#granting-targeted-instance-creation). |
 
 ### Verifying the Tenant
 
@@ -206,7 +206,7 @@ Error: API error 400: Tenant Account status is not Invited
 
 - Create an instance against a specific machine ID, or narrow placement with a machine label selector.
 - Set `isRepairTenant: true` when releasing an instance, which is what the repair tenant workflow requires.
-- Read a set of otherwise provider-only resources, including machines, machine health, SKUs, racks, trays, and expected machines, across the sites of any provider it holds a `Ready` tenant account with.
+- Read a set of otherwise provider-only resources, including machines, machine health, SKUs, racks, trays, and expected machines, at the sites of a provider it holds a `Ready` tenant account with, wherever the capability is effective. A site override that disables it also removes these reads at that site.
 - Receive alternative VPC routing profiles from `tenant/current/routing-profile`.
 
 A Provider Admin configures it per tenant account with the `siteCapabilities` field. This is
@@ -262,8 +262,9 @@ nicocli tenant-account list --tenant-id <tenant-uuid>
 > **Do not read `capabilities.targetedInstanceCreation` from `nicocli tenant current`.** It is
 > a deprecated read-only aggregate, scheduled for removal on **October 1, 2026**. It reports
 > `true` only when every `Ready` tenant account enables the capability and no site override
-> disables it, and it is always `false` on the `tenantSummary` objects embedded in other
-> resources. Use `tenant-account list` instead.
+> disables it, and it is omitted rather than returned as `false` otherwise, so a client cannot
+> branch on a boolean here. On the `tenantSummary` objects embedded in other resources it is
+> always omitted, leaving `"capabilities": {}`. Use `tenant-account list` instead.
 
 ## Instance Types
 

docs/manuals/repair/online_repair.md

@@ -8,7 +8,7 @@ If online repair cannot fix the issue, clear online repair first and then releas
 
 This page is intended for tenant admins and platform operators writing tenant-facing runbooks.
 
-The caller must have access to the Infra Controller REST API through an API profile such as `nico-stg`. The online repair operation is allowed for provider admins and privileged tenant admins. In tenant workflows, this means the tenant must have the required privileged capability for repair operations, such as targeted instance creation access. See [Granting Targeted Instance Creation](../../configuration/tenant_management.md#granting-targeted-instance-creation).
+The caller must have access to the Infra Controller REST API through an API profile such as `nico-stg`. The online repair operation is allowed for provider admins and privileged tenant admins. In tenant workflows, this means the tenant must have the required privileged capability for repair operations, such as effective targeted instance creation at the site. See [Granting Targeted Instance Creation](../../configuration/tenant_management.md#granting-targeted-instance-creation) for what makes it effective.
 
 ## What Online Repair Does
 

docs/manuals/repair/overview.md

@@ -35,7 +35,7 @@ In a multi-Tenant Site, NICo allows certain Tenants to be designated as privileg
 - Update the labels of a Machine to indicate repair related metadata
 - Create a new Instance by specifying a Machine ID
 
-Tenant privileges are described in terms of Capabilities. A Tenant is privileged when its Tenant Account with the Provider is `Ready` and has the `targetedInstanceCreation` capability enabled.
+Tenant privileges are described in terms of Capabilities. A Tenant is privileged at a Site when its Tenant Account with that Site's Provider is `Ready` and `targetedInstanceCreation` is effective there, meaning the account default enables it and no Site override turns it off.
 
 A Provider Admin grants the capability by setting `siteCapabilities` on the Tenant Account, through [`PATCH /v2/org/{org}/nico/tenant/account/{accountId}`](https://docs.nvidia.com/infra-controller/rest-api-reference/api-reference/tenant-account/update-tenant-account). This works for regular Tenants as well as Service Account orgs, and the capability can be set as an account-wide default or overridden per Site. For the payload rules, the per-Site override behavior, and how the effective value resolves, see [Granting Targeted Instance Creation](../../configuration/tenant_management.md#granting-targeted-instance-creation).
 

docs/manuals/repair/release_instance_for_repair.md

@@ -167,7 +167,7 @@ Normal tenants should omit `isRepairTenant` or set it to `false`.
 }
 ```
 
-`isRepairTenant: true` is for repair tenants that are releasing a machine after investigation or repair. It requires the tenant to have the targeted instance creation capability, which a Provider Admin grants on the tenant account; see [Granting Targeted Instance Creation](../../configuration/tenant_management.md#granting-targeted-instance-creation). Do not set this flag for the original tenant's release-for-repair request.
+`isRepairTenant: true` is for repair tenants that are releasing a machine after investigation or repair. It requires effective targeted instance creation for the tenant, which a Provider Admin grants on the tenant account; see [Granting Targeted Instance Creation](../../configuration/tenant_management.md#granting-targeted-instance-creation) for what makes it effective. Do not set this flag for the original tenant's release-for-repair request.
 
 ## After Release
 

docs/manuals/repair/repair_integration.md

@@ -72,7 +72,7 @@ Repair tenants or repair automation use targeted provisioning to claim machines
 - The original tenant releases the instance with `machineHealthIssue`.
 - The repair tenant releases the repair instance after investigation or repair.
 - Repair tenant releases should set `isRepairTenant: true`.
-- `isRepairTenant: true` requires the tenant to have the targeted instance creation capability, granted by a Provider Admin on the tenant account. See [Granting Targeted Instance Creation](../../configuration/tenant_management.md#granting-targeted-instance-creation).
+- `isRepairTenant: true` requires effective targeted instance creation for the tenant, granted by a Provider Admin on the tenant account. See [Granting Targeted Instance Creation](../../configuration/tenant_management.md#granting-targeted-instance-creation) for what makes it effective.
 - The repair tenant should set the machine label `repair_status: InProgress` after claiming the machine, then set the final `repair_status` before releasing the repair instance. This prevents stale completion labels from older repair attempts.
 - A final `repair_status: Completed` with no new issue returns the machine toward the ready pool; failed, incomplete, missing, or unknown status keeps the machine blocked for repair-failed or manual handling.
 

docs/manuals/repair/repair_tenant_workflow.md

@@ -6,7 +6,7 @@ For the original tenant release path, see [Release Instance for Full Repair](rel
 
 ## Audience and Access
 
-The caller needs tenant admin access for the dedicated repair tenant, and the repair tenant must have targeted instance creation enabled. A Provider Admin grants that on the repair tenant's tenant account; see [Granting Targeted Instance Creation](../../configuration/tenant_management.md#granting-targeted-instance-creation). The repair tenant also needs access to the site, VPC, operating system, and network resources used for repair instances.
+The caller needs tenant admin access for the dedicated repair tenant, and the repair tenant must have effective targeted instance creation at the site being repaired. A Provider Admin grants that on the repair tenant's tenant account; see [Granting Targeted Instance Creation](../../configuration/tenant_management.md#granting-targeted-instance-creation) for what makes it effective. The repair tenant also needs access to the site, VPC, operating system, and network resources used for repair instances.
 
 The repair tenant release path uses `isRepairTenant: true`. The REST API only accepts this flag from tenants with targeted instance creation capability.
 
@@ -314,7 +314,7 @@ Provider tooling can also inspect the lower-level health overrides described in
 
 | Error | Meaning | Action |
 |---|---|---|
-| `Tenant does not have capability to create Instances using specific Machine ID` | The repair tenant is missing targeted instance creation, its tenant account is not `Ready`, or a site override disables it. | Have a Provider Admin [grant the capability](../../configuration/tenant_management.md#granting-targeted-instance-creation) on the repair tenant's account, or use the correct repair tenant. |
+| `Tenant does not have capability to create Instances using specific Machine ID` | Targeted instance creation is not effective for the repair tenant at this site: the capability is unset, the tenant account is not `Ready`, or a site override disables it. | Have a Provider Admin [grant the capability](../../configuration/tenant_management.md#granting-targeted-instance-creation) on the repair tenant's account, or use the correct repair tenant. |
 | `Machine is not in Ready state, but it can be provisioned by setting allowUnhealthyMachine to true` | The machine can be targeted for repair but the create request omitted `allowUnhealthyMachine`. | Add `allowUnhealthyMachine: true` and retry. |
 | `Machine is assigned to an Instance` | The machine is still assigned elsewhere. | Confirm the original tenant release completed before claiming the machine. |
 | `Tenant does not have capability to set IsRepairTenant` | The release caller is not a targeted-instance-capable tenant. | Release from the repair tenant or use a properly privileged tenant. |

docs/provisioning/ingesting-hosts-rest-api.md

@@ -8,7 +8,7 @@ Make sure the following are in place before you begin:
 
 1. NICo is deployed and the REST API service is reachable at a known URL.
 1. You have `nicocli` installed (`make nico-cli` from the infra-controller repo) and a working config under `~/.nico/`. For setup, authentication, and config conventions, see the [Quick Start Guide](../getting-started/quick-start.md) and the nicocli reference guide.
-1. You hold the `PROVIDER_ADMIN` role in the org you are operating in. Tenant Admins whose tenant account has [targeted instance creation](../configuration/tenant_management.md#granting-targeted-instance-creation) enabled for the site can also register Expected Machines, but the canonical path is provider-side.
+1. You hold the `PROVIDER_ADMIN` role in the org you are operating in. Tenant Admins with [effective targeted instance creation](../configuration/tenant_management.md#granting-targeted-instance-creation) at the site can also register Expected Machines, but the canonical path is provider-side.
 1. DHCP requests from all managed host BMC networks have been forwarded to the NICo DHCP service.
 1. For every host you plan to register, you have:
    - The MAC address of the host BMC
@@ -28,7 +28,7 @@ nicocli user get
 
 An Expected Machine pre-registers a physical machine so NICo can authenticate to it on discovery and accept it for ingestion. Each Expected Machine carries the factory default BMC credentials NICo uses for first contact, plus identifying information (chassis serial, optional rack/SKU metadata).
 
-The Expected Machine endpoints are scoped per-org per-site. All requests require `PROVIDER_ADMIN`, or `TENANT_ADMIN` with [targeted instance creation](../configuration/tenant_management.md#granting-targeted-instance-creation) in force at that site.
+The Expected Machine endpoints are scoped per-org per-site. All requests require `PROVIDER_ADMIN`, or `TENANT_ADMIN` with [effective targeted instance creation](../configuration/tenant_management.md#granting-targeted-instance-creation) at that site.
 
 ### Single Machine