@seliseblocks/cli-os 0.2.0 → 0.2.2

package/AI_USAGE_GUIDE.md

@@ -128,10 +128,10 @@ Then run with explicit flags so no prompt is reached:
 blocks new web <appName> --x-blocks-key <projectTenantId> --app-domain <appDomainOrUrl> --client-id <publicOidcClientId>
 ```
 
-`new web` also accepts `--blocks-api-url <url>` and `--oidc-url <url>`, same as `sdk client`
-below. `--blocks-api-url` defaults to `https://api.seliseblocks.com` if omitted - pass a
-different Data/IAM/Localization/OS gateway URL explicitly only if your project uses a
-non-default one. `--oidc-url` defaults to `https://iam.seliseblocks.com`.
+`new web` also accepts `--blocks-api-url <url>` and `--oidc-url <url>`, same as `sdk client`
+below. When `--blocks-api-url` is omitted, the scaffold derives it from the app domain as
+`https://blocksapi.<registrable-domain>`; for example `https://dqrsf.slsblx.com` becomes
+`https://blocksapi.slsblx.com`. Pass `--blocks-api-url` only when targeting a non-default Blocks gateway. `--oidc-url` defaults to `https://iam.seliseblocks.com`.
 
 Validate the scaffold:
 
@@ -160,10 +160,10 @@ The generated cert script uses the `selfsigned` Node dependency, so it works fro
 `sdk client` answers "I want to use the Blocks SDK - show me the client." It resolves this project's `@seliseblocks/client` config (same values `new web` scaffolds an app with) and prints a ready-to-paste `createBlocksClient(...)` snippet - **it never writes a file or mutates anything**. To scaffold a full app instead, use `new web` above.
 
 ```bash
-blocks sdk client --x-blocks-key <projectTenantId> --app-domain <appDomainOrUrl> --client-id <publicOidcClientId> --blocks-api-url https://api.seliseblocks.com
+blocks sdk client --x-blocks-key <projectTenantId> --app-domain <appDomainOrUrl> --client-id <publicOidcClientId> --blocks-api-url https://api.seliseblocks.com
 ```
 
