blocks-skills

Onboard a user into SELISE Blocks before any other Blocks skill can run — detect their current state and get them to a working setup: no Blocks account yet (guide signup at https://os.seliseblocks.com), account but no project (ask what they want to build and create the project via API — suggest a dev-only default), project but no credentials file (have the user create the `.env`), or everything present (verify and hand off). Also covers adding more environments (test/stg/uat/prod/…) to an existing project and deleting environments, via API. Use whenever a user is new to Blocks, asks how to get started / sign up / create a project / add or remove an environment, or when a prerequisite fails in another skill — missing `.env` or `BLOCKS_USERNAME`, `auth-login` returns 401/invalid credentials, or `Project/Gets` returns no projects. Only SIGNUP is portal-only (browser, not API); project and environment management is scriptable. Run the preflight here whenever the user's account/project state is unknown.

Configure the data model of a SELISE Blocks project through the data service REST admin API (`https://api.seliseblocks.com/data/v4`): create and edit schemas/collections, add or remove properties/fields, add field validation rules (incl. the AI regex assistant), set schema/field access levels and data-access policies, and RELOAD so changes go live in the runtime gateway. Also covers mock/sample data inventory + deletion and schema-exchange (export/import a data model between projects). Use whenever the user wants to define, edit, secure, validate, reload, copy, or reset the DATA MODEL of a Blocks project — 'add a field to my schema', 'make this collection public', 'validate the email field', 'reload the schema', 'clone my schemas to staging', 'wipe the demo data'. This is the admin/portal side; for running GraphQL create/read/update/delete against the resulting schemas use blocks-data-gateway-crud, and for file/DMS storage use blocks-data-storage.

Implement GraphQL create/read/update/delete against a SELISE Blocks project's runtime data gateway (`POST https://api.seliseblocks.com/data/v4/gateway`). Covers discovering a schema's auto-generated operation names, writing the query (`get<Collection>` with where/paging/order), insert/update/delete mutations (and insertMany/updateMany/deleteMany), the result + ActionResponse shapes, and wiring it all into a frontend (React 19 / TanStack Query hooks). Use whenever the user wants to READ or WRITE actual data/records through a Blocks schema from an app or script — 'fetch products from my Blocks collection', 'insert a record via the gateway', 'write the update mutation', 'CRUD hooks for my schema', 'why does getOrders not exist on Query'. The schema must already be created + reloaded via blocks-data-gateway-configuration; for file storage use blocks-data-storage.

Store and serve files on a SELISE Blocks project via the data service's DMS (document management system) — the `/data/v4/Files/*` API. Covers the pre-signed-URL upload (get upload URL → PUT the file binary to storage, with the Azure `x-ms-blob-type` header when needed → get download URL), downloading/listing files, folders (create/list/delete), tags/metadata/versions, and deleting files. Use whenever the user wants to upload, download, browse, organize, or delete FILES/attachments/documents/images on Blocks — 'upload a PDF and get a link', 'attach an image to a record', 'let users download this file', 'create a folder and list its contents', 'get a presigned upload URL'. This is separate from the data model: to define schemas use blocks-data-gateway-configuration, and to CRUD records use blocks-data-gateway-crud (store a file here, keep its fileId in a schema field there).

Run a frontend React app locally over HTTPS on its real project domain, using a locally-generated SSL certificate — required so SELISE Blocks SSO/OIDC login works, because the auth callback sets a Secure, domain-scoped session cookie that the browser rejects on plain http://localhost. The skill: discovers the project's domain from /os/v4/Project/Gets (projects[].applications[].domain, filtered by environment) or asks the user, adds a hosts entry mapping that domain to 127.0.0.1, generates a self-signed local cert for it with openssl (and trusts it), configures the dev server (Vite/CRA/Next) to serve https on that domain + port, and runs it at https://your.domain.com:PORT. Use whenever the user needs to run/test a Blocks app locally over HTTPS, fix 'SSO cookie not set / session lost on localhost', set up a local dev cert, serve a custom domain locally, or make the OIDC redirect work in local dev. A real/owned domain name is required to issue the cert — you cannot make one without a domain.

Configure SSO / OIDC login for a SELISE Blocks project via the IAM admin API (`https://api.seliseblocks.com/iam/v4`): ensure a `blocks-oidc` identity provider exists, creating the OIDC client (`/oidc-clients`) and the identity provider (`/auth/identity-providers`) if they don't. Use whenever the user wants to SET UP / enable / configure single sign-on, OIDC, or an identity provider for their Blocks app — 'enable SSO for my project', 'configure OIDC login', 'register an OIDC client', 'add a blocks-oidc identity provider', 'set up authorization-code login on Blocks'. This is the admin/portal side and requires impersonating into the project first; once configured, wire the login into the app with blocks-iam-sso-oidc-implementation. If the app invites users via the portal or API, also wire an optional /activate page (blocks-iam-account) — not required for SSO login itself.

Implement SELISE Blocks SSO / OIDC login in a frontend codebase — the authorization-code flow via `/iam/v4/idp/initiate` → redirect to `iam.seliseblocks.com` → `/iam/v4/idp/callback` (which sets the session cookie). Already-activated users log in through this flow directly. Optionally wire `/activate` (blocks-iam-account) only when the app invites inactive users via the portal or API who must activate before their first login. Also covers renewing the browser session via `POST /iam/v4/oidc/token`. Use whenever the user wants to ADD login/sign-in to a Blocks app, wire up SSO/OIDC on the client, build a login button, handle the OIDC redirect/callback, implement account activation for invited users, or keep the session alive after SSO. Do NOT implement username/password login directly — Blocks login goes through this hosted authorization-code flow. The project's OIDC provider must already be configured (blocks-iam-sso-oidc-configuration); this skill is the app-side wiring.

Configure app localization on a SELISE Blocks project via the localization API (`https://api.seliseblocks.com/localization/v4`): manage languages (`/Language/Gets|Save|Delete|SetDefault`), feature modules that group translation keys (`/Module/Gets|Save`), and translation keys with per-language values (`/Key/Save`, `/Key/SaveKeys`, `/Key/Gets`, `/Key/GetsByKeyNames`) — then generate the runtime language files (`/Key/GenerateUilmFile`) so the translations actually reach the app. Use whenever the user wants to set up translations/i18n for static UI content (page titles, labels, button text, descriptions), add or edit a language, create a translation module, add/translate keys, translate a batch of keys into multiple languages, or 'generate the language files' on Blocks. This is the admin/config side (translations are authored here); the frontend that loads and switches languages is blocks-localization-implementation. Requires impersonating into the project first.

Manage RBAC — permissions and roles — on a SELISE Blocks project via the IAM API (`https://api.seliseblocks.com/iam/v4/iam`): create/update/list/get permissions, create/update/list/get roles, and assign or remove permissions on a role. Use whenever the user wants to define or edit permissions, create roles, build a role hierarchy, list/inspect roles or permissions, or grant/revoke permissions to a role on Blocks — 'create a permission', 'add a role', 'give the editor role these permissions', 'list all roles', 'what permissions does this role have'. Works for both admin/config tooling and frontend admin screens. Assigning roles/permissions to a USER lives in blocks-iam-users; SSO/OIDC is separate (blocks-iam-sso-oidc-*).

Manage organizations (tenancy/workspaces) on a SELISE Blocks project via the IAM API (`https://api.seliseblocks.com/iam/v4/iam`): create an organization, update it (branding/theme/locale/addresses), get one by id, list/search organizations, read the current user's organizations (`/organizations/my`), and read or set the project's org-creation config (`/organizations/config`, incl. multi-org enablement). Use whenever the user wants to create or edit an organization, list orgs, fetch 'my organizations', configure whether/where orgs can be created, or turn multi-org on/off on Blocks. Primarily a frontend/implementation concern — most often reading the signed-in user's organizations and rendering an org switcher; the create/update/config operations are the rarer admin/config path. Users/roles within an org are blocks-iam-users / blocks-iam-access-control; SSO is blocks-iam-sso-oidc-*.

Manage users on a SELISE Blocks project via the IAM API (`https://api.seliseblocks.com/iam/v4/iam`): create a user, update a user, get a user by id, list/search users, read the current signed-in user (`/iam/me`), read a user's activity timeline, and assign roles/permissions to a user. Use whenever the user wants to create/invite a user, edit a user profile, list or search users, fetch the logged-in user's own profile/permissions, show a user audit timeline, or grant a user roles/permissions on Blocks — 'add a user', 'update this user', 'who am I / get my profile', 'list users', 'give this user the admin role', 'show the user's activity log'. Works for admin tooling and frontend. Defining the roles/permissions themselves is blocks-iam-access-control; SSO login is blocks-iam-sso-oidc-*.

Implement runtime localization / i18n in a SELISE Blocks frontend: load the project's languages (`/Language/Gets`) and modules (`/Module/Gets`), fetch the generated translation files (`/Key/GetUilmFile?Language=<culture>&ModuleName=<module>`), render UI by translation key, and build a language switcher that swaps the active language live. Use whenever the user wants to make a Blocks app multilingual on the client — add a language switcher/dropdown, load translations, replace hard-coded strings with translation keys, apply the selected language to page titles/labels/buttons, or wire i18n into React. This is the frontend side; the translations themselves are authored with blocks-localization-configuration. No project impersonation needed — it uses the public project key.

SELISE Blocks IAM account/session actions — activate a newly-created user account (`/auth/activate` on an `/activate` page: invitation token as `code`, password + confirm password, firstName, lastName) and log a user out (`/auth/Logout`, a cookie/session-based call that revokes the session and clears the auth cookies). Use whenever the user wants to activate/confirm a new account, finish signup with an invitation/activation code, implement the /activate route, set the initial password on activation, or implement logout / end-session in a Blocks app or admin tool. Works for both admin tooling and frontend implementation. This is distinct from SSO/OIDC login (see blocks-iam-sso-oidc-implementation) — activate and logout are direct account-lifecycle calls.