@seliseblocks/cli-os 0.2.3 → 0.2.5

package/dist/skills/blocks-iam-mfa/SKILL.md

@@ -1,124 +1,124 @@
----
-name: blocks-iam-mfa
-description: "Self-service MFA for the signed-in user's own account — TOTP enroll/verify, OTP generate/resend/verify, method switch, disable, backup codes — via `blocksClient.mfa.*` or the project-scoped `blocks mfa *` CLI, plus tenant-wide MFA policy admin (`mfa.saveConfig` / `blocks mfa config get/save`). Use for an MFA settings screen, scripted enrollment/checks, or reading/setting a tenant's MFA policy. Not for admin-forcing MFA onto another specific user."
----
-
-# Blocks IAM — MFA (Multi-Factor Authentication)
-
-Two different things live under "MFA," and this skill covers both without conflating them:
-
-1. **Self-service enrollment/verification** — the signed-in user setting up, challenging, switching, or removing MFA on **their own** account. This is `blocksClient.mfa.*` (minus `saveConfig`) in an app, or `blocks mfa totp *` / `mfa generate` / `mfa resend` / `mfa verify` / `mfa method set` / `mfa disable` / `mfa backup-codes *` from a terminal.
-2. **Tenant-wide MFA policy admin** — whether MFA is enabled/required for the tenant at all, which methods are allowed, backup-code settings, and which roles are required/exempt. This is `blocksClient.mfa.config()` / `mfa.saveConfig(request)`, or `blocks mfa config get` / `mfa config save`. It configures the tenant's rules, not any one user's enrollment state.
-
-Source of truth: the `@seliseblocks/client` SDK's `mfa` namespace and the `blocks mfa *` CLI command family — this skill surfaces their documented behavior, it doesn't add new capability.
-
-## Scope: this vs. the other IAM skills
-
-- **This skill** — the signed-in user's own MFA enrollment/verification, and tenant-wide MFA policy configuration (`config`/`saveConfig`).
-- **blocks-iam-account** — the rest of the signed-in user's own account lifecycle (activation, forgot/reset/change password, logout, profile bootstrap, signup). It links here for MFA depth; don't duplicate that material in this file.
-- **blocks-iam-users** — an admin managing *other* users' IAM records (create, deactivate, grant/revoke access). Nothing in the SDK's `mfa` namespace or the CLI's `mfa` command family lets an admin force-enroll, reset, or disable MFA on a specific *other* user's account — the closest thing is tenant-wide, role-based policy (`mfaRequiredRoles`/`mfaExemptRoles` in `saveConfig`), which applies to a role, not a targeted user id. If a caller wants to act on another named user's MFA specifically, that capability wasn't found in this source; don't invent an endpoint for it.
-
-## SDK — `blocksClient.mfa.*`
-
-| Method | What |
-|---|---|
-| `mfa.config()` | Reads the tenant's current MFA policy. Tenant-wide, not per-user. |
-| `mfa.saveConfig(request)` | Saves the tenant's MFA policy (enable/require MFA, allowed methods, backup-code settings, required/exempt roles). Admin/tenant-settings action — IAM enforces the required role, the SDK does not gate it. |
-| `mfa.totp.setup()` | Starts authenticator-app enrollment for the signed-in user; render IAM's returned secret/QR payload in your UI. |
-| `mfa.totp.verifySetup({ code })` | Confirms enrollment with the 6-digit code from the authenticator app. |
-| `mfa.generate({ mfaType, sendPhoneNumberAsEmailDomain? })` | Sends an email/SMS OTP challenge; IAM returns an `mfaId` to pass to `resend`/`verify`. |
-| `mfa.resend({ mfaId, sendPhoneNumberAsEmailDomain? })` | Re-sends a pending OTP (e.g. SMS delay, spam filtering). |
-| `mfa.verify({ mfaId, verificationCode, authType, isFromTokenCall? })` | Confirms an OTP or step-up challenge; set `isFromTokenCall` when verifying as part of a login/token exchange rather than a standalone check. |
-| `mfa.setMethod({ mfaType })` | Switches which enrolled method is active for a user with more than one enrolled. |
-| `mfa.disable()` | Self-service opt-out for the signed-in user, where the tenant's policy allows it. |
-| `mfa.backupCodes.list()` | Lists the signed-in user's backup codes (e.g. remaining-count display). |
-| `mfa.backupCodes.generate()` | Mints a fresh set of recovery codes. Treat the response as sensitive and show it to the user only once. |
-| `mfa.backupCodes.use({ code, userId })` | Consumes one backup code to complete login/step-up when the primary method is unavailable. `userId` is the signed-in user's own id, not a target for an admin acting on someone else. |
-
-```ts
-// enrollment
-await blocksClient.mfa.totp.setup();          // render the returned secret/QR
-await blocksClient.mfa.totp.verifySetup({ code });
-
-// OTP challenge (email/SMS-based methods)
-const { mfaId } = await blocksClient.mfa.generate({ mfaType });
-await blocksClient.mfa.verify({ mfaId, verificationCode, authType });
-
-// tenant policy (admin screen only)
-const policy = await blocksClient.mfa.config();
-await blocksClient.mfa.saveConfig({ enableMfa: true, requireMfaForAllUsers: false });
-```
-
-`mfaType` and `authType` are plain numbers defined by IAM's own contract, treated as opaque by both the SDK and CLI — their enum names aren't published anywhere. Neither documents what integer means "TOTP" vs. "SMS" vs. "email" for a given tenant; confirm the value against the tenant's actual IAM config (`mfa.config()` / `blocks mfa config get`) rather than guessing one.
-
-## CLI — `blocks mfa *`
-
-Every `mfa` command is **project-scoped**: it requires a project already selected (`blocks use <tenantId>`) and calls IAM with an impersonated project token — never the account token. Command segments joined by a space also accept a colon form (`mfa:totp:setup`, `mfa:backup-codes:generate`, etc.) — both resolve to the same command.
-
-Tenant policy admin (reads/mutates the tenant's rules, not a user's enrollment):
-
-| Command | What |
-|---|---|
-| `blocks mfa config get [--json]` | Reads the tenant's MFA policy. |
-| `blocks mfa config save [--enable] [--require-for-all-users] [--allow-user-opt-out] [--allow-backup-codes] [--backup-codes-count <n>] [--user-mfa-type 0,1] [--required-roles a,b] [--exempt-roles a,b] [--body '<json>'\|--file <path>] [--dry-run] [--yes] [--json]` | Saves the tenant's MFA policy. `--body`/`--file` supplies a base JSON payload; any convenience flag also passed overwrites the matching key on top of it. Requires `--dry-run` (preview only) or `--yes`/an interactive `yes` before it executes. |
-
-Self-service enrollment, challenge, and recovery for the calling (impersonated) user:
-
-| Command | What |
-|---|---|
-| `blocks mfa totp setup [--json]` | Starts TOTP enrollment; prints IAM's secret/QR payload. |
-| `blocks mfa totp verify-setup <code> [--json]` | Confirms TOTP enrollment with the 6-digit code. |
-| `blocks mfa totp enable --mfa-type <n> [--code <c>] [--dry-run] [--yes] [--json]` | Composed enrollment — see below. |
-| `blocks mfa generate --mfa-type <n> [--send-phone-number-as-email-domain <domain>] [--json]` | Sends an OTP challenge; returns an `mfaId` to pass to `resend`/`verify`. |
-| `blocks mfa resend <mfaId> [--send-phone-number-as-email-domain <domain>] [--json]` | Re-sends a pending OTP. |
-| `blocks mfa verify <mfaId> <code> --auth-type <n> [--from-token-call] [--json]` | Confirms an OTP/step-up challenge. |
-| `blocks mfa method set --mfa-type <n> [--json]` | Switches the impersonated user's active MFA method. |
-| `blocks mfa disable [--dry-run] [--yes] [--json]` | Disables MFA for the impersonated user. Mutating: needs `--dry-run` or `--yes`. |
-| `blocks mfa backup-codes list [--json]` | Lists the impersonated user's backup codes. Read-only. |
-| `blocks mfa backup-codes generate [--dry-run] [--yes] [--json]` | Generates a fresh set, invalidating existing ones. Mutating: needs `--dry-run` or `--yes`. |
-| `blocks mfa backup-codes use <userId> <code> [--json]` | Consumes one backup code. |
-
-```sh
-blocks mfa config get --json                        # check tenant policy before prompting enrollment
-blocks mfa totp setup                               # prints secret/QR
-blocks mfa totp verify-setup 123456
-blocks mfa method set --mfa-type 0
-blocks mfa backup-codes generate --dry-run           # preview, no call
-blocks mfa backup-codes generate --yes               # after explicit confirmation
-```
-
-## The composed `mfa totp enable` command
-
-`mfa totp enable --mfa-type <n>` chains the individual TOTP steps into one enrollment sitting, with one confirmation, rather than four separate commands run at different times:
-
-`totp setup` → prints the QR/secret → **verification code** (from `--code`, or an interactive prompt if omitted) → `totp verify-setup <code>` → `method set --mfa-type <n>` → `backup-codes generate --yes`.
-
-Two things worth calling out precisely, both confirmed against source:
-
-- **`--mfa-type` is required, never defaulted.** The numeric value that means "TOTP" for a given tenant isn't documented anywhere in this CLI or SDK (the same opaque-integer caveat as `mfa generate`/`method set` above) — the command throws rather than guessing one. Look it up (e.g. via `mfa config get`, or ask the user) instead of assuming a value like `0`.
-- **Two separate prompts can block a non-interactive run**, not just one: the command asks the operator to type `yes` before it starts (skipped by `--yes`, same as `--dry-run`), and then, independently, if `--code` isn't passed, it prompts for the verification code from stdin with no timeout — in a non-interactive/agent context with no TTY to answer it, this hangs indefinitely rather than failing fast. An agent or script running this command must pass **both** `--yes` and `--code <c>` (the code sourced from wherever the authenticator output is captured) to avoid a hang.
-- `--dry-run` short-circuits before either prompt and before any network call: it prints the planned step list (`mfa:totp:setup`, the scan/enter-code step, `mfa:totp:verify-setup <code>`, `mfa:method:set <n>`, `mfa:backup-codes:generate`) and exits.
-
-Deliberately excluded from this composed command: `mfa config save`. That's the separate tenant-wide policy action covered above, not part of enrolling one user.
-
-## Gotchas
-
-- **`config`/`saveConfig` (SDK) and `mfa config get`/`config save` (CLI) are tenant policy, not a user's enrollment state.** Don't call these expecting to see or change one user's MFA status — that's every other method/command in this file.
-- **`mfaType`/`authType` are opaque, tenant-defined integers.** Neither the SDK's types nor the CLI documents what number means "TOTP," "SMS," or "email" — confirm against the tenant's own IAM config rather than guessing.
-- **`mfa totp enable` can hang waiting on stdin twice over** if run non-interactively without `--yes` and `--code` — see above. Always pass both when scripting or agent-driving this command.
-- **Backup codes are shown once.** Treat `backupCodes.generate()` / `mfa backup-codes generate`'s response as sensitive; there's no re-display endpoint for the raw codes, only `list()`/`backup-codes list`, which is for a remaining-count style view, not for recovering codes you didn't save.
-- **No admin "force MFA on this specific user" capability was found in this source.** The nearest thing is tenant-wide, role-based policy (`mfaRequiredRoles`/`mfaExemptRoles` via `saveConfig`/`config save`), which targets a role, not a user id. If a request needs a specific other user's MFA changed, that's out of this skill's scope — don't fabricate an endpoint to satisfy it.
-- **Every `mfa` CLI command is project-scoped and impersonation-only**, same rule as the rest of the project-scoped CLI surface — `blocks use <tenantId>` first, or commands fail with `project_not_selected`.
-- **Mutating CLI commands (`config save`, `disable`, `backup-codes generate`, and the composed `totp enable`) require `--dry-run` or `--yes`/an interactive `yes`** before they execute — apply the same confirm-before-mutating discipline an agent uses for any other mutating Blocks CLI command: state the exact change and get explicit go-ahead first.
-
-## Example trigger prompts
-
-- "Let a signed-in user enroll in authenticator-app (TOTP) MFA."
-- "Build the MFA settings screen: enroll, switch method, disable, view backup codes."
-- "Check whether this tenant requires MFA before showing the enrollment prompt."
-- "Turn on MFA for the whole tenant and require it for the admin role."
-- "Send an OTP code to the user and verify what they typed."
-- "Let a user regenerate their MFA backup codes."
-- "From the terminal, enroll the current project's impersonated user in TOTP MFA end to end."
-- "Run TOTP enrollment non-interactively from a script" → pass both `--yes` and `--code <c>` to `blocks mfa totp enable`, never run it unattended without them.
-- "Read the tenant's current MFA policy from the CLI."
+---
+name: blocks-iam-mfa
+description: "Self-service MFA for the signed-in user's own account — TOTP enroll/verify, OTP generate/resend/verify, method switch, disable, backup codes — via `blocksClient.mfa.*` or the project-scoped `blocks mfa *` CLI, plus tenant-wide MFA policy admin (`mfa.saveConfig` / `blocks mfa config get/save`). Use for an MFA settings screen, scripted enrollment/checks, or reading/setting a tenant's MFA policy. Not for admin-forcing MFA onto another specific user."
+---
+
+# Blocks IAM — MFA (Multi-Factor Authentication)
+
+Two different things live under "MFA," and this skill covers both without conflating them:
+
+1. **Self-service enrollment/verification** — the signed-in user setting up, challenging, switching, or removing MFA on **their own** account. This is `blocksClient.mfa.*` (minus `saveConfig`) in an app, or `blocks mfa totp *` / `mfa generate` / `mfa resend` / `mfa verify` / `mfa method set` / `mfa disable` / `mfa backup-codes *` from a terminal.
+2. **Tenant-wide MFA policy admin** — whether MFA is enabled/required for the tenant at all, which methods are allowed, backup-code settings, and which roles are required/exempt. This is `blocksClient.mfa.config()` / `mfa.saveConfig(request)`, or `blocks mfa config get` / `mfa config save`. It configures the tenant's rules, not any one user's enrollment state.
+
+Source of truth: the `@seliseblocks/client` SDK's `mfa` namespace and the `blocks mfa *` CLI command family — this skill surfaces their documented behavior, it doesn't add new capability.
+
+## Scope: this vs. the other IAM skills
+
+- **This skill** — the signed-in user's own MFA enrollment/verification, and tenant-wide MFA policy configuration (`config`/`saveConfig`).
+- **blocks-iam-account** — the rest of the signed-in user's own account lifecycle (activation, forgot/reset/change password, logout, profile bootstrap, signup). It links here for MFA depth; don't duplicate that material in this file.
+- **blocks-iam-users** — an admin managing *other* users' IAM records (create, deactivate, grant/revoke access). Nothing in the SDK's `mfa` namespace or the CLI's `mfa` command family lets an admin force-enroll, reset, or disable MFA on a specific *other* user's account — the closest thing is tenant-wide, role-based policy (`mfaRequiredRoles`/`mfaExemptRoles` in `saveConfig`), which applies to a role, not a targeted user id. If a caller wants to act on another named user's MFA specifically, that capability wasn't found in this source; don't invent an endpoint for it.
+
+## SDK — `blocksClient.mfa.*`
+
+| Method | What |
+|---|---|
+| `mfa.config()` | Reads the tenant's current MFA policy. Tenant-wide, not per-user. |
+| `mfa.saveConfig(request)` | Saves the tenant's MFA policy (enable/require MFA, allowed methods, backup-code settings, required/exempt roles). Admin/tenant-settings action — IAM enforces the required role, the SDK does not gate it. |
+| `mfa.totp.setup()` | Starts authenticator-app enrollment for the signed-in user; render IAM's returned secret/QR payload in your UI. |
+| `mfa.totp.verifySetup({ code })` | Confirms enrollment with the 6-digit code from the authenticator app. |
+| `mfa.generate({ mfaType, sendPhoneNumberAsEmailDomain? })` | Sends an email/SMS OTP challenge; IAM returns an `mfaId` to pass to `resend`/`verify`. |
+| `mfa.resend({ mfaId, sendPhoneNumberAsEmailDomain? })` | Re-sends a pending OTP (e.g. SMS delay, spam filtering). |
+| `mfa.verify({ mfaId, verificationCode, authType, isFromTokenCall? })` | Confirms an OTP or step-up challenge; set `isFromTokenCall` when verifying as part of a login/token exchange rather than a standalone check. |
+| `mfa.setMethod({ mfaType })` | Switches which enrolled method is active for a user with more than one enrolled. |
+| `mfa.disable()` | Self-service opt-out for the signed-in user, where the tenant's policy allows it. |
+| `mfa.backupCodes.list()` | Lists the signed-in user's backup codes (e.g. remaining-count display). |
+| `mfa.backupCodes.generate()` | Mints a fresh set of recovery codes. Treat the response as sensitive and show it to the user only once. |
+| `mfa.backupCodes.use({ code, userId })` | Consumes one backup code to complete login/step-up when the primary method is unavailable. `userId` is the signed-in user's own id, not a target for an admin acting on someone else. |
+
+```ts
+// enrollment
+await blocksClient.mfa.totp.setup();          // render the returned secret/QR
+await blocksClient.mfa.totp.verifySetup({ code });
+
+// OTP challenge (email/SMS-based methods)
+const { mfaId } = await blocksClient.mfa.generate({ mfaType });
+await blocksClient.mfa.verify({ mfaId, verificationCode, authType });
+
+// tenant policy (admin screen only)
+const policy = await blocksClient.mfa.config();
+await blocksClient.mfa.saveConfig({ enableMfa: true, requireMfaForAllUsers: false });
+```
+
+`mfaType` and `authType` are plain numbers defined by IAM's own contract, treated as opaque by both the SDK and CLI — their enum names aren't published anywhere. Neither documents what integer means "TOTP" vs. "SMS" vs. "email" for a given tenant; confirm the value against the tenant's actual IAM config (`mfa.config()` / `blocks mfa config get`) rather than guessing one.
+
+## CLI — `blocks mfa *`
+
+Every `mfa` command is **project-scoped**: it requires a project already selected (`blocks use <tenantId>`) and calls IAM with an impersonated project token — never the account token. Command segments joined by a space also accept a colon form (`mfa:totp:setup`, `mfa:backup-codes:generate`, etc.) — both resolve to the same command.
+
+Tenant policy admin (reads/mutates the tenant's rules, not a user's enrollment):
+
+| Command | What |
+|---|---|
+| `blocks mfa config get [--json]` | Reads the tenant's MFA policy. |
+| `blocks mfa config save [--enable] [--require-for-all-users] [--allow-user-opt-out] [--allow-backup-codes] [--backup-codes-count <n>] [--user-mfa-type 0,1] [--required-roles a,b] [--exempt-roles a,b] [--body '<json>'\|--file <path>] [--dry-run] [--yes] [--json]` | Saves the tenant's MFA policy. `--body`/`--file` supplies a base JSON payload; any convenience flag also passed overwrites the matching key on top of it. Requires `--dry-run` (preview only) or `--yes`/an interactive `yes` before it executes. |
+
+Self-service enrollment, challenge, and recovery for the calling (impersonated) user:
+
+| Command | What |
+|---|---|
+| `blocks mfa totp setup [--json]` | Starts TOTP enrollment; prints IAM's secret/QR payload. |
+| `blocks mfa totp verify-setup <code> [--json]` | Confirms TOTP enrollment with the 6-digit code. |
+| `blocks mfa totp enable --mfa-type <n> [--code <c>] [--dry-run] [--yes] [--json]` | Composed enrollment — see below. |
+| `blocks mfa generate --mfa-type <n> [--send-phone-number-as-email-domain <domain>] [--json]` | Sends an OTP challenge; returns an `mfaId` to pass to `resend`/`verify`. |
+| `blocks mfa resend <mfaId> [--send-phone-number-as-email-domain <domain>] [--json]` | Re-sends a pending OTP. |
+| `blocks mfa verify <mfaId> <code> --auth-type <n> [--from-token-call] [--json]` | Confirms an OTP/step-up challenge. |
+| `blocks mfa method set --mfa-type <n> [--json]` | Switches the impersonated user's active MFA method. |
+| `blocks mfa disable [--dry-run] [--yes] [--json]` | Disables MFA for the impersonated user. Mutating: needs `--dry-run` or `--yes`. |
+| `blocks mfa backup-codes list [--json]` | Lists the impersonated user's backup codes. Read-only. |
+| `blocks mfa backup-codes generate [--dry-run] [--yes] [--json]` | Generates a fresh set, invalidating existing ones. Mutating: needs `--dry-run` or `--yes`. |
+| `blocks mfa backup-codes use <userId> <code> [--json]` | Consumes one backup code. |
+
+```sh
+blocks mfa config get --json                        # check tenant policy before prompting enrollment
+blocks mfa totp setup                               # prints secret/QR
+blocks mfa totp verify-setup 123456
+blocks mfa method set --mfa-type 0
+blocks mfa backup-codes generate --dry-run           # preview, no call
+blocks mfa backup-codes generate --yes               # after explicit confirmation
+```
+
+## The composed `mfa totp enable` command
+
+`mfa totp enable --mfa-type <n>` chains the individual TOTP steps into one enrollment sitting, with one confirmation, rather than four separate commands run at different times:
+
+`totp setup` → prints the QR/secret → **verification code** (from `--code`, or an interactive prompt if omitted) → `totp verify-setup <code>` → `method set --mfa-type <n>` → `backup-codes generate --yes`.
+
+Two things worth calling out precisely, both confirmed against source:
+
+- **`--mfa-type` is required, never defaulted.** The numeric value that means "TOTP" for a given tenant isn't documented anywhere in this CLI or SDK (the same opaque-integer caveat as `mfa generate`/`method set` above) — the command throws rather than guessing one. Look it up (e.g. via `mfa config get`, or ask the user) instead of assuming a value like `0`.
+- **Two separate prompts can block a non-interactive run**, not just one: the command asks the operator to type `yes` before it starts (skipped by `--yes`, same as `--dry-run`), and then, independently, if `--code` isn't passed, it prompts for the verification code from stdin with no timeout — in a non-interactive/agent context with no TTY to answer it, this hangs indefinitely rather than failing fast. An agent or script running this command must pass **both** `--yes` and `--code <c>` (the code sourced from wherever the authenticator output is captured) to avoid a hang.
+- `--dry-run` short-circuits before either prompt and before any network call: it prints the planned step list (`mfa:totp:setup`, the scan/enter-code step, `mfa:totp:verify-setup <code>`, `mfa:method:set <n>`, `mfa:backup-codes:generate`) and exits.
+
+Deliberately excluded from this composed command: `mfa config save`. That's the separate tenant-wide policy action covered above, not part of enrolling one user.
+
+## Gotchas
+
+- **`config`/`saveConfig` (SDK) and `mfa config get`/`config save` (CLI) are tenant policy, not a user's enrollment state.** Don't call these expecting to see or change one user's MFA status — that's every other method/command in this file.
+- **`mfaType`/`authType` are opaque, tenant-defined integers.** Neither the SDK's types nor the CLI documents what number means "TOTP," "SMS," or "email" — confirm against the tenant's own IAM config rather than guessing.
+- **`mfa totp enable` can hang waiting on stdin twice over** if run non-interactively without `--yes` and `--code` — see above. Always pass both when scripting or agent-driving this command.
+- **Backup codes are shown once.** Treat `backupCodes.generate()` / `mfa backup-codes generate`'s response as sensitive; there's no re-display endpoint for the raw codes, only `list()`/`backup-codes list`, which is for a remaining-count style view, not for recovering codes you didn't save.
+- **No admin "force MFA on this specific user" capability was found in this source.** The nearest thing is tenant-wide, role-based policy (`mfaRequiredRoles`/`mfaExemptRoles` via `saveConfig`/`config save`), which targets a role, not a user id. If a request needs a specific other user's MFA changed, that's out of this skill's scope — don't fabricate an endpoint to satisfy it.
+- **Every `mfa` CLI command is project-scoped and impersonation-only**, same rule as the rest of the project-scoped CLI surface — `blocks use <tenantId>` first, or commands fail with `project_not_selected`.
+- **Mutating CLI commands (`config save`, `disable`, `backup-codes generate`, and the composed `totp enable`) require `--dry-run` or `--yes`/an interactive `yes`** before they execute — apply the same confirm-before-mutating discipline an agent uses for any other mutating Blocks CLI command: state the exact change and get explicit go-ahead first.
+
+## Example trigger prompts
+
+- "Let a signed-in user enroll in authenticator-app (TOTP) MFA."
+- "Build the MFA settings screen: enroll, switch method, disable, view backup codes."
+- "Check whether this tenant requires MFA before showing the enrollment prompt."
+- "Turn on MFA for the whole tenant and require it for the admin role."
+- "Send an OTP code to the user and verify what they typed."
+- "Let a user regenerate their MFA backup codes."
+- "From the terminal, enroll the current project's impersonated user in TOTP MFA end to end."
+- "Run TOTP enrollment non-interactively from a script" → pass both `--yes` and `--code <c>` to `blocks mfa totp enable`, never run it unattended without them.
+- "Read the tenant's current MFA policy from the CLI."

