feat(agentbase): switch default inbound mode to IAM

docs/commands/agentbase/gateway/create.md

@@ -10,14 +10,19 @@ By default the gateway is built from flags (the simple path: no inline targets).
 For targets, outbound auth, JWT inbound auth, or anything nested, use `--file`
 with a template produced by `grn agentbase gateway generate`.
 
+Inbound auth defaults to `IAM` (callers authenticate via the platform IAM);
+pass `--inbound-mode NONE` to open the gateway or `JWT` to validate caller
+JWTs.
+
 The gateway is created asynchronously; this command returns as soon as the
 service accepts the spec (state `WAITING_CREATING`). Converge with
 `grn agentbase gateway wait <name>`.
 
 When `--file` is set it is authoritative and the individual flags below are
 ignored. `--file` (produced by [generate](generate.md)) is the recommended path
 for complex nested configuration (targets / outboundAuth / inboundAuth /
-privateNetwork).
+privateNetwork). A spec that omits `inboundAuth` (or its `mode`) is defaulted
+to `{mode: IAM}`; a `jwt` block without `mode: JWT` is rejected.
 
 ## Synopsis
 
@@ -95,10 +100,13 @@ Replica count. Sealed at create.
 
 **`--inbound-mode`** (string)
 
-Inbound (caller) authentication mode.
+Inbound (caller) authentication mode. Callers authenticate via the platform
+IAM by default; `NONE` opens the gateway, `JWT` validates caller JWTs (the
+`--jwt-*` flags below then build the config).
 
-- Required: Yes (or `--interactive`)
-- Possible values: `NONE`, `IAM`, `JWT`
+- Required: No
+- Default: `IAM`
+- Possible values: `NONE`, `IAM`, `JWT` (case-insensitive)
 
 **`--client-redirect-uri`** (list&lt;string&gt;)
 
@@ -110,52 +118,56 @@ Allowed client redirect URI for DCR/authorize. *(repeatable)*
 **`--iam-require-owner`** (boolean)
 
 IAM mode only: require the caller to own the resource. Only sent when explicitly
-set.
+set; rejected unless `--inbound-mode` is `IAM` (the default).
 
 - Required: No
 - Default: `false`
 
 **`--jwt-source`** (string)
 
-JWT inbound-auth source. Triggers JWT config assembly when set (or when
-`--inbound-mode` is `JWT`).
+JWT inbound-auth source. Only applies when `--inbound-mode` is `JWT` (error
+otherwise); with `JWT` it triggers the JWT config assembly.
 
 - Required: No
 - Possible values: `DISCOVERY`, `JWKS`
 
 **`--jwt-discovery-url`** (string)
 
-JWT OIDC discovery URL (used when `--jwt-source` is `DISCOVERY`).
+JWT OIDC discovery URL (used when `--jwt-source` is `DISCOVERY`). Only applies
+when `--inbound-mode` is `JWT`.
 
 - Required: No
 
 **`--jwt-jwks`** (string)
 
-JWT inline JWKS document (used when `--jwt-source` is `JWKS`).
+JWT inline JWKS document (used when `--jwt-source` is `JWKS`). Only applies
+when `--inbound-mode` is `JWT`.
 
 - Required: No
 
 **`--allowed-audience`** (list&lt;string&gt;)
 
-Allowed JWT audience. *(repeatable)*
+Allowed JWT audience. *(repeatable)* Only applies when `--inbound-mode` is
+`JWT`.
 
 - Required: No
 
 **`--allowed-client`** (list&lt;string&gt;)
 
-Allowed JWT client id. *(repeatable)*
+Allowed JWT client id. *(repeatable)* Only applies when `--inbound-mode` is
+`JWT`.
 
 - Required: No
 
 **`--allowed-scope`** (list&lt;string&gt;)
 
-Allowed JWT scope. *(repeatable)*
+Allowed JWT scope. *(repeatable)* Only applies when `--inbound-mode` is `JWT`.
 
 - Required: No
 
 **`--principal-claim`** (string)
 
-JWT principal claim.
+JWT principal claim. Only applies when `--inbound-mode` is `JWT`.
 
 - Required: No
 - Default: `sub`
@@ -227,15 +239,15 @@ All `grn agentbase` commands accept:
 
 ## Examples
 
-Create a simple PUBLIC gateway from flags:
+Create a simple PUBLIC gateway from flags (inbound auth defaults to `IAM`;
+add `--inbound-mode NONE` to open the gateway):
 
 ```bash
 grn agentbase gateway create \
   --name my-gateway \
   --network-mode PUBLIC \
   --flavor-id fill-flavor-id \
-  --replicas 1 \
-  --inbound-mode NONE
+  --replicas 1
 grn agentbase gateway wait my-gateway
 ```
 

