@smartkomm/plexus-cli 0.0.0-stage → 0.1.1

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`

package/dist/skill/references/offer/insert-and-rewire-node.md

@@ -0,0 +1,67 @@
+# Insert a node on one edge and rewire it
+
+**When to use:** a new step must sit between two existing ones — e.g. „Unterlagen prüfen"
+between the form and the first decision — and it must land on an existing board column
+instead of adding one. Replaces the hand-written bundle edits of `apply-doccheck.py`
+(insert a `review` node, re-point `form.next.standard`, add a progress mapping).
+
+## Prerequisites
+- An offer bundle on disk (`offer export --slug <slug> --out <dir>`). Fully offline: every
+  command runs the publish gate on the result and writes nothing when it fails.
+- The ids of the edge you cut: `plexus-cli offer workflow node list --dir <dir>` shows each
+  node's outcomes and targets.
+- The state ids of the process board: `plexus-cli offer workflow show --dir <dir>`.
+
+## Steps
+```bash
+# A review step on exactly the edge form —standard→ (whatever it pointed at):
+plexus-cli offer workflow node add --dir <dir> --type review --id docCheck \
+  --label "Unterlagen prüfen" --label-en "Check documents" \
+  --reads '$node.form.admission.kind.masernschutz,$node.form.admission.kind.proofOfIdentity' \
+  --on-edge form:standard \
+  --progress reviewing=eingereicht \
+  --assign-decision bewerbungsteam
+
+# Any other type works the same way, e.g. a waiting list on ONE decision outcome:
+plexus-cli offer workflow node add --dir <dir> --type waitlist --id warteliste \
+  --label "Warteliste" --label-en "Waiting list" --on-edge decision:waitlisted
+
+# Re-route an existing node's outcome afterwards:
+plexus-cli offer workflow node set --dir <dir> --id docCheck --outcomes reviewed:decision
+```
+
+- `--on-edge <from>:<outcome>` re-points exactly that edge to the new node; the new node's
+  outcomes continue to the edge's old target (route others with `--outcomes`). A sibling
+  outcome of `<from>` that reaches the same target keeps its route — unlike `--after`, which
+  rewires every edge of the anchor that points at its first target. The two exclude each other.
+- `--progress <event>=<stateId>` puts the node's progress event on a state the board already
+  has (the family keeps reading „Eingereicht"). Without it the node gets its own state and
+  column — for a review that is a second „In Prüfung" column, which the board's
+  distinct-label rule (`checkProgressBoardDistinctLabels`) refuses.
+- `--reads` names the fields a reviewer of a `--type review` ticks (entered, non-repeated
+  fields only), each by its full address `$node.<formNode>.admission.<field>` (single
+  quotes; a bare key is refused with the addresses visible at the new node). Without it the
+  review ticks nothing and still parks. Other node types declare reads with
+  `node set-reads` (which also takes the short form `--from <formNode> --field <path>,…`).
+  The form must run on every path before the new node (`[address/notVisible]` otherwise).
+
+## Verify
+```bash
+plexus-cli offer validate --dir <dir>
+plexus-cli offer workflow node list --dir <dir>
+plexus-cli --env staging --tenant <t> offer plan --dir <dir>     # expect: ~ workflow (+ ~ smartform if fields changed)
+```
+
+## Idempotency / gotchas
+- Not idempotent: a second `node add` with the same `--id` is refused (`already exists`).
+- An event the node type does not emit, or a state the board does not have, is refused by
+  name (`emits no progress event …`, `no state … on the process board`).
+- A review holds every non-rejecting outcome until all `reads` fields are ticked — so a
+  waiting-list exit belongs on the decision after it, not on the review.
+- Making the read fields required is a form edit: `offer form field set --key <k> --required`.
+- Nothing here touches a live process until `offer apply --publish`; running applications
+  stay on their pinned version.
+
+## Related
+- [Add a workflow node](./add-workflow-node.md) · [Edit a workflow node](./edit-workflow-node.md)
+- [Name what a node reads](./addresses.md) · [Declare what a document node reads](./declare-node-reads.md) · [Edit a live tenant's offer](./edit-live-tenant-offer.md)

package/dist/skill/references/offer/node-tasks.md

@@ -0,0 +1,162 @@
+# Author a workflow node's tasks
+
+**When to use:** give a workflow node a task a team must do — with a typed result
+(„Empfehlung", „Auswahl", Freitext, a priced item or a reduction), a blocking edge onto the same or a later node, a
+spawn condition, evidence fields or its plain-text description — or change / remove one, without
+hand-editing `workflow.json`. Works on any bundle: the `test` template, a fixture, or a
+live tenant's export (then follow [Edit a live tenant's offer](./edit-live-tenant-offer.md)
+around it).
+
+## The model in four lines
+- A task (`node.tasks[]`, key unique per node) spawns when its node is entered — with
+  `--when`, only while that **boolean form export** holds. Everything a task reads names
+  its producer by full address (single quotes): `--when` / `--reads`
+  (`'$node.<formNode>.admission.<field>'`, one form per task — `[address/mixedForms]`),
+  `--documents` (`artifact:<own slot>`, `field:<address>`, `document:$node.<node>.document`),
+  `--family-request-fields <addresses>` / `--family-request-from '$node.<formNode>.admission'`,
+  a record field's `"suggest":{"kind":"form","address":"$node.…"}`. A bare key is refused
+  with the addresses visible at the node; the producer must run on every path before it
+  (`[address/notVisible]`). A value a task records is `$task.<taskKey>.<storeKey>` for its
+  readers — renaming the task key changes that address.
+- `--blocks <templateKey>` withholds a sibling's actions on the same node;
+  `--blocks <nodeId>:<templateKey>` withholds a template on a **later** node (a
+  cross-node blocker: it survives its node and needs a `--result`). Intrinsic targets:
+  `decision`, `prepareDocument`, `releaseApproval`. The target's **whole** action group
+  waits — on a decision Freigeben, Warteliste, Ablehnen, and Nachrücken on the waitlist
+  it routes into. There is no partial hold; the staff escape is „Bewerbung
+  ablehnen".
+- A task with `--result` closes only by recording it; `--chat` posts a result with text
+  into `all`, `team:<group>` or an authored channel key — never `external`.
+- A result **with a value** (`choice`, `pricedItem`, `reduction`) writes it under the
+  task's own address — `--writes '$task.<thisTaskKey>.<storeKey>'`, stored as the bare
+  `result.writes` — and names it with `--result-label` (`--result-label-en`). A
+  `pricedItem` names its article with `--item <catalog key>` (not an address: the key of
+  the billing item); a `reduction` the derived price it lowers with
+  `--prices '$derived.<key>'`.
+- The CLI checks **shape**; the graph rules (`[workItems/*]`, `[taskResult/*]`) are the
+  publish validators, run before every write and by `offer validate`.
+
+## Steps
+
+```bash
+B=<bundle dir>
+
+# What a node carries today.
+plexus-cli offer workflow node list --dir $B
+jq '.graph.nodes[] | {id, tasks}' $B/workflow.json   # the tasks themselves
+
+# 1. A cross-node blocker with a recommendation, posted to the whole team chat:
+#    the review team's estimate holds the whole Aufnahme decision.
+plexus-cli offer workflow node task add --dir $B --node reviewEingereicht --key einschaetzung \
+  --title "Einschätzung abgeben" --title-en "Give an assessment" \
+  --team oeffentlichkeitsarbeit --due-in-days 3 \
+  --blocks aufnahme:decision \
+  --result recommendation --chat all
+
+# 2. A conditional choice task that holds the contract (the reduced-fee shape):
+#    it exists only while the family asked for a reduction, comes back when the
+#    answer returns to „Ja", and is judged again when the income proofs change.
+plexus-cli offer workflow node task add --dir $B --node contract --key ermaessigung \
+  --title "Ermäßigung prüfen" --team finanzen --due-in-days 5 \
+  --blocks prepareDocument \
+  --result choice --option voll="Voller Beitrag|Full fee" --option halb="Halbiert|Halved" \
+  --text-required --chat team:finanzen \
+  --when '$node.form.admission.ermaessigungBeantragt' --on-condition-return respawn \
+  --reads '$node.form.admission.gebuehren.einkommensnachweise' \
+  --description "Nachweise prüfen und die Ermäßigung berechnen." \
+  --description-en "Check the proofs and calculate the reduction."
+
+# 3. A reduction that lowers the derived tuition (the `test` template's shape): it
+#    writes its deduction under its own address and names the price it lowers.
+#    The derived price must be declared in graph.processStore with
+#    derive.reduction = $task.reducedFee.reducedFee ([process/reductionPrices]).
+plexus-cli offer workflow node task add --dir $B --node reviewEingereicht --key reducedFee \
+  --title "Ermäßigung berechnen" --team finanzen \
+  --result reduction --writes '$task.reducedFee.reducedFee' --prices '$derived.schulgeld' \
+  --result-label "Einkommensermäßigung (Abzug)" --result-label-en "Income-based reduction (deduction)" \
+  --chat team:finanzen
+#    A priced item names its article instead:
+#    --result pricedItem --item tuition --writes '$task.<key>.<storeKey>' --result-label "Schulgeld"
+
+# 4. Change only what you name (everything else stays).
+plexus-cli offer workflow node task set --dir $B --node reviewEingereicht --key einschaetzung --text-required
+plexus-cli offer workflow node task set --dir $B --node contract --key ermaessigung --clear-description
+
+# 5. Remove a task (refused while another task's --blocks still names it — the
+#    refusal lists the dependents; retarget or --clear-blocks them first).
+plexus-cli offer workflow node task rm --dir $B --node contract --key ermaessigung
+
+# 6. Gate, diff, release.
+plexus-cli offer validate --dir $B
+plexus-cli --env <env> offer plan  --tenant <t> --dir $B
+plexus-cli --env <env> offer apply --tenant <t> --dir $B --publish
+```
+
+Every verb prints a field diff (`before` / `after`); `--json` gives
+`{action, node, key, before, after, changes, dropped}`.
+
+## Example: move a task to another node on a live tenant
+
+A form task `oeaEinschaetzung` on `formAnmeldung` should become one recommendation task
+on the review node that holds the Aufnahme decision (reject / waitlist stay open).
+Work in a scratch dir and keep an untouched copy to diff against:
+
+```bash
+WORK=<scratch dir>/$(date +%F)-einschaetzung
+T=<slug>; S=<offer-slug>
+plexus-cli --env prod offer export --tenant $T --slug $S --out $WORK/$S
+cp -a $WORK/$S $WORK/$S.orig
+
+plexus-cli offer workflow node task rm  --dir $WORK/$S --node formAnmeldung --key oeaEinschaetzung
+plexus-cli offer workflow node task add --dir $WORK/$S --node reviewEingereicht --key einschaetzung \
+  --title "Einschätzung abgeben" --team oeffentlichkeitsarbeit --due-in-days 3 \
+  --blocks aufnahme:decision \
+  --result recommendation --chat all
+
+diff -ru $WORK/$S.orig $WORK/$S                      # exactly these two tasks
+plexus-cli offer validate --dir $WORK/$S
+plexus-cli --env prod offer plan  --tenant $T --dir $WORK/$S
+plexus-cli --env prod offer apply --allow-prod --tenant $T --dir $WORK/$S --publish
+```
+
+If `offer plan` refuses task fields that `offer validate` accepts, the deployment runs an
+older release than your CLI — that needs a platform operator, not a bundle edit.
+
+## Verify
+- `offer validate --dir $B` → clean.
+- After publish, a new application reaching the node shows the task in the cockpit's
+  task rail („Empfehlung erfassen"), and the blocked target's actions stay held until
+  the result is recorded.
+
+## Gotchas
+- **Only errors the edit introduces block the write.** Errors the bundle already carried
+  print as `⚠ vorbestehend …` and do not stop you — but `offer apply --publish` still
+  refuses them.
+- **`--title` without `--title-en` writes the German into both locales**; `--title-en`
+  alone relabels English only.
+- **`blocks.except` is retired** — `offer validate` refuses a bundle that still
+  carries it (`[workItems/blocksExceptRetired]`); re-setting `--blocks` drops it
+  (`⚠ blocks.except entfällt`). A result kind change drops
+  options / `textRequired` / `writes` / `label` / `item` / `prices` that no longer fit
+  (each listed under `dropped`), and keeps `chat`.
+- **`--writes` takes this task's own address only** — `'$task.<key>.<storeKey>'` without a
+  path; a bare key, another task's address or a path is refused. `--prices` takes
+  `'$derived.<key>'`. Whether the store key is declared and the reduction's
+  `derive.reduction` points back at this task is the publish gate's check
+  (`[process/*]`).
+- **`--option` replaces the whole list** — repeat every entry you keep.
+- **`--description` is plain text under the title, never a checklist.** There are no
+  checklist steps any more (a bundle still carrying `steps` is refused at publish,
+  `[workItems/unknownKey]`, like any key a task does not declare); several work steps are several tasks (a `spawnTasks`
+  optional action, chained by `blocks`). Without `--description-en` the German stands in
+  for English.
+- **An old bundle** (bare keys in `when` / `reads` / documents /
+  `familyRequest` / `suggest`) is refused (`[address/bareIdentifier]`) — export it again.
+- **Offline, team and channel existence are not checked** — the tenant's permission
+  groups are known only at `offer apply --publish`.
+- **The positional `node add|set --task`** replaces a node's whole task list and knows
+  none of the fields above; use it only to scaffold a new node.
+
+## Related
+- [Name what a node reads](./addresses.md) · [Edit a workflow node](./edit-workflow-node.md) · [Author default chat channels](./workflow-default-channels.md)
+- `plexus-cli offer workflow node task add --help` (every result kind and flag)

package/dist/skill/references/offer/optional-assessment.md

@@ -0,0 +1,65 @@
+# Ask for an optional assessment („Einschätzung einholen")
+
+**Use it to** model assessments the decision does not have to wait for: the
+Öffentlichkeitsarbeit may say „Keine Einschätzung abgeben", the Schulleitung attaches a
+Beurteilung as a file, and the Sekretariat can ask the Geschäftsführung for one more
+assessment from the „Weiteres" menu — without a letter to the family.
+
+## The model
+
+- **Optional task** (`optional: { skipLabel: { de, en } }`): nothing waits for it. The
+  task holds no step, so publish refuses it together with `blocks`, `gatesNode`,
+  `locksEvidence` and `completableIf` (`[workItems/optionalHolds]`). Its holder closes it
+  with its result or with the skip button. The Sekretariat skips it by deciding: an open
+  optional task then reads „Aufgabe hinfällig" in the Verlauf, naming the decider.
+  The result must be prose: free text, a recommendation, or a choice without `writes`
+  (`[workItems/optionalNeedsProseResult]`). A task of an action listed in `requiresOneOf`
+  is never optional (`[workItems/optionalInRequiresOneOf]`).
+- **Files** (`result.files: true`): the person attaches up to 20 files next to the text.
+  Text and files go into the result's chat as one message. Find them later in the cockpit
+  under Verlauf/Aktivitäten (tab of the chat the result names), shown only to people who
+  read that chat — never under „Dokumente"
+  ([task-result-files.md](./task-result-files.md)).
+- **„Einschätzung einholen"** is a `spawnTasks` optional action that references an optional
+  task assigned to a role (`--team geschaeftsfuehrung`). Pressing the action spawns that
+  task. A triggered optional task does not hold the decision. An internal task never
+  writes to the family.
+
+## CLI
+
+Use a scratch dir for a real tenant
+([edit-live-tenant-offer.md](./edit-live-tenant-offer.md)).
+
+```bash
+# 1. The ÖA assessment: optional, no longer blocking the decision
+plexus-cli offer workflow node task set --dir <dir> --node aufnahme --key oeaEinschaetzung \
+  --clear-blocks --optional "Keine Einschätzung abgeben" --optional-en "No assessment"
+
+# 2. The Schulleitung's assessment takes files (it may stay owed — keep its blocks)
+plexus-cli offer workflow node task set --dir <dir> --node aufnahme --key schulleitungPruefung --files
+
+# 3. The task the action spawns, then the action
+plexus-cli offer workflow node task add --dir <dir> --node aufnahme --key gfEinschaetzung \
+  --title "Einschätzung Geschäftsführung" --title-en "Management assessment" \
+  --team geschaeftsfuehrung --due-in-days 3 --result freetext --chat all --files \
+  --optional "Keine Einschätzung abgeben" --optional-en "No assessment"
+plexus-cli offer workflow node optional-action set --dir <dir> --node aufnahme --key einschaetzung \
+  --label "Einschätzung einholen" --label-en "Request an assessment" \
+  --tasks gfEinschaetzung --trigger bewerbungsteam --repeatable
+
+plexus-cli offer validate --dir <dir>
+```
+
+The group named by `--team` must hold `aufgaben.*` rights, or its members cannot open the
+task (`tenant_admin` usually holds none). A rights failure blocks nothing at publish; it
+only shows up in the cockpit.
+
+## Verify
+
+1. Cockpit, application on `aufnahme`: the decision row shows „Wartet auf: …" for
+   every task that still blocks it, but not for optional ones.
+2. As the ÖA member, open the task. The dialog shows „Keine Einschätzung abgeben" next to
+   „Ergebnis erfassen". After a skip, the Verlauf card reads „Keine Einschätzung abgeben".
+3. As the Sekretariat, use „Weiteres → Einschätzung einholen". The Geschäftsführung's queue
+   gets the task, and the family's Verlauf gets nothing.
+4. Testmodus: „<Aufgabe> (Test): Keine Einschätzung abgeben" skips through the real verb.