@seliseblocks/cli-os 0.1.4 → 0.1.5

package/dist/skills/blocks-data-storage/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: blocks-data-storage
+description: "Store and serve files on a SELISE Blocks project: presigned/local-storage upload, download, folder browsing, tags/metadata, and delete, via the blocks CLI ('data files *') for admin/scripting or the @seliseblocks/client SDK ('data.files'/'data.dms') for in-app upload/download flows. Use for prompts like upload a file and get a download link, attach an image to a record, create a folder, let users download a file, tag or delete an uploaded file. Separate from the data model — schemas/records live in blocks-data-gateway-configuration/-crud; this covers files/DMS only, implementation-mode, SDK-driven."
+---
+
+# Blocks Data — Storage (Files / DMS)
+
+Storage is DMS (document management system). Two ways to reach it, pick based on what the user is actually doing:
+
+- **`blocks data files *` (CLI)** — admin tasks, one-off scripts, or anything the user is doing from a terminal/agent context rather than inside a running app.
+- **`@seliseblocks/client`'s `data.files` / `data.dms` namespaces (SDK)** — wiring upload/download/browse into actual app code (a React component, a form submit handler).
+
+Both surfaces do the same work; which one to use is about *where the code runs*, not a capability gap — unlike some other Data resources, this one has full CLI coverage.
+
+**Prerequisite:** a project is selected (`blocks use <tenantId>`). For the SDK path, a frontend also needs to be scaffolded. If login/project state is unknown, or there's no app to write SDK code into yet, run the blocks-onboarding skill first — it gets `blocks new web` scaffolding in place (React 18 + TypeScript + Vite + Tailwind + Radix + TanStack Query + a single `@seliseblocks/client` instance). The SDK examples below assume that scaffold's shared client, conventionally exported as `blocksClient` from `src/lib/blocks/client.ts`.
+
+```ts
+import { blocksClient } from "../lib/blocks/client";
+const { files, dms } = blocksClient.data;
+```
+
+Store a file here and keep its returned `fileId` in a schema field (see the blocks-data-gateway-crud skill) to associate it with a record.
+
+## CLI quick reference
+
+```bash
+# Cloud storage (pre-signed URL), two steps
+blocks data files presigned-upload-url --name invoice.pdf --access-modifier Public --json
+blocks data files upload-to-url --url "<uploadUrl from above>" --file ./invoice.pdf --content-type application/pdf --yes --json
+
+# Local storage, one step
+blocks data files upload-to-local-storage --file ./invoice.pdf --access-modifier Public --yes --json
+
+# Register the uploaded file in a DMS folder (upload alone doesn't do this)
+blocks data files dms-upload --file-storage-id <fileId> --artifact-name invoice.pdf --yes --json
+
+# Read it back
+blocks data files dms-list --parent-id "" --json
+blocks data files get <fileId> --json
+
+# Folders, metadata, cleanup
+blocks data files create-folder Invoices --yes --json
+blocks data files update-additional-info <fileId> --additional-properties '{"status":"reviewed"}' --yes --json
+blocks data files delete <fileId> --yes --json
+```
+
+Same two upload paths as the SDK section below (pick based on the project's storage backend, not per-call), same `--dry-run`-before-`--yes` discipline as every other `blocks` mutation.
+
+**Shortcut:** `blocks data files upload --file ./invoice.pdf --yes --json` composes the manual sequence above into one command — presign + PUT + `dms.uploadFiles` registration for cloud storage, or add `--local-storage` for the one-step local-storage path (uploads only, no DMS registration in that case). Same relationship as `data sync` is to the manual schema/rules/reload sequence elsewhere in this skill pack: reach for the manual steps when you need to inspect or reuse an intermediate result (e.g. the presigned URL itself), reach for `upload` when you just want the file stored.
+
+## Two upload paths — pick one per deployment
+
+A project's storage is backed by either cloud object storage (Azure Blob, S3, etc.) or local storage on the Blocks Data host. Which one applies is a property of the project's storage configuration, not something the frontend chooses per call — but the SDK exposes a distinct method for each:
+
+| Deployment | Call sequence |
+|---|---|
+| **Cloud storage** (pre-signed URL) | `files.presignedUploadUrl(...)` → `files.uploadToUrl(...)` |
+| **Local storage** | `files.uploadToLocalStorage(...)` (one call, no presign step) |
+
+Both are followed by the same registration step, `dms.uploadFiles(...)`, if the file needs to show up in a DMS folder.
+
+**Where that configuration lives:** `blocks storage config get/list/save/delete` (a separate top-level command group, not `data files`) reads/writes the named storage configuration itself — host, port, credentials, region/endpoint or connection string, and strategy — i.e. which provider a given `configurationName` points at, cloud or local. This skill only covers *using* that config name when uploading; managing the config's own fields is out of scope here — see the blocks-storage-configuration skill.
+
+## Step 1a (cloud) — get a pre-signed upload URL
+
+```ts
+const presign = await files.presignedUploadUrl({
+  name: "invoice.pdf",
+  contentType: "application/pdf",
+  configurationName: "Default",       // example only — confirm the storage config name for this project
+  moduleName: 3,                      // example only — confirm the module value expected by this project
+  parentDirectoryId: "",              // required — "" for root, or a folder id; never omit/null
+  accessModifier: "Public"            // "Public" (readable without auth) or "Private"
+});
+```
+
+It returns the pre-signed `uploadUrl` plus a `fileId` you'll need for the next steps — the method's return type is `Promise<unknown>`, so read the exact response shape at runtime rather than assuming a typed contract. Note `contentType` in this request is not forwarded to the presign call itself (the normalizer drops it); pass it again to `uploadToUrl` below so the PUT gets the right `Content-Type` header. Treat `configurationName` and `moduleName` values as project-specific unless the tenant's storage configuration says otherwise.
+
+## Step 1b (cloud) — PUT the binary to that URL
+
+```ts
+await files.uploadToUrl({
+  url: presign.uploadUrl,
+  body: fileBlob,              // Blob | ArrayBuffer | ArrayBufferView | ReadableStream
+  contentType: "application/pdf"
+});
+```
+
+This is the one call in the whole skill that is **provider-direct, not a Blocks API call** — it sends **no `x-blocks-key` and no bearer token**. It PUTs straight to the storage provider's pre-signed URL. If you don't set your own `x-ms-blob-type` header, the SDK adds `x-ms-blob-type: Blockblob` for you (Azure's block-blob upload header); verify that this matches the storage provider and signed-URL policy for the project rather than assuming every provider ignores extra headers.
+
+## Step 1 (local storage) — the one-call alternative
+
+For local-storage-backed deployments, skip the presign/PUT pair entirely and upload straight through Blocks Data:
+
+```ts
+await files.uploadToLocalStorage({
+  name: "invoice.pdf",
+  file: fileBlob,               // Blob | File
+  configurationName: "Default",
+  parentDirectoryId: "",
+  accessModifier: "Public",
+  tags: ["invoice", "2026"]
+});
+```
+
+The SDK builds a multipart `FormData` body for you (`File`, `Name`, `ItemId`, `MetaData`, `ParentDirectoryId`, `Tags`, `AccessModifier`, `ConfigurationName`, `AdditionalProperties[key]`) and sends it as a normal authenticated Blocks API call (`x-blocks-key` + bearer, unlike the pre-signed PUT above).
+
+## Step 2 — register the file in a DMS folder
+
+Neither upload path above makes a file appear in a document folder by itself — that's a separate registration call:
+
+```ts
+await dms.uploadFiles({
+  upload: [{
+    fileStorageId: presign.fileId,   // the fileId from presignedUploadUrl (or the equivalent id from uploadToLocalStorage's response)
+    artifactName: "invoice.pdf",
+    parentId: "",                    // "" for root, or a folder id
+    tags: ["invoice"]
+  }]
+});
+```
+
+Despite the method's name suggesting a binary upload, this is the DMS *registration* call — the bytes are already stored by Step 1a/1b or Step 1. `upload` is an array, so multiple files can be registered into folders in one call.
+
+## Step 3 — read it back
+
+```ts
+const folder = await dms.list({ parentId: "", take: 20 });
+const meta = await files.get(presign.fileId, { configurationName: "Default" });
+```
+
+`dms.list` returns the combined folder+file listing for a `parentId` (`""` = root), with `searchKey`/`skip`/`take` for search and paging. The same endpoint is also reachable as `files.listFolder(...)` — they're identical calls, `dms.list` is the more discoverable name for folder-browsing UI. `files.get` confirms a specific upload landed: a successful response with a non-null `url` (download link) and matching `name`/size means the file is stored.
+
+## Other file operations
+
+- **`files.getMany({ fileIds, configurationName })`** — batch read instead of one `files.get` per attachment.
+- **`files.info({ page, pageSize, sort, filter })`** — paged file metadata/listing for storage-browser UIs; unlike `presignedUploadUrl`, the SDK does not remap these field names to PascalCase — pass exactly what your app builds.
+- **`files.updateAdditionalInfo({ itemId, additionalProperties })`** — attach searchable metadata to an uploaded file, e.g. a business reference or workflow status.
+- **`files.delete({ fileId, configurationName?, eventQueueName? })`** — delete a file.
+- **`dms.createFolder({ artifactName, parentId?, configurationName? })`** / **`dms.deleteFolder({ folderId, configurationName? })`** — DMS folder management.
+
+## Gotchas
+
+- **Terminal/admin task → CLI (`data files *`); app code → SDK.** Both exist and both are fully supported; don't default to writing a throwaway script against the SDK for something the CLI already does in one command, and don't reach for `blocks` from inside a React component.
+- **`--module-name` / `moduleName` and `--parent-directory-id` / `parentDirectoryId` on the presigned-upload-url call** — optional in the CLI/SDK types, but the underlying endpoint may require them for a given project/storage setup. Confirm the expected module value with the project's storage configuration, and always send a `parentDirectoryId` value (`""` for root) when the endpoint requires a parent folder value — the CLI command defaults it to `""` automatically if you omit `--parent-directory-id`.
+- **The pre-signed PUT is the one call with no Blocks auth.** `uploadToUrl` sends no `x-blocks-key` and no bearer token by design — everything else in this skill (`presignedUploadUrl`, `uploadToLocalStorage`, `dms.*`, `files.get`/`getMany`/`info`/`delete`) is a normal authenticated Blocks API call.
+- **Upload ≠ visible in a folder.** `uploadToUrl`/`uploadToLocalStorage` only gets the bytes stored; call `dms.uploadFiles` afterward if the file needs to appear under a DMS folder.
+- **Most file/DMS methods return `Promise<unknown>`.** The SDK doesn't hand you a typed response for this surface — check the actual JSON shape at runtime (e.g. log the presign response once) rather than assuming field names beyond what's documented here.
+- **`accessModifier`** is `"Public"` (readable without auth) or `"Private"` — decide per file, not per project.
+- Don't confuse this with the data model: a file's `fileId` is just a string you store in a schema field via **blocks-data-gateway-crud**; this skill never touches schemas.
+
+## Example trigger prompts
+
+- "Upload a PDF and get a download link." → CLI (`data files presigned-upload-url` + `upload-to-url`, or `upload-to-local-storage`) for a one-off; SDK if it's a feature in the app.
+- "Attach an image to this record." (upload via CLI or SDK, then store the `fileId` via blocks-data-gateway-crud)
+- "Let users download this file from the app." → SDK, this is in-app behavior.
+- "Create a folder and list its contents." → `data files create-folder` + `data files dms-list`.
+- "Get a presigned upload URL for a cloud storage upload." → `data files presigned-upload-url`.
+- "This deployment uses local storage — how do I upload a file?" → `data files upload-to-local-storage`.
+- "Tag this uploaded file with a status so it's searchable later." → `data files update-additional-info`.
+- "Delete this file / delete this folder." → `data files delete` / `data files delete-folder`.

package/dist/skills/blocks-frontend-local-https/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: blocks-frontend-local-https
+description: "Run a scaffolded (`blocks new web`) Blocks app locally over HTTPS on its real project domain — required for hosted IAM login, since plain HTTP or localhost never gets the session cookie. The scaffold already automates cert generation (npm run cert, no OpenSSL needed) and HTTPS serving via vite.config.ts. Covers running that flow, trusting the cert, the hosts-file entry, and troubleshooting. Use when running a scaffolded app over HTTPS, hitting 'SSO cookie not set' / Vite 'Blocked request' errors, trusting the dev cert, or asking why local login redirects back but doesn't stay signed in."
+---
+
+# Blocks Frontend — Local HTTPS for a Scaffolded App
+
+This is the local dev loop for an app already created with `blocks new web` (see the blocks-onboarding skill for the scaffold command itself — this skill doesn't repeat it). The scaffold **already generates its own cert tooling**; nothing here is built from scratch, and nothing uses raw `openssl`/`curl`/`fetch`.
+
+## Why localhost doesn't work
+
+Browser login goes through the hosted Blocks IAM IdP flow (`blocksClient.auth.idp.redirectToProvider()` / `.callback()`), which finishes by IAM setting a **Secure, domain-scoped session cookie**. Browsers won't store or send that cookie on plain `http://localhost` — it has to be HTTPS, and it has to be on the project's real domain, or the cookie silently never lands and the app looks "logged in" for a second then bounces back to logged-out.
+
+## Where the domain comes from
+
+`--app-domain` on `blocks new web` is the app's real Blocks origin, e.g. `https://dbpdba.seliseblocks.com`. The generated `.env` keeps two derived values:
+
+- `VITE_BLOCKS_APP_DOMAIN` — the full value as passed, with scheme (`https://dbpdba.seliseblocks.com`).
+- `VITE_BLOCKS_DEV_HOST` — the same host with no scheme (`dbpdba.seliseblocks.com`), computed by the scaffold generator and used everywhere locally: hosts file, cert `commonName`/SAN, and `vite.config.ts`'s `server.host`/`allowedHosts`.
+
+You never need to look this up separately — it's already sitting in `.env` after scaffolding.
+
+## The flow
+
+```bash
+cd <appName>
+npm install
+npm run cert
+```
+
+`npm run cert` runs `scripts/generate-cert.mjs`, which reads `VITE_BLOCKS_DEV_HOST` from `.env` (or `process.env`, or an explicit `npm run cert -- <domain>` argument) and uses the `selfsigned` npm dependency to write `.cert/dev-key.pem` and `.cert/dev-cert.pem`, with `subjectAltName` covering the domain, `localhost`, and `127.0.0.1`. This is pure Node — it works from a plain PowerShell prompt with no OpenSSL and no Git Bash/WSL switch.
+
+Next, map the domain to your machine — add one line to the hosts file (needs admin/elevated):
+
+```text
+127.0.0.1 dbpdba.seliseblocks.com
+```
+
+Windows path: `C:\Windows\System32\drivers\etc\hosts` (edit as Administrator).
+
+Then:
+
+```bash
+npm run dev
+```
+
+`vite.config.ts` picks up `.cert/dev-key.pem` + `.cert/dev-cert.pem` automatically when both exist and serves HTTPS on `VITE_BLOCKS_DEV_HOST`:`VITE_BLOCKS_DEV_PORT` (default port `5173`, `strictPort: true` because the port is baked into the registered OIDC redirect URI). It also sets `allowedHosts` to that domain, working around Vite's default DNS-rebinding protection which otherwise 404s custom hosts with "Blocked request."
+
+Finally, open the app at:
+
+```text
+https://dbpdba.seliseblocks.com:5173
+```
+
+**Not** `http://`, **not** `localhost` — either one skips the cookie entirely even though the app loads.
+
+## Trusting the cert (optional but recommended)
+
+The cert is self-signed, so the browser shows a one-time warning until trusted. `npm run cert` prints the exact trust command for your OS when it finishes:
+
+- Windows (elevated prompt): `certutil -addstore -f Root .cert\dev-cert.pem`
+- macOS: `sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain .cert/dev-cert.pem`
+- Linux: `sudo cp .cert/dev-cert.pem /usr/local/share/ca-certificates/blocks-dev.crt && sudo update-ca-certificates`
+
+Restart the browser after trusting so it picks up the new trust store entry. `.cert/` is already gitignored by the scaffold — it's per-machine, never committed.
+
+## Still need a public OIDC client
+
+Local HTTPS alone doesn't make login succeed if no OIDC client is registered yet, or if its `redirect_uris` don't include this exact dev origin. That registration is portal-only (see blocks-onboarding's Gotchas) — out of scope here, but it's the next thing to check if HTTPS is right and login still fails. The redirect URI must match byte-for-byte, including `:5173`.
+
+## Gotchas
+
+**Custom app domain: the API base URL must share its registrable domain, or the cookie never lands.** `blocks new web --app-domain` isn't limited to `*.seliseblocks.com` — it also supports custom domains (e.g. `abc.slsblx.com`, `xyz.blx10.com`). On a custom domain, the hosted-login session cookie is only stored by the browser if `VITE_BLOCKS_API_URL` shares the app's registrable domain. Concretely:
+
+- `abc.slsblx.com` → `VITE_BLOCKS_API_URL` must be `https://blocksapi.slsblx.com`
+- `xyz.blx10.com` → `VITE_BLOCKS_API_URL` must be `https://blocksapi.blx10.com`
+
+If `VITE_BLOCKS_API_URL` is left at the default `https://api.seliseblocks.com` while the app itself runs on a custom domain, the browser treats the API as cross-site relative to the app and never stores the cookie — login still redirects back and *looks* successful, but cookie-based calls (`/iam/me`, organization switching, logout) silently fail. Check `VITE_BLOCKS_API_URL` in `.env` first whenever the app domain is not `*.seliseblocks.com` and auth-dependent calls are failing despite HTTPS and the cert being set up correctly.
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Login redirects back but app shows logged-out | Opened on `http://` or `localhost` instead of the HTTPS dev host | Check the URL bar: must be `https://<VITE_BLOCKS_DEV_HOST>:5173` exactly |
+| Browser "not private" warning | Self-signed cert not trusted yet | Run the OS trust command `npm run cert` printed, then restart the browser |
+| Vite: "Blocked request. This host is not allowed" | `allowedHosts` doesn't include the host being requested — usually `.env`'s `VITE_BLOCKS_DEV_HOST` was edited/missing after scaffold, or the browser is hitting a different hostname than expected | Confirm `.env` has the right `VITE_BLOCKS_DEV_HOST` and that the URL bar matches it exactly |
+| Page doesn't load at all / DNS error | Hosts file entry missing or wrong | Add `127.0.0.1 <VITE_BLOCKS_DEV_HOST>` to `C:\Windows\System32\drivers\etc\hosts` (as Administrator) |
+| `npm run cert` errors "No domain given" | `.env` missing or `VITE_BLOCKS_DEV_HOST` not set | Confirm `.env` exists with `VITE_BLOCKS_DEV_HOST=<host>`, or run `npm run cert -- <domain>` explicitly |
+| `npm run dev` fails to bind the port | Port 5173 already in use (dev server uses `strictPort`, won't fall back) | Free port 5173, or the port is fixed because it's part of the registered OIDC redirect URI — don't just change it without updating the OIDC client too |
+| HTTPS works, cert trusted, login still fails | No OIDC client registered yet, or its redirect URI doesn't match this origin exactly | Register/update the public OIDC client in the portal with `https://<VITE_BLOCKS_DEV_HOST>:5173/login/callback` as a redirect URI (portal-only, see blocks-onboarding) |
+| Works for one dev, fails for a teammate | Each machine needs its own cert + hosts entry — `.cert/` is gitignored on purpose | Teammate runs `npm run cert` and adds the hosts entry on their own machine |
+
+## Example trigger prompts
+
+- "Run my app locally over HTTPS on its real domain so SSO works"
+- "My local login isn't working — it just bounces back to the login page"
+- "How do I set up the dev cert for this scaffolded app?"
+- "I'm getting 'Blocked request. This host is not allowed' from Vite"
+- "Do I need OpenSSL to run npm run cert on Windows?"
+- "Why does login work in production but not on localhost?"

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

@@ -0,0 +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.

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

@@ -0,0 +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).

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

@@ -0,0 +1,109 @@
+# 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`.
+- **`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.