Minctrl Docs

Changelog

What has shipped in Minctrl, dated and honest — company-owned processes with the 45 flows as importable examples, the governed run engine, park/resume, user-configurable connectors with shadow-until-signed-off, BPMN 2.0 import/export, and this docs site.

This is a real, dated record of what has shipped. The API is v0.1 and path-unversioned (see Versioning below and the versioning reference). No version numbers are claimed here beyond v0.1 — the entries below describe the actual work.

2026-11-02 — A blank LLM budget means the platform default

Changed. A company that leaves the monthly LLM budget blank is now bounded by the platform default (MINCTRL_LLM_MONTHLY_BUDGET_USD, $50) instead of having no monthly limit; Settings → AI models shows the default in force next to each blank limit, and GET /llm-settings returns platform_defaults.

2026-11-01 — Review fixes: embedding, model proposals, PHI, budgets, webhooks

Fixed.

  • Embedding: a person mints an embed token only for their own email (embed.sign also needs gate.approve); a host key mints embed.sign only for a member who allows embedded signing (their own switch on Settings → Embedding, or the company's allow-list with settings.governance); changing the allowed origins needs settings.governance.
  • LLM steps: a tool bound live without a declared reversibility (reversible: true, or a catalog action declared reversible) is only proposed by the model, never run on its word.
  • Model proposals: the sign tier counts an LLM step's llm.tools and the run's proposals; a parked proposal is never signable from Slack or Teams, needs the gate id typed in the embed widget, on the phone and in the console, and every card shows the proposed tool and its arguments.
  • PHI mode: the retention purge also removes the model content of finished runs' traces (LLM outputs, tool-call inputs/results, proposal inputs); the audit chain receives field names and counts instead of form, extracted and decided values.
  • Concurrent signatures: the sign door claims the park before it drives the run, so of two signatures at once only one calls the model or runs a reversible tool.
  • LLM budgets: every call reserves its estimate against the monthly budget before it is made (concurrent runs overrun it by at most one call); a blank per-run cap is the server default (MINCTRL_LLM_RUN_CAP_USD, $5). Migration migrate_llm_reservations.sql.
  • Host webhooks: the delivery lease is renewed before every send, so a second worker never sends an event a slow receiver is still being sent; deliveries connect to the address the SSRF guard checked at connect time (no DNS-rebinding window).
  • Embed exchange: the claimed framing origin is checked against the request's Origin and Sec-Fetch-Site (403 when they contradict it).
  • Release bundles: the bundle routes cap the body (BUNDLE_MAX_BYTES, 4 MiB; 413) and bound its nesting (64 levels, 422) before parsing — a hostile bundle is no longer a 500.
  • Embed widgets: a sign-off token covers one process unless it sets all_processes: true; the widget names people instead of showing their email addresses.
  • Roles: who may claim a ticket's required_role is decided by permissions, not by the role's name; the built-in role seed has one authoritative definition, run last (migrate_builtin_roles_last.sql), with one seeding trigger.
  • GET /embed/frame-policy answers for the one framing origin asked about (origin, read by the UI from the widget request's Referer) and no longer lists a company's allowed origins.

2026-11-01 — Document extraction

Added. Runs carry documents — PDF, PNG, JPEG, TIFF, WebP and email (its PDF/image attachments become documents of their own) — attached at the start (Runs page, API, a webhook's _documents) or while the run waits at a gate. The type is read from the file's first bytes, never its name; limits on size, pages, count and a run's total; a PDF is opened only to count its pages; files are encrypted at rest with a key of their own and served back sandboxed. An agent step's extract block sends them to Claude as native PDF/image input and fills a declared schema: each field with a confidence and a page citation, checked here (schema, real page counts; one retry, then the step fails), flagged under its threshold. A gate with review: "<step>" shows the documents beside the pre-filled fields, the uncertain ones highlighted; what the reviewer signs replaces the model's values for the steps after it, and an extraction_reviewed entry names each correction and who made it. Budgets, llm_call entries and test-suite fixtures (extraction) as for LLM steps; the PHI purge deletes a run's documents with a content-free entry. New permissions documents.upload and documents.read (every built-in role). Migration migrate_documents.sql.

2026-11-01 — Embedding, white-label and host webhooks

Added. Embedding and white-label: a host product mints short-lived embed tokens (≤ 15 minutes, used once, stored hashed) with an embed:issue API key for one of its users and one resource, and mounts the sign-off queue or one run in an iframe with the new SDK @minctrl/embed (Minctrl.mount(el, {token, view}), events minctrl:ready, minctrl:resize, minctrl:signed, minctrl:error). The widget pages are served with frame-ancestors from the company's allowed origins (every other page is X-Frame-Options: DENY), take the token from the URL fragment, keep the session in memory (no cookie), and sign through the one sign door as the token's member — roles, separation of duties, gate forms and the typed confirmation of a live irreversible gate, checked by the server on the new embed channel. Settings → Branding: display name, primary colour (contrast-checked), support email, email sender name and a raster logo (SVG refused) brand the widgets, the gate digest email and the sign-in page of a verified SSO domain. Settings → Webhooks: per-company outbound webhooks for run.started, run.parked, gate.signed, run.completed and run.failed, signed like triggers (Minctrl-Signature), recorded in the run's own transaction, delivered in order with a cursor that moves only after a 2xx, retried with backoff, with a delivery log and "Send test".

2026-11-01 — Environments: signed release bundles between installations

Added. Promoting between environments: a published version is exported as a minctrl.bundle/v1 file signed with the company's Ed25519 key (graph, forms, SLA, decision tables, connectors by tool-id and template — never a credential), imported on another installation only when its key is trusted (untrusted, tampered or hash mismatch: refused, nothing created), lands in review with the importer as author, and publishes only after its connectors are mapped to local connections and another owner or admin publishes it. Promotion log and drift check per process; key rotation keeps old bundles verifiable. Settings → Environments; scope processes:promote; permissions process.promote, settings.environments; SDK methods in Python and TypeScript.

2026-11-01 — Process mining

Added. Process mining: import an event log — a CSV with its columns mapped from a preview, an XES file (standard extensions, read as a stream, DOCTYPE and ENTITY declarations refused), or your own run history — as a company dataset with a retention, and see the directly-follows map with frequencies, median and p90 times, start and end activities, bottlenecks, variants and a case explorer, filtered by date, variant and activity or path frequency. Conformance aligns each case with a published version (token replay for very large logs) and lists skipped steps, unexpected activities and wrong order, with the share of conforming cases. A map becomes a process draft through the save door. A refused row is reported with its line; a partial import is stored only when asked and is marked partial. New permissions mining.read, mining.manage, mining.draft; audit kinds mining_dataset_imported, mining_dataset_changed, mining_dataset_deleted. Migration infra/migrate_process_mining.sql.

2026-11-01 — LLM agent steps (Claude)

Added. An agent step may declare an llm block — model (Claude Sonnet 5.5 by default, Opus 5.5 or Haiku 5.5), system prompt, instructions, output JSON Schema, connector tools — and Claude does the step: the answer is checked against the schema (one retry with the error, then the step fails), written to run state as llm.<step>.<field> and may route the next decision. Reversible tool calls run through the connectors; an irreversible one only becomes a proposal the step parks on for a person's signature. Every call is in the trace and an llm_call audit entry (model, prompt hash, tokens, cost, latency, output hash, stop reason); prompt/output text is kept with the usage record per the company's model-text switch (never in PHI mode), for its retention. Monthly budget and per-run cap (Settings → AI models, audited): reached → the step fails with "LLM budget reached", never a heuristic stand-in. Company Anthropic key, write-only and sealed. A resume never re-calls the model. Test suites replay recorded llm_output. New run status failed.

2026-11-01 — Approvals in Microsoft Teams and on your phone

Added. Teams and mobile: each company connects its own Azure Bot (App ID, client secret stored encrypted, tenant) on Settings → Notifications and uploads the generated Teams app package. People who open the bot get an Adaptive Card when a gate waits; a plain gate (the Slack rule: no form, one signature, nothing live and irreversible, not a shadow run) is approved or refused on the card — a refusal with its required reason — through the one sign door, audited with channel: "teams"; other signers' cards are refreshed with who signed. Incoming activities are verified against the Bot Framework's signing keys (issuer, audience = App ID, expiry, serviceUrl, tenant) and accepted once. Minctrl is installable as a PWA, sends a Web Push (VAPID, RFC 8291 encryption) that says only how many gates wait, removes a device the push service reports gone, and has a phone-first sign-off screen at /m/signoff with forms and the typed confirmation of live irreversible gates. The service worker never caches sign-off data. Migration infra/migrate_teams_mobile.sql.

2026-11-01 — Custom roles and named permissions

Added. Roles and permissions: every check now asks for a named permission (gate.approve, gate.approve.high_tier, process.publish, roles.manage, connectors.bind_live, …) instead of a role name. Companies create custom roles on Settings → Roles from a permission picker grouped by area (or based on another role), assign them on the Team page, map IdP groups and SCIM to them, and name them on gates. Nobody grants a permission they do not hold; the owner role stays unique and fixed; a role in use is not deleted. Role changes are audited (role_created, role_changed, role_deleted) with the permission sets before and after. The five built-in roles hold exactly what they did before; the migration seeds them for every company.

2026-11-01 — Self-hosting: Helm chart, Hetzner Terraform, data region

Added. A Helm chart for Kubernetes (API, UI, a migration hook gated on every file, bundled or external Postgres, Redis, Ingress or Cloudflare Tunnel, NetworkPolicy, non-root containers, and pg_dump → S3 backups with a weekly restore test) and Terraform for the Hetzner single-server shape (server bootstrapped by cloud-init, SSH-only firewall, kept IPs, optional volume and bucket). A deployment setting MINCTRL_DATA_REGION (eu-central, eu-north, us-east) shows on /health and Settings → Install with the declared backup location, is recorded in evidence packs, and picks the backup endpoint and server location; an unknown id stops the API at startup. Several API replicas run the startup cleanup under an advisory lock (MINCTRL_STARTUP_CLEANUP_LOCK). Tested by lint, render, schema validation and mocked-provider plans — applying them is the operator's.

2026-11-01 — Decision tables (DMN 1.3 subset)

Added. A process version carries decision tables: inputs read from run state, outputs, rules in FEEL-lite (literals, < 500, [100..500], lists, not(...), -), hit policies UNIQUE, FIRST, PRIORITY, COLLECT (+ SUM/MIN/MAX/COUNT) and an optional no-match default. A new decision step evaluates a table and writes decision.<step>.<output>; an exclusive gateway's Branch on routes on it. No match without a default, two matches on a UNIQUE table or a wrong type fail the run at that step (status failed) with the reason. Tables are in the save door, the diff, the pinned hash, JSON export/import and test suites; the trace and run_started / gate_signed name the matched rules. The Processes screen has a table editor with live cell checks and a test panel; DMN 1.3 export and import (unsupported constructs refused with a list, 422); BPMN businessRuleTask ↔ decision step. No migration.

2026-11-01 — Compliance readiness (SOC 2, HIPAA)

Added. Settings → Compliance shows every SOC 2 (TSC 2017: Security, Availability, Confidentiality) and HIPAA Security Rule control with its live state computed from the product — SSO required, separation of duties, chain verification and the last external timestamp, SIEM delivery, backups (from MINCTRL_BACKUP_REPORT_URL, else "not read"), API key age, inactive members, connectors live vs shadow — and "not read" (never green) when a signal cannot be read. The evidence pack gains a compliance/ folder: the matrix filled with live states, the access reviews, the publish/rollback log and incident-relevant events of the period. PHI mode per company: model text never stored, run inputs purged after N days (phi_inputs_purged, without the data), every opening of a run recorded (phi_run_viewed). A quarterly access review reminds owners and records their confirmation (access_review_opened, access_review_confirmed). Matrices, policy templates, a subprocessor list and a BAA checklist are in docs/compliance/. This makes a company audit-ready; a SOC 2 report or HIPAA attestation still needs an external auditor.

2026-10-31 — Process test suites and version comparison

Added. A process has test cases: inputs, the answer each gate gets (outcome, form values, approvers on an N-of-M gate) and the path, final status and step outputs the run must show. A suite runs against any version, never live — every connector shadowed, gates answered from the case, agent steps from recorded fixtures unless a case says llm: "live" — and is not a process run (not in Runs, analytics, queues or SLAs); one process_suite_run entry records it. Each case passes or fails with its first divergence; two versions are compared side by side. A case can be made from a run, and live step outputs recorded as fixtures. The company switch publish_requires_green_suite (default off) makes publish and rollback need a green suite on that exact version. New API-key scope processes:test; both SDKs run a suite and read its result.

2026-10-31 — Escalation, delegation, reassignment, N-of-M approvals

Added. A gate may need several signatures: approvals: {required, distinct_people, order, roles}. Each approval is recorded (gate_approval_recorded) and the run continues only at quorum; a denial by anyone ends the gate. The card shows "1 of 2 signed" with who; Slack offers no buttons for such a gate. Members set an out-of-office delegate for a period (/delegations, the Out of office page): their notices go to the delegate, who signs with their own role, and the audit names both (on_behalf_of). A manager assigns a waiting gate to a member who may sign it (PUT /process-runs/{id}/assignment, audited gate_reassigned, notified); the company switch only_assignee_signs (default off) keeps others off an assigned gate. SLA levels gain level_actions: notify, reassign_to_role, assign_to_user — they never sign or reroute. See Escalation, delegation and N-of-M approvals.

2026-10-31 — Publishing: draft, review, published, rollback

Changed. A saved version is a draft and does not run. Its author submits it for review; an owner or admin reads the diff (steps, connections, gate forms, deadlines, connectors) and publishes it — with the company's separation of duties on (the default), one who did not author it; with it off, the author may publish their own version and the entry records "sod": false. Runs — manual, API key, trigger — start only from the published version; a draft runs only as its author's shadow test run ("shadow": true, every connector shadowed). Rollback publishes a retired version again under the same rule. Every move is in the audit chain with the published version before and after. Processes saved before this change: the latest version of each is published, older ones retired. See Publishing processes. A trigger starts only the published version too: with none, its webhook answers 409 and its schedule records the reason as last_error and keeps its slot.

2026-10-31 — Triggers: webhooks and schedules start runs

Added. Triggers start runs of a saved process without a person: a webhook (POST /hooks/t/<token> — the URL is shown once, optional timestamped HMAC-SHA256 signature Minctrl-Signature: t=…,v1=… refused after 5 minutes, JSON body or a JSONPath mapping as inputs, Idempotency-Key returns the first run for 24 h) or a schedule (5-field cron + IANA time zone; one run per slot with any number of replicas, missed slots fire once). Runs record created_by: "trigger:<name>"; a trigger never signs a gate. Managed by owners, admins or a key with triggers:manage, every change in the audit chain; a Triggers tab on each saved process; both SDKs gain triggers.

2026-10-31 — Notifications on park; Slack, Teams and email; sign from Slack

Added. When a gate parks, the people who may sign it are told on their channels — email, a Slack DM from your company's own Slack app, or a Microsoft Teams card — with personal preferences and quiet hours; SLA escalations go through the same fan-out. A plain gate (no form, one signature, no live irreversible action) can be signed from the Slack message through the console's own checks, recorded with "channel": "slack"; anything else links to the sign-off card. Every delivery and its failure is on the run. See Notifications, Slack and Teams.

2026-10-31 — Enterprise identity: SSO, require SSO, group roles, SCIM

Added. Sign in with your company's identity provider — SAML 2.0 or OpenID Connect (Okta, Entra ID, Google Workspace, Auth0) — after verifying your email domain; a test sign-in before it goes live; Require SSO for your domains, with an audited owner break-glass; IdP group → role mapping; and SCIM 2.0 provisioning, where deactivating a user suspends their access at once. See Single sign-on and SCIM.

2026-10-31 — Connector catalog and OAuth2

Added. A connector catalog of ten templates — FHIR R4, Salesforce, ServiceNow, Jira, Slack, Google Sheets, HubSpot, Zendesk, Stripe, generic REST — with OAuth2 client credentials and authorization code (state + PKCE), credentials sealed at rest, and every action declaring reversible; an irreversible one stays shadowed until an owner binds it live.

2026-10-31 — The audit chain goes out: SIEM sinks, ranged export, evidence pack, RFC 3161 timestamps

Added. Stream the audit chain to Splunk HEC, Datadog Logs or an HMAC-signed webhook — in order, with a per-sink cursor that moves only after a 2xx, so an outage never skips an entry; export any range as JSONL or CSV with each row's hash and a verification manifest; download an evidence pack for an auditor; and stamp the chain head with an RFC 3161 Time-Stamp Authority, which /audit-chain/verify now re-checks. Settings → Audit & SIEM. See Audit export, SIEM sinks and evidence.

2026-10-31 — Forms in the gate

Added. A gate can declare a form — text, textarea, number, date, select and checkbox fields, up to 20 — that the signer fills in on the Sign-off card. POST /process-runs/{id}/resume takes the values as form and checks them server-side (422 naming the field, nothing signed); they are recorded in the run's decisions and in the gate_signed audit entry, and the steps after the gate read them as gate_form.<step_id>.<field_id>. Forms are edited in the node inspector, kept in JSON export and BPMN (a minctrl:form extension element), and replay with the pinned graph. See Forms in the gate.

2026-10-31 — API keys for scripts and integrations

Added. Owners and admins create company API keys (mk_live_…, shown once) with scopes runs:start, runs:read, processes:read, audit:read; a key is refused on every other route and never signs a gate (403 "A machine cannot sign a gate."). Runs a key starts record created_by: "key:<name>"; create and revoke are in the audit chain; each key has its own rate limit. Both SDKs accept api_key / apiKey.

2026-10-28 to 2026-10-30 — Processes belong to your company; the 45 flows become examples

Changed. Minctrl no longer ships built-in processes into a company. A new company starts with no processes and adds its own: build one on the canvas, import a BPMN 2.0 model or a minctrl.process/v1 JSON file, or describe it in text and review the draft. The admin's Processes and Runs pages show only your company's processes.

  • The 45 flows are examples. Each page on minctrl.com/flows links a minctrl.process/v1 file at https://minctrl.com/examples/<slug>.process.json, which POST /process-templates/import accepts unchanged. See Example processes.
  • Runs name your process. Start a run with {"vertical": "<slug>", "draft": true}; it is pinned to one version (draft_version, latest by default) and its hash for its whole life.
  • JSON export / import. GET /process-templates/drafts/{slug}/export and POST /process-templates/import move a process between environments; a file whose hash no longer matches its graph is refused (422). GET /process-templates/drafts/{slug} reads a saved process back as a graph.
  • Migrating. Calls that ran a built-in by name ({"vertical": "aml"} without draft) are still accepted by the API, but nothing in the admin uses them. Import the example and run it with "draft": true instead.

v0.1 — 2026-07-02

The first coherent release of the governed-orchestration platform: an engine that runs a process to a human gate, parks, and resumes on a signed verdict — with every irreversible side effect held behind a connector you opt in to.

Governed run engine + park/resume

  • Durable process runs. A run executes a process's flow until it reaches a human gate, then parks (status: awaiting_human) and persists. It resumes when a resume signal arrives carrying the gate's step-id and the human's decision, which is merged and the flow re-driven idempotently. See Governance model and Run a governed process.
  • Exclusive / parallel gateways in flows route on the recorded verdict, so a single gate decision (e.g. approved, SAR signed, sanctions hit confirmed) steers the run down the correct downstream branch.

User-configurable HTTP connectors, shadowed until signed off

  • Bring-your-own connectors. Steps map to HTTP connectors you configure per step, so a step can call your real systems of record.
  • Shadow-until-signed-off. Irreversible steps (reversible: false) run shadowed (dry-run) by default and only fire for real once (a) the connector is deliberately opted in and (b) a human gate upstream has collected a signed verdict. Governance is the default, not an add-on. See Connect a step and Configure gates and autonomy.

BPMN 2.0 import/export

  • Round-trip BPMN 2.0. Import an existing BPMN 2.0 process and export Minctrl flows back out, so the governed flow lives alongside the notation your organization already uses. See Import / export BPMN.

45 governed flows across 11 domains

  • 45 process flows, spanning 11 domains — fintech, finance, healthcare, HR, insurance, IT, legal, logistics, security, supply-chain, and telecom. Each is an end-to-end flow with primary-source steps, exclusive/parallel gateways, human gates, and an irreversible-execute step held behind a gate. Changed 2026-10-28: these were built-in templates at the time; they are now examples you import (see above).

Docs site

  • This documentation site launched — quickstart, tutorials, guides, cookbook recipes, concepts, an API reference generated from the OpenAPI schema, and the two SDKs generated against that same schema.

Versioning

The API is v0.1 and path-unversioned — there is no /v1 prefix in the URL; you call /process-runs, /auth/*, and so on directly. While the API is at v0.1 it should be treated as pre-1.0: the surface can still change as endpoints are hardened.

How breaking changes will be communicated. Until a stable v1.0 is cut:

  • Every breaking change is recorded here in the changelog, dated, with a note on what moved and how to migrate.
  • Additive changes (new endpoints, new optional fields) are not treated as breaking and may land at any time — the generated SDKs surface them automatically.
  • When the API stabilizes, a versioning scheme and deprecation policy will be published in the versioning reference before anything is removed.

Pin the SDK version you build against and read this changelog before upgrading. During v0.1, assume any endpoint not listed in Rate limits as hardened may still change shape.

On this page

2026-11-02 — A blank LLM budget means the platform default2026-11-01 — Review fixes: embedding, model proposals, PHI, budgets, webhooks2026-11-01 — Document extraction2026-11-01 — Embedding, white-label and host webhooks2026-11-01 — Environments: signed release bundles between installations2026-11-01 — Process mining2026-11-01 — LLM agent steps (Claude)2026-11-01 — Approvals in Microsoft Teams and on your phone2026-11-01 — Custom roles and named permissions2026-11-01 — Self-hosting: Helm chart, Hetzner Terraform, data region2026-11-01 — Decision tables (DMN 1.3 subset)2026-11-01 — Compliance readiness (SOC 2, HIPAA)2026-10-31 — Process test suites and version comparison2026-10-31 — Escalation, delegation, reassignment, N-of-M approvals2026-10-31 — Publishing: draft, review, published, rollback2026-10-31 — Triggers: webhooks and schedules start runs2026-10-31 — Notifications on park; Slack, Teams and email; sign from Slack2026-10-31 — Enterprise identity: SSO, require SSO, group roles, SCIM2026-10-31 — Connector catalog and OAuth22026-10-31 — The audit chain goes out: SIEM sinks, ranged export, evidence pack, RFC 3161 timestamps2026-10-31 — Forms in the gate2026-10-31 — API keys for scripts and integrations2026-10-28 to 2026-10-30 — Processes belong to your company; the 45 flows become examplesv0.1 — 2026-07-02Governed run engine + park/resumeUser-configurable HTTP connectors, shadowed until signed offBPMN 2.0 import/export45 governed flows across 11 domainsDocs siteVersioning