docs/commands/agentbase/gateway/generate.md

@@ -11,7 +11,8 @@ Defaults to YAML (with comments); pass `-o json` for a JSON skeleton.
 
 The template keys are the JSON (camelCase) field names, so the file round-trips
 through `create --file` exactly. Required keys: `name`, `networkMode`,
-`flavorId`, `replicas`, `inboundAuth.mode`. Sealed at create: `name`,
+`flavorId`, `replicas` (`inboundAuth.mode` is optional — omitted it defaults
+to `IAM`; the template ships with `mode: IAM`). Sealed at create: `name`,
 `networkMode`, `flavorId`, `replicas`, and (PRIVATE)
 `privateNetwork.vpcId`/`subnetId`.
 

docs/commands/agentbase/runtime/create.md

@@ -8,7 +8,8 @@ Create a new agent runtime.
 
 By default the runtime is built from flags: `--name` is prompted for when
 missing, `--command`/`--args`/`--env` are repeatable, `--network-mode VPC`
-places the runtime in a VPC, `--inbound-mode IAM|JWT` configures inbound auth,
+places the runtime in a VPC, `--inbound-mode NONE|IAM|JWT` configures inbound
+auth (defaults to `IAM` on `PUBLIC` networks; not available in VPC mode),
 `--allowed-cidrs` restricts inbound CIDRs, and `--protocol MCP` selects the
 MCP protocol. `imageAuth` is required by the API: with no `--image-auth-*`
 flags the CLI sends `{enabled: false}` (public image). Prefer `--file` with a
@@ -20,7 +21,9 @@ service accepts the spec (state `CREATING`). Converge with
 `grn agentbase runtime wait <id>`.
 
 When `--file` is set it is authoritative — every flag below is ignored and the
-file must contain `name`, `imageUrl`, and `flavorId`.
+file must contain `name`, `imageUrl`, and `flavorId`. A spec that omits
+`inboundAuth` is sent with `inboundAuth: {mode: IAM}` unless the spec puts the
+runtime in a VPC (`inboundAuth` is `PUBLIC`-network only).
 
 > **Deprecation:** `--min-replicas` is gone. The platform owns the autoscaling
 > floor (minimum replicas is always 1); only `--max-replicas` is configurable.
@@ -178,7 +181,8 @@ Autoscaling: memory scale-up threshold % (10-90).
 
 - Required: No
 - Default: `PUBLIC`
-- Constraints: `VPC` requires `--vpc-id` and `--subnet-id`.
+- Constraints: `VPC` requires `--vpc-id` and `--subnet-id`; explicitly set but
+  empty is rejected (an empty `$NETWORK_MODE` expansion used to read as unset).
 
 **`--vpc-id`** (string)
 
@@ -213,12 +217,16 @@ traffic on `PUBLIC` networks.
 
 **`--inbound-mode`** (string)
 
-`inboundAuth` mode: `NONE`, `IAM`, or `JWT` (unset = `NONE`).
+`inboundAuth` mode: `NONE`, `IAM`, or `JWT`. `PUBLIC` networks only — the API
+rejects `inboundAuth` on VPC runtimes. Unset = `IAM` on create (callers
+authenticate via the platform IAM); pass `NONE` to open the runtime.
 
 - Required: No
-- Default: (empty = `NONE`)
+- Default: `IAM` on create (when the network is `PUBLIC` or unset)
 - Constraints: `JWT` requires the `--inbound-jwt-*` flags; cannot be combined
-  with them when set to `IAM`/`NONE`.
+  with them when set to `IAM`/`NONE`; not available with `--network-mode VPC`;
+  explicitly set but empty is rejected (an empty `$INBOUND_MODE` expansion
+  used to read as unset and default to `IAM`).
 
 **`--inbound-jwt-source`** (string)
 

docs/commands/agentbase/runtime/generate.md

@@ -10,8 +10,12 @@ and apply with `grn agentbase runtime create --file <file>`.
 The template ships with `imageAuth: {enabled: false}` — the API requires the
 field, and `enabled: false` is the public-image default. For a private
 registry, enable it and fill in `username`/`password` (send-only) or set
-`useAgentBaseRegistryCredentials`. The same file (minus the create-only `poc`,
-keeping `name`) feeds `runtime update --file`.
+`useAgentBaseRegistryCredentials`. The template also includes a live
+`inboundAuth: {mode: IAM}` block — the create-time default on `PUBLIC`
+networks (the field is not available in VPC mode) — so a template-driven
+create or update is explicit about inbound auth instead of relying on the
+default/carry-over. Drop the block only for VPC specs. The same file (minus
+the create-only `poc`, keeping `name`) feeds `runtime update --file`.
 
 Defaults to YAML (with comments); pass `-o json` for a JSON skeleton.
 

