procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/tools/procesio/PROCESIO-AUTH-NOTES.md

@@ -0,0 +1,226 @@
+# PROCESIO API — live-validated auth & coverage notes
+
+Recorded 2026-06-23 against the production Web API. No secrets in this file.
+
+## Hosts & infrastructure
+
+| Host | Resolves to | TLS | Role | Reachable from here |
+|------|-------------|-----|------|---------------------|
+| `webapi.procesio.app` | 86.105.154.113 (Kong) | valid `*.procesio.app` | **Web API** (v1.19 Swagger, 295 ops) | ✅ yes |
+| `auth.procesio.app` | 86.105.154.113 (Kong) | **self-signed Kong default** (`CN=localhost,O=Kong`) | Proxy/Auth API (login) | ❌ Kong "no route" / cert fail |
+| `procesio.app` | nginx | valid | the Vue SPA (`VUE_APP_*` build env) | SPA only, `/api` = 405 |
+| `procesio.com` | Cloudflare | valid | Next.js marketing site | n/a |
+
+All `*.procesio.app` names (auth, app, identity, login, sso, …) resolve to the
+same Kong node; only `webapi` has a configured cert+route. So the documented
+auth host `auth.procesio.app` currently serves Kong's default cert and 404s its
+own `/api/Authentication` and `/swagger` from the public edge.
+
+## Auth mode 1 — API key  ✅ WORKING
+
+Three request headers on every Web-API call:
+
+```
+key:         <api key name>
+value:       <api key value>
+workspaceid: <workspace GUID>     # required for workspace-scoped keys
+```
+
+The Swagger security schemes define `key` (KeyName) and `value` (KeyValue); the
+developer docs add `workspaceid`. Live results for the two showcase keys:
+
+| Profile | key/value | workspaceid | `GET /api/Workspaces` |
+|---------|-----------|-------------|------------------------|
+| `personal` | valid | (none) | **200** — 146 workspaces |
+| `ws-scoped` | valid | (none) | 401 Unauthorized |
+| `ws-scoped` | valid | its own workspace GUID | **200** |
+| `ws-scoped` | valid | a DIFFERENT workspace GUID | 401 |
+
+**The `key` header is the key HANDLE, not its display name.** The API Keys page
+shows each key with a human name (e.g. a short label) and a separate random
+*handle* (~16 chars). Sending the display name as `key` returns **403
+`Unauthorized`** on every endpoint; sending the handle returns 200. An empty
+`key` returns 401 instead of 403, so a 403 with a valid value + workspaceid means
+"wrong key name/handle", not "wrong workspace". Store the handle with
+`add-credential --key <handle>`.
+
+**Conclusion:** a personal/master key authenticates without `workspaceid`; a
+workspace-scoped key **requires** the exact workspace GUID. Such a profile must be stored WITH its `workspace_id` to authenticate at all. Find any workspace's GUID with `list-workspaces` (`id`).
+
+### Endpoints exercised live with the `personal` key (all 200)
+- `GET /api/Workspaces` → 146 workspaces
+- `GET /api/Projects` → `{totalItemCount, pageNumber, pageItemCount, pageItems}`
+- `GET /api/DataTypes` → same paginated envelope
+- `GET /api/Actions` → `{actions, grouping, prototypes}`
+- `GET /api/Credentials/types` → 33 connection types
+
+`GET /api/ApiKey` returns 401 even for the personal key — that endpoint needs a
+`workspaceid`-scoped context (use a workspace profile).
+
+## Auth mode 2 — username / password  ✅ WORKING (cookie session)
+
+Confirmed from a real login HAR (`procesio.app.har`) + live replay. The actual
+flow is a **cookie session on the Web API**, NOT the OAuth/Bearer flow the docs
+describe and NOT on `auth.procesio.app` (that host is obsolete — "auth moved to
+webapi"):
+
+```
+POST https://webapi.procesio.app/api/authentication      # lowercase path
+Content-Type: application/x-www-form-urlencoded
+x-requested-by: playground-v1                            # REQUIRED (omitting it = 407)
+body: username=<>&password=<>&client_id=procesio-ui      # form, no realm/grant_type/client_secret
+
+200 -> {"message":"Authentication successful"}
+Set-Cookie: __Host-procesio.access  (HttpOnly, Secure, Path=/)
+Set-Cookie: __Host-procesio.refresh (HttpOnly, Secure, Path=/)
+Response header: x-session-expires-at  (exposed via Access-Control-Expose-Headers)
+```
+
+Every subsequent Web-API call carries those two cookies plus
+`x-requested-by: playground-v1` (browser uses `credentials: include`;
+`Access-Control-Allow-Credentials: true`). Live-verified end to end:
+`POST /api/authentication` → 200, then `GET /api/users/me` → 200 (real user
+`facaf267-…`), `GET /api/workspaces` → 200.
+
+The tool implements exactly this: `login` form-posts and caches the cookies in
+Credential Manager (`token-<profile>`), `auth_headers` sends `Cookie` +
+`x-requested-by`, and a 401 transparently re-logs-in. The `client_id` is
+overridable per profile; the gateway id defaults to `playground-v1`
+(`requested_by` profile field to override). No Bearer token, no `auth_base` is
+involved any more for login.
+
+> Earlier 407/401 dead-ends were because the documented flow (JSON body,
+> realm/grant_type, `auth.procesio.app`) is obsolete: the gateway needs the
+> form body **and** the `x-requested-by` header on **webapi**.
+
+### Session caching (Windows Credential Manager blob limit)
+
+Windows Credential Manager rejects a blob over **2560 bytes** — `CredWrite` fails
+with `WinError 1783 "stub received bad data"`. The trap: keyring stores the value
+as **UTF-16LE**, so the real ceiling is **1280 CHARACTERS**, not 2560. Measured by
+binary search on this machine: 1280 chars writes, 1281 fails. Budget in
+characters and halve the byte figure, or you will conclude a payload fits when it
+does not — the two cookies are ~1700 chars, which "fits" 2560 bytes on paper and
+is rejected in practice.
+
+### The login 401 is GENERIC — it never tells you which half is wrong
+
+A rejected form login answers:
+
+```
+401  "Authentication token is null!"
+```
+
+Verified by probing the endpoint with an account that does not exist: the body is
+byte-identical to a real account with a wrong password. So the string proves only
+that the gateway accepted the REQUEST shape (path, form body, `x-requested-by`)
+and refused the CREDENTIALS. It does not distinguish, and must not be read as, a
+missing/expired token despite what it says — nothing about a cached session is
+involved on a login call.
+
+Diagnose by elimination, in this order (cheapest first):
+1. **Wrong environment.** A profile is bound to one environment; an account that
+   lives on QA/DEV (or a client installation) simply does not exist on PROD and is
+   rejected exactly like a bad password. Match the profile's environment to the
+   host the user actually logs into in the browser.
+2. **Typo at the hidden prompt.** getpass echoes nothing, and `Ctrl+V` does not
+   paste in a Windows console — a truncated paste looks like a wrong password.
+3. **SSO account.** An account that reaches the platform through an external IdP
+   has no platform-side password to submit; the redirect-based SSO flow is not
+   implemented here, so use an api-key profile instead.
+
+Rule of thumb for any gateway that returns one opaque message for every auth
+failure: probe it once with a knowingly invalid identity. If the response matches
+what the user is getting, the message carries no information and the fault must be
+located by varying one input at a time.
+
+### Storing a credential needs the runner bypassed
+
+`add-credential` deliberately prompts for the secret instead of taking it on the
+command line (flags leak into shell history and process listings). But run-tool
+routes tools through the persistent runner by default, so the tool runs in a
+daemon worker with no TTY, `sys.stdin.isatty()` is False, and the prompt is
+unreachable — even though the human IS at a console. Bypass it for that one call:
+
+```powershell
+$env:AAT_RUNNER_DIRECT = "1"
+python scripts/run-tool.py procesio add-credential --name <profile> --type userpass --username <you> --make-default
+Remove-Item Env:AAT_RUNNER_DIRECT
+```
+
+Generalizes to every framework action that prompts for a secret. See
+`tools/_lib/toolrunner/TOOLRUNNER-NOTES.md` ("Limitations").
+
+### The dashboard's secret list is not where a profile is added
+
+A tool that keeps its OWN multi-profile store shows only its bookkeeping secrets
+in the dashboard's generic per-tool secret list — here `credentials` (the
+non-secret JSON index of profile names) and `form-code-key` (unrelated to login).
+Neither is the credential a user is hunting for, and hand-writing the index
+desyncs it from the real `cred-<name>` entries. Profiles are added through the
+tool's own action only; the dashboard panel manages environments and
+set-default/remove for profiles that already exist.
+
+The two JWTs therefore cannot share one entry, and both must survive (the access
+cookie authenticates; the refresh cookie is what renews the session without the
+password). They get **one entry each** — `token-<name>` for the access cookie
+plus its expiry, `refresh-<name>` for the refresh cookie. At ~961 and ~733 chars
+each fits comfortably.
+
+So the tool: (1) keeps an **in-process** cookie cache (always works, avoids
+re-login within one CLI invocation), and (2) best-effort persists both entries
+independently — a failed refresh write only costs the next process a full login,
+it does not break the access cache. If a write fails it logs to stderr and
+re-logs-in next invocation. Never let a token cache write crash a request.
+
+### Renewing a session — refresh, don't re-login
+
+The access cookie is a **~30-minute JWT**; the refresh cookie outlives it. A
+browser never notices, because for cookie/BFF clients the gateway refreshes
+behind a `307` redirect. A programmatic cookie client gets no such help and must
+ask explicitly:
+
+```
+POST {web_base}/api/Authentication/refreshToken
+Content-Type: application/x-www-form-urlencoded
+x-requested-by: playground-v1
+body: refresh_token=<value of __Host-procesio.refresh>&client_id=procesio-ui
+```
+
+→ `200 {"message":"Token refreshed successfully"}` plus a fresh **pair** of
+Set-Cookie headers. Verified live: the refreshed access cookie authenticates an
+ordinary Web-API call. This is why the refresh cookie must be cached — without
+it the only way to renew is to re-send the account password every half hour.
+
+Resolution order is therefore: in-process cache → persistent cache → **refresh**
+→ full login. A refresh token that is dead by its own `exp` is skipped rather
+than spending a round-trip proving it.
+
+### Which status means "your session is stale"
+
+Measured against the prod gateway with a bad access cookie:
+
+| Cookie sent | Status |
+| --- | --- |
+| valid | `200` |
+| present but rejected (bad/expired token) | **`403`** |
+| present but unparseable | `401` |
+| absent entirely | `401` |
+
+The trap: a **rejected session comes back 403, not 401**. A client that
+re-authenticates only on 401 surfaces a stale session as a permission error the
+user cannot act on. Treat both as re-authable; make it one-shot so a genuine
+permission denial still terminates. The cost of including 403 is one cheap
+refresh round-trip when the denial was real.
+
+### Bearer (token-in-body) is also available
+
+Omitting `x-requested-by` on the login POST switches the gateway out of cookie/BFF
+mode: the 200 body then carries `access_token` / `refresh_token` / `expires_in`
+(1800) instead of setting cookies, and `Authorization: Bearer <access_token>`
+authenticates Web-API calls normally (verified live). PROCESIO's own API
+documentation recommends this style for integrations and reserves the cookie path
+for the official SPA. This tool still uses the cookie flow — switching is a
+migration to make deliberately, not a bug fix — but the option is real and
+carries no extra dependency.
+