-As with `new web`, `--blocks-api-url` already defaults to `https://api.seliseblocks.com`; only pass it explicitly if your project uses a different gateway URL. Passing both `--app-domain` and `--client-id` skips the project lookup entirely, so it needs no CLI login at all - useful for a quick, non-interactive check. Omit either one and it resolves from the selected project instead (auto-picks when there's exactly one match, otherwise lists the options and asks you to pass the flag explicitly - it does not prompt or create anything, since this command is read-only). Use `--json` for the resolved values instead of the snippet.
+Unlike `new web`, `sdk client` keeps `--blocks-api-url` defaulted to `https://api.seliseblocks.com`; only pass it explicitly if your project uses a different gateway URL. Passing both `--app-domain` and `--client-id` skips the project lookup entirely, so it needs no CLI login at all - useful for a quick, non-interactive check. Omit either one and it resolves from the selected project instead (auto-picks when there's exactly one match, otherwise lists the options and asks you to pass the flag explicitly - it does not prompt or create anything, since this command is read-only). Use `--json` for the resolved values instead of the snippet.
 
 ## Skills
 
@@ -181,9 +181,9 @@ Every other command below is project-scoped: it requires a project already selec
 
 Command families (run `blocks --help` for the full flag reference on each):
 
-- `iam users *`, `iam email available` - list/get/create/update/activate/deactivate, access grant/revoke, existence and email-availability checks.
-- `iam roles *` - list/get/create/update, assign-permissions, assignable.
-- `iam permissions *` - list/get/create/update, by-severity.
+- `iam users *`, `iam email available` - list/get/create/update/activate/deactivate, access grant/revoke, existence and email-availability checks.
+- `iam roles *` - list/get/create/update, assign-permissions, assignable. `assign-permissions` accepts permission resource strings and resolves them to itemIds before sending IAM's id-based mutation.
+- `iam permissions *` - list/get/create/update, by-severity.
 - `iam resources *` - resource groups and feature flags (read-only).
 - `iam organizations *` - list/get/create/update, `my`, and organization config get/save.
 - `iam signup-settings *` - get/save tenant signup policy.

package/README.md

@@ -95,9 +95,9 @@ Global options available on every command:
 | `blocks release status <buildId> [--json]` | Read Release build status by build id. Read-only. |
 | `blocks release builds list [repoId] [--repo-id <repoId>] [--json]` | List Release build details for a repository. When `repoId` is omitted, resolves it from the selected project's linked repo assets - auto-picked if there's exactly one, otherwise you're prompted to choose. Read-only. |
 | `blocks release builds get <buildId> [--json]` | Alias for `release status`. Read-only. |
-| `blocks new web <name> [--app-domain <domain>] [--client-id <oidcClientId>] [--x-blocks-key <tenantId>] [--blocks-api-url <url>] [--oidc-url <url>]` | Create a Vite React starter app that talks to Blocks exclusively through `@seliseblocks/client` (a single `createBlocksClient()` instance) using the SDK hosted IdP flow: `blocksClient.auth.idp.redirectToProvider()` on login click and `blocksClient.auth.idp.callback()` on `/login/callback`. Includes route guards, auto-refresh through `auth.oidc.refreshToken()`, live `auth`/`iam`/`data`/`localization` SDK examples, environment config, and safe `.gitignore` defaults. Uses the selected project (see `use`) unless `--x-blocks-key` overrides it. `--app-domain` and `--client-id` are resolved from the project record when omitted: the domain auto-picks if the project has exactly one, otherwise you're prompted to choose; the OIDC client is picked from the project's existing clients, or you can create a minimal one (display name + redirect URI) on the spot, or skip and register one later from the portal or `auth oidc-clients save`. `--blocks-api-url` defaults to `https://api.seliseblocks.com` if omitted - pass a different Data/IAM/Localization/OS gateway URL explicitly only if your project uses a non-default one. `--oidc-url` defaults to `https://iam.seliseblocks.com`. |
+| `blocks new web <name> [--app-domain <domain>] [--client-id <oidcClientId>] [--x-blocks-key <tenantId>] [--blocks-api-url <url>] [--oidc-url <url>]` | Create a Vite React starter app that talks to Blocks exclusively through `@seliseblocks/client` (a single `createBlocksClient()` instance) using the SDK hosted IdP flow: `blocksClient.auth.idp.redirectToProvider()` on login click and `blocksClient.auth.idp.callback()` on `/login/callback`. Includes route guards, auto-refresh through `auth.oidc.refreshToken()`, live `auth`/`iam`/`data`/`localization` SDK examples, environment config, and safe `.gitignore` defaults. Uses the selected project (see `use`) unless `--x-blocks-key` overrides it. `--app-domain` and `--client-id` are resolved from the project record when omitted: the domain auto-picks if the project has exactly one, otherwise you're prompted to choose; the OIDC client is picked from the project's existing clients, or you can create a minimal one (display name + redirect URI) on the spot, or skip and register one later from the portal or `auth oidc-clients save`. When `--blocks-api-url` is omitted, `new web` derives it from the app domain as `https://blocksapi.<registrable-domain>`; for example `https://dqrsf.slsblx.com` becomes `https://blocksapi.slsblx.com`. Pass a different Data/IAM/Localization/OS gateway URL explicitly only if your project uses a non-default one. `--oidc-url` defaults to `https://iam.seliseblocks.com`. |
 | `blocks skill list [--json]` / `skill show <name> [--json]` / `skill add <name> [--dir <path>]` | Local-only, no cloud calls: list/print the bundled `blocks-skills/*/SKILL.md` agent context docs, or copy a skill's entire directory (`SKILL.md` plus any supporting files) into `<dir>/<name>/` (default `./blocks-skills`) for use in a project outside this monorepo. `list`'s output and `show`/`add`'s "unknown skill" error both point at the full public skill catalog in case the bundled set is out of date. |
-| `blocks sdk client [--app-domain <domain>] [--client-id <oidcClientId>] [--x-blocks-key <tenantId>] [--blocks-api-url <url>] [--oidc-url <url>] [--json]` | Read-only: resolves this project's `@seliseblocks/client` config (same values `new web` scaffolds with) and prints a ready-to-paste `createBlocksClient(...)` snippet. Passing both `--app-domain` and `--client-id` skips the project lookup entirely (no login required). Writes nothing - use `new web` to scaffold a full app. |
+| `blocks sdk client [--app-domain <domain>] [--client-id <oidcClientId>] [--x-blocks-key <tenantId>] [--blocks-api-url <url>] [--oidc-url <url>] [--json]` | Read-only: resolves this project's `@seliseblocks/client` config and prints a ready-to-paste `createBlocksClient(...)` snippet. Unlike `new web`, the API URL defaults to `https://api.seliseblocks.com` unless `--blocks-api-url` is passed. Passing both `--app-domain` and `--client-id` skips the project lookup entirely (no login required). Writes nothing - use `new web` to scaffold a full app. |
 
 Use `--json` on commands when AI or automation needs machine-readable output. Use `--dry-run` before mutations and `--yes` only after approval.
 

package/dist/commands/data/schema/aggregation.js

@@ -6,6 +6,9 @@ import { parseCommand, selectedProject } from "../../../lib/workspace.js";
 export async function dataSchemaAggregation(argv) {
     const { flags } = parseCommand(argv);
     const projectKey = await selectedProject(flags);
+    const page = integerFlag(flags, "page", 1);
+    if (page < 1)
+        throw new Error("--page must be greater than or equal to 1");
     const result = await blocksRequest("/data/v4/schemas/aggregation", {
         impersonatedProjectAuth: true,
         ...requestContext(flags),
@@ -13,7 +16,7 @@ export async function dataSchemaAggregation(argv) {
         query: {
             CollectionName: stringFlag(flags, "collection-name") || undefined,
             Keyword: stringFlag(flags, "keyword") || undefined,
-            PageNo: integerFlag(flags, "page", 1),
+            PageNo: page,
             PageSize: integerFlag(flags, "page-size", 100),
             ProjectKey: projectKey,
             SchemaName: stringFlag(flags, "schema-name") || undefined,

package/dist/commands/iam/permissions/list.js

@@ -1,4 +1,4 @@
-import { integerFlag, optionalBooleanFlag, optionalIntegerFlag, stringFlag } from "../../../lib/args.js";
+import { booleanFlag, integerFlag, optionalBooleanFlag, optionalIntegerFlag, stringFlag } from "../../../lib/args.js";
 import { blocksRequest } from "../../../lib/api.js";
 import { compact, jsonBodyFlag, listFlag } from "../../../lib/json-flag.js";
 import { writeOutput } from "../../../lib/output.js";
@@ -7,6 +7,7 @@ import { parseCommand, selectedProject } from "../../../lib/workspace.js";
 export async function iamPermissionsList(argv) {
     const { flags } = parseCommand(argv);
     const projectKey = await selectedProject(flags);
+    const sortBy = stringFlag(flags, "sort-by");
     const filter = {
         ...(await jsonBodyFlag(flags)).filter,
         ...compact({
@@ -23,13 +24,13 @@ export async function iamPermissionsList(argv) {
     const body = {
         filter,
         organizationId: stringFlag(flags, "organization-id") || undefined,
-        page: integerFlag(flags, "page", 1),
+        page: iamBackendPage(flags),
         pageSize: integerFlag(flags, "page-size", 20),
         roles: listFlag(flags, "roles"),
-        sort: {
-            isDescending: stringFlag(flags, "sort-desc") === "true",
-            property: stringFlag(flags, "sort-by") || undefined
-        }
+        sort: sortBy ? {
+            isDescending: booleanFlag(flags, "sort-desc"),
+            property: sortBy
+        } : undefined
     };
     const result = await blocksRequest("/iam/v4/iam/permissions", {
         body,
@@ -39,3 +40,9 @@ export async function iamPermissionsList(argv) {
     });
     writeOutput(result, flags);
 }
+function iamBackendPage(flags) {
+    const page = integerFlag(flags, "page", 1);
+    if (page < 1)
+        throw new Error("--page must be greater than or equal to 1");
+    return page - 1;
+}

package/dist/commands/iam/roles/assign-permissions.js

@@ -8,10 +8,13 @@ import { parseCommand, selectedProject } from "../../../lib/workspace.js";
 export async function iamRolesAssignPermissions(argv) {
     const { args, flags } = parseCommand(argv);
     const slug = args[0] || stringFlag(flags, "slug", { required: true });
+    const addPermissions = listFlag(flags, "add-permissions");
+    const removePermissions = listFlag(flags, "remove-permissions");
+    const organizationId = stringFlag(flags, "organization-id") || undefined;
     const body = {
-        addPermissions: listFlag(flags, "add-permissions"),
-        oragnizationId: stringFlag(flags, "organization-id") || undefined,
-        removePermissions: listFlag(flags, "remove-permissions"),
+        addPermissions,
+        organizationId,
+        removePermissions,
         slug
     };
     if (!body.addPermissions && !body.removePermissions) {
@@ -21,13 +24,71 @@ export async function iamRolesAssignPermissions(argv) {
         writeOutput({ dryRun: true, endpoint: "/iam/v4/iam/roles/assign-permissions", request: body }, flags);
         return;
     }
-    await confirmMutation(flags, `Change permission assignments for IAM role '${slug}'.`);
     const projectKey = await selectedProject(flags);
+    const resolvedBody = {
+        ...body,
+        addPermissions: await resolvePermissionIdentifiers(addPermissions, organizationId, flags, projectKey),
+        removePermissions: await resolvePermissionIdentifiers(removePermissions, organizationId, flags, projectKey)
+    };
+    await confirmMutation(flags, `Change permission assignments for IAM role '${slug}'.`);
     const result = await blocksRequest("/iam/v4/iam/roles/assign-permissions", {
-        body,
+        body: resolvedBody,
         impersonatedProjectAuth: true,
         ...requestContext(flags),
         projectTenantId: projectKey
     });
     writeOutput(result, flags);
 }
+async function resolvePermissionIdentifiers(identifiers, organizationId, flags, projectKey) {
+    if (!identifiers?.length)
+        return identifiers;
+    const resources = identifiers.filter((item) => item.includes("::"));
+    if (resources.length === 0)
+        return identifiers;
+    const response = await blocksRequest("/iam/v4/iam/permissions", {
+        body: {
+            filter: {
+                isArchived: false,
+                resources
+            },
+            organizationId,
+            page: 0,
+            pageSize: Math.max(resources.length, 20)
+        },
+        impersonatedProjectAuth: true,
+        ...requestContext(flags),
+        projectTenantId: projectKey
+    });
+    const permissions = extractPermissionRows(response);
+    const byResource = new Map();
+    for (const permission of permissions) {
+        const resource = stringProperty(permission, "resource");
+        const itemId = stringProperty(permission, "itemId") || stringProperty(permission, "_id") || stringProperty(permission, "id");
+        if (resource && itemId)
+            byResource.set(resource, itemId);
+    }
+    const missing = resources.filter((resource) => !byResource.has(resource));
+    if (missing.length > 0) {
+        throw new Error(`Could not resolve IAM permission resource(s) to itemId: ${missing.join(", ")}`);
+    }
+    return identifiers.map((identifier) => byResource.get(identifier) ?? identifier);
+}
+function extractPermissionRows(response) {
+    if (Array.isArray(response))
+        return response.filter(isRecord);
+    if (!isRecord(response))
+        return [];
+    for (const key of ["data", "Data", "items", "Items", "permissions", "Permissions"]) {
+        const value = response[key];
+        if (Array.isArray(value))
+            return value.filter(isRecord);
+    }
+    return [];
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function stringProperty(record, name) {
+    const value = record[name] ?? record[name[0].toUpperCase() + name.slice(1)];
+    return typeof value === "string" ? value : "";
+}

package/dist/commands/iam/roles/list.js

@@ -1,4 +1,4 @@
-import { integerFlag, stringFlag } from "../../../lib/args.js";
+import { booleanFlag, integerFlag, stringFlag } from "../../../lib/args.js";
 import { blocksRequest } from "../../../lib/api.js";
 import { compact, jsonBodyFlag, listFlag } from "../../../lib/json-flag.js";
 import { writeOutput } from "../../../lib/output.js";
@@ -7,6 +7,7 @@ import { parseCommand, selectedProject } from "../../../lib/workspace.js";
 export async function iamRolesList(argv) {
     const { flags } = parseCommand(argv);
     const projectKey = await selectedProject(flags);
+    const sortBy = stringFlag(flags, "sort-by");
     const filter = {
         ...(await jsonBodyFlag(flags)).filter,
         ...compact({
@@ -17,12 +18,12 @@ export async function iamRolesList(argv) {
     const body = {
         filter,
         organizationId: stringFlag(flags, "organization-id") || undefined,
-        page: integerFlag(flags, "page", 1),
+        page: iamBackendPage(flags),
         pageSize: integerFlag(flags, "page-size", 20),
-        sort: {
-            isDescending: stringFlag(flags, "sort-desc") === "true",
-            property: stringFlag(flags, "sort-by") || undefined
-        }
+        sort: sortBy ? {
+            isDescending: booleanFlag(flags, "sort-desc"),
+            property: sortBy
+        } : undefined
     };
     const result = await blocksRequest("/iam/v4/iam/roles", {
         body,
@@ -32,3 +33,9 @@ export async function iamRolesList(argv) {
     });
     writeOutput(result, flags);
 }
+function iamBackendPage(flags) {
+    const page = integerFlag(flags, "page", 1);
+    if (page < 1)
+        throw new Error("--page must be greater than or equal to 1");
+    return page - 1;
+}

package/dist/commands/new/web.js

@@ -2,6 +2,7 @@ import { stringFlag } from "../../lib/args.js";
 import { blocksRequest } from "../../lib/api.js";
 import { confirmMutation } from "../../lib/confirm.js";
 import { defaults, readConfig, writeConfig } from "../../lib/config.js";
+import { apiUrlFromAppDomain } from "../../lib/domains.js";
 import { CliActionableError } from "../../lib/errors.js";
 import { findProjectByTenantId } from "../../lib/project-info.js";
 import { promptText, selectFromList } from "../../lib/prompt.js";
@@ -16,9 +17,9 @@ export async function newWeb(argv) {
     const tenantId = stringFlag(flags, "x-blocks-key") || (await selectedProject(flags));
     const explicitAppDomain = stringFlag(flags, "app-domain");
     const project = explicitAppDomain ? {} : (await findProjectByTenantId(tenantId, flags)).project;
-    const apiUrl = stringFlag(flags, "blocks-api-url", { defaultValue: defaults().apiUrl });
     const oidcUrl = stringFlag(flags, "oidc-url", { defaultValue: defaults().oidcUrl });
     const appDomain = await resolveAppDomain(project, flags);
+    const apiUrl = stringFlag(flags, "blocks-api-url") || apiUrlFromAppDomain(appDomain);
     const oidcClientId = await resolveOidcClientId(tenantId, appDomain, name, flags);
     await scaffoldWebProject({
         apiUrl,

package/dist/index.js

@@ -1089,9 +1089,11 @@ Scaffold:
     name + redirect URI, active, registered as a Blocks OIDC identity
     provider) on the spot, or skip and register one later from the portal or
     'auth oidc-clients save'.
-    --blocks-api-url defaults to https://api.seliseblocks.com if omitted -
-    pass a different Data/IAM/Localization/OS gateway URL explicitly only if
-    your project uses a non-default one.
+    If --blocks-api-url is omitted, it is derived from the app domain:
+    https://blocksapi.<registrable-domain> (for example, app domain
+    https://dqrsf.slsblx.com uses https://blocksapi.slsblx.com). Pass a
+    different Data/IAM/Localization/OS gateway URL explicitly only if your
+    project uses a non-default one.
     --oidc-url defaults to https://iam.seliseblocks.com.
 
 Skills:
@@ -1109,11 +1111,12 @@ Skills:
 SDK:
   blocks sdk client [--app-domain <domain>] [--client-id <oidcClientId>]
                     [--x-blocks-key <tenantId>] [--blocks-api-url <url>] [--oidc-url <url>] [--json]
-    Read-only: "I want to use the Blocks SDK -- show me the client." Resolves this
-    project's @seliseblocks/client config (same values 'new web' scaffolds with,
-    using the selected project unless --x-blocks-key overrides it, and the
-    project's registered domain/OIDC client when --app-domain/--client-id are
-    omitted) and prints a ready-to-paste createBlocksClient(...) snippet.
+    Read-only: "I want to use the Blocks SDK -- show me the client." Resolves this
+    project's @seliseblocks/client config using the selected project unless
+    --x-blocks-key overrides it, and the project's registered domain/OIDC client
+    when --app-domain/--client-id are omitted. Its API URL defaults to
+    https://api.seliseblocks.com unless --blocks-api-url is passed.
+    Prints a ready-to-paste createBlocksClient(...) snippet.
     Passing both --app-domain and --client-id skips the project lookup entirely
     (no login required). Never writes a file; to scaffold a new app use 'new web'.
 `);

package/dist/lib/domains.d.ts

@@ -0,0 +1,2 @@
+export declare function hostFromAppDomain(appDomain: string): string;
+export declare function apiUrlFromAppDomain(appDomain: string): string;

package/dist/lib/domains.js

@@ -0,0 +1,14 @@
+export function hostFromAppDomain(appDomain) {
+    try {
+        return new URL(appDomain).host;
+    }
+    catch {
+        return appDomain.replace(/^https?:\/\//, "").replace(/\/.*$/, "");
+    }
+}
+export function apiUrlFromAppDomain(appDomain) {
+    const hostname = hostFromAppDomain(appDomain).split(":")[0].toLowerCase();
+    const labels = hostname.split(".").filter(Boolean);
+    const registrableDomain = labels.length >= 2 ? labels.slice(-2).join(".") : hostname;
+    return `https://blocksapi.${registrableDomain}`;
+}

package/dist/lib/scaffold-web/fs.d.ts

@@ -1,2 +1,3 @@
+import { hostFromAppDomain } from "../domains.js";
+export { hostFromAppDomain };
 export declare function write(root: string, path: string, content: string): Promise<void>;
-export declare function hostFromAppDomain(appDomain: string): string;

package/dist/lib/scaffold-web/fs.js

@@ -1,15 +1,9 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
+import { hostFromAppDomain } from "../domains.js";
+export { hostFromAppDomain };
 export async function write(root, path, content) {
     const fullPath = join(root, path);
     await mkdir(dirname(fullPath), { recursive: true });
     await writeFile(fullPath, `${content.endsWith("\n") ? content : `${content}\n`}`);
 }
-export function hostFromAppDomain(appDomain) {
-    try {
-        return new URL(appDomain).host;
-    }
-    catch {
-        return appDomain.replace(/^https?:\/\//, "").replace(/\/.*$/, "");
-    }
-}

package/dist/lib/scaffold-web/root-files.js

@@ -8,6 +8,14 @@ export async function writeRootFiles(root, options) {
         type: "module",
         scripts: {
             build: "vite build",
+            "build:dev": "vite build --mode dev && node scripts/write-release-env.mjs dev",
+            "build:test": "vite build --mode test && node scripts/write-release-env.mjs test",
+            "build:stg": "vite build --mode stg && node scripts/write-release-env.mjs stg",
+            "build:iat": "vite build --mode iat && node scripts/write-release-env.mjs iat",
+            "build:uat": "vite build --mode uat && node scripts/write-release-env.mjs uat",
+            "build:preprod": "vite build --mode preprod && node scripts/write-release-env.mjs preprod",
+            "build:prodshadow": "vite build --mode prodshadow && node scripts/write-release-env.mjs prodshadow",
+            "build:prod": "vite build --mode prod && node scripts/write-release-env.mjs prod",
             cert: "node scripts/generate-cert.mjs",
             dev: "vite",
             lint: "tsc --noEmit",
@@ -74,9 +82,76 @@ export async function writeRootFiles(root, options) {
         ".env",
         ".env.local",
         ".env.*.local",
+        "env.*",
         ".cert/",
         ""
     ].join("\n"));
+    await write(root, "nginx.conf", [
+        "server {",
+        "  listen 8080;",
+        "  root /usr/share/nginx/html/;",
+        "  server_tokens off;",
+        "  client_max_body_size 200m;",
+        "",
+        "  gzip on;",
+        "  gzip_comp_level 6;",
+        "  gzip_min_length 1000;",
+        "  gzip_proxied expired no-cache no-store private auth;",
+        "  gzip_types text/plain application/x-javascript text/xml text/css application/xml text/javascript application/javascript application/json application/font-woff application/font-woff2 application/vnd.ms-fontobject application/x-font-ttf font/opentype;",
+        "",
+        "  location / {",
+        "    try_files $uri $uri/ /index.html;",
+        "  }",
+        "}",
+        ""
+    ].join("\n"));
+    await write(root, "Dockerfile", [
+        "FROM node:22-alpine AS builder",
+        "",
+        "WORKDIR /app",
+        "",
+        "COPY package*.json ./",
+        "",
+        "RUN if [ -f package-lock.json ]; then npm ci; else npm install; fi",
+        "",
+        "COPY . .",
+        "",
+        "ARG ci_build=dev",
+        "ARG VITE_BLOCKS_API_URL",
+        "ARG VITE_BLOCKS_PROJECT_KEY",
+        "ARG VITE_BLOCKS_X_BLOCKS_KEY",
+        "ARG VITE_BLOCKS_APP_DOMAIN",
+        "ARG VITE_BLOCKS_OIDC_URL=https://iam.seliseblocks.com",
+        "ARG VITE_BLOCKS_OIDC_CLIENT_ID",
+        "ARG VITE_BLOCKS_OIDC_SCOPE=\"openid profile\"",
+        "ARG VITE_BLOCKS_REDIRECT_URI",
+        "ARG VITE_BLOCKS_HOSTED_LOGIN=true",
+        "",
+        "ENV VITE_BLOCKS_API_URL=${VITE_BLOCKS_API_URL}",
+        "ENV VITE_BLOCKS_PROJECT_KEY=${VITE_BLOCKS_PROJECT_KEY}",
+        "ENV VITE_BLOCKS_X_BLOCKS_KEY=${VITE_BLOCKS_X_BLOCKS_KEY}",
+        "ENV VITE_BLOCKS_APP_DOMAIN=${VITE_BLOCKS_APP_DOMAIN}",
+        "ENV VITE_BLOCKS_OIDC_URL=${VITE_BLOCKS_OIDC_URL}",
+        "ENV VITE_BLOCKS_OIDC_CLIENT_ID=${VITE_BLOCKS_OIDC_CLIENT_ID}",
+        "ENV VITE_BLOCKS_OIDC_SCOPE=${VITE_BLOCKS_OIDC_SCOPE}",
+        "ENV VITE_BLOCKS_REDIRECT_URI=${VITE_BLOCKS_REDIRECT_URI}",
+        "ENV VITE_BLOCKS_HOSTED_LOGIN=${VITE_BLOCKS_HOSTED_LOGIN}",
+        "",
+        "RUN NODE_OPTIONS=\"--max-old-space-size=4096\" npx vite build --mode \"${ci_build}\" \\",
+        "  && node scripts/write-release-env.mjs \"${ci_build}\"",
+        "",
+        "FROM nginxinc/nginx-unprivileged:1.29-alpine",
+        "",
+        "COPY --from=builder /app/dist /usr/share/nginx/html",
+        "",
+        "COPY nginx.conf /etc/nginx/conf.d/default.conf",
+        "",
+        "EXPOSE 8080",
+        "",
+        "# HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \\",
+        "#   CMD wget -qO- http://localhost:8080/ || exit 1",
+        ""
+    ].join("\n"));
     await write(root, "README.md", [
         `# ${options.name}`,
         "",
@@ -116,6 +191,12 @@ export async function writeRootFiles(root, options) {
         "",
         "`.cert/` is gitignored — each developer generates and trusts their own cert.",
         "",
+        "## Blocks Release deployment",
+        "",
+        "The scaffold includes `Dockerfile` and `nginx.conf` for Blocks Release. The Release service must pass Docker build arg `ci_build=<environment>` plus the public `VITE_BLOCKS_*` build args documented in the Dockerfile. The generated `package.json` also provides `build:dev`, `build:test`, `build:stg`, `build:iat`, `build:uat`, `build:preprod`, `build:prodshadow`, and `build:prod` scripts for local checks.",
+        "",
+        "During each environment build, `scripts/write-release-env.mjs` writes `dist/env.<environment>` from client-safe Docker build args or local `.env` files. Root `.env` remains gitignored and must not be committed.",
+        "",
         "## What's included",
         "",
         "- `/login` — login page (redirects to Blocks IAM).",
@@ -275,4 +356,81 @@ export async function writeRootFiles(root, options) {
         "}",
         ""
     ].join("\n"));
+    await write(root, "scripts/write-release-env.mjs", [
+        "#!/usr/bin/env node",
+        "// Writes the client-safe Blocks env snapshot into dist for release artifacts.",
+        "import { existsSync, mkdirSync, readFileSync, writeFileSync } from \"node:fs\";",
+        "import { join } from \"node:path\";",
+        "",
+        "const mode = (process.argv[2] || \"dev\").trim();",
+        "if (!mode) {",
+        "  console.error(\"Usage: node scripts/write-release-env.mjs <environment>\");",
+        "  process.exit(1);",
+        "}",
+        "",
+        "const env = readEnv(mode);",
+        "const appDomain = env.VITE_BLOCKS_APP_DOMAIN || \"\";",
+        "const redirectUri = env.VITE_BLOCKS_REDIRECT_URI || callbackUri(appDomain);",
+        "const projectKey = env.VITE_BLOCKS_X_BLOCKS_KEY || env.VITE_BLOCKS_PROJECT_KEY || \"\";",
+        "",
+        "const output = [",
+        "  \"# SELISE Blocks production/default configuration.\",",
+        "  \"# Only client-safe values belong here. Never put passwords, PTOKs, JWTs,\",",
+        "  \"# refresh tokens, cookies, or client secrets in VITE_-prefixed variables.\",",
+        "  \"\",",
+        "  `VITE_BLOCKS_API_URL=${env.VITE_BLOCKS_API_URL || \"\"}`,",
+        "  `VITE_BLOCKS_PROJECT_KEY=${projectKey}`,",
+        "  `VITE_BLOCKS_X_BLOCKS_KEY=${projectKey}`,",
+        "  `VITE_BLOCKS_APP_DOMAIN=${appDomain}`,",
+        "  `VITE_BLOCKS_OIDC_URL=${env.VITE_BLOCKS_OIDC_URL || \"\"}`,",
+        "  `VITE_BLOCKS_OIDC_CLIENT_ID=${env.VITE_BLOCKS_OIDC_CLIENT_ID || \"\"}`,",
+        "  `VITE_BLOCKS_OIDC_SCOPE=${env.VITE_BLOCKS_OIDC_SCOPE || \"openid profile\"}`,",
+        "  `VITE_BLOCKS_REDIRECT_URI=${redirectUri}`,",
+        "  \"VITE_BLOCKS_HOSTED_LOGIN=true\",",
+        "  \"\"",
+        "].join(\"\\n\");",
+        "",
+        "mkdirSync(\"dist\", { recursive: true });",
+        "writeFileSync(join(\"dist\", `env.${mode}`), output);",
+        "console.log(`Wrote dist/env.${mode}`);",
+        "",
+        "function readEnv(mode) {",
+        "  const result = {};",
+        "  for (const file of [\".env\", `.env.${mode}`, \".env.local\", `.env.${mode}.local`]) {",
+        "    if (!existsSync(file)) continue;",
+        "    Object.assign(result, parseEnv(readFileSync(file, \"utf8\")));",
+        "  }",
+        "  for (const [key, value] of Object.entries(process.env)) {",
+        "    if (!key.startsWith(\"VITE_BLOCKS_\") || value === undefined) continue;",
+        "    result[key] = value;",
+        "  }",
+        "  return result;",
+        "}",
+        "",
+        "function parseEnv(content) {",
+        "  const values = {};",
+        "  for (const rawLine of content.split(/\\r?\\n/)) {",
+        "    const line = rawLine.trim();",
+        "    if (!line || line.startsWith(\"#\")) continue;",
+        "    const equals = line.indexOf(\"=\");",
+        "    if (equals < 1) continue;",
+        "    const key = line.slice(0, equals).trim();",
+        "    let value = line.slice(equals + 1).trim();",
+        "    if ((value.startsWith(\"\\\"\") && value.endsWith(\"\\\"\")) || (value.startsWith(\"'\") && value.endsWith(\"'\"))) {",
+        "      value = value.slice(1, -1);",
+        "    }",
+        "    values[key] = value;",
+        "  }",
+        "  return values;",
+        "}",
+        "",
+        "function callbackUri(appDomain) {",
+        "  if (!appDomain) return \"\";",
+        "  const origin = appDomain.startsWith(\"http://\") || appDomain.startsWith(\"https://\")",
+        "    ? appDomain.replace(/\\/+$/, \"\")",
+        "    : `https://${appDomain.replace(/\\/+$/, \"\")}`;",
+        "  return `${origin}/login/callback`;",
+        "}",
+        ""
+    ].join("\n"));
 }

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

@@ -103,6 +103,7 @@ blocks iam roles assign-permissions editor --add-permissions content::publish --
 
 - **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.

package/dist/skills/blocks-onboarding/SKILL.md

@@ -66,7 +66,7 @@ Run `blocks init` once per project directory to create `blocks.json`, `blocks/da
 Then route to what the user actually wants:
 - Building a frontend from scratch → resolve the app's public OIDC client first, then scaffold:
   - `blocks auth oidc-clients list --json` — check whether a client already registered for this project fits. If none fits, create one directly (no portal visit needed): `blocks auth oidc-clients save --client-display-name <appName> --redirect-uris https://<domain>:5173/login/callback --scope "openid profile" --require-pkce --register-as-identity-provider --dry-run --json`, then re-run with `--yes` after showing the dry-run output and getting approval. See the blocks-iam-sso-oidc-configuration skill for the full decision tree and field-level gotchas.
-  - `blocks new web <name> --x-blocks-key <tenantId> --app-domain <domain> --blocks-api-url https://api.seliseblocks.com --client-id <the-resolved-client-id>`. **Always pass `--client-id` and `--app-domain` explicitly** — omitting either drops `new web` into an interactive pick-list prompt with no non-interactive escape (not even to "skip"), which hangs a scripted/agent run with no stdin to answer it.
+  - `blocks new web <name> --x-blocks-key <tenantId> --app-domain <domain> --client-id <the-resolved-client-id>`. **Always pass `--client-id` and `--app-domain` explicitly** — omitting either drops `new web` into an interactive pick-list prompt with no non-interactive escape (not even to "skip"), which hangs a scripted/agent run with no stdin to answer it. Omit `--blocks-api-url` unless the project uses a non-default gateway; the scaffold derives it from the app domain, e.g. `https://dqrsf.slsblx.com` -> `https://blocksapi.slsblx.com`.
 - Defining data / CRUD / localization / release on an existing project → hand off to the matching skill; the project is already selected via `blocks use`, so its commands can proceed directly.
 
 ## Gotchas

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seliseblocks/cli-os",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "CLI for SELISE Blocks project setup and configuration.",
   "license": "MIT",
   "type": "module",