procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/tools/procesio/PROCESIO-CUSTOM-ACTION-NOTES.md

@@ -0,0 +1,179 @@
+# PROCESIO C# Custom Actions — packaging, whitelist, and the file channel
+
+What the platform documents about the **C# Custom Action** (`.nupkg` upload), and how
+that compares with the scripting actions. Everything below is **vendor-documented**,
+read from `docs.procesio.com/llms-full.txt`, and is labelled as such: none of it has
+been executed against a live instance from this framework. Read
+[`PROCESIO-NODE-MODULE-WHITELIST.md`](PROCESIO-NODE-MODULE-WHITELIST.md) for the
+sandbox facts that **were** probed live.
+
+## The build contract
+
+- **C# only**, class library, implementing `IAction` from `Ringhel.Procesio.Action.Core`
+  with `ClassDecorator` / `FEDecorator` / `BEDecorator` / `Validator` attributes.
+- **Target framework (changed in v3.0.0, 2026-10).** The hosts run on **net10.0**. Target
+  `net10.0` for a new build (preferred), or multi-target
+  `<TargetFrameworks>net8.0;net10.0</TargetFrameworks>`; a `net8.0` package still loads. The
+  public docs still say .NET Core 3.1 / net6.0 in places, which is stale, and the earlier advice
+  here ("target net6.0, keep 3.1 as the fallback") is withdrawn: Action-Core 2.x ships only
+  `net8.0;net10.0`, so there is no net6 build of the core package to compile against. Upload
+  runs server-side validations, so a wrong target fails late, at upload, not at build. See
+  "Runtime, loader and upload (v3.0.0)" below.
+- The core package comes from a **GitHub Packages feed** and needs a GitHub PAT with
+  `read:packages`. It is not on nuget.org.
+- The `.csproj` must set `CopyLocalLockFileAssemblies`, `GeneratePackageOnBuild` and an
+  `IncludeDepsInPackage` target, because **dependencies ship inside the `.nupkg`**.
+
+## Runtime, loader and upload (v3.0.0, 2026-10)
+
+Unlike the rest of this note, this section comes from the platform's own v3.0.0 release
+(Action-Core 2.0 / 2.1, Action-Execution v3, Test-Action v2, the Web-Api upload validator), not
+from the public docs.
+
+- **Which lib folder loads.** Action-Execution v3 loads the package's `lib/<tfm>` folder closest
+  to the host at or below net10.0, so net8, net6 and netstandard packages still load. (Before, it
+  probed only netcoreapp3.1 / net6 / net8 and loaded nothing from a net10-only package.)
+  Assemblies the host already holds (Action-Core, Newtonsoft.Json) are skipped, so a package
+  built against Action-Core 1.x binds to the host's 2.1 at run time.
+- **Multi-targeting passes upload.** The validator reads only the lib folder the host would
+  load, so a `net8.0;net10.0` package no longer fails with `MULTIPLE_ACTIONS`. The whitelist,
+  the blacklist and the codes are unchanged: `MULTIPLE_ACTIONS`, `FORBIDDEN_NAMESPACE`,
+  `FORBIDDEN_ASSEMBLY`, `INVALID_NUGET_PACKAGE`.
+- **The one breaking change (Action-Core 2.1):** `AiCredentialsManager`,
+  `AiCredentialsConfiguration` and `StructuredOutputMode` moved from namespace
+  `...Models.Credentials.API` to `...Models.Credentials.AI_API`. A package compiled against 2.1
+  must use the new namespace; a 1.x package that uses the AI credential types may fail to bind
+  on a 2.1 host, so rebuild it. The REST and DB credential types did not move.
+- **Additive in Action-Core 2.x:** `FeComponentType.Auto = 102`, `FeTextFormat.DATASTORE = 8`,
+  and the Azure Storage credential models (`AzureStorageCredentialsManager`,
+  `IAzureStorageClient`, `AzureStorageAuthenticationType`). Newtonsoft.Json is 13.0.4.
+- **The NuGet store is switchable per environment** (`ActiveNugetStore` = `None` /
+  `CodeArtifact` / `GitHub`). With `None`, upload and delete fail with `statusCode` 1013
+  (`FEATURE_DISABLED`), value "This feature is disabled on this environment.", target
+  `Action Library`; custom-action lists come back empty and the front end hides the feature. So
+  an empty custom-action list is not proof that nothing was uploaded: an upload answering 1013
+  means the environment has no store. Action-Execution downloads each package from the store
+  path recorded on its own template.
+- **Upload and delete stamp `UpdatedOn` / `UpdatedById`** on the action template.
+- **`Credentials_Rest` uploads no longer fail with `TEMPLATE_ERROR`.** A credential type now
+  resolves to its ROOT template. Before v3.0.0 a derived template that kept its parent's `Type`
+  (the REST API / Prelude template, for one) made every upload whose action had a
+  `Credentials_Rest` property fail with `TEMPLATE_ERROR`.
+- **Test-Action v2** is .NET 10 only, with no API change: `/api/Actions/test` and
+  `/api/Credentials/test` are unchanged.
+
+## Lifecycle — plan for it, it is unusually rigid
+
+- **A Custom Action cannot be updated in place.** The only route is a new package version
+  and a fresh create.
+- **It cannot be deleted once used in at least one process.** Deletion is guaranteed only
+  while the action has never been placed on a canvas. **Anything that promises to clean up
+  after itself must either never drag the action onto a process, or exercise it through the
+  action's own test area** (`IsTestable = true` opens one), or the cleanup fails by design.
+
+## The dependency whitelist — two lists, and the second is the sharp one
+
+"Other libraries that are not offered by Microsoft need to be whitelisted with us." The
+docs publish both lists as a JSON configuration block.
+
+**Packages:** `Ringhel.Procesio.Action.Core`, `Newtonsoft.Json`, `JetBrains.Annotations`,
+`SimMetrics.Net`, `CsvHelper`, `DocumentFormat`, `DocumentFormat.OpenXml`,
+`DocumentFormat.OpenXml.Packaging`, `DocumentFormat.OpenXml.Spreadsheet`, `Ical.Net`.
+
+**Namespaces:** the packages above plus `System.Runtime`, `System.Linq`,
+`System.Threading.Tasks`, `System.Collections`, `System.Private.CoreLib`,
+`System.Private.Uri`, `corlib`, `System.Text.RegularExpression`,
+`System.Diagnostics.Debug`, `System.ComponentModel`, `System.Data`, `System.Console`,
+and five `System.Net.*` entries.
+
+Four things fall out, and they decide designs:
+
+1. **The package list allows OpenXml; the namespace list only names `.Packaging` and
+   `.Spreadsheet`.** `DocumentFormat.OpenXml.Wordprocessing` (a DOCX body) and
+   `DocumentFormat.OpenXml.Presentation` (a PPTX) are **absent**. So the documented
+   capability is **XLSX-shaped**, and the common assumption that one library buys three
+   formats does not survive the namespace list. Untested; treat DOCX and PPTX in C# as
+   unproven until someone runs it.
+2. **`System.IO` is absent** while the core assemblies are present. The file example in
+   the same docs uses a `Stream`. Read that as **streams yes, file system unstated** —
+   and do not design against a temp path without measuring first.
+3. **Also absent**: `System.Net.Http`, `System.Security.Cryptography`, `System.Text.Json`,
+   `System.IO.Compression`. No PDF library of any kind appears, so **PDF inside a Custom
+   Action is a vendor request**, while PDF text extraction is available with no gate at all
+   through the native action and the Python action.
+4. **The published list contains two misspellings**, `WhitelistNamesapaces` and
+   `System.Text.RegularExpression` in the singular. If namespaces are matched literally,
+   `System.Text.RegularExpressions` is not whitelisted. A typo inside an allowlist is
+   load-bearing; verify before relying on regex.
+
+The whitelist is published **as a configuration block**, which is a deployment-owned
+artefact. Whether a self-hosted operator can edit it, and therefore whether the dependency
+constraint is topology-dependent, **is not documented**. Ask before promising a customer a
+library that is not on the list.
+
+## How a file reaches a Custom Action — a stream, never a path
+
+```csharp
+IEnumerable<FileModel> FileList { get; set; }   // or a single FileModel
+
+foreach (var file in FileList)
+{
+    _ = file.Name;              // string
+    _ = file.File;              // Stream — the content
+}
+```
+
+`FileModel` has exactly two properties, `Name` and `File`. The front end binds it with
+`[FEDecorator(Type = FeComponentType.File)]` against a file-typed process variable.
+**Nothing in the documentation states that a Custom Action has a file system**, in either
+direction, and nothing states whether anything written during one invocation survives into
+the next. Both are open questions, and the second one is the expensive one: a per-run
+filesystem and no filesystem look identical in the docs and behave very differently across
+an async split.
+
+## The scripting actions, for comparison
+
+Four exist, and they are not one sandbox with four languages.
+
+| Action | Libraries | File position |
+|---|---|---|
+| **Javascript** | none ("no access to specific libraries") | — |
+| **Node** | a fixed list of **24**, no additions | docs state plainly it "does not support working with files" |
+| **Python** | 9 preinstalled, including **pdfplumber**, **PyPDF2**, **pandas**, **spacy**, **pillow** | "Files cannot be added in Python script", then the base64 bridge below |
+| **Ruby** | 9 gems, none document-related | — |
+
+**The platform's documented file channel for a script is base64 through process
+variables**, not a file system: `File to BASE64` turns a File variable into a string, the
+script works on the string, and `Base64 to File` turns the result back into a File. Use
+that bridge rather than looking for a path.
+
+## Before building a Custom Action, check the catalogue
+
+A large amount of file work needs no custom code, no upload and no whitelisting request:
+
+- **PDF**: Extract Text (returns concatenated text **plus** per-word JSON with position and
+  font), Extract Embedded Files, Area Mapper, Merge Files, Select/Remove pages,
+  Acroform Insert Image.
+- **Excel**: Create Workbook, Split Workbook, XLS To XLSX, Insert/Rename/Delete Sheet,
+  Get Sheet Names, Read Range, Read Range from CSV, Copy Paste, Apply Formula,
+  Get Named Range, Get Last Used Row.
+- **Documents**: Generate Document (from a Document Designer template), HTML to PDF,
+  DOCX to PDF, DOCX to HTML, Word Mail Merge, Export to CSV/XLSX, Write (list) to file,
+  Read file, File to Base64, plus an Archive sub-folder for compress and decompress.
+
+**Rule of thumb: catalogue action first, then Python action, then Node, then a Custom
+Action.** The order tracks cost — the first three need no upload, no versioning ritual, no
+GitHub PAT and no vendor whitelisting request, and only the Custom Action carries a
+lifecycle you cannot undo.
+
+## Documented size limits — and which ones do not apply
+
+| Limit | Applies to |
+|---|---|
+| 100 MB | FTP/sFTP **Download File** |
+| 1 GB | FTP/sFTP **Upload File** |
+| 500 MB (default `maxfilesize`) | form **File Upload** element |
+
+**None of these binds a Custom Action.** No size limit, timeout, memory limit or
+concurrency statement is documented for Custom Actions at all. Measure before quoting a
+figure to anyone.

