@smartkomm/plexus-cli 0.0.0-stage → 0.1.0

package/dist/skill/references/offer/declare-node-reads.md

@@ -0,0 +1,99 @@
+# Declare what a document node reads
+
+**When to use:** a contract or offer letter is produced by hand and **uploaded**
+(a school without a contract generator), or a generated contract prints answers it does not bind.
+Such a node binds no form field, so without `reads` a correction on the child's
+name never holds it, and an issued contract does not protect the fields it
+printed. `reads` names those fields, each by its full address
+(`$node.<formNode>.admission.<field>` — the address names WHICH form): the readiness gate holds
+„Freigabe anfordern" / release / issue while one of them has an open correction
+or is empty where the form requires it, and once the document is issued they are
+**consumed** — a correction on them is refused until the document is rescinded.
+
+## Prerequisites
+- An offer bundle on disk: a **fresh export of the target environment**
+  (`offer export`) into a private scratch dir. A live tenant's bundle is never kept
+  in a shared or versioned place — the server is its source of truth; any older copy can lag behind what is live (fields added
+  later are then refused as unknown).
+- Authoring is offline; `offer plan` / `offer apply` need a token for `--env`.
+- A bundle exported before addresses were introduced carries bare keys and is refused (`[address/bareIdentifier]`,
+  `[graph/retiredField]` for `wires`) — export it again. Model: [Name what a node reads](./addresses.md).
+
+## Steps
+```bash
+# 1. Export what is live (read-only).
+plexus-cli --env staging --tenant <slug> offer export --slug <offer-slug> --out ./bundle
+
+# 2. Declare the fields the document carries (replaces the list). Each entry is
+#    an address of the form node that CREATES the instance (here `form`) —
+#    entered or computed fields (a computed key such as derivedConstellation
+#    expands to the answers it is computed from). --address is repeatable and
+#    comma-separated (single quotes!); --from <formNode> --field <path>,… is the
+#    short form that composes the same addresses:
+plexus-cli offer workflow node set-reads --dir ./bundle --node contract \
+  --from form --field kind.firstMiddleNames,kind.surname,kind.geburtsdatum,derivedConstellation \
+  --address '$node.form.admission.elternteil_1.vorname,$node.form.admission.elternteil_1.nachname'
+
+#    Later edits:
+plexus-cli offer workflow node add-reads    --dir ./bundle --node contract --address '$node.form.admission.kind.homeAddress'
+plexus-cli offer workflow node remove-reads --dir ./bundle --node contract --from form --field kind.homeAddress
+plexus-cli offer workflow node set-reads    --dir ./bundle --node contract --clear
+
+#    A bare key (`--address kind.surname`, or `--field` without `--from`) is
+#    refused with the addresses visible at the node.
+
+# 3. Validate offline, then see what the apply would change.
+plexus-cli offer validate --dir ./bundle
+plexus-cli --env staging --tenant <slug> offer plan --dir ./bundle     # ~ workflow change + ~reads:contract +… (against the live head)
+
+# 4. Publish (a new workflow version).
+plexus-cli --env staging --tenant <slug> offer apply --publish --dir ./bundle
+```
+
+## Verify
+```bash
+plexus-cli offer workflow node list --dir ./bundle          # `reads` column: "30 Felder"
+plexus-cli offer workflow node reads --dir ./bundle --node contract   # every address, „geschrieben" in nodes.contract.reads.<i>
+plexus-cli --env staging --tenant <slug> offer plan --dir ./bundle          # everything "same", no ~reads rows
+plexus-cli --env staging --tenant <slug> offer export --slug <offer-slug> --out ./check
+jq '.graph.nodes[] | select(.id=="contract") | .reads | length' ./check/workflow.json
+```
+
+## Idempotency / gotchas
+- **Only new errors block.** The verb compares the bundle's errors before and
+  after the edit: an error the edit introduces (`[address/pathNotInTarget]` for a field
+  the form lacks, a repeated-block field, a duplicate, `[address/notVisible]` for a form that
+  does not run before the node, `[address/mixedForms]` for two forms in one list, `reads` on a
+  form/end node → `[readiness/readsNotGated]`) writes
+  nothing; an unrelated error the bundle already had (e.g. an undecided
+  assignment row) is printed as `⚠ vorbestehend` and does not stop the edit —
+  `offer apply --publish` will still refuse it.
+- **`add-reads` is rerunnable** (addresses already read are reported, not an error);
+  `remove-reads` fails on an address the node does not read.
+- **One form per list.** A node's `reads` is judged on ONE form instance; a second form's
+  fields in the same list are `[address/mixedForms]`. An adopting form node (`adoptForm`)
+  produces nothing — read the fields at the creating node's address.
+- **What to read:** exactly what the document prints — names, birth date,
+  address of the child and of every party that can sign, the answers that decide
+  who signs (the constellation), start date, fee answers. Not uploads, free text
+  or health data: every read field is **locked** once the document is issued.
+  A read field that the form does not currently require is never awaited.
+- **`[readiness/readsMissesPartyCondition]`** (warning, resolver documents only):
+  the contract's parties depend on answers neither read nor bound — add them
+  (or the computed constellation key).
+- **Running applications keep their pinned version.** Publishing does not give
+  applications already in flight the new `reads`; they stay on the version they
+  were pinned to. Either re-pin them, discard a test application
+  (`plexus-cli --env <env> applications discard-test <id>`, test applications only), or —
+  on a test environment — delete them all:
+  `plexus-cli --env staging config wipe --tenant <slug> --target applications`
+  (dry-run count first, then `--confirm`). A real application has no
+  per-application hard delete; its personal data go only by erasure
+  (`retention apply`, [Erase due applications](../retention/erase-due-applications.md)).
+- **Removing a form field that a node reads** fails the form's publish with
+  `[address/pathNotInTarget]` at the workflow — `remove-reads` it first.
+
+## Related
+- [Name what a node reads](./addresses.md) · [Edit a workflow node](./edit-workflow-node.md) · [Release an offer bundle](./publish-offer-bundle.md)
+- [Wipe tenant config/data](../config/wipe-tenant-config.md)
+- `plexus-cli offer workflow node set-reads --help` — the verb's flags

