@seliseblocks/cli-os 0.1.4 → 0.1.5

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

@@ -0,0 +1,69 @@
+---
+name: blocks-notification
+description: "Manage SELISE Blocks notification-channel configuration via `blocks notification *` — no SDK path exists (`@seliseblocks/client` has no `notification` namespace, only the unrelated real-time `notifier` surface). Covers `notification list`/`get` (read configs) and `notification save`/`delete` (project-scoped mutations, impersonated-project-token only). Use for 'list/get notification configs', 'save/update a channel', 'delete a config'. Always `--dry-run` before `--yes` on save/delete."
+---
+
+# Blocks Notification — Channel Configuration
+
+Manage notification-channel configuration through `blocks notification *`. This is **100% CLI, no SDK equivalent** — `@seliseblocks/client` has no `notification` namespace at all. It does have a `notifier` namespace (backing `blocks notifier *`), but that's a **different, unrelated surface**: `notifier` pushes real-time/offline notifications and reads a user's own inbox; `notification` (this skill) manages the tenant's notification *channel configuration* — which channel/method a notification type uses, not sending one. Never write a frontend/app-code path for channel configuration — it's always this CLI.
+
+**Prerequisite:** a project is selected (`blocks use <tenantId>`, or pass `--project <tenantId>`) — see the blocks-onboarding skill. Every one of the four commands requires an impersonated project session; there is no account-level mode for any of them.
+
+## Safe read commands
+
+- **`blocks notification list [--page <n>] [--page-size <n>] [--sort-by <property>] [--sort-desc] [--filter <text>] [--json]`** — read-only.
+- **`blocks notification get <itemId> [--json]`** — `itemId` may be given positionally or as `--id <itemId>`; one of the two is required (the command throws `Missing --id` if neither is given). Read-only.
+
+Neither read command mutates anything and neither accepts `--dry-run` (there's nothing to preview — no request body is built, no confirmation gate exists for either).
+
+## Mutating: save (create or update a channel config)
+
+```bash
+blocks notification save --name <n> --channel <0|1> --type <0-3> --dry-run --json   # preview first
+blocks notification save --name <n> --channel <0|1> --type <0-3> --yes --json        # only after approval
+blocks notification save --update --body '<json>' --yes --json                       # full custom payload
+```
+
+The request body is built by merging (in this order, later keys win) whatever `--body '<json>'` or `--file <path.json>` supplies, then these convenience flags layered on top (so an unset convenience flag never overwrites a value from `--body`/`--file`):
+
+| Flag | Body field | Notes |
+|---|---|---|
+| `--channel <int>` | `channelToNotify` | Raw integer — the CLI does **not** validate or enum-check the value itself. |
+| `--type <int>` | `notificationType` | Same — raw integer, no validation in the command. |
+| `--enable-persistence` | `enablePersistence` | Boolean flag; only ever sent as `true` when passed — passing it absent never sends an explicit `false`. |
+| `--update` | `isUpdateRequest` | Same true-only pattern as `--enable-persistence`. Set this when saving over an existing config rather than creating a new one. |
+| `--name <text>` | `name` | |
+| `--notify-method <text>` | `notifyMethod` | |
+
+`--dry-run` prints the resolved request and returns — no network call, no confirmation prompt. Without `--dry-run`, it prompts interactively for a typed `yes` before sending (unless `--yes` is also passed); only then does it resolve the selected project and issue the request. Always show `--dry-run` output and get explicit approval before re-running with `--yes`.
+
+`--channel`/`--type` don't have machine-readable names published by the API; the CLI's own usage docs note they correspond to the OS API's channel/receiver-type enums (`--channel` roughly `0|1`, `--type` roughly `0-3`) — treat those ranges as documentation convention, not something this command enforces, and ask the user for the exact intended value rather than guessing one.
+
+## Mutating: delete
+
+```bash
+blocks notification delete <itemId> --dry-run --json
+blocks notification delete <itemId> --yes --json
+```
+
+Same `itemId` resolution as `get` — positional arg or `--id`, one required. `--dry-run` prints the resolved query and returns; otherwise it goes through the same confirmation gate as `save` (interactive `yes` prompt unless `--yes` is passed) before resolving the project and sending the request.
+
+## Gotchas
+
+- **No SDK path, ever.** If asked "how do I manage notification channels from my app," the answer is: you don't — this is CLI-only, human/CI-operated configuration, not something to wire into frontend or backend app code.
+- **`notification` and `notifier` are not the same thing.** `notification save/list/get/delete` (this skill) configures *which channel/method* a notification type uses. `notifier notify/list/unread/mark-read/mark-all-read` *sends* notifications and reads a user's inbox — a separate command family with its own commands, not covered here. Don't answer a "send a notification" request with `notification save`, and don't answer a "configure the notification channel" request with `notifier`.
+- **`list` and `get` have no `--dry-run`.** Only `save` and `delete` build a request that's worth previewing; the two read commands hit the API directly. Don't tell a user to `--dry-run` a `list` or `get` call.
+- **`--enable-persistence` and `--update` are true-only flags.** Passing them sets the field to `true`; not passing them omits the field entirely (never sends an explicit `false`). If a user wants to explicitly *unset* persistence or force a plain create, that has to go through `--body`/`--file` directly, not the convenience flag.
+- **`--channel`/`--type` are unvalidated raw integers.** The command will happily send any integer you give it — there's no local check against the underlying enums. Confirm the intended value with the user (or check the Blocks portal/API docs) rather than inventing one.
+- **`itemId` for `get`/`delete` is always required**, positional or `--id` — never guessed. Ask the user rather than assuming a value.
+- **Every command is project-scoped.** All four require a resolved project and an impersonated project token; behavior follows whichever project is currently selected via `blocks use` (or an explicit `--project` override).
+- **`--dry-run` before `--yes`, always**, on `save` and `delete` — same discipline as every other mutating `blocks` command in this pack.
+
+## Example trigger prompts
+
+- "List the notification channel configs for this project."
+- "Get notification config `<itemId>`."
+- "Save a new notification config named `<name>` on channel 0, type 1." → preview with `--dry-run` first.
+- "Update the existing `<name>` notification config." → add `--update`, still `--dry-run` before `--yes`.
+- "Delete notification config `<itemId>`."
+- "Send a notification to these users" / "show me a user's unread notifications" → not this skill; that's `blocks notifier *`, a different command family for sending/reading, not channel configuration.

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

@@ -0,0 +1,107 @@
+---
+name: blocks-notifier
+description: "Push real-time/offline notifications and manage a signed-in user's own notification inbox, via both the SDK (`blocksClient.notifier.*`) and the CLI (`blocks notifier notify|list|unread|mark-read|mark-all-read`). Distinct from the sibling blocks-notification skill, which configures tenant notification-*channel* settings on a different backing service, not sending. `notifier unread` flattens its subscription filter into GET query params since Fetch forbids a GET body. `--dry-run` before `--yes` on CLI `notify`/`mark-read`/`mark-all-read`."
+---
+
+# Blocks Notifier — Send & Inbox
+
+`notifier` pushes real-time/offline notifications to users, roles, or subscription-filter matches, and reads/manages the signed-in user's own notification inbox. This is a **separate, deliberate concern from the blocks-notification skill**, which manages a tenant's notification-*channel configuration* — which channel/method a notification type uses — on an unrelated backing service. Both this skill and the sibling skill confirm the same distinction from their own side. Don't merge them, and don't reconcile them as if one were a typo for the other — they hit different backing services. If the ask is "configure which channel a notification type uses," route to the blocks-notification skill instead.
+
+Unlike `blocks-notification` (100% CLI, no SDK path), **`notifier` has both a CLI and an SDK surface**, and every one of the five operations exists on both:
+
+| Operation | CLI | SDK (`blocksClient.notifier.*`) |
+|---|---|---|
+| Send a notification | `blocks notifier notify` | `notify(request)` |
+| List the inbox | `blocks notifier list` | `getNotifications(options)` |
+| Unread by subscription filter | `blocks notifier unread` | `getUnreadNotificationsBySubscriptionFilter(request)` |
+| Mark one read | `blocks notifier mark-read <id>` | `markNotificationAsRead(request)` |
+| Mark all read | `blocks notifier mark-all-read` | `markAllNotificationAsRead()` |
+
+## CLI — `blocks notifier *`
+
+Every CLI command is project-scoped: each requires an impersonated project session — there is no account-level mode for any of the five. Project resolution follows the same order as everywhere else in this CLI: `--project <tenantId>` flag, then the workspace's `blocks.json`, then the globally selected project from `blocks use <tenantId>`. See the blocks-onboarding skill if no project is selected yet.
+
+- **`blocks notifier notify [--user-ids a,b] [--roles a,b] [--connection-id <id>] [--configuration-name <n>] [--subscription-filters '<json>'] [--denormalized-payload <text>] [--save-denormalized-payload-as-object] [--content-available] [--response-key <k>] [--response-value <v>] [--body '<json>'|--file <path>] [--dry-run] [--yes] [--json]`** — target with at least one of `--user-ids`/`--roles`/`--subscription-filters`. `--user-ids` and `--roles` are comma-separated lists; `--subscription-filters` is a raw JSON array string (e.g. `[{"context":"orders","actionName":"created","value":"*"}]`, matching `BlocksNotifierSubscriptionFilter[]`). The body is built by merging `--body`/`--file` first, then layering the convenience flags on top — so an explicit convenience flag always wins over the same field in `--body`/`--file`, and an unset one never overwrites what `--body`/`--file` supplied. `--content-available` and `--save-denormalized-payload-as-object` are true-only booleans (absent when not passed, never an explicit `false`).
+- **`blocks notifier list [--unread-only] [--page <n>] [--page-size <n>] [--sort-by <property>] [--sort-desc] [--filter <text>] [--json]`** — read-only.
+- **`blocks notifier unread [--user-id <id>] [--context <c>] [--action-name <a>] [--value <v>] [--order-by <1|2>] [--json]`** — read-only. See "The GET-with-a-body quirk" below.
+- **`blocks notifier mark-read <id> [--dry-run] [--yes] [--json]`** — `id` may be positional or `--id`; one of the two is required (`Missing --id` if neither given).
+- **`blocks notifier mark-all-read [--dry-run] [--yes] [--json]`** — no body/arguments needed.
+
+### The GET-with-a-body quirk (`unread`)
+
+This operation is documented upstream as a read with a JSON request body, which the Fetch spec forbids sending on a plain GET-style read. Both the CLI and SDK work around it the same way: flatten the filter fields into the query string instead. Confirmed field names, read directly from source:
+
+```
+UserId
+SubscriptionFilterData.Context
+SubscriptionFilterData.ActionName
+SubscriptionFilterData.Value
+OrderBy
+```
+
+CLI flags map to them as `--user-id` -> `UserId`, `--context` -> `SubscriptionFilterData.Context`, `--action-name` -> `SubscriptionFilterData.ActionName`, `--value` -> `SubscriptionFilterData.Value`, `--order-by` -> `OrderBy` (an integer, `1|2` per the SDK type — its enum meaning isn't published anywhere, so treat it as opaque and confirm with the user rather than guessing which value means what).
+
+This flattening is a **client-side inference, not something verified against a live call** — both the CLI and SDK made the same choice independently, which is corroborating but not proof the real backend accepts it. If a live `notifier unread` call ever errors, re-check this against the actual API response rather than assuming the flattening above is still correct.
+
+## SDK — `blocksClient.notifier.*`
+
+```ts
+import { blocksClient } from "../../lib/blocks/client";
+
+await blocksClient.notifier.notify({
+  userIds: ["user-1"],
+  roles: ["admin"],
+  denormalizedPayload: '{"orderId":"123"}',
+  saveDenormalizedPayloadAsAnObject: true
+});
+
+const inbox = await blocksClient.notifier.getNotifications({ isUnreadOnly: true, page: 1, pageSize: 20 });
+
+const unread = await blocksClient.notifier.getUnreadNotificationsBySubscriptionFilter({
+  userId: "user-1",
+  subscriptionFilterData: { context: "orders", actionName: "created" }
+});
+
+await blocksClient.notifier.markNotificationAsRead({ id: notificationId });
+await blocksClient.notifier.markAllNotificationAsRead();
+```
+
+- **`notify(request: BlocksNotifyRequest)`** — fields: `configurationName?`, `connectionId?`, `contentAvailable?: boolean`, `denormalizedPayload?: string`, `responseKey?`, `responseValue?`, `roles?: string[]`, `saveDenormalizedPayloadAsAnObject?: boolean`, `subscriptionFilters?: BlocksNotifierSubscriptionFilter[]`, `userIds?: string[]`.
+- **`getUnreadNotificationsBySubscriptionFilter(request)`** — fields: `orderBy?: 1 | 2` (opaque enum), `subscriptionFilterData?: { actionName?, context?, value? }`, `userId?`. Internally builds the same flattened query as the CLI (see above) — this is the SDK-side half of the same documented workaround.
+- **`getNotifications(options: BlocksGetNotificationsOptions = {})`** — options: `filter?`, `isUnreadOnly?`, `page?`, `pageSize?`, `sortBy?`, `sortDescending?`. Response shape: `{ notifications: Record<string, unknown>[], totalNotificationsCount: number, unReadNotificationsCount: number }`.
+- **`markAllNotificationAsRead()`** — no arguments.
+- **`markNotificationAsRead(request: BlocksMarkNotificationAsReadRequest)`** — request: `{ id: string }`.
+
+`BlocksOfflineNotification` (the shape of items `getUnreadNotificationsBySubscriptionFilter` resolves to) is a loose `Record<string, unknown>` plus known fields `correlationId?`, `createdTime?`, `denormalizedPayload?`, `id?`, `isRead?`, `payload?`, `readByRoles?: string[]`, `readByUserIds?: string[]`. `BlocksNotifierPassThroughResponse` (the `notify`/mark-read/mark-all-read return type) is an untyped `Record<string, unknown>` — the SDK doesn't shape it further; don't assume fields beyond what a live response actually contains.
+
+The SDK methods don't take a project/tenant argument per call — project context comes from however the app's shared `blocksClient` instance was constructed (its `xBlocksKey`/`appDomain`), same as every other `blocksClient.*` namespace. Don't create a second client just for notifier calls.
+
+## Mutation discipline (CLI only)
+
+`notify`, `mark-read`, and `mark-all-read` are the three CLI mutations, and all three follow the same two-gate pattern used throughout this CLI:
+
+1. **`--dry-run`** short-circuits before any network call or confirmation prompt, printing a preview of what would be sent (`mark-all-read`'s preview has no request body since it sends none).
+2. Without `--dry-run`, a confirmation step accepts `--yes` outright or, interactively, prompts to type "yes" to continue, and cancels on anything else.
+
+Always show the `--dry-run` output and get explicit approval before re-running with `--yes`. `list` and `unread` are read-only and have neither flag — don't tell a user to `--dry-run` a `list` or `unread` call. The SDK methods have no equivalent gate at all; that discipline is a CLI-only convention for terminal/CI operators, not something app code needs to replicate.
+
+## Gotchas
+
+- **`notifier` and `notification` are not the same thing, and this is not an oversight to fix.** `notifier` (this skill) sends notifications and reads a user's inbox, on both CLI and SDK. `notification` (the sibling skill) configures a tenant's notification channel settings, CLI-only. Don't answer a "send a notification" ask with `notification save`, and don't answer a "configure the channel" ask with `notifier`.
+- **`notifier unread`'s query-param flattening is an inferred client-side workaround for a Fetch-spec conflict, not verified against a live call.** See "The GET-with-a-body quirk" above. If it ever errors in practice, re-check whether the real endpoint tolerates a body server-side (some non-browser/non-Node HTTP stacks do) before assuming the flattening itself is broken.
+- **`--content-available` and `--save-denormalized-payload-as-object` on `notify` are true-only flags.** Passing them sends `true`; omitting them omits the field entirely — there's no way to send an explicit `false` through the convenience flags (use `--body`/`--file` for that).
+- **Convenience flags on `notify` win over `--body`/`--file`.** The merge order is `--body`/`--file` first, then the individual flags spread on top — so a flag like `--connection-id` always overrides the same key in `--body` if both are given.
+- **`order-by` (both CLI `--order-by` and SDK `orderBy`) is an opaque `1|2` enum** — its meaning isn't published anywhere. Ask the user or confirm from the live API rather than guessing which value sorts which way.
+- **Every CLI command is project-scoped**; there's no account-level mode. The SDK has no per-call project argument — it inherits whatever project the shared `blocksClient` was configured for.
+- **`mark-read`'s `id` (positional or `--id`) is always required** — never guessed or defaulted.
+- **`--dry-run` before `--yes`, always**, on the three CLI mutations — same discipline as every other mutating `blocks` command in this pack.
+
+## Example trigger prompts
+
+- "Send a notification to these user IDs from my app." -> SDK `blocksClient.notifier.notify({ userIds: [...] })`.
+- "Push a notification to everyone matching this subscription filter." -> SDK `notify({ subscriptionFilters: [...] })`, or `blocks notifier notify --subscription-filters '<json>' --dry-run --json` from the terminal.
+- "Show me a user's unread notifications for the 'orders' context." -> `blocks notifier unread --user-id <id> --context orders --json`, or SDK `getUnreadNotificationsBySubscriptionFilter({ userId, subscriptionFilterData: { context: "orders" } })`.
+- "List my notification inbox, unread only." -> `blocks notifier list --unread-only --json`, or SDK `getNotifications({ isUnreadOnly: true })`.
+- "Mark this notification as read." -> `blocks notifier mark-read <id> --dry-run --json`, then `--yes`.
+- "Mark everything in the inbox as read." -> `blocks notifier mark-all-read --dry-run --json`, then `--yes`.
+- "Configure which channel the order-shipped notification uses." -> not this skill; that's the blocks-notification skill.

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

@@ -0,0 +1,78 @@
+---
+name: blocks-onboarding
+description: "Onboard a user into SELISE Blocks before any other Blocks skill can run, using the `blocks` CLI — never raw API calls. Detects current state (CLI installed?, logged in?, project selected?) via `blocks auth status --json`/`doctor --json` and closes each gap: install, `login` (device-code, no setup needed), list/select a project (`projects create` is currently disabled — new projects come from the portal), `blocks init`, then resolve/create the app's OIDC client via `auth oidc-clients` (no portal needed) before handing off to `blocks new web`. Use when a user is new to Blocks, asks how to get started, or hits `not_logged_in`/`project_not_selected` from another command."
+---
+
+# Blocks — Onboarding
+
+Every other Blocks skill assumes: the `blocks` CLI is installed, the user is logged in (`login`), and a project is selected (`use`). This skill detects which of those is missing and closes the gap. **Everything here goes through `blocks` — never a raw `fetch`/`curl` against `api.seliseblocks.com`.**
+
+The CLI's own usage guide (bundled with the `blocks-cli` package) is the command-level ground truth (exact flags, defaults, failure codes); this skill is the conversational flow around it — what to ask, what's portal-only, and in what order.
+
+## Probe first, ask second
+
+Run `blocks auth status --json` and branch on the result — don't interrogate the user about state that's discoverable:
+
+| Signal | State | Do this |
+|---|---|---|
+| command not found | CLI not installed | `npm install -g @seliseblocks/cli-os`, then re-probe |
+| `accountAccessToken`/`accountRefreshToken` both `"missing"` | Never logged in | Step 1 — `login` |
+| logged in, no project selected (check `blocks doctor --json`'s "Project selected" check) | No project selected | Step 2 — list/`use` |
+| logged in, project selected | Ready | Confirm the project with the user — always show the full accessible-project list and which one is currently selected, never silently continue on a prior session's selection — then hand off to the skill/task that brought you here |
+
+If anything looks broken rather than simply "not yet done" (unreadable/stale local token storage after a machine migration, Windows profile change, Keychain reset), run `blocks doctor --json` for the fuller diagnostic — it checks Node version, config/token/secret file locations, and token freshness in one pass. If storage itself is unreadable or corrupted, `blocks auth remove <account>` clears cached tokens and stored local credentials (restoring the packaged default account), then re-run `login`.
+
+## Step 1 — Log in
+
+The CLI authenticates itself with no setup. There is no OIDC client to register in the portal for this, no client id/secret to collect from the user, and nothing about how the CLI does it to look up, print, or report — just log in:
+
+```bash
+blocks login
+```
+
+Device-code flow: it prints a verification URL and user code, opens the browser to the verification page when possible so the user only needs to click approve, then polls until the device is authorized; stores account access and refresh tokens and auto-refreshes later. Run it yourself rather than only telling the user to run it, so you can read the printed code/URL and confirm the result right after.
+
+Verify with `blocks auth status --json` — re-run after login rather than assuming it worked.
+
+## Step 2 — Project
+
+Ask **what the user wants to build** and whether they already have a project, rather than assuming:
+
+```bash
+blocks projects list --json
+```
+
+Always show the full list of accessible projects, and if one already appears selected, say which one — never silently continue on a prior session's selection. If projects exist, confirm which one (and which environment) the user wants; never guess.
+
+**`projects create` is currently disabled in this CLI build** (commented out pending a product decision — there is no CLI path to create a new project). If none of the listed projects fit, tell the user a new project must be created from the Blocks portal first; once they confirm it exists, re-run `blocks projects list --json` and continue from here.
+
+Then select it:
+
+```bash
+blocks use <x-blocks-key>
+```
+
+Project (impersonation) tokens are created lazily from the account session the first time a project-scoped command needs one — never ask the user for a project token directly. If an impersonated project token later gets stuck, rejected, or expired and `blocks auth refresh --project --json` doesn't fix it, recover with:
+
+```bash
+blocks deselect              # drops the selection and its cached impersonation token
+blocks use <x-blocks-key>     # reselect the same x-blocks-key to force a fresh impersonation
+```
+
+## Step 3 — Local workspace + hand off
+
+Run `blocks init` once per project directory to create `blocks.json`, `blocks/data/schemas/`, `blocks/data/rules.json`, and `.env.example` — the later data-gateway skills read/write these. Safe to re-run: it never overwrites files that already exist. (`init` does not create a localization folder or any release-related file — `blocks/localization/` only appears later, lazily, the first time `blocks localization pull` writes to it, and there is no `blocks/release/*` file at all.)
+
+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.
+- 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
+
+- **Only one OIDC client matters here, and it's not the CLI's.** The CLI authenticates itself with no setup — nothing to register, nothing portal-only about `blocks login` itself, and nothing about how it does so to look up or mention. The only OIDC client involved is the scaffolded app's *public* browser client for its own end-user login (Step 3) — and that no longer requires the portal either: `blocks auth oidc-clients list`/`save` resolve or create it entirely through the CLI on the project's impersonated token. The portal remains available if the user prefers it, but it's an alternative, not a requirement. Don't tell a user they need to register anything before `blocks login` will work, and don't send them to the portal for the app's OIDC client by default.
+- **`blocks new web` hangs a non-interactive run if `--client-id` or `--app-domain` is omitted** — it drops into an interactive pick-list (even to offer "skip") with no stdin to answer it in an agent-driven session. Always resolve both explicitly first (Step 3) rather than omitting either and hoping for a graceful default.
+- **Never open, read, print, or expose the CLI's local storage files** (its config/token/secret files on disk) or anything inside them — client ids, root tenant id, account names, tokens. Only ever interact with them through `blocks` commands, never by inspecting the files directly. `auth status`/`doctor` only ever report token state (`missing`/`valid`/`expired`), never the value.
+- **Known CLI error codes and fixes** (from the CLI's own error handling): `not_logged_in` → `blocks login`; `refresh_token_rejected` → `blocks login`; unreadable/stale local auth storage → `blocks auth remove <account>` then `blocks login`; `project_not_selected` → `blocks use <x-blocks-key>` (or pass `--project <tenantId>` for a single one-off command); `api_auth_failed` → `blocks auth status --json` then log in again; `impersonation_invalid_client` → not a stale-token problem, the account's OIDC client isn't registered for impersonation — check `blocks auth config get` and have an admin register it, `login`/`deselect`+`use` won't fix this one.
+- **`--dry-run` before `--yes`** on every mutating command (`auth oidc-clients save`, `data schema push`/`data rules deploy`, `localization push`, `release deploy`) — this recurs in every skill that mutates project state.

package/dist/skills/blocks-release-deployment/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: blocks-release-deployment
+description: "Trigger and inspect SELISE Blocks Release builds/deploys entirely through `blocks release *` — never raw fetch/curl; there is no SDK path (Release has no `@seliseblocks/client` namespace). Covers `release deploy` (auto-resolves the repo, verifies branch matches environment), `release status`/`builds get` (build lookup by id), and `builds list` (list builds for a repo). Use for 'deploy/trigger a release', 'check build status', 'list recent builds'. Always `--dry-run` before `--yes`. No artifact-upload capability — deploy triggers a configured pipeline only."
+---
+
+# Blocks Release — Deployment
+
+Trigger and read Release builds through `blocks release *`. This is **100% CLI, no SDK equivalent** — `@seliseblocks/client` (`createBlocksClient()`) exposes only `auth`, `data`, `iam`, and `localization`; there is no `release` namespace anywhere in the SDK. Never write a frontend/app-code path for this — it's always a terminal command.
+
+**Prerequisite:** a project is selected (`blocks use <tenantId>`) and that project has a repo linked from the Blocks portal — see the blocks-onboarding skill. There is no local config file for release settings; `blocks init` only scaffolds `blocks/data/schemas/`, `blocks/data/rules.json`, and `.env.example` — it has no release-related output at all. `deploy` and `builds list` both resolve which repo to act on directly from the project's linked assets (see below), not from any file on disk.
+
+## Safe read commands
+
+- **`blocks release status <buildId> [--json]`** — one build's status by id (positional arg, or `--build-id <id>`).
+- **`blocks release builds get <buildId> [--json]`** — literally the same call as `release status`; it's a pure alias in the CLI's own source (`releaseBuildsGet` just calls `releaseStatus(argv)`), not a different endpoint or response shape. Use whichever name the user said.
+- **`blocks release builds list [<repoId>] [--repo-id <repoId>] [--json]`** — all builds for one repository. `repoId` is optional: if omitted, the CLI auto-resolves it from the selected project's linked repo assets the same way `deploy` does (see "Resolving the repo" below) — **except** when more than one repo is linked, in which case it falls back to an interactive `selectFromList()` prompt instead of erring or guessing. That prompt has no stdin in a non-interactive/agent run and will hang — if you can't guarantee a human is watching the terminal, resolve and pass `--repo-id` explicitly instead of letting this fall through to the prompt (the same hang risk applies to `blocks new web`'s OIDC-client picker when `--client-id` is omitted — always resolve and pass required values explicitly rather than relying on an interactive fallback).
+
+None of these mutate anything — safe to run without confirmation.
+
+## Mutating: trigger a deploy
+
+```bash
+blocks release deploy --dry-run --json   # show the exact request first
+blocks release deploy --yes --json       # only after the user approves
+```
+
+There is **no `--repo-id` flag on `deploy`** — the repo is always resolved automatically (see below); passing `--repo-id` is not recognized by this command.
+
+### Resolving the repo
+
+`deploy` never takes a repo id as input. It resolves one from the currently selected project's linked assets:
+
+1. It looks up the project's linked repo resources for the project's `tenantGroupId`.
+2. If exactly one repo is linked, that's the one used.
+3. If multiple are linked, it picks the one whose asset `name` matches the project's `environment` (case-insensitive); if none matches, it throws `repo_ambiguous`.
+4. If none are linked at all, it throws `repo_not_linked`.
+
+### Branch/environment safety check
+
+Before building, `deploy` fetches the resolved repo's details to read its linked branch, then compares that branch to the project's `environment` (case-insensitive). If they don't match, it throws `branch_environment_mismatch` rather than building the wrong branch.
+
+### Error codes you may see
+
+| Code | Meaning | Fix |
+|---|---|---|
+| `repo_not_linked` | No repo is linked to this project at all. | Link a repo from the Blocks portal (requires GitHub OAuth), then re-run. |
+| `repo_ambiguous` | Multiple repos are linked and none is named for the project's `environment`. | Check the repo links for this project from the Blocks portal. |
+| `repo_not_found` | The linked asset's repo id wasn't found in blocks-release when fetching repo details. | Check the repo link for this project from the Blocks portal. |
+| `branch_environment_mismatch` | The linked repo's branch doesn't match the project's `environment` (e.g. repo is on `main` but environment is `staging`). Message states the branch found and the environment required. | Point the linked repo at a branch named for the environment, or relink the correct branch from the Blocks portal. |
+| `build_wait_timeout` | Only with `--wait`: no terminal build status was seen before `--timeout` elapsed. | Check manually with `blocks release status <buildId>`. |
+
+### Optional flags
+
+- **`--domain <domain>`** — before triggering the build, makes an extra call to set a custom deployment domain for this repo/environment.
+- **`--wait`** — after triggering, polls the build status (by the returned `buildId`) every `--poll-interval` seconds until the status matches a terminal pattern (succeeded/success/completed/failed/error/cancelled/aborted/done, case-insensitive) or `--timeout` elapses (then throws `build_wait_timeout`).
+- **`--poll-interval <seconds>`** — polling interval for `--wait`, default `10`.
+- **`--timeout <seconds>`** — max time to wait for `--wait`, default `900`.
+
+`--dry-run` prints the resolved `repoId`, `branch`, `environment`, `projectKey`, and (if given) `domain` — it does **not** build a request body from any local file, since none exists. The real request when not a dry run is simply `{ repoId }`. Always show the `--dry-run` output and get explicit approval before re-running with `--yes` — never skip straight to `--yes`.
+
+## Gotchas
+
+- **No SDK path, ever.** If asked "how do I trigger a deploy from my app," the answer is: you don't — this is a CLI-only, human/CI-operated action, not something to wire into frontend code.
+- **No artifact upload.** `release deploy` triggers a *configured* pipeline/repository build — it does not accept or upload a build artifact you hand it. If a user asks to "upload my build and deploy it," that capability doesn't exist in this CLI; say so rather than inventing an upload flag.
+- **`release builds get` and `release status` are the same command.** Don't treat them as returning different data or document them separately — the CLI's own source has `builds get` call `release status` directly.
+- **Release commands are project-scoped, not account-level.** `deploy`, `status`, and `builds list` all run on an impersonated project token, and `deploy`/`builds list` both resolve which project's linked assets to use from whichever project is currently selected via `blocks use`. Behavior changes if the selected project changes; there is no account-level/project-independent mode here.
+- **`deploy` never takes a repo id from the user** — it's always auto-resolved from the project's linked assets, with a real branch/environment safety check before it will build. Don't offer or accept a `--repo-id` flag on `deploy`.
+- **`builds list --repo-id` is optional, not required** — it falls back to the same auto-resolve logic as `deploy`, but that fallback can hit an interactive prompt if multiple repos are linked. Pass `--repo-id` explicitly in any non-interactive/agent context to avoid the hang.
+- **`buildId` for `status`/`builds get` is always required**, never guessed — ask the user rather than assuming a value.
+- **`--dry-run` before `--yes`, always** — same discipline as every other mutating `blocks` command in this pack.
+
+## Example trigger prompts
+
+- "Deploy this project's configured release."
+- "Trigger a build for the linked repo."
+- "Check the status of build `<buildId>`."
+- "Did my last deploy finish? Look up build `<buildId>`."
+- "List the recent builds for this repo."
+- "Deploy and wait until it finishes." → add `--wait` (optionally `--poll-interval`/`--timeout`).
+- "Deploy this to a custom domain." → add `--domain <domain>`.
+- "Can you upload my compiled artifact and deploy it?" → not supported; explain there's no artifact-upload path, only triggering the repo's configured pipeline.

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

@@ -0,0 +1,81 @@
+---
+name: blocks-secrets
+description: "Save and retrieve arbitrary named secret values (e.g. captcha provider config, third-party API keys) for a SELISE Blocks project via the blocks CLI's `secrets get`/`secrets save` commands, project-scoped with an impersonated project token. CLI-only surface, no SDK equivalent by design. Storage is generic key/value — shape depends entirely on the secret key, not fixed per type. Use for saving/rotating a secret's key-value pairs or reading one back. `get`'s response is the raw, unredacted value — treat CLI output as sensitive."
+---
+
+# Blocks Secrets
+
+This skill manages **generic tenant secret storage** — arbitrary named secret values scoped to a project, via the `blocks secrets *` CLI. It is not tied to any one feature: a project can store a `captcha` secret, an `smtp` secret, or anything else under whatever `secretKey` name it chooses. The shape of the stored value is a flat, caller-defined JSON object (`--key-value-pairs`) — there is no fixed schema across secrets.
+
+**CLI-only, no SDK path, by explicit design.** There is no `@seliseblocks/client` method anywhere for reading or writing tenant secrets (the SDK's only "secret" surfaces are unrelated: MFA enrollment secrets and OIDC `clientSecret`). If a user wants to store or fetch a project secret, `blocks secrets get`/`blocks secrets save` is the only path — don't suggest an SDK call for this.
+
+**Prerequisite:** a project is selected (`blocks use <tenantId>`). If login/project state is unknown, run the blocks-onboarding skill first.
+
+## Command family
+
+Both commands require an **impersonated project token** — there is no account-token path, consistent with `storage config *` and other project-scoped admin surfaces.
+
+| Command | What it does |
+|---|---|
+| `blocks secrets get <secretKey>` | `<secretKey>` positional, or `--secret-key` (required if no positional). Also takes `--page-number` (default `0`) / `--page-size` (default `10`). Read-only. Response is untyped and printed as-is — **not redacted** (see Gotchas). |
+| `blocks secrets save` | Upsert — create or update. Mutating; standard `--dry-run`/`--yes` discipline applies. |
+
+```bash
+blocks secrets get captcha --json
+blocks secrets get --secret-key captcha --page-size 25 --json
+```
+
+The `secretKey` positional argument wins over `--secret-key` if both are somehow given; only one is required. The paging flags imply the response can be a paged list of items filed under that `secretKey`, not necessarily a single flat value — confirm actual shape from what the call returns rather than assuming a single-object response.
+
+## `secrets save` — fields
+
+`save` builds its request body from `--body`/`--file` (a raw JSON object, applied first) merged with these convenience flags (applied second, so they win if both are given):
+
+| Flag | Body field |
+|---|---|
+| `--secret-key` | `secretKey` |
+| `--item-id` | `itemId` |
+| `--key-value-pairs` | `keyValuePairs` |
+
+`--key-value-pairs` takes a JSON **object** string (e.g. `'{"isEnable":"true"}'`) — the CLI rejects arrays or non-objects with `--key-value-pairs must be a JSON object`. Unset convenience flags are dropped, so they never overwrite a field already present in `--body`/`--file`.
+
+```bash
+blocks secrets save --secret-key captcha \
+  --key-value-pairs '{"isEnable":"true","provider":"recaptcha","captchaKey":"...","captchaSecret":"..."}' \
+  --dry-run --json
+
+blocks secrets save --secret-key captcha \
+  --key-value-pairs '{"isEnable":"true","provider":"recaptcha","captchaKey":"...","captchaSecret":"..."}' \
+  --yes --json
+
+# Update an existing secret record
+blocks secrets save --secret-key captcha --item-id <itemId> --key-value-pairs '{...}' --yes --json
+```
+
+`save` is create-or-update in one command: omit `--item-id` to create, pass it to update. The captcha example above is only an illustration — `--key-value-pairs` accepts whatever fields the caller's `secretKey` namespace needs.
+
+## `--dry-run` before `--yes` — always
+
+`save` follows the standard `blocks` mutation discipline: passing neither `--dry-run` nor `--yes` drops into an interactive "Type 'yes' to continue" prompt, which is not viable in a scripted/agent context — always pass one explicitly.
+
+- `--dry-run` short-circuits **before** the confirmation prompt and **before any network call**: it prints the resolved request, with a redacted body, and returns.
+- `--yes` skips the interactive prompt and sends the real request.
+
+The dry-run preview's redaction is narrow: it walks `keyValuePairs` only, and replaces the *value* of any entry whose *key* matches a secret-shaped pattern (case-insensitive, e.g. ends in "key," or contains "secret"/"password") with `"***"`. It does **not** touch `secretKey`/`itemId` at the top level, and does **not** touch anything injected via `--body`/`--file` outside `keyValuePairs`. This redaction is preview-only — it never changes what is actually sent when `--yes` is used, and it has no effect on `secrets get`'s response or on the live response from `save` itself.
+
+## Gotchas (secret-handling — read before running either command)
+
+- **`get`'s response is raw and completely unredacted.** The command applies zero masking — the result is passed straight through and printed verbatim. There is no masked/redacted variant of this command. Whatever is stored under that `secretKey` comes back in full, as-is. Treat the output as sensitive: don't repeat the value back to the user beyond what they explicitly asked for, don't paste it into chat/logs/tickets, and never write it into a file that could get committed.
+- **`save`'s live response is also unredacted.** The dry-run preview masks secret-shaped `keyValuePairs` keys, but that's a preview-only convenience. The actual request always sends plaintext values, and whatever comes back is written unredacted too — if the API echoes the saved value back, handle that response with the same care as `get`'s.
+- **This is generic storage, not a captcha-specific feature.** `--key-value-pairs` is a flat JSON object whose fields are entirely defined by whoever picked the `secretKey` — there's no schema registry. Don't assume `isEnable`/`provider`/`captchaKey`/`captchaSecret` apply to a secret that isn't actually a captcha config.
+- **Impersonated project token only, no account-token path.** Both commands require a selected project (`blocks use <tenantId>`) first — same pattern as `storage config *`.
+- **No SDK equivalent exists.** Don't reach for `@seliseblocks/client` for this; the CLI is the only surface, by design.
+- **`save` is upsert, not two verbs.** Whether a call creates or updates is decided by the presence of `--item-id`, not by a different command name.
+
+## Example trigger prompts
+
+- "Save our reCAPTCHA settings as a project secret." → `secrets save --secret-key captcha --key-value-pairs '{...}' --dry-run --json`, confirm, then re-run with `--yes`.
+- "What's stored under the `captcha` secret?" → `secrets get captcha --json` — tell the user the raw stored value will be printed, and don't restate it beyond what they asked for.
+- "Rotate the captcha secret key." → `secrets save --secret-key captcha --item-id <itemId> --key-value-pairs '{...}' --yes --json` (update path — need the existing `itemId`, typically from a prior `secrets get`).
+- "Is there a way to list every secret in the project?" → there's no list-all; `secrets get` requires a `secretKey` and pages within it (`--page-number`/`--page-size`), it doesn't enumerate unknown keys.
+- "Can I read this from my frontend app with the SDK?" → no — `blocks secrets *` is CLI/admin-only; don't scaffold an SDK call, and never put a secret value into frontend code or a committed `.env` file.

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

@@ -0,0 +1,93 @@
+---
+name: blocks-storage-configuration
+description: "Configure which storage provider (Azure Blob, S3, or local disk) backs a SELISE Blocks project's files: named configurations with host, port, credentials, region/endpoint or connection string, and strategy, via the blocks CLI ('storage config get/list/save/delete'), project-scoped with an impersonated project token. CLI-only admin surface, no SDK equivalent. Use for set up a storage provider, list/inspect storage configs, rotate storage credentials, switch to local storage, delete a config. Uploading/downloading files once configured is blocks-data-storage's job."
+---
+
+# Blocks Storage — Configuration
+
+This skill manages the **storage configuration record itself** — which cloud provider (or local disk) a named configuration points at, and the connection details needed to reach it. It does not upload, download, or browse files; that's a separate, project-scoped runtime concern handled by the sibling blocks-data-storage skill (`blocks data files *` CLI, or the SDK's `data.files`/`data.dms` at runtime).
+
+**CLI-only, no SDK path.** There is no `@seliseblocks/client` method for reading or writing a storage configuration's own fields — the SDK's role in this area starts *after* a configuration exists (it takes a `configurationName` and uploads/downloads against whatever that config points at). If a user wants to set up, inspect, or change a storage provider, that's this skill's `blocks storage config *` commands; if they want to move bytes, hand off to blocks-data-storage.
+
+**Prerequisite:** a project is selected (`blocks use <tenantId>`). If login/project state is unknown, run the blocks-onboarding skill first.
+
+## Command family
+
+All four commands require an **impersonated project token** — there is no account-token path for this surface, consistent with other project-scoped admin commands (`secrets *`, `data config *`, etc.).
+
+| Command | Notes |
+|---|---|
+| `blocks storage config list` | No parameters beyond the selected project. Read-only. |
+| `blocks storage config get <name>` | `<name>` (positional) or `--name` (required if no positional arg). Read-only. |
+| `blocks storage config save` | Upsert — create or update a configuration. Mutating. |
+| `blocks storage config delete <name>` | `<name>` (positional) or `--name` (required if no positional arg). Mutating. |
+
+```bash
+blocks storage config list --json
+blocks storage config get Default --json
+blocks storage config get --name Default --json
+```
+
+## `storage config save` — fields
+
+`save` builds its request body from `--body`/`--file` (a raw JSON object, spread first) merged with these convenience flags (later, so they win if both are given):
+
+| Flag | Body field |
+|---|---|
+| `--name` | `name` |
+| `--item-id` | `itemId` |
+| `--strategy` | `storageStrategy` |
+| `--host` | `host` |
+| `--port` | `port` |
+| `--region-endpoint` | `cloudStorageRegionEndPoint` |
+| `--connection-string` | `connectionString` |
+| `--access-key` | `accessKey` |
+| `--secret-key` | `secretKey` |
+| `--username` | `userName` |
+| `--password` | `password` |
+| `--remote-base-path` | `remoteBasePath` |
+| `--update` (boolean) | `updateRequest` |
+
+Unset flags are dropped (`compact`), so they never overwrite fields already present in a `--body`/`--file` payload. `save` is a create-or-update in one command, not two separate verbs — pass `--item-id` (and typically `--update`) when modifying an existing configuration, omit it to create a new one.
+
+```bash
+blocks storage config save --name Default --strategy AzureBlob \
+  --host mystorageaccount.blob.core.windows.net --region-endpoint eu-west-1 \
+  --access-key <key> --secret-key <secret> --dry-run --json
+blocks storage config save --name Default --strategy AzureBlob \
+  --host mystorageaccount.blob.core.windows.net --region-endpoint eu-west-1 \
+  --access-key <key> --secret-key <secret> --yes --json
+
+# Update an existing configuration
+blocks storage config save --item-id <id> --update --connection-string "<new connection string>" --dry-run --json
+blocks storage config save --item-id <id> --update --connection-string "<new connection string>" --yes --json
+```
+
+## `--dry-run` before `--yes` — always
+
+Both mutating commands (`save`, `delete`) follow the standard `blocks` mutation discipline: `--dry-run` prints what would be sent and returns without calling the API; `--yes` skips the interactive confirmation prompt and sends the request for real. Omitting both drops into an interactive "Type 'yes' to continue" prompt — not viable in a scripted/agent context, so always pass one or the other explicitly.
+
+```bash
+blocks storage config delete Default --dry-run --json
+blocks storage config delete Default --yes --json
+```
+
+`save`'s dry-run output redacts secret-shaped fields before printing (`accessKey`, `connectionString`, `password`, `secretKey` become `"***"`) — this redaction is **dry-run-preview only**, it does not change what's actually sent when you run with `--yes`, and it doesn't apply to `get`/`list` responses (see Gotchas).
+
+## Gotchas
+
+- **`get`/`list` are not redacted.** Only `save --dry-run`'s own preview output redacts `accessKey`/`connectionString`/`password`/`secretKey`. If a `get`/`list` response ever echoes credential fields back, treat that output as sensitive — don't paste it into logs, tickets, or chat verbatim.
+- **`save` is upsert, not separate create/update commands.** Whether a call creates or updates is determined by whether `--item-id` is present, not by a different command name.
+- **This is provider configuration, not file operations.** `blocks storage config *` never touches an actual file's bytes. For "upload a file," "get a download link," "list a folder" — that's **blocks-data-storage** (`blocks data files *` or the SDK), using a `configurationName` that a `storage config` record already defines.
+- **No positional-or-flag ambiguity trap:** `get`/`delete` accept the configuration name as either the first positional argument or `--name`; only one is required, not both.
+- **Impersonated project token only.** Like `secrets *` and `data config *`, none of these four commands run against the account token — a project must be selected first (`blocks use <tenantId>`).
+
+## Example trigger prompts
+
+- "Set up Azure Blob storage for this project." → `storage config save --strategy AzureBlob ...`.
+- "What storage configurations exist on this project?" → `storage config list`.
+- "Show me the `Default` storage configuration." → `storage config get Default`.
+- "Rotate the access key on our storage config." → `storage config save --item-id <id> --update --access-key <new key> ...`.
+- "Switch this project to local storage." → `storage config save --strategy <local strategy value> --host ... --port ...` (confirm the exact strategy value expected by the project rather than guessing).
+- "Delete this storage configuration, we don't use it anymore." → `storage config delete <name>`.
+- "How do I actually upload a file once storage is configured?" → hand off to **blocks-data-storage**, not this skill.