procesio_cli/tools/procesio/PROCESIO-DOCS-FIX-REPORT.md

@@ -0,0 +1,123 @@
+# PROCESIO API docs — corrections needed
+
+Audience: the PROCESIO docs/dev team.
+Source of truth: a real login HAR from `procesio.app` + live calls against
+`webapi.procesio.app` (2026-06-23). Target page:
+`https://docs.procesio.com/developers-guide/procesio-api-documentation`.
+
+The **username/password authentication** chapter is materially out of date — it
+documents an OAuth/Bearer flow on a host that no longer serves it. The API-key /
+run-a-process chapter is mostly correct. Details below.
+
+---
+
+## 1. Authentication host moved: `auth.procesio.app` → `webapi.procesio.app`
+
+**Docs say:** *"Use the Proxy API `https://auth.procesio.app/swagger/index.html`
+to reach the Authentication Service … POST `/api/Authentication`."*
+
+**Reality:** login happens on the Web API host. `auth.procesio.app` now answers
+with Kong's **default self-signed certificate** (`CN=localhost, O=Kong`) and
+returns `{"message":"no Route matched"}` for `/api/Authentication` and
+`/swagger/index.html`. Any integrator following the docs hits a TLS/404 wall.
+
+**Fix:** point the auth chapter at `https://webapi.procesio.app`, and remove (or
+repoint) the dead `auth.procesio.app/swagger/index.html` link.
+
+## 2. Login request shape is wrong (JSON+OAuth → form + `x-requested-by`)
+
+**Docs say:** `POST /api/Authentication` with a JSON body
+`{realm:"procesio01", grant_type:"password", username, password,
+client_id:"procesio-ui", client_secret:""}`.
+
+**Reality (from the HAR):**
+
+```http
+POST https://webapi.procesio.app/api/authentication
+Content-Type: application/x-www-form-urlencoded
+x-requested-by: playground-v1
+
+username=<user>&password=<pass>&client_id=procesio-ui
+```
+
+Differences to correct:
+- **Content type is `application/x-www-form-urlencoded`**, not JSON.
+- Body fields are only **`username`, `password`, `client_id`**. `realm`,
+  `grant_type`, and `client_secret` are **not used** — drop them from the docs.
+- A **`x-requested-by`** request header is **required**. Without it the gateway
+  returns **`407`**. (The web app sends `x-requested-by: playground-v1`.) This
+  header is currently undocumented and is the single most common reason an
+  integration "mysteriously" fails to authenticate.
+- Path casing in production is lowercase `/api/authentication` (ASP.NET is
+  case-insensitive, so both resolve, but the docs/Swagger differ — align them).
+
+## 3. Token delivery: Bearer JWT → HttpOnly cookie session
+
+**Docs say:** *"you will receive an access token in the response which you will
+be able to use to access the Web API"* and a **"Bearer Authentication"** section
+(Authorize with `Bearer {token}`).
+
+**Reality:** the `200` response body contains **no token** — it is literally
+`{"message":"Authentication successful"}`. Authentication is delivered as **two
+HttpOnly cookies**:
+
+```
+Set-Cookie: __Host-procesio.access   (HttpOnly, Secure, Path=/)
+Set-Cookie: __Host-procesio.refresh  (HttpOnly, Secure, Path=/)
+```
+
+Subsequent Web-API calls authenticate by **sending those cookies** (the SPA uses
+`fetch(..., {credentials:"include"})`; the server replies with
+`Access-Control-Allow-Credentials: true`) plus the same `x-requested-by` header.
+Lifetimes come from the cookies' own `Expires` attribute — observed
+**~24 h for `.access`** and a longer window for `.refresh` (values were 961 and
+733 bytes, i.e. JWTs). The `x-session-expires-at` header is declared in
+`Access-Control-Expose-Headers` but was **empty** in the login response we
+captured — either populate it consistently or remove it from the contract.
+
+**Fix:** replace the "access token + Bearer {token}" narrative for the
+username/password flow with a **cookie-session** description:
+- list the two `__Host-procesio.*` cookies and that they are HttpOnly/Secure,
+- state that callers must send cookies (`credentials: include`) + `x-requested-by`,
+- document `x-session-expires-at` and the refresh mechanism (what calls the
+  refresh cookie, and the refresh endpoint, if any),
+- if `Authorization: Bearer` is still accepted by the Web API for
+  machine-to-machine use, document **how to obtain that token now** (the login
+  no longer returns one); otherwise remove the Bearer section for this flow.
+
+## 4. API-key auth — mostly correct, two clarifications
+
+The run-a-process chapter correctly lists the three headers `key` (key name),
+`value` (key value), `workspaceid` (workspace GUID) on
+`POST https://webapi.procesio.app/api/projects/{id}/run` with body
+`{"payload":{}, "connectionid":null}`. Confirmed working live. Two additions:
+
+- **State that `workspaceid` is required for workspace-scoped keys.** Live: a
+  workspace-scoped key returns **`401`** with no `workspaceid`; supplying the
+  correct workspace GUID returns `200`. (A master/personal key happens to work
+  without one.) This isn't obvious and bites integrators.
+- The Swagger security schemes name these headers `KeyName`→`key` and
+  `KeyValue`→`value`. Make sure the prose and Swagger use the same names
+  (`key`/`value`, not `api_key`).
+
+## 5. Minor path/casing alignments
+
+- Process **list** is `GET /api/Projects`; **run** is `POST /api/Projects/{id}/run`
+  (capital `P`; the run endpoint also accepts `runSynchronous` &
+  `secondsTimeOut` query params). The "ProcessTemplate" tag maps to the
+  `/api/Projects` path — worth a note so readers don't look for `/api/ProcessTemplate`.
+- Workspace **list** is `GET /api/Workspaces` (plural). `GET /api/Workspace`
+  (singular) is not a route → 401/404. Align docs/examples to the plural form.
+- The `webapi.procesio.app` v1.19 Swagger is accurate and reachable — keep it as
+  the canonical Web-API reference; just fix the **auth chapter** that precedes it.
+
+---
+
+### TL;DR for the doc owner
+1. Auth host: `auth.procesio.app` → `webapi.procesio.app`.
+2. Login is **form-urlencoded** with **`username`+`password`+`client_id`** and a
+   required **`x-requested-by`** header — not JSON/OAuth.
+3. Auth is a **cookie session** (`__Host-procesio.access`/`.refresh`), not a
+   Bearer token in the body.
+4. Spell out that **`workspaceid` is required** for workspace-scoped API keys.
+5. Fix the dead `auth.procesio.app/swagger` link and small path-casing mismatches.

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