package/dist/skills/blocks-iam-organizations/SKILL.md

@@ -1,43 +1,43 @@
----
-name: blocks-iam-organizations
-description: "Work with organizations (multi-tenant workspaces) via `iam.organizations`/`iam.signupSettings`/`auth.switchOrganization` (SDK, in-app) or `blocks iam organizations *`/`iam signup-settings *` (CLI, project-scoped, `--dry-run`→`--yes`) — never raw fetch/curl. Covers the org switcher, switching active org context (SDK/app-only, no CLI equivalent), public signup policy, and — human-confirmed only — creating/editing organizations and org/signup config. Use for 'org switcher', 'switch organization', 'multi-org', 'create/update an organization', 'organization settings', 'signup settings'. Users/roles within an org are blocks-iam-users/blocks-iam-access-control; SSO/OIDC client setup is blocks-onboarding, portal-optional now."
----
-
-# Blocks IAM — Organizations
-
-Organizations are the tenancy/workspace unit inside a Blocks project. Two equally real surfaces exist for managing them:
-
-- **Inside a Blocks app** — `@seliseblocks/client` SDK calls from app code (`blocksClient` in `src/lib/blocks/client.ts`, from `blocks new web`). Never write raw `fetch`/`curl` against Blocks APIs.
-- **Outside an app UI** — scripting, one-off inspection, CI, an ops task — the `blocks` CLI has a real, project-scoped command surface for the same operations: `blocks iam organizations list/get/create/update/my/config get/config save` and `blocks iam signup-settings get/save`.
-
-The one thing neither surface papers over as a gap is `auth.switchOrganization` — there is no `blocks iam organizations switch` or similar; switching the *active session's* org context only makes sense from inside the app that owns that session, so it stays SDK-only.
-
-**Prerequisite:** the app is a `blocks new web` scaffold with a project selected. If auth/project state is unknown, run the blocks-onboarding skill first.
-
-## The platform boundary — read this before writing any admin-CRUD call
-
-Full organization management (create, update, config, signup-settings) **is** exposed today, on both surfaces above. What's restricted isn't the surface but *who authorizes a mutation and when* — organizations are a tenant-isolation boundary, so creating or reconfiguring them carries the same "human explicitly directs this specific change" discipline as the portal-only OIDC provisioning in blocks-onboarding, just enforced on two different mechanisms (SDK call vs. CLI command) instead of one.
-
-Concretely: **before wiring up or invoking any `create`/`update`/`saveConfig`/`save` call — SDK or CLI — restate the exact change back to the user in plain terms (which organization, which fields, old value vs. new value) and get an explicit go-ahead.** Never something an agent calls on its own initiative, in an unattended script, or as a side effect of some other task.
-
-## Two flows
-
-- **[flows/read-and-switch.md](flows/read-and-switch.md)** — the org switcher (`organizations.my`), switching active org context (`auth.switchOrganization`, SDK-only), and public signup policy (`signupSettings.get`). Safe, no special caveat.
-- **[flows/admin-mutations.md](flows/admin-mutations.md)** — creating/editing organizations, org-level config, and signup policy, on both the SDK and CLI surfaces, including the full CLI command reference. Sensitive — human-confirmed only.
-
-## Gotchas
-
-- **The CLI has real organization/signup-settings commands** — don't tell a user there's no `blocks` command for organizations.
-- **The one genuine gap is `switchOrganization`** — SDK/app-only, no CLI equivalent, don't invent one.
-- **Confirm the payload, not just the intent**, before any mutating call — SDK or CLI. See [flows/admin-mutations.md](flows/admin-mutations.md) for the full discipline.
-- **Multi-org must be enabled** (`isMultiOrgEnabled`) for switching orgs to be meaningful — check this first if a user reports "switching doesn't do anything."
-
-## Example trigger prompts
-
-- "Add an org switcher to the sidebar using the current user's organizations." → read-and-switch
-- "Let a multi-org user switch which organization they're working in." → read-and-switch
-- "Show the tenant's signup policy on our public signup page." → read-and-switch
-- "Build an admin screen to create a new organization." → admin-mutations (confirm the fields with the user before calling `create`)
-- "Turn on multi-org for this project." → admin-mutations (read `getConfig`/`config get` first, confirm the change, then save)
-- "Is there a `blocks` command to list organizations?" → yes, `blocks iam organizations list` (project-scoped, requires `blocks use <tenantId>` first); use the SDK instead only when the ask is a feature inside the app itself.
-- "Is there a CLI way to switch which organization I'm working in?" → no, that's the one gap — `auth.switchOrganization` is SDK/app-only since it mutates the calling session's own tokens.
+---
+name: blocks-iam-organizations
+description: "Work with organizations (multi-tenant workspaces) via `iam.organizations`/`iam.signupSettings`/`auth.switchOrganization` (SDK, in-app) or `blocks iam organizations *`/`iam signup-settings *` (CLI, project-scoped, `--dry-run`→`--yes`) — never raw fetch/curl. Covers the org switcher, switching active org context (SDK/app-only, no CLI equivalent), public signup policy, and — human-confirmed only — creating/editing organizations and org/signup config. Use for 'org switcher', 'switch organization', 'multi-org', 'create/update an organization', 'organization settings', 'signup settings'. Users/roles within an org are blocks-iam-users/blocks-iam-access-control; SSO/OIDC client setup is blocks-onboarding, portal-optional now."
+---
+
+# Blocks IAM — Organizations
+
+Organizations are the tenancy/workspace unit inside a Blocks project. Two equally real surfaces exist for managing them:
+
+- **Inside a Blocks app** — `@seliseblocks/client` SDK calls from app code (`blocksClient` in `src/lib/blocks/client.ts`, from `blocks new web`). Never write raw `fetch`/`curl` against Blocks APIs.
+- **Outside an app UI** — scripting, one-off inspection, CI, an ops task — the `blocks` CLI has a real, project-scoped command surface for the same operations: `blocks iam organizations list/get/create/update/my/config get/config save` and `blocks iam signup-settings get/save`.
+
+The one thing neither surface papers over as a gap is `auth.switchOrganization` — there is no `blocks iam organizations switch` or similar; switching the *active session's* org context only makes sense from inside the app that owns that session, so it stays SDK-only.
+
+**Prerequisite:** the app is a `blocks new web` scaffold with a project selected. If auth/project state is unknown, run the blocks-onboarding skill first.
+
+## The platform boundary — read this before writing any admin-CRUD call
+
+Full organization management (create, update, config, signup-settings) **is** exposed today, on both surfaces above. What's restricted isn't the surface but *who authorizes a mutation and when* — organizations are a tenant-isolation boundary, so creating or reconfiguring them carries the same "human explicitly directs this specific change" discipline as the portal-only OIDC provisioning in blocks-onboarding, just enforced on two different mechanisms (SDK call vs. CLI command) instead of one.
+
+Concretely: **before wiring up or invoking any `create`/`update`/`saveConfig`/`save` call — SDK or CLI — restate the exact change back to the user in plain terms (which organization, which fields, old value vs. new value) and get an explicit go-ahead.** Never something an agent calls on its own initiative, in an unattended script, or as a side effect of some other task.
+
+## Two flows
+
+- **[flows/read-and-switch.md](flows/read-and-switch.md)** — the org switcher (`organizations.my`), switching active org context (`auth.switchOrganization`, SDK-only), and public signup policy (`signupSettings.get`). Safe, no special caveat.
+- **[flows/admin-mutations.md](flows/admin-mutations.md)** — creating/editing organizations, org-level config, and signup policy, on both the SDK and CLI surfaces, including the full CLI command reference. Sensitive — human-confirmed only.
+
+## Gotchas
+
+- **The CLI has real organization/signup-settings commands** — don't tell a user there's no `blocks` command for organizations.
+- **The one genuine gap is `switchOrganization`** — SDK/app-only, no CLI equivalent, don't invent one.
+- **Confirm the payload, not just the intent**, before any mutating call — SDK or CLI. See [flows/admin-mutations.md](flows/admin-mutations.md) for the full discipline.
+- **Multi-org must be enabled** (`isMultiOrgEnabled`) for switching orgs to be meaningful — check this first if a user reports "switching doesn't do anything."
+
+## Example trigger prompts
+
+- "Add an org switcher to the sidebar using the current user's organizations." → read-and-switch
+- "Let a multi-org user switch which organization they're working in." → read-and-switch
+- "Show the tenant's signup policy on our public signup page." → read-and-switch
+- "Build an admin screen to create a new organization." → admin-mutations (confirm the fields with the user before calling `create`)
+- "Turn on multi-org for this project." → admin-mutations (read `getConfig`/`config get` first, confirm the change, then save)
+- "Is there a `blocks` command to list organizations?" → yes, `blocks iam organizations list` (project-scoped, requires `blocks use <tenantId>` first); use the SDK instead only when the ask is a feature inside the app itself.
+- "Is there a CLI way to switch which organization I'm working in?" → no, that's the one gap — `auth.switchOrganization` is SDK/app-only since it mutates the calling session's own tokens.