procesio_cli/tools/procesio/PROCESIO-CARD-BUILD-NOTES.md

@@ -0,0 +1,183 @@
+# Building a PROCESIO card end to end — findings from the build loop
+
+Mechanics learned while shipping a two-process card with forms, a scripted engine and an
+oracle-checked acceptance pass. These are the things that cost time and were not already
+written down. Companions: [PROCESIO-RECONCILIATION-PATTERNS.md](PROCESIO-RECONCILIATION-PATTERNS.md)
+(what to build), [PROCESIO-FORM-API-HANG-NOTE.md](PROCESIO-FORM-API-HANG-NOTE.md) (the form
+read hang), [PROCESIO-NODE-MODULE-WHITELIST.md](PROCESIO-NODE-MODULE-WHITELIST.md).
+
+## 1. Scale every factor KIND separately, not just money
+
+"Integer minor units for money" is necessary and not sufficient. The moment a figure is
+produced by **multiplying two configured values**, each needs its own integer scale, or the
+product re-introduces the float error the minor-unit rule exists to remove.
+
+A default factor times a country multiplier is the canonical case: `11.2 * 1.15` evaluates
+to `12.879999999999999`, and any downstream exact-equality assertion then fails on a figure
+that is arithmetically right. Give the multiplier its own scale — **basis points, x10000** —
+and do the multiply as integers with a rounded integer divide:
+
+```js
+var factorMilli = divRound(baseMilli * markupBp, 10000);   // 11200 * 11500 / 10000 = 12880
+function divRound(a, b) { return Math.floor((a + Math.floor(b / 2)) / b); }  // positive only
+```
+
+Pick the scale from the value's own precision (quantities in thousandths, rates in
+thousandths, percentages and multipliers in basis points, money in cents), multiply into a
+wider unit, and divide only at render. Check the widest product against `2^53` and put a row
+limit in front of it, so a file large enough to break the assumption is refused rather than
+silently wrong.
+
+## 2. Never let a generated script's escape sequences cross a shell layer
+
+Generating Node source from a script is the right way to keep the deployed code identical to
+the locally tested code. But a `\n` written inside a JS **string literal** can be collapsed
+into a real newline by an intervening shell, heredoc, or quoting layer. The result is a
+literal that ends mid-string, and the failure surfaces as `SyntaxError: unexpected end of
+string` at a line number that looks unrelated to the edit.
+
+**Rule:** write the generator as a **file** and execute the file — never pipe the generator
+source through a shell heredoc. Inside the generator, represent the escape as a token and
+substitute it at write time, so no layer can interpret it:
+
+```python
+NL = chr(92) + "n"                       # the two characters \ and n, as JS source
+src = template.replace("~NL~", NL)
+assert "~NL~" not in src
+```
+
+Then assert the property you care about after writing: the file should contain **zero raw
+newlines inside string literals**, which a grep for the escape sequence confirms cheaply.
+
+## 3. A date control submits a LOCALISED display value, not an ISO date
+
+A `datetime-input` bound to a string process variable does not necessarily deliver
+`YYYY-MM-DD`. Given an ISO default it can render and submit a localised display value
+(`"1 July 2026, 04:00"` — note the time, which is a timezone offset applied to midnight).
+An engine that validates `^\d{4}-\d{2}-\d{2}$` then rejects a period the user set correctly.
+
+Normalise defensively at the top of the engine: accept an ISO date, an ISO datetime, the
+`DD/MM/YYYY` display form, and fall back to date parsing for anything else — reading the
+result back in **UTC**, so an offset cannot shift the day across a period boundary. Keep a
+clear fatal for what still will not parse, quoting the raw value.
+
+This class of defect is invisible to an API-side test, because a programmatic submission
+passes the payload directly and never exercises the control's own formatting. Only opening
+the rendered form shows it.
+
+## 4. The same flow comes back in two different casings
+
+`GET /api/Projects/{id}` returns the flow **camelCase** (`variables`, `actions`, `name`,
+`id`, `type`). The Transport **export** (`POST /api/Transport/export-entities`) returns the
+same structure **PascalCase** (`Variables`, `Actions`, `Name`, `Id`, `Type`). Any tool that
+reads a flow from both sources must accept either; a checker written against one silently
+sees zero variables from the other and reports a clean pass over nothing.
+
+## 5. Form event map rows are `left` / `right`, and `right` must have four segments
+
+In the built form DTO, an `inputMap` / `outputMap` row is `{id, left, right}`:
+
+- `left` — the **process variable GUID**
+- `right` — the **form value path**, `formId.FIELDS_NS.elementId.valueConfigId`
+
+A row whose `right` is still a raw field **name** is accepted by the API, renders blank in
+the designer, and never carries a value. Assert `right.split(".")` has **exactly four**
+GUID-shaped segments for every row, and that `left` resolves to a real variable of the right
+direction (inputs to input variables, outputs to output variables). This is cheap, reads
+only the DTO, and catches the whole class before a single run.
+
+## 6. A file output and a JSON output look identical in a run result
+
+In `run-process-with-file` output, a File variable arrives as an object
+(`{id, name, mimeType, size, path, hash}`) — and so does a `json` machine-channel variable.
+"Count the object-valued outputs" is therefore not a way to count produced artefacts, and an
+assertion written that way fails the moment a structured output is added. Assert the file
+variables **by name**, and check `size` is present and non-zero.
+
+## 7. Form-level CSS is NOT a low-risk surface. A bad `Data.code` blob kills the form
+
+Form-level CSS and JavaScript share one storage slot: `Data.code`, AES-encrypted with the
+`procesio / form-code-key` passphrase. It is tempting to treat CSS as the safe half of that
+pair, on the reasoning that the worst a stylesheet can do is look wrong. That is not the
+failure mode.
+
+If the public renderer cannot decrypt the blob it throws **`Malformed UTF-8 data`** out of
+`FormWrapper.component` and **never mounts the form at all** — a spinner forever, every
+control gone, the page unusable. Not "unstyled": absent. A form created with `code: ""`
+renders perfectly; the same form with a `css` string can be dead on arrival, so this is
+easy to introduce while believing you took the cautious option.
+
+Combined with the `form-get` hang (every read-modify-write form action inherits it, so a
+form gets ONE authoring pass over the API), the rule is:
+
+> **Do not send `css` or `javascript` on a form you cannot afford to rebuild.** Express
+> styling through `theme` and per-element `style` configs, which are ordinary DTO fields
+> and cannot break the render.
+
+Diagnose it from the browser console, not the API: creation returns a normal id and
+`form-list` shows the form present and published. Only the console says why the page is
+blank.
+
+**What per-element `style` can and cannot reach.** It does apply: a `--c-input-background`
+set on a textarea resolves on `.pds-c-input-group--wrapper` at runtime. But the design
+system paints that wrapper's `background-color` from its own rule, so the variable is
+plumbed and ignored, and the pane stays white. Colour vars must reference a theme variable
+rather than a hex, so redefining a neutral in `theme` and pointing the element style at it
+is the legal path — it just will not repaint a surface the design system hard-codes. Verify
+the computed `background-color`, not the custom property, before believing a colour landed.
+
+## 8. Prove the engine off-platform, in a real JS engine
+
+The Node sources can be exercised locally under an embedded JS engine (Duktape via `dukpy`
+installs from a wheel on Windows; a native-build engine such as `quickjs` needs a C++
+toolchain and is not worth the dependency). PROCESIO wraps a Node action's code in a
+function, so top-level `return` is legal there; locally, wrap it explicitly:
+
+```python
+dukpy.evaljs("(function(){\n" + src + "\n})()")
+```
+
+Duktape is ES5.1, which is a useful constraint rather than a limitation: writing the engine
+in ES5 keeps it inside what the sandbox reliably supports, and every logic defect surfaces
+in a sub-second local run instead of a multi-minute platform round trip. Feed the same
+source files to both, so what runs on the platform is byte-for-byte what was proved off it.
+
+Assert the OUTPUT, not the call: open a generated workbook with a real reader and read the
+figure back out of the file. "It returned base64" and "it produced a workbook" are different
+claims, and only the second one is worth making.
+
+## 9. Assembling a file-in / file-out card through the builder (the renderer wiring)
+
+A reconciliation-style card is `File(s) in -> engine -> report renderers -> File(s) out`. Every
+piece is a native action the **compact builder can wire by property label** — you do not splice
+raw DTO. The labels (from the live action catalog `configuration[].settings[]`, which the builder's
+`_property_index` reads, recursing into `side-pannel` nested `value` lists):
+
+- **File To Base64** — `File` (input file var) → `Base64 Content` (output string var).
+- **String To Base64** — `Input String` (input) → `Result` (output string var).
+- **HTML To PDF** — a **side-panel** `Configure` holding `HTML string` (the HTML var), `File Name`
+  (a literal, e.g. `Bank-Reconciliation.pdf`) and `File Output` (the output File var).
+- **Base64 To File** — `Base64 String` (the base64 var), `File Name` (a literal) and `File` (the
+  output File var).
+
+⚠ **A File variable is declared with `model:<File datatype GUID 10c6ac59-…-121212121219>`, NOT
+`type:"file"`** — the process-create schema's `type` enum has no `file` (it 400s: "'file' is not one
+of [...]"). Same pattern as a Guid var (`model:<Guid GUID>`). The engine and the report builders are
+ordinary `Node` actions (`Code:{template,vars}`); a downstream Node reads an upstream Node's output
+by binding that output var as its input (`vars:["recon"]`). A linear `edges` chain is enough;
+Start/Stop auto-inject.
+
+**Run it with files, and prove the files, not the run.** `run-process-with-file --id <pid> --file
+StatementFile=stmt.csv --file LedgerFile=ledg.csv --payload '{...non-file inputs...}'` publishes →
+uploads bytes → launches → polls. The File outputs arrive as objects `{id,name,path,size,hash}`;
+`file-download --from-run <result.json> --var ExcelFile --out out.xlsx` fetches one. Judge on
+opening the file (openpyxl sheets + values; the `%PDF-` magic), never on status 50 — a clean 50
+returning a null File is this platform's failure signature (Rule 8).
+
+**Cross-workspace import is CONDITIONAL, not absolute.** The API-NOTES record `Transport/import`
+answering `403 "workspace migration"`; that is the RELOCATION case. `import --file <pack>
+--workspace-id <clean-different-ws>` into a workspace where the ids do not already exist **succeeds**
+(measured: PL-120 B-022, PL-004 B-023) and preserves the flow id — so the round-trip proof (import
+into a clean different ws, run there, judge on the produced files) is achievable over the API for a
+process-bearing pack. Forms still need the designer (a form-bearing pack is not API-installable);
+the process is the marketplace artefact, the intake form is the designer front door.

