@smartkomm/plexus-cli 0.0.0-stage → 0.1.0

package/dist/skill/references/offer/addresses.md

@@ -0,0 +1,129 @@
+# Name what a node reads (addresses)
+
+**When to use:** a node must read data another node produces — the form's answers in a
+contract, a value a review task records, a derived price, the contract a countersignature books
+on — or the gate refuses a bundle with an `[address/*]` code. A read **names its
+producer** in the field that reads it: a full address. There are no data edges any more
+(`node.wires` is gone), no form implied by the node and no bare keys. Control edges (`next`) only
+route. What a node may read is what is produced on every path before it.
+
+## Prerequisites
+- An offer bundle on disk (`offer init`, or `offer export --slug <slug> --out <dir>`; a live
+  tenant's bundle only into a private scratch dir — see
+  [Edit a live tenant's offer](./edit-live-tenant-offer.md)). Fully offline: every verb runs the
+  publish gate on the result and writes nothing when the edit introduces an error.
+- **A bundle exported before addresses were introduced is refused** (`[graph/retiredField]` for `wires`, a binding
+  with `path`, `adoptForm: true`; `[address/bareIdentifier]` for a bare key). Do not patch it by
+  hand — export it again (the server migration folded the live graph onto addresses).
+- The spelling — **always in single quotes on the command line**, or the shell expands `$node`:
+
+  | Address | Names | Example (demo tenant `test`) |
+  |---|---|---|
+  | `$node.<formNode>.admission` | the form instance a form node creates | `$node.form.admission` |
+  | `$node.<formNode>.admission.<field>` | one field (or export, or party leaf `beneficiary` / `signers`) of it | `$node.form.admission.kind.geburtsurkunde` |
+  | `$node.<node>.document` | the newest revision of a document node's slot | `$node.platzangebot.document` |
+  | `$node.<node>.contract` | a machine-produced contract (`production: resolver`) | `$node.contract.contract` |
+  | `$node.<node>.payment` | a payment node's result | `$node.zahlung.payment` |
+  | `$task.<task>.<key>` | the value the ONE task `<task>` writes under store key `<key>` | `$task.reducedFee.reducedFee` |
+  | `$derived.<key>` | a computed price (`processStore[].derive`) | `$derived.schulgeld` |
+  | `$env.applicant.language` | a fact about the application nobody produces | |
+
+  An adopting form node (`adoptForm`, e.g. `formZusage` in the demo tenant `test`) **produces nothing**: the
+  instance stays its creator's, so every later node still reads `$node.form.admission.…`.
+
+## Steps
+```bash
+# What arrives at a node: every address it reads, where it is written, who produces it —
+# including what it reads by carrying (the evidence of a task whose value it reads, the
+# sources of a derived price, the price check):
+plexus-cli offer workflow node reads --dir <dir> --node contract
+
+# A bare key is refused with the list of what that node can read — use it to pick:
+plexus-cli offer workflow node set-reads --dir <dir> --node contract --address kind.vorname
+#   → --address (reads) "kind.vorname": ein nackter Schlüssel …
+#     An „Vertrag" (contract) lesbar:
+#       Bewerbung Grundschule Havelland › Anmeldung ($node.form.admission)
+#       Prüfung › Schulgeld mit Ermäßigung › Einkommensermäßigung ($task.reducedFee.reducedFee)
+#       …
+
+# The flags that read data (each takes full addresses):
+plexus-cli offer workflow node set-input --dir <dir> --node contract --input schulgeld --address '$derived.schulgeld'
+plexus-cli offer workflow node set-reads --dir <dir> --node contract --from form --field kind.vorname,kind.nachname
+plexus-cli offer workflow node set-requires --dir <dir> --node nachreichen --address '$node.form.admission.kind.masernschutz'
+plexus-cli offer workflow node task set --dir <dir> --node reviewEingereicht --key reducedFee \
+  --when '$node.form.admission.ermaessigungBeantragt' --reads '$node.form.admission.gebuehren.einkommensnachweise'
+plexus-cli offer workflow node add --dir <dir> --type setFlag ... --target '$node.form.admission'
+plexus-cli offer workflow node add --dir <dir> --type form ... --adopt-form '$node.form.admission'
+plexus-cli offer workflow node add --dir <dir> --type countersign ... --contract '$node.contract.contract'
+```
+
+The short form `--from <formNode> --field <path>` (set-input, `*-reads`, `*-requires`) only
+composes `$node.<formNode>.admission.<path>` — it names the node, it never picks one.
+
+Which flag sets which field:
+
+| Field | Verb / flag |
+|---|---|
+| an input binding | `node set-input --address` (or `--from/--field`) |
+| `reads` (decision / review / governedDocument) | `node set-reads|add-reads|remove-reads --address`; review at add: `node add --reads` |
+| `requires` (completenessCheck) | `node set-requires|add-requires|remove-requires --address`; at add: `--require` |
+| setFlag `target` | `node add|set --target` |
+| form `adoptForm` | `node add --adopt-form` |
+| resolver governedDocument / engagePush `form` | `node set --form '<instance address>'` (engagePush also at add) |
+| countersign / engagePush `contract`, engagePush `payment` | `node add|set --contract|--payment` |
+| roleAssign / completenessCheck `person` | `node add|set --person` |
+| task `when`, `reads`, `documents` | `node task add|set --when|--reads|--documents` (`field:<address>`, `document:$node.<node>.document`; an own slot stays `artifact:<key>`) |
+| task family request | `--family-request-fields <addresses>` or `--family-request-from '$node.<form>.admission'` |
+| record field suggestion | `--field '{…,"suggest":{"kind":"form","address":"$node.form.admission.alleinerziehend"}}'` |
+| `pricingRules[].rows[].when`, `processStore[].derive.reduction` | **no CLI verb** — edit the bundle JSON; a condition's identifiers are canonical addresses (`$task.geschwisterrang.geschwisterRangSchule >= 3`), a reduction is `{ "scope": "task", "owner": "reducedFee", "key": "reducedFee" }` |
+
+## In the IDE instead
+The Workflow-IDE offers exactly what the gate accepts — the same rules
+(`addressFieldOptions`), one picker in every editor, never a typed key:
+- **What arrives at a node:** select it — the bottom bar's „Eingang" column lists
+  its reads and what it may read (Formular · Dokumente · Zahlungen · Aufgaben ·
+  Abgeleitet · Umgebung), each with producer, address and how it is read; a rose
+  entry is a read publish refuses (`[address/notVisible]`). Drag an entry onto a
+  parameter to bind it.
+- **Node fields** (`reads`, `requires`, setFlag `target`, `adoptForm`, `form` /
+  `contract` / `payment`): node → „Details" → „Einstellungen".
+- **Task fields** (`when`, `reads`, `documents`, `familyRequest`, a record's
+  suggestion): node → „Details" → „Team".
+- **Pricing-rule conditions and reductions:** header → „Preisregeln" („Adresse
+  einfügen" puts the `$task…` identifier into the condition).
+
+## Verify
+```bash
+plexus-cli offer validate --dir <dir>                         # exit 0, no [address/*] error
+plexus-cli offer workflow node reads --dir <dir> --node <id> --json
+plexus-cli --env staging --tenant <t> offer plan --dir <dir>   # ~ workflow; address:/reads: rows against the live head (see edit-live-tenant-offer.md)
+```
+
+## Idempotency / gotchas
+- **The gate judges every address** before writing: `[address/shape]`, `[address/bareIdentifier]`,
+  `[address/unknownOwner]` (no such node / task), `[address/unknownKey]` (the node does not
+  produce it — a form produces `admission`, a resolver contract `contract`, not `document`),
+  `[address/ownerNotWriter]` (the task does not write that store key), `[address/notVisible]`
+  (the producer is not on EVERY path before the reader — on a detour the reader would wait
+  forever), `[address/pathNotInTarget]` (the form has no such field), `[address/typeMismatch]`
+  (a `when` must be a yes/no export, a binding must fit its slot), `[address/notFormInstance]`
+  (`target`, `adoptForm`, `form`, `familyRequest.from` name `$node.<creating form>.admission`
+  without a path), `[address/mixedForms]` (one list — node `reads`, `requires`, a task's
+  `when` + `reads`, `familyRequest.fields` — names ONE form), `[address/missing]` (setFlag
+  `target`, countersign `contract`, a resolver's / engagePush's `form`). Only errors the edit
+  INTRODUCES block it; errors the bundle already had are printed as „vorbestehend".
+- **A node reads its own results** (a value one of its tasks writes, its own document slot)
+  without dominance; it is still in its read list.
+- **`node rm` refuses while an address names the node** — its form instance, document,
+  contract, payment, or a value one of its tasks writes — and lists every place (config path +
+  address). Edit those first; nothing is dropped silently.
+- **Renaming a task key or moving a writing task to another node** changes the address
+  (`$task.<task>.<key>`): every reader must be edited, and running applications cannot re-pin
+  across it.
+- Nothing reaches a live process until `offer apply --publish`; running applications keep their
+  pinned version.
+
+## Related
+- [Bind a node input](./bind-node-input.md) · [Declare what a document node reads](./declare-node-reads.md)
+- [Add a workflow node](./add-workflow-node.md) · [Countersign the contract](./countersign-node.md) · [Node tasks](./node-tasks.md)
+- [Edit a live tenant's offer](./edit-live-tenant-offer.md) — export, plan and apply against a live tenant

package/dist/skill/references/offer/appointment-task.md

@@ -0,0 +1,79 @@
+# Give an appointment its Terminaufgabe („Taster Day durchführen")
+
+**When to use:** a „Termin vereinbaren" task books an appointment (see
+[Make a task close with an appointment](./task-appointment-result.md)), and the work
+done AT that appointment — hold the interview, run the taster day, give feedback with
+attachments — belongs to whoever hosts it, due a few days after it ends.
+
+## The model in three sentences
+
+The **Terminaufgabe** is an ordinary task of the same node with
+`appointment: { of: '<booking task>', dueDaysAfterEnd: N }`. It spawns with its round
+and waits („Wartet auf: <booking task>") until the booking binds it: its holder is the
+appointment's **host** (a person of the task's team, or that team's owner on the
+application), its due day the appointment's end + N. It closes with its result — the
+feedback, a recommendation / choice / free text with `files: true` — and holds whatever
+it `blocks` until then.
+
+## Prerequisites
+
+- The booking task exists with `result.kind: appointment`.
+- The Terminaufgabe's team (`--team`) is the team the hosts come from: the booking
+  dialog offers only that team and its members, and the server refuses others.
+  Teachers who host need cockpit access (`bewerbungsmanagement.applications.read`,
+  `aufgaben.items.read/write`).
+- The target environment runs a platform version that knows Terminaufgaben (`offer apply`
+  publishes against the deployed gate; if publish does not know `appointment`, ask the
+  platform operator).
+
+## Steps
+
+```bash
+# 1. The booking task no longer blocks the follow-up — the hold is derived.
+plexus-cli offer workflow node task set --dir $WORK/$S --node decision --key tasterDayTermin --clear-blocks
+# 2. The Terminaufgabe: team, link, due rule, feedback with files.
+plexus-cli offer workflow node task add --dir $WORK/$S --node decision --key tasterDayDurchfuehren \
+  --title 'Taster Day durchführen' --title-en 'Hold the taster day' --team teachers \
+  --appointment-of tasterDayTermin --due-days-after-end 2 \
+  --result recommendation --chat all --files
+# 3. If the booking task is part of an optional action, the Terminaufgabe joins it —
+#    and the action is repeatable: a cancelled appointment ends the round.
+plexus-cli offer workflow node optional-action set --dir $WORK/$S --node decision --key tasterDay \
+  --tasks tasterDayTermin,tasterDayDurchfuehren --repeatable
+plexus-cli offer validate --dir $WORK/$S
+```
+
+Then the live path ([Edit a live tenant's offer](./edit-live-tenant-offer.md)):
+`--env prod offer plan` → `--env prod offer apply --allow-prod --publish` → plan again
+until every row is `same`.
+
+## Verify
+
+- `offer validate` shows no `[workItems/appointment*]` error.
+- In the cockpit: trigger the action → the Terminaufgabe reads „Wartet auf: …";
+  book with a host of the team → the card shows the appointment line
+  („Taster Day · Di., 21.10. 09:00–12:00 · Raum 2 · Gastgeber: …") and the host holds it.
+
+## Gotchas
+
+- Publish refuses: `of` naming no appointment task of the same node
+  (`appointmentOfUnknown`), two Terminaufgaben for one booking task (`appointmentOfTwice`),
+  `--due-in-days` beside the end rule or N outside 0–60 (`appointmentTaskDue`), any
+  `blocks` aimed at it (`appointmentTaskBlocked`), a different optional action than the
+  booking task (`appointmentTaskBinding`), an optional action spawning the booking task
+  without `repeatable: true` (`appointmentActionRepeatable` — a cancellation ends the
+  round, and without a second one a decision waiting for the action via `requiresOneOf`
+  would hang for good), an approval / `when` / `optional` /
+  family request / missing result (`appointmentTaskShape`). Warning
+  `appointmentChatUnreadable`: the feedback chat is another team's — the host may not
+  read it; prefer `all` or the task's own team.
+- Holder and due day have ONE writer, the appointment: „Zuweisen" refuses a bound
+  Terminaufgabe, and so does „Wiederöffnen" (edit the feedback text instead).
+- A staff member who hosts an appointment with an open Terminaufgabe cannot be
+  withdrawn (`[appointment/hostInUse]`) — change the appointment's host first.
+- Running applications keep their pinned version.
+
+## Related
+
+- [Make a task close with an appointment](./task-appointment-result.md)
+- [Files on a task result](./task-result-files.md)

package/dist/skill/references/offer/assignment-rule.md

@@ -0,0 +1,195 @@
+# Change an offer's assignment rule (Zuständigkeitsregel)
+
+**When to use:** decide who becomes responsible for a new application and who owns
+each team's tasks — for a new offer, after staff changes, or when a workflow starts
+giving work to a team the rule does not cover yet. Also: a staff member a rule names
+is leaving.
+
+## What it is (one paragraph)
+
+The assignment rule is a **section of the workflow graph**: `graph.assignmentRules`
+in the offer bundle's `workflow.json`. It is **one ordered rule list per slot**: per
+slot the first row whose condition holds wins, the last row has no condition
+(`"when": null`, shown as „sonst"). It is versioned with the offer version — saved
+with the draft, checked at publish, pinned with the graph. Each new application
+evaluates its pinned graph's rule **once** at its start (only the slots its workflow
+needs) and records the matched row per slot; a published change reaches only new
+applications. Slots: `responsible` („Prozesszuständig" — always a person, always
+**first**) and `team:<teamKey>` for every team the workflow gives work to. Targets:
+`{kind:"person", configKey}` (the staff member's `user_tenant_access.configKey`),
+`{kind:"creator"}` („wer die Bewerbung anlegt" — only in a row whose own `when` is,
+or has as an `&&` conjunct, exactly `$env.applicant.channel == 'staff'`),
+`{kind:"slot", slot:"responsible"}` („die zuständige Person") and `{kind:"queue"}`
+(„Team-Queue") — both team slots only —, `{kind:"rotation", configKeys:[…], mode}`
+(„Reihum" — any slot: ≥ 2 distinct people, `"strict"` takes turns after the
+rotation's last pick, `"leastLoaded"` takes whoever has the fewest open tasks, ties
+in turn; on a team slot every pool member must be in the team) and
+`{kind:"unassigned"}` („Person wählen"),
+which a draft may hold but publish refuses. The process slot's „sonst" row is always
+a fixed person.
+
+## Prerequisites
+
+- `plexus-cli` installed; a token that may apply offers on the tenant (for the
+  export/apply steps). `offer validate` and `assignment simulate` run offline.
+- The people are active staff of the tenant and members of any team they are named
+  for directly. A person is named by config key: choosing a staff member in the
+  editor gives them one if they have none (opaque `staff_<random>`, never derived
+  from the name).
+
+## Steps — in the workflow editor
+
+1. Open the offer's workflow in the editor → toolbar „Team-Verantwortliche". One
+   table per slot. Rows can be added (they land before „sonst"), removed and moved
+   up/down; the condition is built from field / operator / value („Erweitert" for
+   the raw DSL); the target picker offers a person, „wer die Bewerbung anlegt",
+   „die zuständige Person", „Team-Queue" and „Reihum …" (tick ≥ 2 people — team
+   members only on a team slot — and „Streng reihum" or „Wer am wenigsten offen
+   hat"). Errors show inline, in German, from the
+   same checks publish runs.
+2. Save and publish the workflow like any other change — the rule goes with it.
+3. Nothing to keep elsewhere: a live tenant's bundle lives on the server only.
+   Anyone who changes the offer later starts from a fresh
+   `offer export`, so the rule you published is what they edit.
+
+## Steps — in the bundle
+
+1. Export the live offer into a private scratch dir (a live tenant's bundle is
+   never kept in a shared or versioned place — see
+   [edit-live-tenant-offer](./edit-live-tenant-offer.md)) and edit
+   `workflow.json` → `graph.assignmentRules`:
+
+   ```bash
+   WORK=$(mktemp -d)   # any private scratch dir
+   plexus-cli --env prod offer export --tenant <slug> --slug <offer-slug> --out $WORK/bundle
+   ```
+
+   ```jsonc
+   "assignmentRules": [
+     { "slot": "responsible", "rules": [
+       { "when": "$env.applicant.channel == 'staff'", "assign": { "kind": "creator" } },
+       { "when": "$env.unit.key == 'secondary'",
+         "assign": { "kind": "person", "configKey": "admissions_secondary" } },
+       { "when": null, "assign": { "kind": "person", "configKey": "aufnahme" } }
+     ] },
+     { "slot": "team:bewerbungsteam", "rules": [
+       { "when": null, "assign": { "kind": "slot", "slot": "responsible" } }
+     ] },
+     { "slot": "team:principals", "rules": [
+       { "when": null, "assign": { "kind": "queue" } }
+     ] }
+   ]
+   ```
+
+   Every list ends with exactly one `"when": null` row; a row below a constant or a
+   repeated condition is refused (`[assignment/shadowedRule]`). `$env.unit.key` is
+   the unit's **configKey**, never its name or URL slug. A condition reads the
+   application's environment variables (`$env.*`, the same vocabulary as the graph
+   and the forms — IDE tab „Umgebungsvariablen"). A variable that can be
+   EMPTY — `$env.applicant.language` (no applicant account: started by staff),
+   `$env.stage.gradeLevel`, `$env.run.startDate` — needs a `… != null &&` guard
+   before `!=` / `!` / an ordering (`[condition/unguardedNullable]`); `==` needs
+   none. A bundle still carrying `$ctx.*` (exported before `$env` replaced it) is refused —
+   export again.
+
+2. Validate offline — the same checks the editor shows and publish runs
+   (`[assignment/slotMissing]`, `…/queueOnProcessSlot`, `…/unguardedTarget`,
+   `…/targetMissing`, `[condition/*]`, …):
+
+   ```bash
+   plexus-cli offer validate --dir $WORK/bundle
+   ```
+
+3. Test bench — evaluate the bundle's rule over an application's environment
+   (`$env`), offline:
+
+   ```bash
+   plexus-cli assignment simulate --dir $WORK/bundle \
+     --env-json '{"applicant":{"language":"de","channel":"self-service"},"unit":{"key":"secondary","name":"Secondary"}}'
+   # A staff start: no applicant account, so no language (null).
+   plexus-cli assignment simulate --dir $WORK/bundle --creator "Sekretariat" \
+     --env-json '{"applicant":{"language":null,"channel":"staff"},"unit":{"key":"school_primary","name":"Primary"}}'
+   ```
+
+   Every slot is evaluated; the output names the matched row (`#1`, `#2`, …) per slot.
+   A „Reihum" row shows mode, pool, last pick and pick. Offline there is no rotation
+   position: pass the last pick with `--rotation-previous team:finanzen=finanzen`
+   (none = the rotation's first start), open-task counts for `leastLoaded` with
+   `--open finanzen=3 --open finanzen_2=1` (absent = 0), and someone who left with
+   `--left <key>`. What a real start picked is in its evaluation record
+   („Regel anzeigen" in the cockpit).
+   Only the keys the conditions read are needed; a key a condition reads but the
+   environment lacks fails loud, like a start.
+
+4. Publish — the DB half of the check runs here (people active staff, a team slot's
+   fixed person a member, live unit/offer keys):
+
+   ```bash
+   plexus-cli --env prod offer plan  --tenant <slug> --dir $WORK/bundle            # only your rule change
+   plexus-cli --env prod offer apply --allow-prod --tenant <slug> --dir $WORK/bundle --publish
+   ```
+
+## A staff member leaves
+
+A person a rule names — as a row's person or in a „Reihum" pool — cannot leave the staff (`users remove`, `users unset-group`,
+`users delete`), leave a team whose slot names them, and a team a rule has a slot
+for cannot be deleted — refused (`[CONFLICT] [assignment/ruleReferences] …`), naming offer
+(label + status), slot and row. The check reads every `wip` and published offer
+version (archived ones only run pinned test starts, which fail loud instead). Order:
+
+1. Workflow editor → „Team-Verantwortliche" → „Person ersetzen": pick the leaving
+   person and the successor; the preview shows exactly the rows that change (in a
+   pool the successor takes their place; one already in the pool is not doubled).
+2. Publish the workflow — for every offer the refusal named (the draft counts too).
+3. Only then remove the group membership:
+
+   ```bash
+   plexus-cli --env staging --tenant <slug> users unset-group ada@example.com --group sekretariat \
+     --replace-with <successorConfigKey>
+   ```
+
+   `--replace-with` only hands the person's **active applications** over (required
+   while they are responsible for any); it never rewrites a rule.
+4. Nothing to export or keep elsewhere — the server is the source of truth.
+
+## Verify
+
+- `plexus-cli offer validate --dir <bundle>` is clean; `offer status` shows the
+  change live (see [Release an offer bundle](./publish-offer-bundle.md)).
+- `plexus-cli offer export` of the live offer → `graph.assignmentRules` equals what
+  you meant.
+- In the cockpit, a new application's „Zuständig: …" → „Regel anzeigen" shows one
+  table per slot („Prozesszuständig", „Team …"): rows above the deciding one read
+  „nicht zutreffend", rows below it „übersprungen"; the deciding row itself carries
+  no text label (only its accessible name says it applied).
+
+## Idempotency / gotchas
+
+- **Edit a fresh export, never an older copy.** An older copy (an earlier export,
+  a backup) can be behind the live offer in some places and ahead in
+  others; applying it rolls prod back where it is behind.
+- **A config key like `aufnahme` is a role, not a name.** A school can name its
+  admissions person by such a key; which user carries it may differ per deployment
+  (prod vs. staging). Handing the role over is `Person ersetzen` or a config key
+  move — never a bundle edit.
+- **A person the editor picks is not a config user.** Picking staff created in the
+  admin UI draws them a key (`staff_…`) marked `configKeyOrigin: "rule"`;
+  `config export` leaves such a person out of `foundation.users`. Declaring the key
+  in tenant config later makes them an ordinary config user.
+- **Edits in the editor live only in the DB** until exported — an `offer apply` from
+  an older bundle reverts them.
+- **A new workflow** starts with the process slot „Eingangsweg intern → wer die
+  Bewerbung anlegt; sonst → Person wählen"; a team slot the rule lacks shows
+  „sonst → Team-Queue". Publish refuses until „Person wählen" is replaced.
+- Applications already started keep the rule of the version they are pinned to —
+  a published change reaches only new applications.
+- **The bundle is canonical JSON (keys sorted).** When you edit `workflow.json` by
+  hand or by script, keep that shape — a re-serialised file differs from a fresh
+  export far from your edit — and check the result with `offer validate` and
+  `offer plan` (only your rule change should show).
+
+## Related
+
+- [Release an offer bundle](./publish-offer-bundle.md) — publishing and checking it went live.
+- [Edit a live tenant's offer](./edit-live-tenant-offer.md) — export, plan, apply.
+- `plexus-cli assignment simulate --help` — the test bench's flags.

package/dist/skill/references/offer/attach-form-to-workflow.md

@@ -0,0 +1,79 @@
+# Attach a SmartForm to a workflow form node
+
+**When to use:** an offer's workflow needs a `form` step — bind an existing
+SmartForm to a new form node, or scaffold a brand-new form and bind it in one
+step. Replaces hand-editing `workflow.json` + `bundle.yaml` + `smartforms/<slug>.json`
+in lockstep.
+
+## Prerequisites
+- A bundle on disk (`offer init` / `offer export`). Authoring is **offline**;
+  only `offer apply --publish` is online (needs `--env` + an API token).
+- An installed, current `plexus-cli` (`plexus-cli --help`).
+
+## Steps
+```bash
+# A. Bind an EXISTING form (created earlier with `offer form add`).
+plexus-cli offer workflow node add --dir <bundle> \
+  --type form --form <form-slug> --label "<Step label>" --label-en "<English step label>" --after <nodeId>
+
+# B. Scaffold a NEW form AND bind it, in one command.
+#    --form is the new form's slug; --label is the node + form label.
+plexus-cli offer workflow node add --dir <bundle> \
+  --type form --new-form --form zusatzformular --label "Zusatzangaben" --label-en "Additional details" --after approval
+
+# C. CONTINUE the instance an earlier form node created (a second step of the same
+#    form, e.g. the Grundschule's `formZusage` after the Zusage): no --form; the node
+#    names the instance it continues (single quotes — the shell expands $).
+plexus-cli offer workflow node add --dir <bundle> \
+  --type form --id formZusage --label "Angaben nach der Zusage" --label-en "Details after the offer" \
+  --after setFlagZusage --adopt-form '$node.form.admission'
+
+# Then fill the (new) form out — see Author a SmartForm as code.
+plexus-cli offer form field add --dir <bundle> --form zusatzformular \
+  --section section.allgemein --key zusatz.notiz --type string --label "Notiz"
+
+# Validate offline against the real publish gate, then publish.
+plexus-cli offer validate --dir <bundle>
+plexus-cli --env <env> --tenant test offer apply --publish --dir <bundle>
+```
+
+The form node is written with `inputs.smartForm = { kind: "literal", value: <slug> }`,
+a default `standard` outcome, and the SmartForm lifecycle progress states
+(`started` / `submitted`) materialised into the process board + wiring automatically.
+The outcome only routes: later nodes read the answers at the node's address,
+`$node.<formNode>.admission.<field>` (see [Name what a node reads](./addresses.md)).
+An adopting node (C) produces nothing: the instance stays its creator's, so every later
+node still reads `$node.<creator>.admission.…`.
+
+## Verify
+```bash
+plexus-cli offer workflow show --dir <bundle>     # the form node + routing appear
+plexus-cli offer form list --dir <bundle>         # the bound form shows bound=yes
+plexus-cli offer validate --dir <bundle>          # "local validation clean"
+```
+
+## Idempotency / gotchas
+- **`--type form` requires `--form <slug>`** — bind target (existing) or new slug
+  (with `--new-form`) — or `--adopt-form '<instance address>'` (never both). Without
+  either, the command fails loud. A bare `--adopt-form form` is refused with the
+  addresses visible at the node; an adopting node pointing at a non-creating form is
+  `[address/notFormInstance]`.
+- **`--new-form` fails if the slug already exists** (no silent overwrite) and is
+  only valid with `--type form`.
+- **Binding a non-existent form fails loud** (`no smartform "<slug>"`) — create it
+  with `offer form add` first, or use `--new-form`.
+- **A scaffolded form starts empty** (one section, default outcome). Add fields
+  with `offer form field add` before publishing anything user-facing.
+- **Publish pins the form version.** `offer apply --publish` publishes the
+  smartform(s) *then* the workflow, so the workflow pins the just-published version.
+  Re-publishing the whole bundle after a form edit re-pins it; a standalone form
+  publish would leave the workflow on the old version.
+- **`offer workflow node rm`** of the form node leaves the form carried-but-unbound
+  (a warning); remove the form too with `offer form rm` if it's no longer needed. It is
+  refused while any address still names the node (`$node.<formNode>.admission…` in a
+  binding, `reads`, `requires`, a task, `target`, `adoptForm`) — the refusal lists them.
+
+## Related
+- [Add a workflow node](./add-workflow-node.md) — other node types + splice rules.
+- [Author a SmartForm as code](./author-smartform.md) — build the form's contents.
+- `plexus-cli offer --help` — the full `offer …` command reference.

package/dist/skill/references/offer/author-form-scenarios.md

@@ -0,0 +1,97 @@
+# Author a form's test scenarios and environment variables
+
+**When to use:** give a SmartForm one-click test-mode prefills (`testScenarios`) or let
+its expressions read where the form is filled in (`env`: `$env.stage.key`, …) —
+without hand-editing the form JSON. `$env` is the ONE root for a fact about the
+application; the graph and the assignment rules read the same variables.
+
+## Prerequisites
+- An offer bundle on disk carrying the form (`offer export …` / `offer init …`).
+- Fully offline; every command runs the publish gate on the result and writes nothing
+  when it fails.
+
+## Steps
+```bash
+# A scenario: id (kebab-case), label, prefill. Values are typed by the FIELD:
+# boolean true|false, a multi-select enum a,b, everything else a string.
+plexus-cli offer form scenario add --dir <bundle> --id standard --label "Standardfall" \
+  --label-en "Standard case" \
+  --prefill kind.vorname=Anna --prefill kind.nachname=Muster --prefill agb=true
+
+# Addresses and repeated rows do not fit key=value — give the whole prefill as JSON:
+plexus-cli offer form scenario add --dir <bundle> --id geschwister --label "Mit Geschwistern" --label-en "With siblings" \
+  --prefill-json '{"kind.vorname":"Anna","geschwister":[{"name":"Ben"}]}'
+
+# A variant of an existing scenario: --from copies its prefill and environment sample,
+# --prefill overrides single keys (e.g. „Gemeinsames Sorgerecht“ + reduced-fee request).
+plexus-cli offer form scenario add --dir <bundle> --id joint-reduced-fee --from joint \
+  --label "Gemeinsames Sorgerecht mit Gebührenreduzierung" --label-en "Joint custody with reduced fee" \
+  --prefill elternteil_1.financialAid=true
+
+# Edit: --prefill MERGES, --prefill-json REPLACES, --unset removes keys.
+plexus-cli offer form scenario set --dir <bundle> --id standard --prefill kind.vorname=Lea --unset agb
+plexus-cli offer form scenario rm  --dir <bundle> --id geschwister
+
+# Environment: declare the keys the form reads AND sample them for every scenario in ONE
+# step (the gate refuses a declared key a scenario does not sample, and a sample of an
+# undeclared key — so the two cannot be done one after the other).
+plexus-cli offer form env set --dir <bundle> --keys stage \
+  --sample 'standard={"stage":{"key":"klasse-1","name":"Klasse 1","gradeLevel":1}}'
+
+# The applicant's language and the intake channel are ONE key, `applicant`:
+plexus-cli offer form env set --dir <bundle> --keys stage,applicant \
+  --sample 'standard={"stage":{"key":"klasse-1","name":"Klasse 1","gradeLevel":1},"applicant":{"language":"de","channel":"self-service"}}'
+
+# Remove the declaration (the scenarios' samples of dropped keys go with it):
+plexus-cli offer form env set --dir <bundle> --keys ""
+```
+
+Environment keys: `offer`, `unit`, `stage`, `run`, `applicant` — the one vocabulary,
+listed with labels in the IDE tab „Umgebungsvariablen".
+A sample carries every field of its key (`stage` = `key`, `name`, `gradeLevel`;
+`applicant` = `language`, `channel`), an empty one as `null`. `stage.key` is the
+BUNDLE key (`program.stages[].key`).
+
+**No fallback.** `$env.applicant.language` is EMPTY (`null`) for an application
+without an applicant account (started by staff); `$env.stage.gradeLevel` and
+`$env.run.startDate` can be empty too. `==` is false over null and needs nothing; `!=`
+and `!` are TRUE over null, so the gate refuses them without a guard
+(`[env/unguardedNullable]`) — write what an empty value means:
+`$env.applicant.language != null && $env.applicant.language != 'de'`. The names
+(`offer.title`, `unit.name`, `stage.name`, `run.name`) are in the applicant's language,
+German without an applicant account (declared at the variable).
+
+## Verify
+```bash
+plexus-cli offer validate --dir <bundle>     # scenarios are submitted through the real submit gate
+plexus-cli offer form show --dir <bundle>
+```
+
+After publishing, run a scenario on a test application from the terminal:
+`plexus-cli --env staging --tenant <t> test-actions run --application <id> --action load-scenario:<scenarioId>`
+— see [Drive a test application through test mode](../test-actions/drive-a-test-application.md).
+
+## Idempotency / gotchas
+- A scenario that leaves a visible required field empty, or reaches no outcome, is
+  refused (`scenario.required-field-unfilled` / `scenario.no-outcome`). docRef fields are
+  never prefilled — test mode stubs files itself.
+- A bundle exported before `$env` replaced `context` carries `context` (declaration and samples) and
+  `$ctx.*` expressions: refused (`[env/retiredField]`, unknown identifier). Export
+  again — the stored definitions on the server already use `$env`.
+- `--from` copies prefill and environment sample, not the base's description (it describes the base);
+  `--from` with `--prefill-json` is refused — that would discard the copy. The copy is a
+  snapshot: a later change to the base does not reach the variant.
+- File fields need no prefill: with „Automatisch absenden“ (default on) loading a scenario
+  fills every docRef field of the form's sections and groups with an openable stub file
+  (named after the field, of a type the field accepts) and then submits — also the fields
+  the scenario only makes visible (income proofs behind `financialAid=true`). The fill runs
+  as a scheduled action, so the submit lands a moment later. Without auto-submit, run the
+  test action „File-Felder mit Dummy füllen“ (`auto-fill-files`) yourself. A docRef inside
+  a repeated block is not filled.
+- `--prefill` names an unknown key → refused; so does a docRef or an address key (use
+  `--prefill-json` for the address).
+- Label and description need their English in the same call (`--label-en`,
+  `--description-en`); see [Edit a SmartForm in depth](./edit-smartform.md) → English texts.
+
+## Related
+- [Author a SmartForm as code](./author-smartform.md) · [Edit a SmartForm in depth](./edit-smartform.md)