@@ -0,0 +1,94 @@
+# PROCESIO environments — model & mechanics
+
+PROCESIO ships as independent installations with no data path between them (each has
+its own hosts, its own accounts). This tool models each installation as a named
+**environment** `<Client>-<ENV>` carrying the four hosts it lives on, and binds each
+credential to one environment.
+
+## The four hosts
+
+| field        | what it is                              | prod value                 |
+|--------------|------------------------------------------|----------------------------|
+| `web_base`   | Web API — every REST call                | `https://webapi.procesio.app` |
+| `app_base`   | designer / front-end — designer URLs + the login CORS `Origin`/`Referer` | `https://procesio.app` |
+| `forms_base` | public forms host — rendered-form URLs   | `https://forms.procesio.app` |
+| `auth_base`  | legacy Proxy/Authentication host (login actually goes to `web_base`; rarely used) | `https://auth.procesio.app` |
+
+The `-qa` / `-dev` installations follow a host family: `webapi-qa.` / `qa.` /
+`forms-qa.` and `webapi-dev.` / `dev.` / `forms-dev.`.
+
+## Two layers, merged at read time
+
+- **Built-in presets** in `environments.py::BUILTIN` (`Internal-PROD/QA/DEV`) — PROCESIO's
+  own infra, framework-shared, available with zero setup. These are *framework* data
+  (public app hostnames), like the historical hard-coded defaults were.
+- **User registry** at `context-state-knowledge/config/procesio/environments.json`
+  (per-user, wipeable) — client-specific environments (`Acme-*`, …) and the
+  `default` pointer. A user entry with a built-in's name **overrides** it (correct a
+  moved Internal host without a code change). Client installation URLs are
+  customer-specific, so they are **user data** and live here, never in shared code.
+
+## Resolution precedence (both credential + URL)
+
+Active **environment** for a call, highest first:
+1. `--environment <name>` flag,
+2. the credential's own `environment` binding,
+3. the stored `default` environment,
+4. `Internal-PROD`.
+
+The resolved environment's URLs are folded into the profile the client holds, so
+`config.web_base/app_base/forms_base/auth_base` pick them up. An explicit per-profile
+URL override (a rare `web_base` on the credential blob itself) still wins — injection
+uses `setdefault`.
+
+Active **credential** for a call: `--profile` → the credential bound to the active
+environment → the stored default profile. So switching environment also switches which
+account/key is used, provided exactly one credential is bound there.
+
+## Backward compatibility (why nothing breaks on upgrade)
+
+A pre-existing single-credential setup keeps working as production with **nothing to
+re-enter**: no registry file + an **unbound** credential ⇒ `Internal-PROD` ⇒ the exact
+historical hard-coded URLs. Existing credentials carry no `environment` field, so they
+resolve to `Internal-PROD` automatically.
+
+## Operating it
+
+```
+list-environments                       # what exists, which is default, bound creds
+add-environment --name Acme-PROD \     # register a client installation
+    --web-base https://webapi.acme… --app-base https://acme… --forms-base https://forms.acme…
+set-environment --name Internal-QA       # move the default pointer (persists)
+add-credential --name qa-me --type userpass --username … --environment Internal-QA
+<any action> --environment Internal-DEV  # one call against another env, default unchanged
+```
+
+`add-environment` needs all three of `--web-base/--app-base/--forms-base`; `client`/`env`
+are derived from the `<Client>-<ENV>` name when omitted. Built-in `Internal-*` cannot be
+removed. Names are matched case-insensitively.
+
+## The form-code-key is per environment too
+
+A form's "Switch to code" CSS and JavaScript (`Data.code`) is AES-encrypted with a key
+the installation's web app holds. The platform team confirmed it is one key per
+INSTALLATION: the same on every workspace of it, not guaranteed to match on another. So
+the tool stores it per environment, `form-code-key@<environment>`, and resolves it from
+the call's environment like everything else here (`form_code_keys.py`):
+
+- `form-code-key@<env>` when stored;
+- else, for the DEFAULT environment only, the bare legacy `form-code-key` (the same
+  backward-compatible rule as an unbound credential);
+- else an error naming the secret to store. Never another environment's key: a blob
+  encrypted with the wrong installation's key is one its renderer cannot open, and the
+  form goes blank.
+
+```
+python scripts/set-credential.py procesio form-code-key@Internal-QA
+```
+
+## Tests / isolation
+
+The suite's autouse `_isolate_userdata` fixture (conftest) pins `AAT_USERDATA_DIR` to a
+temp dir, so every test starts from the built-ins with `default = Internal-PROD` and no
+test reads or writes the developer's real registry. Userpass login tests must also take
+the `store` fixture (in-memory creds) or a persistent cached token skips the login.