procesio_cli/tools/procesio/PROCESIO-CONNECTORS-NOTES.md

@@ -0,0 +1,141 @@
+# PROCESIO connectors & platform actions - what the tool resolves live vs what it bundles
+
+Scope: how PROCESIO's built-in **connectors** and **platform actions** reach this tool,
+and the specific ones added in the Aug-Sep 2026 wave and in v3.0.0 (2026-10). Companion to
+`PROCESIO-CUSTOM-ACTION-NOTES.md` (which is about *building* NuGet custom actions) and
+`PROCESIO-SQL-ACTIONS-NOTES.md`.
+
+## The one rule that governs "is a new action supported?"
+
+The process builder resolves the **action catalog live** at build time
+(`dto/process/builder.py` `prepare_ctx` → `GET /api/Actions?getFullAction=true` on the
+target workspace) and only falls back to the bundled `dto/data/action_catalog.json`
+when the live fetch is slow or fails. Credential types are likewise live-resolved
+(`GET /api/Credentials/types`). **Consequence:** a new platform action or a new
+credential type works at runtime the moment PROCESIO ships it - no tool change. What
+goes stale is the *offline* bundle (the fallback) and the human notes.
+
+Refresh the offline bundle with `dto/data/_refresh.py`:
+
+```
+python tools/procesio/dto/data/_refresh.py --profile <name> --workspace-id <guid> --procesio-only            # report
+python tools/procesio/dto/data/_refresh.py --profile <name> --workspace-id <guid> --procesio-only --write    # apply
+```
+
+Always pass **`--procesio-only`** when the refresh runs against a real workspace: it
+keeps only `isProcesioAction=true` entries, so that workspace's own uploaded custom
+actions never leak into the platform bundle. It is additive by default;
+`--replace-existing` also updates the shape of actions already bundled (diff before
+committing - an in-place shape change silently alters every process the builder emits).
+
+## Three action kinds (do not conflate)
+
+`RunActionDto.ActionType` has three values:
+
+- **Platform (built-in) action** - seeded in the DB, `isProcesioAction=true`, global to
+  every workspace. Uploaded by admins via `POST /api/PlatformAction`. This is what the
+  catalog bundle mirrors. Connectors like Prelude/Redis/Data Store are platform actions.
+- **Custom action** - a developer's NuGet package implementing `IAction`, uploaded per
+  workspace via `POST /api/Actions` (multipart), `isProcesioAction=false`, run by the
+  Action-Execution service. Namespace blacklist on upload (Reflection, Diagnostics.Process,
+  IO, InteropServices, Loader, …).
+- **Connector action** - the *design-time* execution of a connector's property/event to
+  populate dynamic UI (chained dropdowns, previews): `POST /api/Actions/event`
+  (`ConnectorActionRequestDto`), async, results over SignalR (`ConnectionId`) or polled
+  at `GET /api/Actions/event/{id}`. A built-in connector (e.g. Data Store) exposes
+  `OnReady`/`OnChange` handlers with `OutputTarget.Options` to fill selects.
+
+## New/relevant `FeComponentType` values (custom-action / connector control types)
+
+Backend enum `Action-Core/.../Utils/FeComponentType.cs`; serialized lowercase-hyphenated
+(e.g. `Data_Store_Decisional` → `data-store-decisional`). Do not confuse with the FE
+form-element enum `ElementType`.
+
+- `Ai_Decisional_Case = 44`, `Credentials_Ai = 45`
+- `Data_Store_Mapper = 46`, `Data_Store_Decisional = 47`
+- `Auto = 102` (Action-Core 2.x, v3.0.0); also new: `FeTextFormat.DATASTORE = 8`
+- (also in play: `Map_Parameters = 43`, `Credentials_Db = 32`, `Document_Mapper = 38`,
+  `Document_Select = 39`, `Form_Template = 42`)
+
+## The connectors/actions added in the Aug-Sep 2026 wave (all prod-verified)
+
+- **Prelude** connector (`isProcesioAction=true`) - phone verification + lookup via
+  prelude.so. Credential is a **REST_API/Bearer** derived template ("REST API/ Prelude",
+  base `https://platform.prelude.so`); pick the operation via a `SelectedAction`/
+  `Operation` select. Inputs vary by operation (Target, TargetType, Code, Method,
+  PreferredChannel, SenderId, TemplateId, Variables, Locale, CodeSize, ForceChallenge,
+  CallbackUrl, CorrelationId, IncludeCallerName); output `Result`/`Status`/
+  `VerificationId`/`RequestId`. Confirms the old "Prelude" worked-example in
+  `PROCESIO-API-NOTES.md` is now a **real shipped connector**, not just an illustration.
+- **Redis** connector + Redis credential - code merged (Web-Api #1452 validation +
+  test client, Process-Execution #250), but **NOT yet activated on PROD**: as of
+  2026-09-21 `Redis` is still absent from `GET /api/Credentials/types` (35 types, no
+  Redis), so a Redis credential cannot be created there yet. Contract is documented in
+  `dto/credential/description.md`; treat as shipped-not-activated until it appears live.
+  Still NOT activated at the v3.0.0 release (2026-10-21): `Redis` is absent from
+  `GET /api/Credentials/types`.
+- **Query Store** action (`DataStoreQueryAction`) - query a data store from a process.
+  Input `Query` in a **code-editor whose text format is `datastore`** (the new format,
+  alongside `sql`/`python`/`ruby`), plus `Parameters` (map-parameters) and `Timeout`
+  (60-1800); output `ResultRows` (datatype) + `TotalCount`. This is the read path a
+  process uses; the interactive rows API is the `DataStore` REST surface the tool
+  already maps. Since v3.0.0 (2026-10) `Query` is a `;`-separated script: no transaction, at
+  most one row-returning statement (error 2003 otherwise, raised after the script ran), user
+  variables allowed, a misspelled `@param` reads as NULL silently. Full contract in
+  `PROCESIO-QUERY-STORE-NOTES.md`.
+- **CURL** action (`CurlAction`) - `CurlCommand` (code-editor) in → `Result` (datatype),
+  `Status` (number), `Error`. "Run curl commands."
+- **Data Store** connector in the process designer - operations
+  `SelectAll/SelectWhere/InsertRows/UpdateRows/DeleteRows` (sent by NAME), a WHERE tree
+  using the 21-value `QueryOperators` vocabulary (superset of the REST filter operators;
+  the tool already carries 0-20 in `handlers/datastore_ops.py`), and the
+  `Data_Store_Mapper`/`Data_Store_Decisional` control types above. In the FORM designer,
+  a data store is not an element - it is an event action
+  `RUN_DATA_STORE_OPERATION` (config `{dataStoreId, operation READ|ADD|UPDATE|DELETE,
+  inputMap[], outputMap[]}`) attachable to any element's `field-events`.
+
+## The connectors/actions added in v3.0.0 (2026-10, prod-verified)
+
+- **GUID Converter** (Utilitary, listed after Generate GUID), actionId
+  `77f61c6d-0000-0200-0000-00000000b001`. Input `Input` (required) plus `InputFormat`, a select
+  of AutoDetect / Standard / Hex / HexBigEndian / Number / Base64 / Base64DotNet. Outputs
+  Standard, Guid, Hex, HexBigEndian, Number, Base64, Base64DotNet. It converts between the
+  standard text form, the `0x` hex literal PROCESIO stores for a Data Store Guid column
+  (`BINARY(16)`, the `Hex` output), a decimal number and Base64, in both byte orders.
+  AutoDetect refuses ambiguous input (codes 1009-1012), so name the format when it is known.
+  See the Guid sections of `PROCESIO-QUERY-STORE-NOTES.md` for why the byte order matters.
+- **Azure Storage** connector, id `83838383-0000-0000-0000-aaaaaaaaaaaa`. Inputs Credentials,
+  Resource (Blob / Container), Operation (14 operations, e.g. Upload blob, List blobs by
+  prefix, Copy blob, Create container), Container, BlobName, InputFile, Prefix, BlobNames,
+  DestinationContainer, DestinationBlobName; outputs Result, UploadedBlobName, OutputFile,
+  Names, Details.
+- **"Azure Storage Account" credential**, a new ROOT credential type `AZURE_STORAGE` (= 10),
+  live in `GET /api/Credentials/types`. Fields (`be_id`): `AuthenticationType` (radio; the
+  option values are GUIDs, their `be_value`s are `SharedKey` / `ServicePrincipal`),
+  `AccountName`, `AccountKey`, `TenantId`, `ClientId`, `ClientSecret`, `BlobEndpoint`. It is
+  NOT the older derived template "OAuth2 (REST API) / Azure Storage"
+  (`REST_API_OAUTH_PREDEFINED`). Contract in `dto/credential/description.md`.
+- **Call Subprocess** gained two engine-written OUTPUT settings: "Call subprocess child
+  instance id" (`...a03fe3`) and "Call subprocess child instance id list" (`...a03fe4`). They
+  fill `Auto` (type 50) variables on the INSTANCE, named `{ActionName}_{PropertyName}` (e.g.
+  `Call_Subprocess_ChildInstanceId`). **Fixed in prod 2026-10-22:** both settings now come
+  back as type `auto` and their instance variables as `Auto` (type 50). The earlier state is
+  gone (2026-10-21 the settings were still served `ignore` and the variables typed 20, which
+  is why the old advice was to read them by name — no longer needed). The started-flow slot
+  (`...a03fe2`) stays type `ignore`; the builder treats `ignore` and `auto` alike and finds it
+  by id, so the fix needs no builder change (`_HIDDEN_SETTING_TYPES` already covers both). The
+  offline bundle (`dto/data/action_catalog.json`) was corrected to type the two slots `auto` to
+  match. Auto variables are engine-owned: read-only, always returned on instance / history /
+  archive reads, and kept through data-retention cleanup. The child instance ids are also kept
+  after the parent resumes.
+- **Query Store** became multi-statement (see its entry above).
+
+The offline bundle was refreshed for this wave on 2026-10-21 (238 actions: GUID Converter and
+Azure Storage added, Call Subprocess and Query Store replaced).
+
+## Scripting languages
+
+Python, Javascript, Node, **Ruby**, and **CURL** - no C# scripting action (C# is the
+custom-action NuGet path). Each takes a `Code` string and returns an output; Node adds a
+`Timeout` (60-300) and a `Stdout` output (console.log capture, added 2026-09). See
+`PROCESIO-NODE-MODULE-WHITELIST.md` / `PROCESIO-PYTHON-ACTION-NOTES.md` for the sandbox.