@seliseblocks/cli-os 0.2.6 → 0.2.8

package/README.md

@@ -2,7 +2,7 @@
 
 CLI for SELISE Blocks Cloud.
 
-- Package: `@seliseblocks/cli-os`
+- Package: [`@seliseblocks/cli-os`](https://www.npmjs.com/package/@seliseblocks/cli-os)
 - Binary: `blocks`
 
 ## Setup

package/dist/commands/auth/config/save.js

@@ -12,6 +12,7 @@ export async function authConfigSave(argv) {
         ...compact({
             absoluteRefreshTokenValidForNumberMinutes: optionalIntegerFlag(flags, "absolute-refresh-token-minutes"),
             accessTokenValidForNumberMinutes: optionalIntegerFlag(flags, "access-token-minutes"),
+            accountActionBaseUrl: stringFlag(flags, "account-action-base-url") || undefined,
             accountLockDurationInMinutes: optionalIntegerFlag(flags, "account-lock-duration-minutes"),
             getNumberOfWrongAttemptsToLockTheAccount: optionalIntegerFlag(flags, "wrong-attempts-to-lock"),
             isOidcEnabled: booleanFlag(flags, "oidc-enabled") || undefined,
@@ -32,10 +33,25 @@ export async function authConfigSave(argv) {
         projectTenantId: projectKey
     });
     const body = { ...current, ...overrides };
+    // Turning isOidcEnabled on isn't a single independent flag: the
+    // activation-link flow keys off accountActivationPath, which has to point
+    // at the OIDC variant once OIDC is on, or activation emails break.
+    // accountActionBaseUrl has no safe default this command can guess across
+    // environments, so the caller must supply it explicitly when the tenant
+    // doesn't already have one.
+    const missingActionBaseUrl = Boolean(body.isOidcEnabled) && !body.accountActionBaseUrl;
+    if (body.isOidcEnabled)
+        body.accountActivationPath = "oidc/activate/";
     if (booleanFlag(flags, "dry-run")) {
+        if (missingActionBaseUrl) {
+            console.warn("Warning: this tenant has no accountActionBaseUrl set. Enabling OIDC login requires one -- pass --account-action-base-url <https://your-iam-host> before re-running with --yes.");
+        }
         writeOutput({ dryRun: true, endpoint: "/iam/v4/auth/config", request: body }, flags);
         return;
     }
+    if (missingActionBaseUrl) {
+        throw new Error("Enabling OIDC login requires accountActionBaseUrl, and this tenant doesn't have one set. Pass --account-action-base-url <https://your-iam-host>.");
+    }
     await confirmMutation(flags, "Save AuthController configuration for the selected project.");
     const result = await blocksRequest("/iam/v4/auth/config", {
         body,

package/dist/commands/new/web.js

@@ -23,7 +23,7 @@ export async function newWeb(argv) {
     const oidcClientId = await resolveOidcClientId(tenantId, appDomain, name, flags);
     if (oidcClientId) {
         try {
-            await ensureOidcLoginEnabled(tenantId, flags);
+            await ensureOidcLoginEnabled(tenantId, oidcUrl, flags);
         }
         catch (error) {
             console.warn(`Warning: could not confirm/enable OIDC login on this project's AuthController config: ${error.message}`);
@@ -135,7 +135,15 @@ async function listOidcClientSummaries(tenantId, flags) {
 // field) -- sending just `{ isOidcEnabled: true }` would reset every other
 // AuthController setting for this tenant, so the fetched config is spread
 // back in full with only that one field overridden.
-async function ensureOidcLoginEnabled(tenantId, flags) {
+//
+// Turning isOidcEnabled on isn't a single independent flag either: the
+// activation-link flow keys off accountActivationPath, which has to point at
+// the OIDC variant ("oidc/activate/") once OIDC is on, or activation emails
+// break. accountActionBaseUrl (the host those links are built against) has
+// no safe cross-environment default, but this project's own IAM host is
+// already known here as `oidcUrl`, so it's used whenever the tenant doesn't
+// already have one set.
+async function ensureOidcLoginEnabled(tenantId, oidcUrl, flags) {
     const config = await blocksRequest("/iam/v4/auth/config", {
         impersonatedProjectAuth: true,
         projectTenantId: tenantId,
@@ -145,7 +153,12 @@ async function ensureOidcLoginEnabled(tenantId, flags) {
         return;
     await confirmMutation(flags, "Enable OIDC login on this project's AuthController configuration.");
     await blocksRequest("/iam/v4/auth/config", {
-        body: { ...config, isOidcEnabled: true },
+        body: {
+            ...config,
+            accountActionBaseUrl: config.accountActionBaseUrl || oidcUrl,
+            accountActivationPath: "oidc/activate/",
+            isOidcEnabled: true
+        },
         impersonatedProjectAuth: true,
         projectTenantId: tenantId,
         ...requestContext(flags)

package/dist/skills/blocks-iam-access-control/SKILL.md

@@ -1,49 +1,49 @@
----
-name: blocks-iam-access-control
-description: "Work with SELISE Blocks RBAC (roles & permissions) via `blocks iam roles/permissions *` (CLI, project-scoped) or `blocksClient.iam.*` (SDK), never raw fetch/curl. Two facets: read-only feature-gating by the current user's own roles/permissions (common, safe) vs. creating/editing role and permission definitions (sensitive, human-confirmed only — CLI `--dry-run`→`--yes` or an in-app admin screen). OIDC/identity-provider provisioning stays portal-only, a different concern. Use for permission-gated UI, role/permission pickers, or building/scripting role & permission admin ('gate this button by permission', 'create a role and grant permissions', 'list permissions by severity')."
----
-
-# Blocks IAM — Access Control (Permissions & Roles)
-
-This skill covers **permission and role definitions** in SELISE Blocks — the RBAC model itself, not who has which role (that's the blocks-iam-users skill). Everything goes through either `blocks iam roles/permissions *` (CLI) or `blocksClient.iam.*` from **`@seliseblocks/client`**, the single SDK instance every `blocks new web` scaffold wires up at `src/lib/blocks/client.ts` and exports as `blocksClient`. No raw `fetch`/`curl` for either surface.
-
-```ts
-import { blocksClient } from "../../lib/blocks/client";
-```
-
-## The platform boundary — read this before writing any code
-
-Role and permission administration is **not** portal-only or app-UI-only — `blocks` has a full, working CLI surface for it too. There are two equally real surfaces for the same operations, and the choice is about *where the human is*, not which one is "allowed" — see [flows/manage-roles-permissions.md](flows/manage-roles-permissions.md) for the full command reference and the CLI-vs-SDK decision.
-
-Identity-provider/OIDC client provisioning is the one piece that really is **portal-only, human-driven**, at `https://os.seliseblocks.com` — unrelated to roles/permissions, don't bolt it onto this skill.
-
-Keep the two facets below (read-only feature-gating vs. sensitive admin mutations) separate in your head (and in your code) — they have very different risk profiles regardless of which surface (CLI or SDK) you're using.
-
-## Facet 1 — Feature-gating a frontend by the user's own permissions (common, low risk)
-
-Read-only, scoped to whoever is signed in, needs no special confirmation. `useCurrentUser()` + `iam.resources.features()` + `iam.roles.assignable()`.
-
-→ Full walkthrough: [flows/feature-gating.md](flows/feature-gating.md)
-
-## Facet 2 — Creating/editing roles & permissions (sensitive)
-
-Legitimate only in direct response to a human's explicit, in-the-moment instruction — CLI (`--dry-run` reviewed, then `--yes`) or a signed-in admin's own in-app screen. Never something an agent decides to invoke on its own initiative.
-
-→ Full command reference, SDK methods, and confirm-before-mutating pattern: [flows/manage-roles-permissions.md](flows/manage-roles-permissions.md)
-
-## Gotchas
-
-- **CLI mutations are project-scoped, not account-scoped** — they run against the impersonated-project token; `blocks iam me` is the one IAM command that uses the account token instead.
-- **Role hierarchy and permission assignment key off `slug`**, not `itemId`.
-- **Never fire a create/update/assign-permissions call — CLI or SDK — without a human confirming that specific change first.** See [flows/manage-roles-permissions.md](flows/manage-roles-permissions.md) for the full discipline.
-- **OIDC/identity-provider client provisioning is always portal-only**, independent of everything above.
-
-## Example trigger prompts
-
-- "Only show the delete button to users who have the `order::delete` permission." → Facet 1
-- "Hide this whole admin section unless the signed-in user has an admin role." → Facet 1
-- "What roles am I allowed to assign to other users?" → Facet 1
-- "Show me permissions grouped by severity in a settings panel." → Facet 1
-- "Build an admin page where I can create a role and pick which permissions it gets." → Facet 2
-- "Create a `content-editor` role from the CLI with these permissions." → Facet 2
-- "Can you just set up a few default roles for my project?" → confirm the exact list with the human first (in chat, or via a reviewed `--dry-run`), then run each `blocks iam roles create`/`assign-permissions` with `--yes` only after they say go — don't auto-provision without that per-change confirmation.
+---
+name: blocks-iam-access-control
+description: "Work with SELISE Blocks RBAC (roles & permissions) via `blocks iam roles/permissions *` (CLI, project-scoped) or `blocksClient.iam.*` (SDK), never raw fetch/curl. Two facets: read-only feature-gating by the current user's own roles/permissions (common, safe) vs. creating/editing role and permission definitions (sensitive, human-confirmed only — CLI `--dry-run`→`--yes` or an in-app admin screen). OIDC/identity-provider provisioning stays portal-only, a different concern. Use for permission-gated UI, role/permission pickers, or building/scripting role & permission admin ('gate this button by permission', 'create a role and grant permissions', 'list permissions by severity')."
+---
+
+# Blocks IAM — Access Control (Permissions & Roles)
+
+This skill covers **permission and role definitions** in SELISE Blocks — the RBAC model itself, not who has which role (that's the blocks-iam-users skill). Everything goes through either `blocks iam roles/permissions *` (CLI) or `blocksClient.iam.*` from **`@seliseblocks/client`**, the single SDK instance every `blocks new web` scaffold wires up at `src/lib/blocks/client.ts` and exports as `blocksClient`. No raw `fetch`/`curl` for either surface.
+
+```ts
+import { blocksClient } from "../../lib/blocks/client";
+```
+
+## The platform boundary — read this before writing any code
+
+Role and permission administration is **not** portal-only or app-UI-only — `blocks` has a full, working CLI surface for it too. There are two equally real surfaces for the same operations, and the choice is about *where the human is*, not which one is "allowed" — see [flows/manage-roles-permissions.md](flows/manage-roles-permissions.md) for the full command reference and the CLI-vs-SDK decision.
+
+Identity-provider/OIDC client provisioning is the one piece that really is **portal-only, human-driven**, at `https://os.seliseblocks.com` — unrelated to roles/permissions, don't bolt it onto this skill.
+
+Keep the two facets below (read-only feature-gating vs. sensitive admin mutations) separate in your head (and in your code) — they have very different risk profiles regardless of which surface (CLI or SDK) you're using.
+
+## Facet 1 — Feature-gating a frontend by the user's own permissions (common, low risk)
+
+Read-only, scoped to whoever is signed in, needs no special confirmation. `useCurrentUser()` + `iam.resources.features()` + `iam.roles.assignable()`.
+
+→ Full walkthrough: [flows/feature-gating.md](flows/feature-gating.md)
+
+## Facet 2 — Creating/editing roles & permissions (sensitive)
+
+Legitimate only in direct response to a human's explicit, in-the-moment instruction — CLI (`--dry-run` reviewed, then `--yes`) or a signed-in admin's own in-app screen. Never something an agent decides to invoke on its own initiative.
+
+→ Full command reference, SDK methods, and confirm-before-mutating pattern: [flows/manage-roles-permissions.md](flows/manage-roles-permissions.md)
+
+## Gotchas
+
+- **CLI mutations are project-scoped, not account-scoped** — they run against the impersonated-project token; `blocks iam me` is the one IAM command that uses the account token instead.
+- **Role hierarchy and permission assignment key off `slug`**, not `itemId`.
+- **Never fire a create/update/assign-permissions call — CLI or SDK — without a human confirming that specific change first.** See [flows/manage-roles-permissions.md](flows/manage-roles-permissions.md) for the full discipline.
+- **OIDC/identity-provider client provisioning is always portal-only**, independent of everything above.
+
+## Example trigger prompts
+
+- "Only show the delete button to users who have the `order::delete` permission." → Facet 1
+- "Hide this whole admin section unless the signed-in user has an admin role." → Facet 1
+- "What roles am I allowed to assign to other users?" → Facet 1
+- "Show me permissions grouped by severity in a settings panel." → Facet 1
+- "Build an admin page where I can create a role and pick which permissions it gets." → Facet 2
+- "Create a `content-editor` role from the CLI with these permissions." → Facet 2
+- "Can you just set up a few default roles for my project?" → confirm the exact list with the human first (in chat, or via a reviewed `--dry-run`), then run each `blocks iam roles create`/`assign-permissions` with `--yes` only after they say go — don't auto-provision without that per-change confirmation.

package/dist/skills/blocks-iam-access-control/flows/feature-gating.md

@@ -1,38 +1,38 @@
-# Flow: Feature-gating a frontend by the user's own permissions (common, low risk)
-
-This is read-only against IAM and scoped to whoever is signed in, so it needs no special confirmation — build it the same way you'd build any other data-fetching feature.
-
-The scaffold already gives you a `useCurrentUser()` hook (`src/features/profile/useCurrentUser.ts`) wrapping `blocksClient.iam.me()` with TanStack Query; `me()` returns `{ data: { itemId, email, firstName, lastName, roles: string[], permissions: string[], ... } }`. Reuse it instead of re-fetching:
-
-```ts
-// src/features/access/usePermission.ts
-import { useCurrentUser } from "../profile/useCurrentUser";
-
-export function useHasPermission(permission: string): boolean {
-  const me = useCurrentUser();
-  return me.data?.data?.permissions?.includes(permission) ?? false;
-}
-
-export function useHasRole(role: string): boolean {
-  const me = useCurrentUser();
-  return me.data?.data?.roles?.includes(role) ?? false;
-}
-```
-
-```tsx
-// src/shared/ui/RequirePermission.tsx
-import type { ReactNode } from "react";
-import { useHasPermission } from "../../features/access/usePermission";
-
-export function RequirePermission({ permission, children }: { permission: string; children: ReactNode }) {
-  if (!useHasPermission(permission)) return null;
-  return <>{children}</>;
-}
-```
-
-Two more read methods round this out:
-
-- `blocksClient.iam.resources.features(query?)` — feature/resource flags for the active user context; use this to drive nav items or feature flags that are more granular than a flat permission string.
-- `blocksClient.iam.roles.assignable()` — lists roles the **current caller** is allowed to assign. If you're building a "grant this user a role" picker, populate it from `assignable()`, not from `roles.list()` — don't assume every role in the system is one this particular admin may hand out.
-
-There is also a CLI read path for the same data, useful outside an app (scripting/inspection): `blocks iam roles list/get/assignable` and `blocks iam permissions list/get/by-severity` — see [manage-roles-permissions.md](manage-roles-permissions.md) for the full CLI command reference (it covers both reads and mutations).
+# Flow: Feature-gating a frontend by the user's own permissions (common, low risk)
+
+This is read-only against IAM and scoped to whoever is signed in, so it needs no special confirmation — build it the same way you'd build any other data-fetching feature.
+
+The scaffold already gives you a `useCurrentUser()` hook (`src/features/profile/useCurrentUser.ts`) wrapping `blocksClient.iam.me()` with TanStack Query; `me()` returns `{ data: { itemId, email, firstName, lastName, roles: string[], permissions: string[], ... } }`. Reuse it instead of re-fetching:
+
+```ts
+// src/features/access/usePermission.ts
+import { useCurrentUser } from "../profile/useCurrentUser";
+
+export function useHasPermission(permission: string): boolean {
+  const me = useCurrentUser();
+  return me.data?.data?.permissions?.includes(permission) ?? false;
+}
+
+export function useHasRole(role: string): boolean {
+  const me = useCurrentUser();
+  return me.data?.data?.roles?.includes(role) ?? false;
+}
+```
+
+```tsx
+// src/shared/ui/RequirePermission.tsx
+import type { ReactNode } from "react";
+import { useHasPermission } from "../../features/access/usePermission";
+
+export function RequirePermission({ permission, children }: { permission: string; children: ReactNode }) {
+  if (!useHasPermission(permission)) return null;
+  return <>{children}</>;
+}
+```
+
+Two more read methods round this out:
+
+- `blocksClient.iam.resources.features(query?)` — feature/resource flags for the active user context; use this to drive nav items or feature flags that are more granular than a flat permission string.
+- `blocksClient.iam.roles.assignable()` — lists roles the **current caller** is allowed to assign. If you're building a "grant this user a role" picker, populate it from `assignable()`, not from `roles.list()` — don't assume every role in the system is one this particular admin may hand out.
+
+There is also a CLI read path for the same data, useful outside an app (scripting/inspection): `blocks iam roles list/get/assignable` and `blocks iam permissions list/get/by-severity` — see [manage-roles-permissions.md](manage-roles-permissions.md) for the full CLI command reference (it covers both reads and mutations).

package/dist/skills/blocks-iam-access-control/flows/manage-roles-permissions.md

@@ -1,110 +1,110 @@
-# Flow: Creating/editing roles & permissions (sensitive)
-
-This is the write side, and it's legitimate **only in direct response to a human's explicit, in-the-moment instruction** — either that human running `blocks iam roles/permissions create|update|assign-permissions` themselves (with a `--dry-run` reviewed first), or a signed-in admin operating their own in-app admin screen. Never something an agent decides to invoke on its own initiative.
-
-## CLI command reference
-
-All project-scoped — every command resolves the active project (`blocks use <tenantId>` or an explicit `--project <tenantId>`) and runs on an impersonated project token, not the account token `iam me` uses.
-
-```
-blocks iam roles list [--page] [--page-size] [--search] [--slugs a,b] [--organization-id] [--filter '<json>'] [--json]
-blocks iam roles get <id> [--json]
-blocks iam roles create --name <n> [--slug] [--description] [--parent-role-slug] [--can-create-own] [--body '<json>'|--file <path>] [--dry-run] [--yes] [--json]
-blocks iam roles update <itemId> [--name] [--description] [--parent-role-slug] [--propagate-to-other-org] [--can-create-own] [--body '<json>'|--file <path>] [--dry-run] [--yes] [--json]
-blocks iam roles assign-permissions <slug> [--add-permissions a,b] [--remove-permissions a,b] [--organization-id] [--dry-run] [--yes] [--json]
-blocks iam roles assignable [--json]
-
-blocks iam permissions list [--page] [--page-size] [--search] [--type <0-3>] [--severity <0-4>] [--resource-group] [--tags a,b] [--resources a,b] [--is-built-in] [--is-archived] [--roles a,b] [--organization-id] [--filter '<json>'] [--json]
-blocks iam permissions get <id> [--json]
-blocks iam permissions create --name <n> [--type] [--description] [--resource] [--resource-group] [--tags a,b] [--severity] [--is-built-in] [--dependent-permissions a,b] [--body '<json>'|--file <path>] [--dry-run] [--yes] [--json]
-blocks iam permissions update <id> [same flags as create, plus --is-archived] [--dry-run] [--yes] [--json]
-blocks iam permissions by-severity [--json]
-```
-
-Mutating commands (`create`, `update`, `assign-permissions`) follow the same discipline as every other mutating command in this CLI: pass `--dry-run` first to see the exact request body and endpoint with no network call, then re-run with `--yes` (or you'll be prompted to confirm) to actually send it.
-
-## Two equally real surfaces
-
-The choice is about *where the human is*, not which one is "allowed":
-
-- **`blocks iam roles/permissions *` from a terminal** — a human (or an agent acting on that human's explicit, in-the-moment instruction) runs the CLI directly. `--dry-run` is the CLI's own review step; treat a clean dry-run plus the human's go-ahead as the confirmation, then run with `--yes`.
-- **`blocksClient.iam.roles`/`iam.permissions` from inside an app** — for building an admin settings screen. If you're building that user their own admin screen, and *they* click "Create role" through that screen, calling `iam.roles.create()` from the app's code is exactly what the SDK method is for.
-
-The actual line is not "CLI vs SDK" — it's:
-
-- **Fine:** a command run because a human just asked for this specific change (terminal or in-app), bounded by that human's own IAM permissions.
-- **Not fine:** an agent deciding on its own to call `create`/`update`/`assignPermissions` (CLI or SDK) — whether to "help out," to fix something it noticed, or as part of a larger task the user didn't ask it to take this specific action for.
-
-## SDK methods (write side)
-
-All from `blocksClient.iam`, per `iam-client.ts`:
-
-- `permissions.create(request)` / `permissions.update(id, request)` — define or edit a permission.
-- `permissions.list(request)` — paged/filtered search.
-- `permissions.bySeverity()` — permissions grouped by severity, handy for a categorized picker.
-- `permissions.get(id)` — one permission's detail.
-- `roles.create(request)` / `roles.update(request)` — define or edit a role.
-- `roles.list(request)` / `roles.get(id)` — search / fetch one role.
-- `roles.assignPermissions(request)` — attach/detach permissions on a role.
-- `roles.assignable()` — same read method as feature-gating; also useful here to limit which roles this admin's screen lets them touch at all.
-- `resources.groups()` — metadata for grouping permissions by resource in the UI (e.g. a permissions picker organized by resource/module).
-
-The SDK deliberately leaves these request bodies as open `Record<string, unknown>` rather than locking you to a fixed shape — confirm exact field names against the portal or a `list()`/`get()` response before hardcoding new ones. Two fields the SDK's own types do pin down: a role's `slug` (`BlocksRole.slug`) is its stable key — use it, not `itemId`, anywhere the API expects a role reference (e.g. `assignPermissions`); a permission's `resource` and `roles[]` (`BlocksPermission`) tell you what it's scoped to and which roles already hold it.
-
-## Confirm before mutating
-
-**Before calling any of `permissions.create`, `permissions.update`, `roles.create`, `roles.update`, or `roles.assignPermissions` from your admin screen's code, the screen itself must get an explicit, in-the-moment confirmation from the admin operating it** — mirror the discipline `blocks iam roles/permissions create|update|assign-permissions` enforces natively with `--dry-run` before `--yes`. Concretely, that means the screen should:
-
-1. Let the admin build up the change in the UI (pick a role, check/uncheck permissions, edit a name) without calling anything yet.
-2. Show a clear summary of exactly what will change — "Grant `Editor` role: + `content::publish`, − `content::archive`" — before any network call.
-3. Only fire the `create`/`update`/`assignPermissions` call after the admin clicks an explicit confirm ("Save changes", "Create role") for *that specific* change.
-
-Don't collapse steps 2–3 into an auto-save on every checkbox click, and don't have an agent call these methods proactively (e.g. as part of "let me clean up your roles" or "I'll just add the permission you mentioned needing") — only in direct response to the human's own confirmed action through the screen.
-
-## Examples
-
-SDK, wired to a confirm step:
-
-```tsx
-// src/features/admin/roles/useAssignPermissions.ts
-import { useMutation, useQueryClient } from "@tanstack/react-query";
-import { blocksClient } from "../../../lib/blocks/client";
-
-export function useAssignPermissions() {
-  const queryClient = useQueryClient();
-  return useMutation({
-    mutationFn: (delta: { slug: string; addPermissions: string[]; removePermissions: string[] }) =>
-      blocksClient.iam.roles.assignPermissions(delta),
-    onSuccess: () => queryClient.invalidateQueries({ queryKey: ["iam", "roles"] })
-  });
-}
-```
-
-```tsx
-// in the role editor component, only after the admin reviews a diff and clicks "Save":
-const assign = useAssignPermissions();
-const onConfirmSave = () =>
-  assign.mutate({ slug: role.slug, addPermissions: pendingAdds, removePermissions: pendingRemoves });
-```
-
-The equivalent from a terminal, doing the same review-then-confirm dance the CLI enforces natively:
-
-```
-blocks use my-tenant-id                      # or pass --project my-tenant-id on every call below
-blocks iam roles create --name Editor --description "Content editors" --dry-run
-# review the printed request body, then:
-blocks iam roles create --name Editor --description "Content editors" --yes
-
-blocks iam roles assign-permissions editor --add-permissions content::publish --dry-run
-blocks iam roles assign-permissions editor --add-permissions content::publish --yes
-```
-
-## Gotchas
-
-- **CLI mutations are project-scoped, not account-scoped** — `blocks iam roles create/update/assign-permissions` and `blocks iam permissions create/update` all require a selected project (`blocks use <tenantId>` or `--project <tenantId>`) and run against the impersonated-project token; `blocks iam me` is the one IAM command that uses the account token instead, so don't expect `iam me`'s auth context to carry over to these.
-- **Role hierarchy and permission assignment key off `slug`**, not `itemId` — grab it from `roles.list()`/`roles.get()` (or `blocks iam roles list/get`) before calling `assignPermissions`.
-- **Permission assignment ultimately uses permission `itemId`s** — the CLI resolves `resource` strings like `content::publish` before mutation; SDK/backend callers should pass permission ids directly in `addPermissions` / `removePermissions`.
-- **`roles.assignPermissions` is additive/subtractive** (`addPermissions[]` / `removePermissions[]` in one call), not a full-set replace — compute the delta from what's checked/unchecked, don't resend the entire permission list as "adds."
-- **`roles.assignable()` scopes to the caller** — always populate role pickers from it rather than `roles.list()`, so an admin can't be shown (or attempt to grant) a role above their own authority.
-- **Never fire a create/update/assign-permissions call — CLI or SDK — without a human confirming that specific change first** (a reviewed `--dry-run` plus explicit go-ahead on the CLI, an explicit in-UI confirm for the SDK) — no auto-provisioning "default roles," no agent-initiated cleanup of permissions, no batch edits without a per-change confirm.
-- **OIDC/identity-provider client provisioning is always portal-only**, independent of everything above — if a request drifts into "create an OIDC client" or "add an identity provider," that's a different skill's territory (or no skill's — send the user to the portal), not something to bolt onto this one.
+# Flow: Creating/editing roles & permissions (sensitive)
+
+This is the write side, and it's legitimate **only in direct response to a human's explicit, in-the-moment instruction** — either that human running `blocks iam roles/permissions create|update|assign-permissions` themselves (with a `--dry-run` reviewed first), or a signed-in admin operating their own in-app admin screen. Never something an agent decides to invoke on its own initiative.
+
+## CLI command reference
+
+All project-scoped — every command resolves the active project (`blocks use <tenantId>` or an explicit `--project <tenantId>`) and runs on an impersonated project token, not the account token `iam me` uses.
+
+```
+blocks iam roles list [--page] [--page-size] [--search] [--slugs a,b] [--organization-id] [--filter '<json>'] [--json]
+blocks iam roles get <id> [--json]
+blocks iam roles create --name <n> [--slug] [--description] [--parent-role-slug] [--can-create-own] [--body '<json>'|--file <path>] [--dry-run] [--yes] [--json]
+blocks iam roles update <itemId> [--name] [--description] [--parent-role-slug] [--propagate-to-other-org] [--can-create-own] [--body '<json>'|--file <path>] [--dry-run] [--yes] [--json]
+blocks iam roles assign-permissions <slug> [--add-permissions a,b] [--remove-permissions a,b] [--organization-id] [--dry-run] [--yes] [--json]
+blocks iam roles assignable [--json]
+
+blocks iam permissions list [--page] [--page-size] [--search] [--type <0-3>] [--severity <0-4>] [--resource-group] [--tags a,b] [--resources a,b] [--is-built-in] [--is-archived] [--roles a,b] [--organization-id] [--filter '<json>'] [--json]
+blocks iam permissions get <id> [--json]
+blocks iam permissions create --name <n> [--type] [--description] [--resource] [--resource-group] [--tags a,b] [--severity] [--is-built-in] [--dependent-permissions a,b] [--body '<json>'|--file <path>] [--dry-run] [--yes] [--json]
+blocks iam permissions update <id> [same flags as create, plus --is-archived] [--dry-run] [--yes] [--json]
+blocks iam permissions by-severity [--json]
+```
+
+Mutating commands (`create`, `update`, `assign-permissions`) follow the same discipline as every other mutating command in this CLI: pass `--dry-run` first to see the exact request body and endpoint with no network call, then re-run with `--yes` (or you'll be prompted to confirm) to actually send it.
+
+## Two equally real surfaces
+
+The choice is about *where the human is*, not which one is "allowed":
+
+- **`blocks iam roles/permissions *` from a terminal** — a human (or an agent acting on that human's explicit, in-the-moment instruction) runs the CLI directly. `--dry-run` is the CLI's own review step; treat a clean dry-run plus the human's go-ahead as the confirmation, then run with `--yes`.
+- **`blocksClient.iam.roles`/`iam.permissions` from inside an app** — for building an admin settings screen. If you're building that user their own admin screen, and *they* click "Create role" through that screen, calling `iam.roles.create()` from the app's code is exactly what the SDK method is for.
+
+The actual line is not "CLI vs SDK" — it's:
+
+- **Fine:** a command run because a human just asked for this specific change (terminal or in-app), bounded by that human's own IAM permissions.
+- **Not fine:** an agent deciding on its own to call `create`/`update`/`assignPermissions` (CLI or SDK) — whether to "help out," to fix something it noticed, or as part of a larger task the user didn't ask it to take this specific action for.
+
+## SDK methods (write side)
+
+All from `blocksClient.iam`, per `iam-client.ts`:
+
+- `permissions.create(request)` / `permissions.update(id, request)` — define or edit a permission.
+- `permissions.list(request)` — paged/filtered search.
+- `permissions.bySeverity()` — permissions grouped by severity, handy for a categorized picker.
+- `permissions.get(id)` — one permission's detail.
+- `roles.create(request)` / `roles.update(request)` — define or edit a role.
+- `roles.list(request)` / `roles.get(id)` — search / fetch one role.
+- `roles.assignPermissions(request)` — attach/detach permissions on a role.
+- `roles.assignable()` — same read method as feature-gating; also useful here to limit which roles this admin's screen lets them touch at all.
+- `resources.groups()` — metadata for grouping permissions by resource in the UI (e.g. a permissions picker organized by resource/module).
+
+The SDK deliberately leaves these request bodies as open `Record<string, unknown>` rather than locking you to a fixed shape — confirm exact field names against the portal or a `list()`/`get()` response before hardcoding new ones. Two fields the SDK's own types do pin down: a role's `slug` (`BlocksRole.slug`) is its stable key — use it, not `itemId`, anywhere the API expects a role reference (e.g. `assignPermissions`); a permission's `resource` and `roles[]` (`BlocksPermission`) tell you what it's scoped to and which roles already hold it.
+
+## Confirm before mutating
+
+**Before calling any of `permissions.create`, `permissions.update`, `roles.create`, `roles.update`, or `roles.assignPermissions` from your admin screen's code, the screen itself must get an explicit, in-the-moment confirmation from the admin operating it** — mirror the discipline `blocks iam roles/permissions create|update|assign-permissions` enforces natively with `--dry-run` before `--yes`. Concretely, that means the screen should:
+
+1. Let the admin build up the change in the UI (pick a role, check/uncheck permissions, edit a name) without calling anything yet.
+2. Show a clear summary of exactly what will change — "Grant `Editor` role: + `content::publish`, − `content::archive`" — before any network call.
+3. Only fire the `create`/`update`/`assignPermissions` call after the admin clicks an explicit confirm ("Save changes", "Create role") for *that specific* change.
+
+Don't collapse steps 2–3 into an auto-save on every checkbox click, and don't have an agent call these methods proactively (e.g. as part of "let me clean up your roles" or "I'll just add the permission you mentioned needing") — only in direct response to the human's own confirmed action through the screen.
+
+## Examples
+
+SDK, wired to a confirm step:
+
+```tsx
+// src/features/admin/roles/useAssignPermissions.ts
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { blocksClient } from "../../../lib/blocks/client";
+
+export function useAssignPermissions() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: (delta: { slug: string; addPermissions: string[]; removePermissions: string[] }) =>
+      blocksClient.iam.roles.assignPermissions(delta),
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ["iam", "roles"] })
+  });
+}
+```
+
+```tsx
+// in the role editor component, only after the admin reviews a diff and clicks "Save":
+const assign = useAssignPermissions();
+const onConfirmSave = () =>
+  assign.mutate({ slug: role.slug, addPermissions: pendingAdds, removePermissions: pendingRemoves });
+```
+
+The equivalent from a terminal, doing the same review-then-confirm dance the CLI enforces natively:
+
+```
+blocks use my-tenant-id                      # or pass --project my-tenant-id on every call below
+blocks iam roles create --name Editor --description "Content editors" --dry-run
+# review the printed request body, then:
+blocks iam roles create --name Editor --description "Content editors" --yes
+
+blocks iam roles assign-permissions editor --add-permissions content::publish --dry-run
+blocks iam roles assign-permissions editor --add-permissions content::publish --yes
+```
+
+## Gotchas
+
+- **CLI mutations are project-scoped, not account-scoped** — `blocks iam roles create/update/assign-permissions` and `blocks iam permissions create/update` all require a selected project (`blocks use <tenantId>` or `--project <tenantId>`) and run against the impersonated-project token; `blocks iam me` is the one IAM command that uses the account token instead, so don't expect `iam me`'s auth context to carry over to these.
+- **Role hierarchy and permission assignment key off `slug`**, not `itemId` — grab it from `roles.list()`/`roles.get()` (or `blocks iam roles list/get`) before calling `assignPermissions`.
+- **Permission assignment ultimately uses permission `itemId`s** — the CLI resolves `resource` strings like `content::publish` before mutation; SDK/backend callers should pass permission ids directly in `addPermissions` / `removePermissions`.
+- **`roles.assignPermissions` is additive/subtractive** (`addPermissions[]` / `removePermissions[]` in one call), not a full-set replace — compute the delta from what's checked/unchecked, don't resend the entire permission list as "adds."
+- **`roles.assignable()` scopes to the caller** — always populate role pickers from it rather than `roles.list()`, so an admin can't be shown (or attempt to grant) a role above their own authority.
+- **Never fire a create/update/assign-permissions call — CLI or SDK — without a human confirming that specific change first** (a reviewed `--dry-run` plus explicit go-ahead on the CLI, an explicit in-UI confirm for the SDK) — no auto-provisioning "default roles," no agent-initiated cleanup of permissions, no batch edits without a per-change confirm.
+- **OIDC/identity-provider client provisioning is always portal-only**, independent of everything above — if a request drifts into "create an OIDC client" or "add an identity provider," that's a different skill's territory (or no skill's — send the user to the portal), not something to bolt onto this one.