procesio_cli/tools/procesio/PROCESIO-FE-VALIDATION-NOTES.md

@@ -0,0 +1,107 @@
+# PROCESIO front-end (designer-layer) validation — notes
+
+Born 2026-07-06. Ports the Process Designer's client-side **"Process Errors"** checks
+(the ones that BLOCK designer *Save*) into an offline validator, and auto-runs it before
+every process save. Source of truth for the rules: `docs_info/process-validation-reference-1.md`
+(the FE team's verbatim dump of `Validation.ts` + `ControlValidators/*`).
+
+## Why this exists (the core insight)
+
+`POST /api/Projects/validate` validates only the **runtime** layer (parameters) and
+returns EMPTY even when the designer would REFUSE to save. The designer's "Process
+Errors" panel is a **separate client-side check of the DESIGNER layer (`customData`)**
+with **no server endpoint**. So a tool-driven save was held to a *lower* bar than a human
+clicking Save. This closes that gap: FE (designer) checks run first, then BE, then save.
+
+## Pieces
+
+- `flowmodel/fevalidation.py` — **pure**, offline, case-insensitive validator over a flow
+  DTO. `validate_flow(flow, *, datatypes=None, target_vars_of=None, include_types=True)`
+  → `list[warning]`. `split_severity()` → `(errors, warnings)`.
+- `handlers/fevalidate.py` — impure layer: gathers the datatype catalog + subprocess-var
+  resolver from the live API, exposes the **`process-fe-validate`** action, and provides
+  the **`pre_save_validate(client, dto, *, force)`** gate (FE → BE, raises
+  `ValidationBlocked` on blocking errors unless `force`).
+- Wiring: `dto/framework.py` gained a `save_gate` field on `Component`;
+  `dto/process/builder.py` defines `_save_gate` and calls it inside `_edit` before the PUT
+  and registers it on `COMPONENT`; `handlers/dto_actions.py` runs the gate in
+  `_make_create` before POST and threads `--force` / `--no-types` into `ctx`.
+- `errors.py` gained `ValidationBlocked` → classified as `validation_failed`, exit 2,
+  with the full `{fe, be, blocked, forced}` report as `details`.
+
+## Severity model (deliberate)
+
+- **error** (blocks save): the deterministic, high-signal checks — connectivity, exactly
+  1 Start / ≥1 Stop, node names, unique/primitive-named variables, numeric limits,
+  required-empty fields, leftover placeholders, number/integer value-format, and
+  subprocess required-input mapping.
+- **warning** (never blocks): the **data-type MISMATCH** layer. The FE helper
+  `getValueDataTypes` (which resolves a value's variable refs to their datatypes) is NOT
+  in the reference file, so it was reconstructed best-effort. Kept non-blocking so an
+  imperfect reconstruction can never wrongly block a legit save. Ported for the default
+  validator + column-definition; the other composite type-checks (TabsPayload,
+  MapProcessData, Conditional) are left for a later tuned pass. `--no-types` skips it.
+
+## DTO ↔ FE-model mapping — quirks discovered the hard way
+
+The reference describes the FE's **in-memory** model; the persisted/live DTO differs.
+These bit me during live verification — get them right or you get false positives:
+
+1. **Node name = `customData.name`, NOT `actionName`.** The FE's `node.name` (the canvas
+   label, defaults from the template, e.g. "Start"/"Call API") is stored in
+   `customData.name`. On many live DTOs `actionName` is `None`. Reading `actionName`
+   flagged `NODE_NAME` on 9/25 valid processes. `_action_name` reads `customData.name`
+   first (sentinel `_ABSENT` when the key is truly absent → falls back to `actionName`
+   for older/fixture DTOs).
+2. **`actionTemplateId` / `actionTemplateName` can BOTH be `None`** on legacy DTOs (e.g.
+   "Github API", "Old/*"). Template-family detection (`_kind`) keys off the GUID first,
+   then the template name, then falls back to `customData.name` for the structural
+   templates (Start/Stop/For Each/(Trigger) Subprocess). A renamed non-structural node
+   just reads as "other" (safe false-negative, never a false block).
+3. **Settings carry the FULL FE `Setting` shape** in `customData.configuration[].settings[]`:
+   `id, type (SettingType), label, value, dataTypeId, isList, isRequired, limits`. So the
+   FE field-level checks CAN run offline — no need to enrich from `/api/Actions`.
+4. **Empty ≠ format error.** The FE's `isValidNumber`/`isValidInteger` treat `""` as
+   valid; emptiness is the *required* check's job. An optional numeric field left blank
+   (e.g. a Delay's unused "Runtime Amount", `type=number dataTypeId=INTEGER value=""`)
+   must NOT be flagged. `_default_value_check` and `_check_limits` skip empty values.
+   This was a real false positive on "AI Decisional Test" (BE-valid).
+5. **`lineArray` is reconstructed from `Ports`.** Edges live on the *source* action's
+   `Ports` (`sourceId`/`destinationId`/`type`/`data.isDefault`). Each line touches BOTH
+   endpoints. **Error path** = `Type == 1` OR `data.isDefault == "error"` (the reference
+   keys on `isDefault === "error"`; the DTO also uses `Type == 1`).
+6. **`flow-list` (subprocess target) setting has NO `id`.** Locate it via a loose walk
+   (`_walk_settings_loose`) that recurses one level into side-panel values; the id-based
+   `getAllSettings` flatten skips it.
+7. Case: exports are PascalCase (`Actions`, `CustomData`), live API is camelCase. Every
+   field access goes through `_g` (case-insensitive). Live flow is under `resp["flow"]`.
+
+## Live verification (2026-07-06)
+
+Swept 25 real processes in the default workspace: **24 FE-clean, 0 false positives**; the
+only FE-flagged one ("AI Connector Builder Result") is genuinely `isValid=False` (an
+`UNCONNECTED` action). FE errors correctly line up with BE invalidity where they overlap.
+
+## Relationship to `flow-lint`
+
+`flow-lint` (handlers/flowlint.py) predates this and covers a few designer checks NOT in
+the reference file: stale subprocess **side-pannel id**, Execute-Query **Output** null /
+scalar-typed, and Node **code binding error-scope/undeclared vars**. Those are
+complementary. **As of 2026-07-06 those three unique flow-lint checks are FOLDED INTO the
+gate**: `run_fe_validation` calls `flowlint.lint_flow_dto` and merges its unique findings
+(SIDEPANEL_ID, EXECQUERY_*, CODE_*, missing_error_variable) as blocking errors — the
+overlapping subprocess-mapping ones are excluded to avoid double-reporting. It's
+best-effort (wrapped in try/except): a flow-lint infra hiccup never blocks a legit save.
+So a stale-sidepanel / bad-Execute-Query / error-scope-code flow is now blocked on save too.
+
+## Gotchas / do-nots
+
+- The gate is process-only (via `Component.save_gate`); other components (form/document)
+  are unaffected — their existing `validate` oracle still runs.
+- `--force` bypasses BOTH FE and BE and saves anyway. `--dry-run` runs the gate in
+  report-only mode (forced open) so you see the validation without saving.
+- The type (warning) layer needs the datatype catalog (`GET /api/DataTypes`,
+  `pageItemCount=1000`); it's fetched best-effort and silently skipped if that call fails.
+- After changing any action's arg/description surface, regenerate the manifest:
+  `python -m tools.procesio.gen_manifest` (never hand-edit tool.yaml; ~236 KB, capped
+  Write). `tests/test_manifest_sync.py` guards it.