docs/commands/agentbase/runtime/update.md

@@ -14,19 +14,35 @@ wholesale (no element-level merge). Set flags only for what you intend to
 change — e.g. a bare `--env K=V` replaces the whole environment map, it does
 not add one key.
 
+An unset `--inbound-mode` carries the current version's inbound auth over,
+and the carried value follows the target network: moving the runtime to `VPC`
+drops it (inbound auth does not apply on a private network; `--inbound-mode`
+is an error there), and opening a `VPC` runtime up to `PUBLIC` defaults it to
+`IAM` — never silently to `NONE` (say `--inbound-mode NONE` to open it
+deliberately). An explicitly-set-but-empty `--inbound-mode` (e.g. an empty
+`$INBOUND_MODE` expansion) is rejected instead of being read as unset.
+
 `imageAuth` is the exception — the API never returns the stored password, so
 username/password image auth cannot be carried over: re-supply
 `--image-auth-username`/`--image-auth-password` (or use `--file` with a full
 spec). Without image auth the update re-sends `{enabled: false}`.
 
 When `--file` is set it is authoritative — every flag below is ignored, and
-the spec is applied as-is. The file must contain `imageUrl` and `flavorId`; a
+the spec is applied as-is except for an omitted `inboundAuth` (see below). The
+file must contain `imageUrl` and `flavorId`; a
 `name` in the file is ignored (the runtime is addressed by the `<id>`
 positional argument and the name is immutable). The file **must include
 `imageAuth` explicitly**: a missing `imageAuth` would silently wipe the stored
 credentials, so it is rejected — `{enabled: false}` drops them deliberately,
 `username`/`password` or `useAgentBaseRegistryCredentials` keeps them.
 
+A spec that omits `inboundAuth` gets the same treatment as an unset
+`--inbound-mode`: the current version's `inboundAuth` is carried over (a
+stderr note names the source version), defaulting to `IAM` when there is
+nothing to carry (`PUBLIC`-network specs only; drop the `inboundAuth` block
+when the spec moves `networkConfig` to `VPC` — `inboundAuth` is
+`PUBLIC`-network only, and the CLI rejects a spec that combines the two).
+
 > **Notes:** `--min-replicas` is gone (the platform owns the autoscaling floor —
 > always 1); only `--max-replicas` is configurable. `--poc` is create-only and
 > cannot be set or cleared on update.
@@ -177,7 +193,8 @@ over; setting any network flag replaces the whole `networkConfig`.
 
 - Required: No (carried over from the current version when unset)
 - Default: (empty = carried over)
-- Constraints: `VPC` requires `--vpc-id` and `--subnet-id`.
+- Constraints: `VPC` requires `--vpc-id` and `--subnet-id`; explicitly set but
+  empty is rejected.
 
 **`--vpc-id`** (string)
 
@@ -212,12 +229,14 @@ Inbound CIDR allowlist (repeatable, max 20).
 **`--inbound-mode`** (string)
 
 `inboundAuth` mode: `NONE`, `IAM`, or `JWT`. Unset = the current version's
-`inboundAuth` is carried over.
+`inboundAuth` is carried over; on a `VPC` target (set or carried) unset drops
+it, and when there is nothing to carry it defaults to `IAM`.
 
 - Required: No (carried over from the current version when unset)
-- Default: (empty = carried over)
+- Default: (empty = carried over; `IAM` when nothing to carry)
 - Constraints: `JWT` requires the `--inbound-jwt-*` flags; cannot be combined
-  with them when set to `IAM`/`NONE`.
+  with them when set to `IAM`/`NONE`; explicitly set but empty is rejected;
+  rejected on a `VPC` target (inbound auth is `PUBLIC`-network only).
 
 **`--inbound-jwt-source`** (string)
 
@@ -283,11 +302,14 @@ Apply a full-spec file (create template minus `name`); authoritative when set.
 
 - Required: No
 - Default: (empty)
-- Constraints: when set, the flags above are ignored; `name` must be present
-  in the file; `imageAuth` must be present in the file (a missing `imageAuth`
+- Constraints: when set, the flags above are ignored; `name` is optional in
+  the file (ignored — the runtime is addressed by the `<id>` positional
+  argument); `imageAuth` must be present in the file (a missing `imageAuth`
   would wipe the stored credentials — set `{enabled: false}` to drop them
   deliberately, or `username`/`password` / `useAgentBaseRegistryCredentials`
-  to keep them).
+  to keep them); an omitted `inboundAuth` is carried over from the current
+  version (defaulted to `IAM` when there is nothing to carry), and a spec that
+  combines `inboundAuth` with a `VPC` `networkConfig` is rejected.
 
 ## Global options