procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/agents/procesio/PROCESIO-ENVIRONMENTS.md

@@ -0,0 +1,62 @@
+# Working across PROCESIO environments
+
+PROCESIO runs as separate installations — production, QA, dev, and each client's own
+PROD/QA/STAGING. This tool calls each one an **environment**, named `<Client>-<ENV>`
+(e.g. `Internal-PROD`, `Internal-QA`, `Internal-DEV`, `Delgaz-PROD`, `Delgaz-DEVQA`).
+Each environment has its own host URLs and its own credentials — there is no data path
+between them.
+
+## When the user says "work on PROCESIO Internal-QA" (or DEV, or a client env)
+
+That is a **switch the default environment** request. Do:
+
+```
+run-tool procesio set-environment --name Internal-QA
+```
+
+From then on every process/form/instance action runs against that environment and uses
+the credential bound to it — until the user switches again. Confirm what happened by
+reading the result's `default_environment`, `web_base`, and `credentials`. If
+`credentials` is empty, tell the user no account is bound there yet and how to add one
+(below) — do not silently fall back to another environment.
+
+For a **one-off** call against a different environment without moving the default, pass
+`--environment <name>` on that single action.
+
+## The built-in environments (zero setup)
+
+`Internal-PROD`, `Internal-QA`, `Internal-DEV` always exist for everyone. Production is
+the default until someone switches. Client environments are added at runtime.
+
+## Adding a client environment
+
+```
+run-tool procesio add-environment --name Delgaz-PROD \
+    --web-base https://webapi.<host> --app-base https://<host> --forms-base https://forms.<host>
+```
+
+`client`/`env` are derived from the `<Client>-<ENV>` name. Then bind that client's
+account to it:
+
+```
+run-tool procesio add-credential --name delgaz-me --type userpass \
+    --username <…> --environment Delgaz-PROD
+```
+
+(Entering the secret itself is the user's action — never take a password on the command
+line for them; the tool prompts without echoing, or the user stores it via the
+dashboard / `set-credential`.)
+
+## What you can rely on
+
+- **Nothing to migrate.** An existing credential with no environment binding is treated
+  as `Internal-PROD` (production URLs, unchanged). Colleagues keep working with no
+  action from them.
+- **Credentials are tied to environments.** Switching environment switches the account
+  too, as long as exactly one credential is bound there; otherwise pass `--profile`.
+- **Read before you switch for someone else.** `list-environments` shows every
+  environment, the current default, and which credentials are bound where — use it to
+  answer "what environments do I have / which am I on".
+
+Mechanics, the registry-file location, and resolution precedence are documented tool-side
+in `tools/procesio/PROCESIO-ENVIRONMENTS-NOTES.md`.

procesio_cli/agents/procesio/PROCESIO-SCHEDULING.md

@@ -0,0 +1,47 @@
+# PROCESIO Scheduling — run a process unattended
+
+A **schedule** runs a process on a recurrence without a caller. Manage them with the
+tool's curated actions (`procesio list-schedules` / `get-schedule` / `create-schedule` /
+`update-schedule` / `delete-schedule` / `set-schedule-status` / the notifications pair /
+`list-project-schedules`) over `/api/Schedules*` — not the untyped `request`.
+
+## Recurrence types
+
+`RecurrenceTypes`: `NONE=0, ONCE=1, MINUTES=2, HOURS=3, DAILY=4, WEEKLY=5, MONTHLY=6,
+YEARLY=7, CRON=8`. The recurrence lives in the schedule body's nested `recurrence` block
+(`recurrence` = the type enum, plus the type-specific fields).
+
+## Crontab schedules (the new capability)
+
+Type **`CRON = 8`** lets you express the recurrence as a standard **5-field crontab**
+(`minute hour day month weekday`, `L`/`W`/`#` tokens supported) with an IANA
+**time zone**.
+
+- **Preview before you commit:** `procesio validate-crontab --cron "0 6 * * *" --timezone
+  Europe/Bucharest [--count N]` calls `POST /api/Schedules/validate-crontab` and returns
+  a human description + the next occurrences (in UTC). Always preview a cron string this
+  way before creating the schedule — it catches an inverted field order or a timezone
+  mistake without creating a live schedule.
+- **Set it:** `create-schedule` / `update-schedule` accept `--cron` + `--timezone`, which
+  set the recurrence to CRON (type 8) over the JSON `--payload` (name, target process,
+  process inputs, notifications). The raw `--payload` remains the authoritative path.
+
+## Gotchas (carried from live runs)
+
+- **The write body must mirror the read DTO closely.** A hand-simplified recurrence block
+  returns HTTP 400 "missing or incorrect resource parameters". When unsure of a
+  non-cron recurrence, `get-schedule` an existing one and adapt its exact shape rather
+  than build from scratch.
+- **`status:false` is ignored on create** — a schedule is created active. To land a
+  disabled schedule, create then `set-schedule-status --active false` (two steps).
+- **`notification.emailList` is a single comma/semicolon-separated string**, not a list.
+- The exact camelCase field names of the cron recurrence block are confirmed against the
+  launched platform — verify a created cron schedule with `get-schedule` before relying
+  on it in production.
+
+## Verify
+
+`validate-crontab` to confirm the occurrences, then `create-schedule`, then
+`get-schedule` to confirm the stored recurrence, then (optionally) let it fire once or
+trigger the target process directly to confirm it runs. Clean up test schedules
+(`delete-schedule`) — a stray active schedule keeps launching instances.