package/dist/skill/references/offer/edit-live-tenant-offer.md

@@ -0,0 +1,144 @@
+# Edit a live tenant's offer (prod is the source of truth)
+
+**Use it to** change anything about a live tenant's offer — close a Schuljahr, change
+capacities, edit the form, the workflow, the assignment rule, the resolver setup — and
+be sure prod ends up exactly as you meant, with nothing else rolled back.
+
+## The rule
+
+A live tenant's offer bundles and config exist **only on the server**. Prod is their
+only source of truth; there is no other copy that a deploy would apply. A copy kept
+somewhere else drifts: editing an old copy to close a Schuljahr changes nothing on prod,
+and applying it later can roll prod back. So every edit starts from a **fresh prod
+export** and ends with a **plan that shows only your change**.
+
+Working copies live in a **private scratch directory** (a temp dir, or a dated folder
+you keep for the session) — never in a shared or versioned place: a live tenant's
+bundle carries the school's data.
+
+## Steps
+
+```bash
+WORK=$(mktemp -d)                             # any private scratch dir
+T=<slug>; S=<offer-slug>                      # tenant slug, manifest slug
+
+# 1. Export what is live. ALWAYS pass --env (the default is prod) and --out
+#    (the default is ./offers/<tenant>/<slug> of the current directory).
+plexus-cli --env prod offer export --tenant $T --slug $S --out $WORK/$S
+#    The export has NO contract/ (resolver-setup.json + DOCX): to change the
+#    resolver setup, copy contract/ from the last rollout's working copy and
+#    prove it equals prod — every row `same`:
+#      plexus-cli --env prod resolver setup plan --tenant $T --file $WORK/$S/contract/resolver-setup.json
+cp -a $WORK/$S $WORK/$S.orig                  # keep the untouched export for the diff
+
+# 2. Edit bundle.yaml / manifest.json / workflow.json / smartforms/*.json in $WORK/$S
+#    (or with the offer verbs: offer form …, offer workflow node …, --dir $WORK/$S).
+diff -ru $WORK/$S.orig $WORK/$S               # exactly your change, nothing else
+
+# 3. Offline gate, then the remote diff. Read every row.
+#    The offline gate cannot see the tenant's catalog: a `pricedItem` task whose
+#    article is not assigned to the offer's program passes here and is refused
+#    only by the live publish ([taskResult/pricedItemNotInProgram]) —
+#    check the assignment under Finanzen → Artikel first.
+#    Nor does it run the signature-anchor rules: [contract/missingSignatureAnchors]
+#    and [contract/undeclaredPartyRole] come from the sealed revision's code + config against
+#    the form: the seal (`resolver setup apply`) checks the resolver names anchors at all,
+#    only the live publish checks every signer of the form. A green validate or plan proves
+#    nothing there. Changing the resolver: publish on staging first (below).
+plexus-cli offer validate --dir $WORK/$S
+plexus-cli --env prod offer plan --tenant $T --dir $WORK/$S
+
+# 4. Apply. --publish when the form or workflow changed (plan's `publish` row says
+#    PENDING); capacities, stages and runs need no publish.
+plexus-cli --env prod offer apply --allow-prod --tenant $T --dir $WORK/$S [--publish]
+
+# 5. Converged: every row `same`, publish `up to date`.
+plexus-cli --env prod offer plan --tenant $T --dir $WORK/$S
+```
+
+Tenant config (Stammdaten shape, roles, units, …) follows the same shape with the
+`config` verbs: `plexus-cli --env prod config export --tenant $T` into the scratch dir →
+edit → `config apply` (dry-run first) → `--confirm --allow-prod`. Recipe:
+[Update a tenant's config](../config/update-tenant-config.md).
+
+## Staging
+
+Staging gets a live tenant's offer **only by an explicit copy from prod** — nothing flows
+there on its own:
+
+```bash
+plexus-cli --env prod    offer export --tenant $T --slug $S --out $WORK/$S
+plexus-cli --env staging offer plan   --tenant $T --dir $WORK/$S
+plexus-cli --env staging offer apply  --tenant $T --dir $WORK/$S --publish
+```
+
+To try a change on staging first, apply the edited copy there, check it, then run the
+prod plan from the same directory — the prod plan still has to show only your change.
+
+A prod offer whose contract node uses `eSignature` publishes **externally** on the staging
+mirror only once the mirror tenant has an active signing connection a test reached
+(`[signing/noActiveProvider]`; `--stage internal` needs none — its test applications run on
+the simulator). On staging that connection is always the provider's sandbox with a
+redirect, never the school's production account; setting it up needs a platform operator.
+
+## What the address rows in `offer plan` mean
+
+Against the **live head** (not the draft), `offer plan` lists what the bundle changes at the
+addresses — display only, never a finding, the exit code stays 0:
+
+```
+~  address:$task.rang.rang          Knoten pruefung → freigabe     # the task moved to another node
++  address:$task.rang.rangSchule    neu (freigabe)                 # a key renamed = one added …
+-  address:$task.rang.rang          entfernt (pruefung)            # … and one removed
+~  reads:vertrag                    +$node.form.admission.kind.nachname −$node.form.admission.kind.vorname
+!  pinned                           3 Anmeldungen (2 echt, 1 Test) auf Fassung 7 bleiben auf ihrer Version — Umpinnen nur per Migration mit Abbildung
+```
+
+- Renaming a key or moving a task is **allowed** in a new version. Every application keeps
+  running on the version it pinned; the new version applies to applications started after the
+  publish.
+- The `pinned` row counts the applications on the live head. They are **not** moved: an
+  identity re-pin refuses a version whose addresses differ (topology hash). Moving them needs
+  a migration with a mapping (old address → new address) — that is platform code, not a CLI
+  verb; ask a platform operator before you publish if those applications must follow.
+- No rows at all: the bundle produces and reads the same addresses as the live head.
+
+## Gotchas
+
+- **Stop if the plan shows more than your change.** Extra rows mean prod moved since
+  your export, or your copy was not a fresh export. Re-export; never apply an older copy
+  (an earlier export, a backup): it can be behind prod in one place and ahead in
+  another, and apply rolls prod back where it is behind.
+- **A change that needs new platform code ships in two steps.** A resolver implementation,
+  a node type or a validator reaches prod with a platform release; only then apply the
+  bundle that uses it. Before the release, `offer plan --env prod` refuses it (e.g.
+  `extra field taxTreatment`, an unknown implementation key). Keep the edited copy in your
+  private scratch dir with a note saying which release it waits for.
+- **An export from before node ids lost their dots is refused** (`[graph/nodeIdFormat]` on
+  ids like `n.form`): prod data was already renamed on the server. Export again — never
+  rename ids by hand in an old copy.
+- **A config export from before the file-reference rename is refused**
+  (`[config/fileRefRenamed]`): its library files still say `fileName` / `size` and its brand
+  files `size` (now `filename` / `sizeBytes`). Pull a fresh `config export` — never rename
+  the keys by hand in an old copy. A CLI that already uses the new names refuses a server
+  that does not yet (`[cli/serverPredatesFileRef]`): use the CLI version that matches the server.
+- **`offer export` leaves out `contract/`.** The resolver setup file and its DOCX are
+  bundle data that exists only in the last rollout's working copy, not in the export. An
+  edit of the resolver setup starts from that copy, and `resolver setup plan` must show
+  every row `same` BEFORE you change anything — else the copy is not what prod runs.
+- **The signature-anchor rules are server-side only.** Every resolver names a line
+  for every party the form lets sign; a resolver that does not is refused at publish with
+  `[contract/missingSignatureAnchors]`, a form role the resolver does not declare with
+  `[contract/undeclaredPartyRole]`. `offer validate` and `offer plan` do not run them; the
+  seal checks only that the resolver names anchors at all, the publish checks every signer
+  of the form. A resolver change therefore goes through staging first (`offer apply
+  --publish` there), then prod.
+- **Close a Schuljahr per cell:** `capacities.<stage>.isOpen: false` on each cell of the
+  run. A run-level `isOpen` is only read when apply creates a new run
+  ([set-offer-capacities](./set-offer-capacities.md)).
+
+## Related
+
+- [Release an offer bundle](./publish-offer-bundle.md) — `offer status`, `--publish`, `--stage internal`
+- [Set an offer's seat capacities](./set-offer-capacities.md)
+- [Manage a contract resolver](../resolver/manage-contract-resolver.md) — `resolver setup plan|apply` before `offer apply --publish`

package/dist/skill/references/offer/edit-smartform.md

@@ -0,0 +1,121 @@
+# Edit a SmartForm in depth
+
+**When to use:** change an existing form beyond adding things — edit a field's
+validation/visibility/enum/docRef/consent props, edit an effect's wiring, reorder
+fields or sections, reparent a section, or edit/remove a repeated or computed field —
+then publish a new version.
+
+## Prerequisites
+- An offer bundle on disk carrying the form (`offer export …` or `offer init …`).
+- Authoring is **fully offline**; only `offer apply --publish` needs an API token of a
+  user who may configure the tenant's offers (a tenant admin — see
+  [Add a tenant admin](../users/add-tenant-admin.md)).
+- An installed, current `plexus-cli` (`plexus-cli offer form --help`).
+
+## Steps
+```bash
+# Form-level: rename / change school.
+plexus-cli offer form set --dir <bundle> --form <slug> --label "Neuer Titel" --label-en "New title"
+
+# Field: edit ANY editable prop (use "" to clear an expression / value).
+plexus-cli offer form field set --dir <bundle> --key kind.vorname \
+  --bucket kind --placeholder "Max" --placeholder-en "Max" --required-if "kind.nachname != null"
+plexus-cli offer form field set --dir <bundle> --key kind.geschlecht --enum-ref geschlecht   # swap inline→catalog
+plexus-cli offer form field set --dir <bundle> --key kind.nachweis --doc-mime application/pdf --doc-max-size 9000000
+plexus-cli offer form field set --dir <bundle> --key kind.attest --required-for sonderfall    # outcome-scoped required
+# Boolean as an explicit Ja | Nein answer (nothing preselected; drop any --default first,
+# publish refuses one: config.yesno-default). "" returns to the checkbox.
+plexus-cli offer form field set --dir <bundle> --key kind.allergien --presentation yesNo --default ""
+
+# Outcome: edit its output shape (replace; "" clears).
+plexus-cli offer form outcome set --dir <bundle> --id standard \
+  --fields kind.vorname,kind.nachname --effect-refs p.kind:applicant
+
+# Effect: edit per-kind props.
+plexus-cli offer form effect set --dir <bundle> --id p.kind --identity keyed --identity-key-from kind.vorname,kind.nachname
+plexus-cli offer form effect set --dir <bundle> --id rel.kindmutter --from p.kind --to p.mutter --rel-kind kind
+
+# Repeated / computed: set + rm (add via `offer form repeated|computed add`).
+plexus-cli offer form repeated set --dir <bundle> --key geschwister --max 3 --unique-by name
+plexus-cli offer form computed set --dir <bundle> --key kind.voll --expression "kind.vorname != null && kind.nachname != null"
+
+# Reorder + reparent (relative anchors; reparent with --parent "" → top-level).
+plexus-cli offer form field move   --dir <bundle> --key kind.nachname --before kind.vorname
+plexus-cli offer form field move   --dir <bundle> --key kind.ausweis --section section.kind --after kind.foto   # into another section
+plexus-cli offer form section move --dir <bundle> --id section.kind --to-top
+plexus-cli offer form section set  --dir <bundle> --id section.eltern --parent section.kind
+
+# Section visibility: only these teams / permission groups (plus admins
+# and the family) read the section's values; everyone else sees „Nur für …
+# sichtbar". Comma-separated keys; "" clears.
+plexus-cli offer form section set  --dir <bundle> --id section.financialDocs --visible-to finanzen
+
+# Validate + publish (publishing re-versions the form).
+plexus-cli offer validate --dir <bundle>
+plexus-cli --env <env> offer apply --publish --dir <bundle>
+```
+
+### English texts
+
+A SmartForm text is ONE field holding `{ de, en }` — `label`, `placeholder`,
+`helpText`, `description`; there is no `localized…` twin. Every verb that writes a German
+text takes the English in the same call: `--label-en` (form, section, field, outcome,
+repeated, scenario), `--placeholder-en`, `--help-text-en`, `--declaration-label-en` on
+fields and `--description-en` on scenarios.
+
+```bash
+plexus-cli offer form field add --dir <bundle> --section section.kind --key kind.vorname --type string \
+  --label Vorname --label-en "First name" --placeholder "z. B. Anna" --placeholder-en "e.g. Anna"
+plexus-cli offer form section set --dir <bundle> --id section.kind --label-en "Child"   # English only
+```
+
+**The rule:** a new text without its English is refused at the command
+(`[i18n/missingTranslation]`) — the reader's language picks the text with no fallback
+to German, so the publish gate refuses it anyway. The CLI never copies the German into
+`en`. Changing the German of a text whose English is a real translation refuses unless
+you pass the new English too; an English that is blank (a migrated text) or a copy of
+the German becomes blank, and `offer validate` names it until it is translated.
+`--label-en ""` is refused. A field, repeated block or outcome added without any label
+is named by its key in both languages (an identifier, not a German text).
+
+## Verify
+```bash
+plexus-cli offer form show --dir <bundle> --form <slug>   # props/order/repeated/computed reflect the edits
+plexus-cli offer validate --dir <bundle>                  # "local validation clean"
+```
+
+## Idempotency / gotchas
+- **Validate-before-write.** Every mutator runs the real publish gate first; on any
+  error (bad expression, unknown enum-ref, wrong-kind effect flag, reparent cycle,
+  move anchor missing) it writes **nothing**.
+- **Clearing.** Expression/string props clear with `""`; `--required-for ""`, `--map`
+  (fieldMap) replaces; repeated `--min/--max -1` clears; `--unique-by ""` clears.
+- **Per-kind effect flags fail loud.** Passing `--org-kind` to a `person` effect (etc.)
+  is rejected — no silent drop.
+- **Catalog checks stay server-side.** Effect `role`/`relKind`, fieldMap `to`, and a
+  custom-field target resolve against the **tenant catalog** at `apply --publish`, not
+  offline. `enum-ref` is the one catalog the CLI carries, so it's checked offline.
+- **Reorder is sibling-scoped.** `field move` reorders within the field's section;
+  `section move` reorders among siblings. `field move --section <id>` moves a field into
+  another section unchanged — same key, so its values and every address that names it stay
+  valid; never rm + add, which drops the field's settings and trips the field-key
+  gate. The anchor then names a field of the TARGET section; a section left empty stays
+  until `section rm`. Into a `--visible-to` section only an unbound field may move
+  (`section.visibleTo-party` refuses a `cf_value`). Moving a section under a new parent =
+  `section set --parent`.
+- **`--visible-to` is judged at publish.** `offer validate` checks the shape, nesting,
+  party-bound fields (`cf_value` → `section.visibleTo-party`) and expressions outside the
+  section that read its keys (`section.visibleTo-read-outside`); whether the key names a
+  team or permission group of the school (`section.visibleTo-unknown`) is checked only at
+  `apply --publish`. It applies to applications on the NEW revision — existing ones keep
+  the definition they were pinned to.
+- **Removing a field/section/repeated breaks publish stability.** `publishSmartForm`
+  refuses to drop a field key a prior published version had — the `rm` commands warn.
+- **Re-publishing = a new version.** `offer apply --publish` after edits cuts a new
+  `smart_form_versions` row (and the full-bundle path re-pins the workflow).
+
+## Related
+- [Author a SmartForm as code](./author-smartform.md) — the add-from-scratch flow.
+- [Author a form's test scenarios and context](./author-form-scenarios.md).
+- [Edit a workflow node](./edit-workflow-node.md) — rebind which form a node uses.
+- Command reference: `plexus-cli offer form --help`.

package/dist/skill/references/offer/edit-workflow-node.md

@@ -0,0 +1,126 @@
+# Edit a workflow node
+
+**When to use:** change an existing node in an offer's workflow — relabel it, change
+who decides on a decision node, rebind a form node to a different
+SmartForm, or rewire where an outcome routes — without removing and re-adding it.
+
+## Prerequisites
+- An offer bundle on disk carrying a `workflow.json` (`offer init …` or `offer export …`).
+- Authoring is **fully offline**; only `offer apply --publish` needs an API token of a
+  user who may configure the tenant's offers (a tenant admin — see
+  [Add a tenant admin](../users/add-tenant-admin.md)).
+- An installed, current `plexus-cli` (`plexus-cli offer workflow node set --help`).
+
+## Steps
+```bash
+# Relabel a node — its label is ONE { de, en } field. A German-only change
+# refuses while a real English exists (pass --label-en too); --label-en alone
+# re-translates the current German.
+plexus-cli offer workflow node set --dir <bundle> --id form --label "Bewerbungsformular" --label-en "Application form"
+
+# Decision node: hand the decision row to another team (permission-group key) and
+# name the outcomes that need a comment (there are no approver slots).
+plexus-cli offer workflow node set --dir <bundle> --id freigabe \
+  --assign-decision schulleitung --comment-required rejected
+
+# Form node: rebind to a different carried SmartForm.
+plexus-cli offer workflow node set --dir <bundle> --id form --form <other-form-slug>
+
+# Rewire routing: send an outcome to a different existing node.
+plexus-cli offer workflow node set --dir <bundle> --id form --outcomes "standard:freigabe"
+
+# End node: re-author the terminal outcome (re-syncs the terminal progress column).
+plexus-cli offer workflow node set --dir <bundle> --id endRejected --outcome rejected
+
+# End node: keep or discard the application's data at this end. Changing
+# --outcome never changes it; a node without one must be given it here.
+plexus-cli offer workflow node set --dir <bundle> --id endRejected --data-decision discard
+
+# roleAssign node: change the granted role / mode; the person is an address.
+plexus-cli offer workflow node set --dir <bundle> --id roleAssignSchueler --role schueler --mode add \
+  --person '$node.form.admission.beneficiary'
+
+# What a node reads is named by address (single quotes — the shell expands $):
+# setFlag: the instance it raises the flag on; countersign / engagePush: the
+# contract; engagePush: the payment; a resolver contract / engagePush: the form
+# instance (`--form` takes a SmartForm slug only on a FORM node).
+plexus-cli offer workflow node set --dir <bundle> --id setFlagZusage --target '$node.form.admission'
+plexus-cli offer workflow node set --dir <bundle> --id gegenzeichnung --contract '$node.contract.contract'
+plexus-cli offer workflow node set --dir <bundle> --id contract --form '$node.form.admission'
+plexus-cli offer workflow node set --dir <bundle> --id engagePush --payment '$node.zahlung.payment'
+# A bare key is refused with the addresses visible at the node — see
+# [Name what a node reads](./addresses.md). Check the result with
+#   plexus-cli offer workflow node reads --dir <bundle> --node <id>
+
+# Document node (governedDocument): contract without a Freigabe, asking before it
+# goes out („„Vertrag" jetzt senden?" on „Bereitstellen"). `--approval none` drops
+# assign.releaseApproval + titles.approve; `--approval release` restores a
+# Freigabe (title via --approve-title, default "<Dokument> freigeben") and drops
+# the confirmation. Same edits as the IDE's Knotendetails → Einstellungen.
+plexus-cli offer workflow node set --dir <bundle> --id contract --approval none --confirm-issue true
+
+# Document node that the family returns signed (signedUpload / signedUploadChecked):
+# „Bestätigung der Vertragsbedingungen" is ON by default — before the
+# signed copy is uploaded the uploader confirms the terms, the protocol records
+# who and when. Switch it off, or reword the question in BOTH languages
+# ("" "" restores the default wording):
+plexus-cli offer workflow node set --dir <bundle> --id contract --confirm-terms false
+plexus-cli offer workflow node set --dir <bundle> --id contract \
+  --terms-question-de "Haben Sie den Schulvertrag gelesen und verstanden?" \
+  --terms-question-en "Have you read and understood the school contract?"
+
+# Decision node: no outcome until ONE of its optional actions is COMPLETED —
+# e.g. „Interview oder Taster Day vor der Grundsatzentscheidung". The keys are
+# `optionalActions` keys of THIS node (add the actions first); a foreign or
+# unknown key fails the publish gate ([decision/requiresOneOfUnknownAction]).
+# `--requires-one-of ""` drops the rule. Only on `node set`: the actions must exist.
+plexus-cli offer workflow node set --dir <bundle> --id decision --requires-one-of interview,tasterDay
+
+# Then validate + publish (publishing re-versions the workflow).
+plexus-cli offer validate --dir <bundle>
+plexus-cli --env <env> offer apply --publish --dir <bundle>
+```
+
+## Verify
+```bash
+plexus-cli offer workflow node list --dir <bundle>   # label / outcomes / routing reflect the edit
+plexus-cli offer validate --dir <bundle>             # "local validation clean"
+```
+
+## Idempotency / gotchas
+- **Validate-before-write.** Every `node set` runs the real publish gate before
+  touching disk — on any error (bad routing target, unknown outcome, …) it
+  writes **nothing**.
+- **A bundle exported before addresses were introduced is refused** (`[graph/retiredField]`: `wires`, a binding
+  with `path`, `adoptForm: true`) — export it again; never patch it by hand.
+- **`--type` is not editable.** A type change rewires outcomes/specs/progress, so it is
+  a remove + add: `offer workflow node rm` then `offer workflow node add`. Passing
+  `--type` to `set` fails loud with that guidance.
+- **Routing is validated at the boundary:** the outcome must be one the node declares
+  (or the implicit `done` for a no-outcome node), and the target must be an existing
+  node id — else it fails loud and writes nothing.
+- **Approver group existence is server-side.** The CLI authors the
+  `permissionGroupKey`; whether it resolves to a real tenant permission group is checked
+  at `apply --publish` / runtime, not offline.
+- **Relabel never touches progress.** Progress state/column labels come from the node's
+  events, not its label, so a `set` leaves the progress layout/wiring untouched.
+- **`--confirm-issue true` needs approval `none`.** With a Freigabe, „Freigabe
+  anfordern" sends nothing to the family and the Freigabe is itself the check — the
+  flag would be dead wiring, so the CLI refuses it (and publish would too).
+- **`--confirm-terms` / `--terms-question-*` only on a signing node.** A `confirm`
+  document (Platzangebot) has no signed copy to upload — the CLI refuses it, publish
+  too (`[governedDocument/deadWiring]`); so does a reworded question while the
+  confirmation is off.
+- **`--requires-one-of` holds the whole decision group** — Freigeben, Warteliste and
+  Ablehnen alike, for everyone incl. the process responsible; only „Bewerbung
+  ablehnen" (reject-anytime) stays open. Running applications on the old version are
+  not affected until they are re-pinned.
+- **Re-publishing = a new workflow version.** `offer apply --publish` after an edit cuts
+  a new `workflow_def_versions` row (and re-pins the smartform versions).
+
+## Related
+- [Add a workflow node](./add-workflow-node.md) — splice a new node (incl. the
+  `contractCreate`/`contractSign` mockup pair).
+- [Attach a form to a workflow](./attach-form-to-workflow.md) — bind a form at add time.
+- [Name what a node reads](./addresses.md) — the address flags and `node reads`.
+- Command reference: `plexus-cli offer workflow --help`.

package/dist/skill/references/offer/engage-push-node.md

@@ -0,0 +1,147 @@
+# Push accepted applications to Engage („Engage-Übertragung", TEMPORARY)
+
+**When to use:** a school that still runs Engage SMIS wants each accepted
+application transferred once, one-way, into Engage as a prospective pupil with its
+contacts. The node `engagePush` sits right before the „angenommen" end, records
+the push and goes on at once — the engine never waits for Engage. A stopped push opens
+the team task „Engage-Übertragung prüfen". Each push is a document of the application,
+„Übertragungsprotokoll" (Artefakte rail): every step, every request with what was
+sent and what came back, and what was not sent — the acts sit in its action bar.
+The node type is temporary and is removed with its slice.
+
+## Prerequisites
+- A bundle on disk, a live tenant's only in a private scratch dir
+  ([Edit a live tenant's offer](./edit-live-tenant-offer.md)).
+- The mapping as a JSON file (`node.engage`; `plexus-cli offer workflow node set-engage --help`).
+  It carries the school's Engage ids — lookup ids, AIF field ids, the admission stage,
+  the address format — so it lives next to the bundle, **never in version control**.
+  The `test` tenant carries no Engage push, so there is no example offer to export;
+  `offer validate` names every gap in a mapping you write.
+  The application's stage, school year, unit, offer or applicant come from an environment
+  variable by its address: `{ "from": { "address": { "scope": "env", "key": "stage.key" } }, "lookup": "yearGroup" }`
+  (the keys: IDE tab „Umgebungsvariablen"). An older mapping with
+  `{ "from": { "context": "stageKey" } }` is refused — export again.
+  Two answers that make ONE Engage value are joined: `{ "from": { "join": [".vorname", ".nachname"] } }`
+  (space-separated, in this order, empty unless every part is answered — never half a name;
+  a lookup then keys on the joined text, e.g. `"monatlich sepa"`). An answer the form leaves
+  optional but Engage requires gets an explicit Engage value: `{ "from": { "field": ".geschlecht" },
+  "lookup": "gender", "whenEmpty": "U" }` — sent as it stands, only for a form source and only
+  when the whole answer is missing (not when a `pick` finds nothing); it fills a record that
+  goes out, it never makes an unanswered optional record (address, e-mail, nationality …) go
+  out. Never use it to turn an unanswered (possibly hidden) yes/no question into „no".
+  The mapping is Engage vocabulary: a body field like `jobTitle` is fine (publish's i18n gate
+  skips `node.engage`).
+- A team (permission-group key) that checks a stopped transfer.
+- The deployment's Engage push mode — deployment configuration a platform operator sets,
+  not a CLI verb. Local and staging run `dry`; prod runs `live`, but with production not
+  allowed, so only the Sandbox school is written. Every push starts as a dry run; live is the cockpit's „Jetzt live übertragen"
+  after a clean dry run. The target `production` of the Engage connection is refused
+  unless the platform operator explicitly allowed production on that deployment — also
+  in a dry run.
+
+## Steps
+```bash
+# 1. The accepting edge into the end:
+plexus-cli offer workflow node list --dir <dir>
+
+# 2. Splice the push onto it. It names what it reads by address (single
+#    quotes!): the form instance always; the contract and the payment when the
+#    mapping reads `{ contract: … }` / `{ payment: … }` sources. An uploaded
+#    contract is `$node.<contract>.document`, a generated one (`production:
+#    resolver`) `$node.<contract>.contract`.
+plexus-cli offer workflow node add --dir <dir> --type engagePush \
+  --id engagePush --label "Engage-Übertragung" --label-en "Engage transfer" \
+  --on-edge contract:signed \
+  --assign-team bewerbungsteam \
+  --engage-target sandbox \
+  --engage-config <scratch>/engage-mapping.json \
+  --form '$node.form.admission' --contract '$node.contract.document' \
+  --payment '$node.collectPayment.payment'
+
+#    Change them later: node set --id engagePush --form|--contract|--payment '<address>'.
+#    An old bundle that still carries `wires` is refused
+#    ([graph/retiredField]) — export it again.
+
+#    Contract fields F01–F25 (meaning not confirmed by the school): --engage-contract-fields on
+
+# 3. Later changes to the mapping:
+plexus-cli offer workflow node set-engage --dir <dir> --node engagePush --config <scratch>/engage-mapping.json
+
+# 4. Validate, plan, publish (publish only with the go of the process owner).
+plexus-cli offer validate --dir <dir>
+plexus-cli --env <env> offer plan --dir <dir>
+```
+
+## Verify
+- `offer validate` shows no `[engagePush/*]` or `[address/*]` error (`[address/missing]`: no
+  `form`); `[engagePush/unmappedField]` (warning) lists mapped fields the form its `form`
+  address names does not have.
+- `offer workflow node reads --dir <dir> --node engagePush` lists the three addresses.
+- Every path into an `approved` end runs through the node (`[engagePush/bypassed]`).
+- After an application reaches the node: its cockpit lists the document
+  „Übertragungsprotokoll · Engage · Sandbox · Probelauf" with the recorded requests; nothing
+  was sent. A finished dry run can run again („Probelauf wiederholen", e.g. after a form
+  correction) — a finished LIVE push never.
+
+## Go-live (platform operator only — production school, credentials)
+Order matters; each step names why.
+1. **Put every offer on target `production` BEFORE the first real application starts.**
+   The target belongs to the PINNED version: an application started on a `sandbox` version
+   transfers to the Sandbox school forever, also after the offer is switched.
+   `node set` has no `--engage-target` flag: on an existing node, set its
+   `inputs.target` literal to `production` in the exported bundle, then `offer validate`
+   and `offer apply --publish`.
+2. **Allowing production and the Engage account** are deployment configuration: they need a
+   platform operator (an agent never sets them).
+3. **Sweep the dry runs that finished while the deployment was dry** — this needs a platform
+   operator too. A run opens its task only when it finishes, so a clean dry run from before
+   the switch would stay „Fertig" and never be transferred; the sweep (idempotent) opens
+   those tasks and reports `sandboxPinned`: the clean dry runs whose PINNED version still
+   targets the Sandbox school. They get no task (a live push would land in the Sandbox and
+   read as done) — re-pin each onto a `production` version (identical topology) or transfer
+   it by hand. The same rule refuses „Jetzt live übertragen" on such a run and opens no task
+   for it as soon as production is allowed (without that, a Sandbox live test stays
+   possible). Applications that ended without a place (rejected, withdrawn, waitlisted,
+   expired) are left out, live refuses them, and their open Engage task closes with them.
+   Every opened task „Engage-Übertragung prüfen" ends with „Jetzt live übertragen" (or with a
+   fixed answer + „Probelauf wiederholen" when the dry run lists issues). Test applications
+   are left out — they never go live.
+
+## Gotchas
+- **Engage has no idempotency key.** Never re-run a push by hand: „Erneut übertragen"
+  resumes at the first open step and first asks Engage whether an unclear create landed.
+  An id the team types in is read back by id before it is taken.
+- A create answers with the new id (`{"newPupilID":"4068"}`, `newContactID`, `newAddressID` —
+  observed in the sandbox write test); it is read back by id before it is taken. Without one, the id
+  comes from the difference of the list, verified the same way — never from a name search.
+- A write without a body (`LinkAddressToPupil`) is sent with an EMPTY body: Engage answers
+  `411 Length Required` to a body-less PUT.
+- A sibling already at the school holds the contact steps for the team: link the
+  existing Engage contact id or create a new contact.
+- The API cannot enrol: the pupil lands as a prospective pupil at the configured
+  admission stage. Whether Engage enrols from its completion stage is open.
+- A fee billed separately (`settlement: separate`) is never sent as „paid".
+- **A dry run that waits for the team opens its task „Engage-Übertragung prüfen"**: when
+  it lists an issue (fix the answer or the mapping, then „Probelauf wiederholen"), or on a live
+  deployment when nothing stands between it and „Jetzt live übertragen". A clean re-run on a dry
+  deployment or „Jetzt live übertragen" closes it; a stop of the live run opens the live row's
+  own task. A gap that lies in the PINNED mapping (a value without an Engage id) keeps the task
+  open until the application is re-pinned or the answer changes.
+- **The mapping an application uses is the one of its PINNED version.** A mapping fix reaches
+  applications started after the publish; older ones keep theirs (re-pin only with an identical
+  topology).
+- **Address lines for address format `CL1-117`:** line 1 street + number (`subdwelling`), line 3
+  town (`street`), line 6 postcode (`postcode`). Line 5 feeds `town` — a postcode there is lost.
+- **A lookup table is keyed by the exact value its source delivers — check each source's
+  vocabulary, `offer validate` does not.** The address field's `land` is its own closed
+  vocabulary in upper case (`DE`/`AT`/`CH`/`OTHER`), not the
+  lower-case ISO keys of a `countries` list. One `country` table for both made every
+  address „unmapped" (`[engagePush/unmappedLookup] … „DE"`), seen first in a production
+  dry run. Give such a source its own table (`addressCountry`). Leave a value
+  like `OTHER` unmapped: it names no country, and the push reports it instead of guessing.
+  Before going live, a dry run of an application with realistic data must list no issue
+  („Jetzt live übertragen" is hidden while any issue is listed).
+
+## Related
+- [Name what a node reads](./addresses.md) · [Edit a live tenant's offer](./edit-live-tenant-offer.md)
+- `plexus-cli offer workflow node add --help` (`--engage-*` flags) · `plexus-cli offer workflow node set-engage --help`