package/dist/skills/blocks-iam-organizations/flows/admin-mutations.md

@@ -1,89 +1,89 @@
-# Flow: Admin-CRUD surface — confirm the exact change first
-
-These mutate tenant-level state. Build them as an explicit feature in an admin settings screen (SDK), or run them as an operator from a terminal with a reviewed `--dry-run` (CLI). Both surfaces exist and are equally real — see "The platform boundary" in [SKILL.md](../SKILL.md).
-
-## SDK methods
-
-### `organizations.list(query)` / `organizations.get(id)` — browse and inspect
-
-Read-only, so no confirmation is needed to call them — but they're part of the admin org-management surface (browsing arbitrary orgs, not just "my own"), so gate the screen itself behind whatever admin permission the app already checks. Typical use: an org-picker/detail view feeding into an edit form, populated before a `create`/`update` call.
-
-```ts
-const page = await blocksClient.iam.organizations.list({ Page: 1, PageSize: 20, "Filter.Name": search });
-const org = await blocksClient.iam.organizations.get(organizationId);
-```
-
-### `organizations.create(request)` / `organizations.update(id, request)`
-
-Create/edit an organization's record (name, description, contact info, branding, addresses, default roles/permissions for new members, etc. — verify current field names against what the admin UI/API actually accepts rather than assuming they haven't changed).
-
-```ts
-// Only after the admin has reviewed and confirmed this exact payload:
-await blocksClient.iam.organizations.create({
-  name: "Acme Logistics",
-  description: "Acme's logistics division workspace"
-  // ...remaining fields the user confirmed
-});
-
-await blocksClient.iam.organizations.update(organizationId, {
-  name: "Acme Logistics (Renamed)"
-  // ...only the fields the user asked to change
-});
-```
-
-### `organizations.getConfig()` / `organizations.saveConfig(request)` — org-level settings
-
-Project/org-wide policy, including multi-org enablement. Read the current config first, show the user the diff of what would change, then save.
-
-```ts
-const current = await blocksClient.iam.organizations.getConfig();
-// ...user reviews current vs. proposed, confirms...
-await blocksClient.iam.organizations.saveConfig({
-  ...current,
-  isMultiOrgEnabled: true
-});
-```
-
-### `signupSettings.save(request)` — save signup policy
-
-Same confirm-first rule: this changes what the public signup screen allows for every future visitor, so restate the exact policy change (e.g., "turn on org creation from signup") before calling.
-
-```ts
-await blocksClient.iam.signupSettings.save({
-  ...currentSettings,
-  allowOrgCreationFromSignup: true
-});
-```
-
-## CLI surface — scripting/inspection, outside an app UI
-
-For anything that isn't a feature inside a running Blocks app (one-off lookups, ops scripts, CI checks), the `blocks` CLI has a matching, project-scoped command for every SDK method above except `switchOrganization` (see [read-and-switch.md](read-and-switch.md)). Every command below requires a project already selected (`blocks use <tenantId>`) — they all call IAM through an impersonated project token via `selectedProject()`, the same tenant scoping the SDK calls get from the app's own session.
-
-| CLI command | Maps to | Notes |
-|---|---|---|
-| `blocks iam organizations list` | `organizations.list()` | `--search`, `--is-disabled`, `--parent-organization-id`, `--ids <a,b>`, `--page`, `--page-size`, `--sort-by`, `--sort-desc`. Read-only. |
-| `blocks iam organizations get <id>` (or `--id`) | `organizations.get(id)` | Read-only. |
-| `blocks iam organizations my` | `organizations.my()` | Read-only. |
-| `blocks iam organizations create --name <n> [...]` | `organizations.create()` | `--name` (required), `--description`, `--email`, `--phone-number`, `--website-url`, `--default-permissions`, `--default-roles`, or a full `--body '<json>'`/`--file <path.json>`. Mutation. |
-| `blocks iam organizations update <id> [...]` | `organizations.update(id, ...)` | `--name`, `--description`, `--email`, `--phone-number`, `--website-url`, `--currency`, `--industry`, `--locale`, `--time-zone`, `--is-enabled`, or `--body`/`--file`. Mutation. |
-| `blocks iam organizations config get` | `organizations.getConfig()` | Read-only. |
-| `blocks iam organizations config save [...]` | `organizations.saveConfig()` | `--multi-org-enabled`, `--consent-for-multi-org-enable`, `--allow-org-creation-from-signup`, `--allow-org-creation-from-portal`, `--allow-org-creation-from-cloud`, `--allow-org-creation-from-construct`, or `--body`/`--file`. Mutation. |
-| `blocks iam signup-settings get` | `signupSettings.get()` | Read-only. |
-| `blocks iam signup-settings save [...]` | `signupSettings.save()` | `--email-password-signup`, `--sso-signup`, `--default-permissions`, `--default-roles`, or `--body`/`--file`. Mutation. |
-
-```bash
-blocks use <tenantId>                              # select the project once per session
-blocks iam organizations list --search acme --json
-blocks iam organizations config get --json
-blocks iam organizations config save --multi-org-enabled --dry-run   # review the request body first
-blocks iam organizations config save --multi-org-enabled --yes       # only after the user confirms
-```
-
-Every mutating command (`create`, `update`, `config save`, `signup-settings save`) supports `--dry-run` (prints the resolved request body without calling the API) and requires either `--yes` or an interactive `yes` at a confirmation prompt to actually run — the same "state the exact change, get an explicit go-ahead" discipline as the SDK guidance above, just enforced by the CLI itself instead of app code you write.
-
-## Gotchas
-
-- **The CLI has real organization/signup-settings commands** — don't tell a user there's no `blocks` command for organizations; there is, it's just project-scoped and separate from the SDK path used inside an app.
-- **Confirm the payload, not just the intent**, before any `create`/`update`/`saveConfig`/`signupSettings.save` call — SDK or CLI — restate which organization and which fields are changing, old value vs. new, and wait for a clear yes. On the CLI this means running with `--dry-run` first and only adding `--yes` after that review.
-- **These are legitimate app/operator features, not agent shortcuts.** It's fine to build a "Create Organization" admin screen with a confirm dialog, or run the CLI command yourself with a human's go-ahead — that's the intended use. It's not fine for an agent to call `organizations.create`/`saveConfig` (CLI or SDK) on its own initiative (e.g., to "set things up" for a demo) without that human-in-the-loop step.
-- **Different response shapes per call** — `my()`/`list()` return an array-shaped payload, `get(id)` returns a single organization, `create` returns an id. Don't assume a single envelope shape across all of them; check the actual response before wiring UI to a field path.
+# Flow: Admin-CRUD surface — confirm the exact change first
+
+These mutate tenant-level state. Build them as an explicit feature in an admin settings screen (SDK), or run them as an operator from a terminal with a reviewed `--dry-run` (CLI). Both surfaces exist and are equally real — see "The platform boundary" in [SKILL.md](../SKILL.md).
+
+## SDK methods
+
+### `organizations.list(query)` / `organizations.get(id)` — browse and inspect
+
+Read-only, so no confirmation is needed to call them — but they're part of the admin org-management surface (browsing arbitrary orgs, not just "my own"), so gate the screen itself behind whatever admin permission the app already checks. Typical use: an org-picker/detail view feeding into an edit form, populated before a `create`/`update` call.
+
+```ts
+const page = await blocksClient.iam.organizations.list({ Page: 1, PageSize: 20, "Filter.Name": search });
+const org = await blocksClient.iam.organizations.get(organizationId);
+```
+
+### `organizations.create(request)` / `organizations.update(id, request)`
+
+Create/edit an organization's record (name, description, contact info, branding, addresses, default roles/permissions for new members, etc. — verify current field names against what the admin UI/API actually accepts rather than assuming they haven't changed).
+
+```ts
+// Only after the admin has reviewed and confirmed this exact payload:
+await blocksClient.iam.organizations.create({
+  name: "Acme Logistics",
+  description: "Acme's logistics division workspace"
+  // ...remaining fields the user confirmed
+});
+
+await blocksClient.iam.organizations.update(organizationId, {
+  name: "Acme Logistics (Renamed)"
+  // ...only the fields the user asked to change
+});
+```
+
+### `organizations.getConfig()` / `organizations.saveConfig(request)` — org-level settings
+
+Project/org-wide policy, including multi-org enablement. Read the current config first, show the user the diff of what would change, then save.
+
+```ts
+const current = await blocksClient.iam.organizations.getConfig();
+// ...user reviews current vs. proposed, confirms...
+await blocksClient.iam.organizations.saveConfig({
+  ...current,
+  isMultiOrgEnabled: true
+});
+```
+
+### `signupSettings.save(request)` — save signup policy
+
+Same confirm-first rule: this changes what the public signup screen allows for every future visitor, so restate the exact policy change (e.g., "turn on org creation from signup") before calling.
+
+```ts
+await blocksClient.iam.signupSettings.save({
+  ...currentSettings,
+  allowOrgCreationFromSignup: true
+});
+```
+
+## CLI surface — scripting/inspection, outside an app UI
+
+For anything that isn't a feature inside a running Blocks app (one-off lookups, ops scripts, CI checks), the `blocks` CLI has a matching, project-scoped command for every SDK method above except `switchOrganization` (see [read-and-switch.md](read-and-switch.md)). Every command below requires a project already selected (`blocks use <tenantId>`) — they all call IAM through an impersonated project token via `selectedProject()`, the same tenant scoping the SDK calls get from the app's own session.
+
+| CLI command | Maps to | Notes |
+|---|---|---|
+| `blocks iam organizations list` | `organizations.list()` | `--search`, `--is-disabled`, `--parent-organization-id`, `--ids <a,b>`, `--page`, `--page-size`, `--sort-by`, `--sort-desc`. Read-only. |
+| `blocks iam organizations get <id>` (or `--id`) | `organizations.get(id)` | Read-only. |
+| `blocks iam organizations my` | `organizations.my()` | Read-only. |
+| `blocks iam organizations create --name <n> [...]` | `organizations.create()` | `--name` (required), `--description`, `--email`, `--phone-number`, `--website-url`, `--default-permissions`, `--default-roles`, or a full `--body '<json>'`/`--file <path.json>`. Mutation. |
+| `blocks iam organizations update <id> [...]` | `organizations.update(id, ...)` | `--name`, `--description`, `--email`, `--phone-number`, `--website-url`, `--currency`, `--industry`, `--locale`, `--time-zone`, `--is-enabled`, or `--body`/`--file`. Mutation. |
+| `blocks iam organizations config get` | `organizations.getConfig()` | Read-only. |
+| `blocks iam organizations config save [...]` | `organizations.saveConfig()` | `--multi-org-enabled`, `--consent-for-multi-org-enable`, `--allow-org-creation-from-signup`, `--allow-org-creation-from-portal`, `--allow-org-creation-from-cloud`, `--allow-org-creation-from-construct`, or `--body`/`--file`. Mutation. |
+| `blocks iam signup-settings get` | `signupSettings.get()` | Read-only. |
+| `blocks iam signup-settings save [...]` | `signupSettings.save()` | `--email-password-signup`, `--sso-signup`, `--default-permissions`, `--default-roles`, or `--body`/`--file`. Mutation. |
+
+```bash
+blocks use <tenantId>                              # select the project once per session
+blocks iam organizations list --search acme --json
+blocks iam organizations config get --json
+blocks iam organizations config save --multi-org-enabled --dry-run   # review the request body first
+blocks iam organizations config save --multi-org-enabled --yes       # only after the user confirms
+```
+
+Every mutating command (`create`, `update`, `config save`, `signup-settings save`) supports `--dry-run` (prints the resolved request body without calling the API) and requires either `--yes` or an interactive `yes` at a confirmation prompt to actually run — the same "state the exact change, get an explicit go-ahead" discipline as the SDK guidance above, just enforced by the CLI itself instead of app code you write.
+
+## Gotchas
+
+- **The CLI has real organization/signup-settings commands** — don't tell a user there's no `blocks` command for organizations; there is, it's just project-scoped and separate from the SDK path used inside an app.
+- **Confirm the payload, not just the intent**, before any `create`/`update`/`saveConfig`/`signupSettings.save` call — SDK or CLI — restate which organization and which fields are changing, old value vs. new, and wait for a clear yes. On the CLI this means running with `--dry-run` first and only adding `--yes` after that review.
+- **These are legitimate app/operator features, not agent shortcuts.** It's fine to build a "Create Organization" admin screen with a confirm dialog, or run the CLI command yourself with a human's go-ahead — that's the intended use. It's not fine for an agent to call `organizations.create`/`saveConfig` (CLI or SDK) on its own initiative (e.g., to "set things up" for a demo) without that human-in-the-loop step.
+- **Different response shapes per call** — `my()`/`list()` return an array-shaped payload, `get(id)` returns a single organization, `create` returns an id. Don't assume a single envelope shape across all of them; check the actual response before wiring UI to a field path.