procesio_cli/agents/procesio/PROCESIO-VISUAL-ORGANIZATION.md

@@ -0,0 +1,175 @@
+# PROCESIO visual organization & build patterns (agent guidance)
+
+How to lay out a process so a human can read it, and the build patterns that recur in
+production. Agent-scoped: these are standards a build should meet, not tool mechanics.
+The DTO shapes behind every claim are in `tools/procesio/PROCESIO-RESOURCE-MODEL-NOTES.md`;
+the deterministic re-layout tool is specced in `todo/procesio-canvas-layout-tool.md`.
+Additive to [PROCESIO-BEST-PRACTICES.md](PROCESIO-BEST-PRACTICES.md) (§2 modularize,
+§10 speed) — it does not replace anything there.
+
+---
+
+## 1. Why layout matters
+
+A process is read far more often than it is built — by the next builder, by QA, by the
+person debugging a 2am failure. A tangled canvas hides the logic; a tidy one shows it.
+Layout is not cosmetic, it is part of "document & handover" (best-practices §7). The
+target: someone with no prior context can follow the flow left-to-right and see where it
+branches, loops, and stops.
+
+## 2. Layout rules (what "tidy" means on a PROCESIO canvas)
+
+The canvas model: a node's shape is set by its action (inherited, never changed when you
+place it); edges are `Ports` (`Type 0` normal, `Type 1` error); a `Decisional` fans out
+any number of branches that need not re-merge; the only container is the `For Each` loop
+frame, whose children sit *inside* it via `ParentId`. Given that, the rules:
+
+1. **Flow left-to-right.** `Start` on the left, `Stop`(s) on the right. Depth from Start
+   sets the column. Time reads as horizontal distance.
+2. **One column per dependency level.** All actions at the same distance from Start share
+   a vertical axis. Never stack unrelated actions in the same column.
+3. **Center children on their parent.** A node with several successors sits at the
+   vertical center of that group (tidy-tree rule). Branches of a Decisional spread
+   symmetrically around the diamond.
+4. **No overlaps, consistent gaps.** Equal horizontal gap between columns; minimum
+   vertical gap between siblings. When a deeper level grows, push siblings apart — never
+   let boxes collide.
+5. **Lay out the For Each frame recursively.** Place a `For Each`'s children first, size
+   the frame to fit them, then place the frame as one node at its level.
+6. **Error ports go down-and-out.** `Type 1` (error) edges route to a handler placed
+   below the main lane, so the happy path stays a clean horizontal line.
+7. **Re-converge only where paths should reunite.** A Decisional's branches may end at
+   their own `Stop` or merge at a `Join` — don't force a Join where branches are genuinely
+   independent. Where they do reunite, make the `Join` visible so the reader sees it.
+8. **Deterministic order.** Same graph → same layout. Order siblings by descendant-count
+   then id, so re-running layout doesn't reshuffle the diagram.
+
+This is the Reingold-Tilford "tidy tree with contours" idea applied to a DAG: layer by
+depth, pack each column without overlap using subtree contours, center on the parent.
+The same algorithm, run on the **process→process** graph (`Call Subprocess` /
+`Trigger Subprocess` targets) instead of the in-flow graph, produces the **Resource Map**
+(left = who calls this process, right = what it calls). The layout tool will do both.
+
+## 3. The For Each container
+
+The only container the Process Designer supports today is the `For Each` loop frame (an
+`area`). Keep its body small and self-contained — everything inside runs once per item,
+so cost multiplies (best-practices §10). **A `For Each` cannot contain another `For
+Each`.** To nest a loop, put a `Call Subprocess` (or `Trigger Subprocess`) inside the
+`For Each` and place the inner loop in that subprocess — that also keeps each loop body
+flat and independently testable. (Free-form grouping areas are not yet supported by the
+designer; don't rely on them.)
+
+## 4. Build patterns to reach for
+
+The actions that carry most real systems, and the shapes they form:
+
+- **Modular by subprocess.** Real systems are a thin main process orchestrating small
+  reusable subprocesses (auth, paging, upsert, notify), exactly as best-practices §2/§3
+  prescribe. Synchronous `Call Subprocess` when you need the result; async
+  `Trigger Subprocess` to fire-and-forget.
+- **Branch then (maybe) join.** `Decisional` + `Join` is the standard control shape:
+  decide, run the branch-specific work, optionally re-merge. Keep decisionals single where
+  you can — five chained decisionals (~2s) collapse to one (<200ms) (best-practices §10).
+- **Model JSON, don't chain extractors.** `Extract Objects/List/Object/Text` exist, but
+  the fast path is a typed Data Model read directly (best-practices §10). Reserve the
+  extract family for genuinely dynamic shapes.
+- **Script to do more per node.** A `Node` script often replaces a chain of primitives
+  (and `Node` returns raw, typed output; `Javascript` wraps `{result}` — see API notes).
+  Fewer nodes = faster + more readable.
+- **Throw on purpose.** `Throw` raises a controlled error into the error port — use it to
+  fail loudly on a business-rule violation instead of letting bad data flow on.
+- **Centralize SQL through credentials.** `Execute Query`/`Execute Command` bind a
+  credential by gid (never inline secrets). Apply the `sql-server-optimizer` skill.
+
+## 5. Forms: design for the user, route approvals cleanly
+
+(DTO detail in the resource-model note; here the standards.)
+
+- **Calls to processes are the expensive part of a form.** A control's `RUN_PROCESS`
+  event should call a process of 1-3 actions, optimized for speed (best-practices §9).
+  Prefer `syncRun:false` + a scoped loader for anything that might exceed 1s; fill the
+  result back via `outputMap`. Drive option lists from a static `sourceType:JSON` where
+  the data is fixed — don't call a process to fetch constants.
+- **Approval = assign + show + capture + branch.** Put an `approval` control with a named
+  `approver` (and `approverReplacement` fallbacks) on a task form (`Assignees` set). Show
+  approver-only fields with `visibility:{type:"task-assignees"}`. The control captures
+  `approved` + `comment` + `responseUser` + `responseDate`; branch the downstream process
+  on `approved`. For sequential sign-offs use multi-step `approvalSteps`. Keep the
+  approver's screen minimal — they decide, they don't re-enter data.
+- **Compose apps with `chainConfig`.** Several forms tied into one columnar dashboard is
+  the "App" pattern — use it for an operator landing page that links to sub-forms, rather
+  than one giant form.
+- **Style via theme variables, not hacks.** Set the `--c-*` theme variables; reserve
+  `Data.code` (encrypted) for genuine custom CSS/JS, and run form JS against
+  `window.parent.document` inside the sandbox iframe.
+- **Dark theme + per-mode palettes.** A form now carries a light AND a dark palette
+  (the 16-var `DARK_PALETTE`), swapped at runtime by `themeMode`. Opt in via the form
+  config (`themeMode` / `themeDark` overrides); don't fake dark mode with custom CSS.
+- **Element alignment.** Container elements (section, list-item, column, step, tab,
+  side-panel) accept three flex vars in their per-control style — `--fd-<scope>`
+  (direction), `--jc-<scope>` (main axis), `--ai-<scope>` (cross axis). Use them to lay
+  out contents instead of custom CSS.
+- **Trigger a Data Store operation like a process.** Besides `RUN_PROCESS`, a control can
+  raise `RUN_DATA_STORE_OPERATION` (READ/ADD/UPDATE/DELETE) straight against a data store,
+  with input/output maps and (for every op except ADD) filters. Reach for it when the
+  form just needs to read or write a tenant table without authoring a process. See the
+  `datastore` topic.
+
+## 6. Shapes in the Process Designer (decorative, execution-irrelevant)
+
+Cuore's **Shapes** (rectangle / ellipse / diamond, PRC-4391) are annotation objects on
+the canvas — they group and label a region and never affect execution. They persist
+under the flow's opaque `canvasData.shapes` blob (not a top-level field) and sit in a
+z-order band **below** the connectors. Two rules for the agent: **never reason about a
+shape as a node** (it has no ports, no config, no run behavior), and **never let an edit
+or a re-layout drop `canvasData`** — the tool's `process-edit` carries the live canvas
+through, and the layout engine leaves `canvasData` byte-identical; preserve that when
+touching a flow by hand.
+
+## 6. When you build or re-organize a process
+
+- After building programmatically, the node positions the builder emits are functional
+  but not tidy. Run the layout tool to make the diagram readable before handover —
+  deterministic, so it won't fight a future edit:
+  `python scripts/run-tool.py procesio layout-flow --in <export.procesio> --out <tidy.procesio>`
+  (changes only positions; re-imports cleanly). `inspect-flow` gives a structural summary
+  (counts, families, branches, smells); `read-flow-graph` gives the raw node/edge model.
+- Until then, if you place nodes by hand, follow §2: left-to-right by level, center
+  children, error ports below, and a `Join` only where branches truly reunite.
+- Verify the diagram communicates: open it and check a stranger could narrate the flow.
+  That check is part of "done" (playbook §C/§E spirit — verified behavior + handover).
+
+
+## Layout engine upgrade 2026-07-05 (brief: "fix the tool so it layouts right")
+
+Four engine changes in `tools/procesio/layout/engine.py` (all covered by the existing test suite):
+1. **Error-region detection stops AT error targets**: main-flow reach may point INTO an error-port
+   target (e.g. a script-gate's normal case edge into the shared error Join) but never THROUGH it.
+   Before, one normal edge into the sink pulled the whole notify subtree into the main graph.
+2. **ALAP layer pull with branch-head anchoring**: single-successor chains get pulled RIGHT adjacent
+   to their join (kills 8-layer join edges), but a branch HEAD (predecessor fans out) keeps its ASAP
+   layer so it stays next to its decisional.
+3. **Error components anchor independently, laid VERTICALLY**: each weakly-connected component of the
+   error region becomes a vertical rail below the canvas, anchored at the median x of ITS OWN feeders.
+   Vertical rails cannot cross the horizontal main flow.
+4. **MINIMIZE_CROSSINGS defaults ON** (strictly better in every measurement).
+
+FLOW-side pattern that finishes the job: with feeders spread across a wide canvas, a SINGLE shared
+error Join forces ~feeder-span-length edges (geometry, not layout). Split into ONE ERROR RAIL PER
+CANVAS REGION (Networky v2: rails A/left/right - Join+Compose+notice+Stop each, cloned). Result on
+the 78-node v2: crossings 10 -> 0 (proper-intersection; report's endpoint-touch counter: 2),
+max edge 3729 -> ~1500, all four Networky flows re-laid clean.
+LEGACY engine remains the default (ELK is opt-in backup via LAYOUT_ENGINE=elk).
+
+
+### Layout round 2 (same day, after the designer re-review)
+5. **At most ONE folded dead-end chain per branch node** (`_deadend_chains` cap): several chains
+   folding onto the same column stacked into overlapping piles (the AI Router 5-way fan). The
+   shortest chain folds; the rest lay out normally. Result incl. label-aware collision check:
+   v2 = 0 crossings, 0 label collisions; ALL FOUR flows 0/0 by layout-report.
+6. **Designer code sync for authored Nodes**: when creating a Node via API, the customData Code
+   setting must hold the GUID-reference form (variableId[.attributeId]), NOT the runtime `<%N%>`
+   form — the designer renders `<%N%>` literally and the variable picker breaks. Convert with
+   the param's variable map (flowpatch `_config_value_from_param` pattern). Synced on 9 authored
+   Nodes across v2/HCT/SendExport/PEC.

procesio_cli/agents/procesio/README.md

@@ -0,0 +1,97 @@
+# PROCESIO agent - knowledge base (staged)
+
+**Status:** runtime built (v0.1.0). Registered agent, JSON in / JSON out, driven
+by `python scripts/run-agent.py procesio <action>`. This folder is both the agent's
+knowledge base (the docs below) and its code. It is the home for everything the
+PROCESIO agent needs to create use cases, edit resources, improve implementations,
+and handle formatting/styling in PROCESIO using the registered tools.
+
+## Actions
+
+| Action | What it does |
+|---|---|
+| `status` | Agent + driven-tool readiness. |
+| `guidance` | Serve the playbook / best-practices / boundary docs from one place. `--topic`. |
+| `checklist` | Emit the rigorous self-test checklist as structured steps. `--phase`, `--automatable-only`. |
+| `verify` | The enforcement gate against a live process: validate, designer-vs-runtime parity audit, and (with `--run`) run + read the real instance status. Lists the manual checks it cannot run. `--process-id`, `--profile`, `--workspace-id`. |
+| `audit` | Static best-practice + correctness audit of a process (action count, slow actions, error handling, inline secrets, parity). `--process-id`, `--profile`, `--workspace-id`. |
+
+`verify` and `audit` are the executable side of the playbook: they turn the
+prose discipline into a gate. `verify` exits with a `verdict` of pass/warn/fail
+and always returns `manual_checks` (forms in a real browser, webhooks, E2E) so the
+human/LLM steps cannot be silently skipped.
+
+**Pass `--workspace-id` for any process outside the profile's default workspace.**
+A session is scoped to one workspace, so without the flag the platform answers
+`User is not authorized for the requested resource` even though the credential is
+valid and the process id is right - it reads like a permission problem, not a
+scoping one. Both actions forward the credential scope (profile + workspace) to
+every inner tool call via `verifylib.scope_args`; any new inner call must splat
+the same list, or it will fail on the second hop while the first one succeeded.
+
+## The boundary - agent notes vs tool notes (read first)
+
+Two kinds of knowledge, two homes. Keep them apart on purpose.
+
+- **AGENT notes (here, `agents/procesio/`)** - how to BUILD WELL and how to BEHAVE:
+  methodology, the build-and-test loop, best practices, which skills to use, the
+  quality bar. Audience: the agent doing the work.
+- **TOOL notes (stay in `tools/<tool>/`)** - how the tools work and WHY they work
+  that way: API mechanics, DTO shapes, auth, builder internals, platform gotchas.
+  Audience: whoever maintains or improves the tools. Keeping these with the tools
+  means when we change a tool the reasoning is right there, so we do not repeat a
+  mistake we already solved.
+
+**Routing rule for any new learning (Hard rule 6, compounding):**
+- About a TOOL, the PLATFORM API, a DTO quirk, or builder behavior -> the tool
+  folder (`tools/procesio/*-NOTES.md`, or the relevant tool, e.g. `tools/web/`).
+- About METHODOLOGY or how to build well -> here.
+- A cross-cutting standing preference -> user memory (`memory/MEMORY.md` + a file).
+- Never let a discovery live only in a chat.
+
+## Contents
+
+- **PROCESIO-BUILD-AND-TEST-PLAYBOOK.md** - the operating procedure. The loop the
+  agent runs on every build/edit: frame -> design -> build -> rigorous self-test ->
+  capture learnings -> fix bugs/inefficiency/UX -> re-verify -> document. Includes
+  the self-test checklist (validate, run instances, forms render + behavior in a
+  real browser, webhooks, end-to-end) and the skills-to-use map.
+- **PROCESIO-BEST-PRACTICES.md** - distilled platform best practices (framing,
+  design, integrations, robustness, observability, SQL actions, forms UX, optimize
+  for speed). Source: the "Best practices for implementing with PROCESIO" doc.
+
+- **IMPLEMENTATION-PATTERNS/** - the house style: how this team actually builds processes, forms,
+  integrations and SQL for PROCESIO, distilled (client data stripped) from a full workspace audit.
+  Served as `guidance --topic patterns` (index) + `patterns-processes|forms|integrations|database`.
+  The index also defines where per-workspace knowledge lives (user data, never here).
+
+## Tool notes this agent relies on (in `tools/procesio/`)
+
+- `PHASE4-E2E-NOTES.md` - end-to-end build/test rounds; the verified mechanics for
+  validating, running instances, form data-model + trigger behavior, document and
+  webhook gotchas. The empirical backbone the playbook checklist points at.
+- `PROCESIO-API-NOTES.md` - API behaviors not obvious from Swagger.
+- `PROCESIO-AUTH-NOTES.md` - auth modes, workspace scoping.
+- `DTO-SUBTOOLS-NOTE.md` - the resource-builder sub-tools contract.
+- `PROCESIO-SEND-EMAIL-NOTES.md` - Send Email action node (attachment + recipient).
+
+## Layout
+
+```
+agent.yaml            manifest (actions/args/tools/routing)
+main.py               action dispatch (JSON in/out)
+context.py            stateless tool-invoker context
+knowledge.py          loads the KB docs for `guidance`
+checklist.py          the self-test checklist (single source)
+audit.py              static auditor (correctness + practice); ci() case helper
+verifylib.py          the verify gate logic
+handlers/             one file per action
+tests/                manifest-sync guard + unit tests (31, all faked - no live calls)
+```
+
+## Next slices
+
+- Wire `web` (real-browser form render + behavior) and `google-*` (deliverables)
+  into actions, so the manual checklist steps become agent-driven where possible.
+- A `build` / `edit` action surface over the procesio DTO sub-tools, with `verify`
+  run automatically after every build.

procesio_cli/agents/procesio/agent.yaml

@@ -0,0 +1,73 @@
+name: procesio
+description: >-
+  PROCESIO build-and-test agent. Knows how to create use cases, edit resources,
+  and improve implementations on the PROCESIO platform, and enforces the
+  build-and-test discipline: it serves the operating playbook + best practices,
+  emits the rigorous self-test checklist, runs an automatable verify gate against
+  a live process (validate, designer-vs-runtime parity, run + read instance
+  status), and statically audits a process for inefficiency / UX / robustness
+  smells. Methodology lives in this folder; tool mechanics stay in tools/procesio/.
+version: 0.1.0
+runtime: python
+entrypoint: main.py
+
+# Tools this agent DRIVES programmatically (registry-resolved, never hardcoded at
+# call sites). Only procesio today - that is what verify/audit/run actually invoke.
+# The agent also KNOWS web (real-browser form testing) and google-* (deliverables)
+# through the served playbook, but they are NOT listed here until an action drives
+# them: the registry derives agent readiness from this list, so naming an unused
+# tool would make `status` report the agent blocked on secrets it never needs.
+tools:
+  - procesio
+
+routing:
+  triggers:
+    - build a procesio use case
+    - test / verify a procesio process or resource
+    - audit a procesio process for best practices
+    - how should I build / test in procesio
+    - improve a procesio implementation
+  primary_action: verify
+  example: >-
+    procesio verify --process-id <id>   (audit: procesio audit --process-id <id>;
+    guidance: procesio guidance; checklist: procesio checklist)
+
+actions:
+  - name: status
+    description: Report agent + driven-tool readiness (presence + secrets).
+  - name: guidance
+    description: >-
+      Serve the build-and-test playbook + best practices (the agent's knowledge
+      base) from one place. Building a FORM is a separate discipline: start at
+      topic=forms (the index) and load the one chapter you need - the form
+      chapters are deliberately NOT in topic=all, because the guide is ~100 KB.
+    args:
+      - {name: topic, type: string, default: all, description: "processes: playbook | best-practices | visual-organization | datastore | scheduling | environments | reliability | boundary | all. forms: forms (index, start here) | forms-anatomy (elements + the field VALUE PATH) | forms-process (RUN_PROCESS event, inputMap/outputMap row shape) | forms-interaction | forms-code | forms-dom | forms-motion | forms-deploy | forms-pitfalls. house style (how we build, from a workspace audit): patterns (index, start here) | patterns-processes | patterns-forms | patterns-integrations | patterns-database"}
+  - name: checklist
+    description: Emit the rigorous self-test checklist as structured steps.
+    args:
+      - {name: phase, type: string, description: "filter to one phase: validate | run | forms | webhooks | e2e"}
+      - {name: automatable-only, type: boolean, default: false, description: only steps the verify gate can run}
+  - name: verify
+    description: >-
+      Run the automatable self-test gate against a process: validate, config-parity
+      audit, and with --run execute it and read the real instance status. Lists the
+      manual checks it cannot run.
+    args:
+      - {name: process-id, type: string, required: true, description: process (project) id to verify}
+      - {name: run, type: boolean, default: false, description: actually run the process and read instance status}
+      - {name: payload, type: string, description: input variables as a JSON object (with --run)}
+      - {name: timeout, type: integer, description: secondsTimeOut for the synchronous run}
+      - {name: profile, type: string, description: procesio credential profile to use}
+      - {name: workspace-id, type: string, description: "workspace GUID the process lives in (required whenever it is not the profile's default workspace)"}
+  - name: audit
+    description: >-
+      Static best-practice + correctness audit of a process (action count, slow
+      actions, error handling, inline secrets, designer-vs-runtime parity).
+    args:
+      - {name: process-id, type: string, required: true, description: process (project) id to audit}
+      - {name: profile, type: string, description: procesio credential profile to use}
+      - {name: workspace-id, type: string, description: "workspace GUID the process lives in (required whenever it is not the profile's default workspace)"}
+
+# No own secret: readiness comes from the tools it drives (see `procesio` tool).
+secrets: []