@smartkomm/plexus-cli 0.0.0-stage → 0.1.0

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.

package/dist/skill/references/offer/publish-offer-bundle.md

@@ -0,0 +1,117 @@
+# Release an offer bundle — and check that it actually went live
+
+**Use it to** take an edited bundle live on a tenant, stage it for testing first,
+or find out why a change you applied is not visible to applicants.
+
+## The model in one paragraph
+
+An offer family is one ascending version stream. Exactly one generation is
+**editable** (the draft, always the newest revision); at most one is **live**
+(what real applicants run); at most one sits between them as the **internal
+candidate** (testable, not public). Applying a bundle writes into the *draft*.
+Publishing freezes the draft and spawns a fresh one. Applications already running
+keep the generation they started on — forever, unless migrated explicitly.
+
+So there are two different questions, and they have different answers:
+
+| Question | Answered by |
+|---|---|
+| What would `offer apply` write into the draft? | `offer plan` / `offer diff` per-target rows |
+| Is anything waiting to go live? | the `publish` row of `plan`/`diff`, and `offer status` |
+
+## Check before you publish
+
+```bash
+plexus-cli --env staging offer status --tenant <slug> --slug <offer-key>
+```
+
+```
+field      value
+─────────  ───────────────────────────────
+manifest   published
+workflow   bound
+pedagogy   Grundschule Beispielstadt
+draft      v12
+internal   -
+live       v11
+publish    PENDING (draft is ahead of live)
+```
+
+`publish: PENDING` means the draft says something the live generation does not —
+regardless of whether *your* bundle changed anything. That is the state you are
+in after an `offer apply` without `--publish`, or after someone saved in the
+Workflow IDE.
+
+## Publish
+
+```bash
+# Go live (default).
+plexus-cli --env staging offer apply --tenant <slug> --dir ./bundle --publish
+
+# Or stage as the testable candidate only — real applicants keep the live
+# generation; a Testmodus application can be started against this one.
+plexus-cli --env staging offer apply --tenant <slug> --dir ./bundle --publish --stage internal
+```
+
+The final step of the report names what happened:
+
+```
+step                  action      detail
+────────────────────  ──────────  ──────
+manifest              unchanged
+smartform:anmeldung   unchanged
+workflow              created
+offer                 published
+```
+
+- `offer: published` — a new generation went live. With the detail *"promoted the
+  tested candidate"* it released the generation you staged with `--stage internal`
+  rather than cutting a fresh copy of it, so what goes live is what you tested.
+- `offer: already-live` — the draft already equalled the live generation. Nothing
+  was flipped, and that is correct.
+- `offer:internal: …` — the same two outcomes for `--stage internal`.
+
+## Verify
+
+```bash
+plexus-cli --env staging offer status --tenant <slug> --slug <offer-key>
+```
+
+`live` must have moved to the draft's old revision and `publish` must read
+`up to date`. In the app, the Workflow IDE's version picker shows the new
+generation as **Aktuell**, and the one below it as **Vorgänger**.
+
+## Gotchas
+
+- **`--publish` publishes on the distance to the LIVE head, not to your file.**
+  Applying a bundle that matches the draft byte-for-byte still publishes when the
+  draft is ahead of live. This is deliberate: the older behaviour compared the
+  bundle against the draft, so a second run with `--publish` reported `unchanged`
+  everywhere and silently released nothing.
+- **The form and workflow publish gates run only when something is released**,
+  and always before the flip — so a draft edited in the IDE is validated and
+  finalized before it is frozen, and an apply that releases nothing validates
+  nothing. A validation error aborts before any generation changes.
+- **`--stage internal` discards an existing internal candidate** (it is archived).
+  That candidate never went live, so nothing an applicant sees changes.
+- **Stage then release is two commands, not two generations.** `--stage internal`
+  followed by a plain `--publish` of the same bundle promotes the staged
+  generation in place. It does not archive it and release a copy.
+- **Running applications are not migrated.** After a release, older applications
+  keep their generation and appear in the board's amber *Veraltete
+  Workflow-Version* section when their board layout differs.
+- **`offer plan` is read-only and now carries a `publish` row too** — use it to
+  see a pending release without applying anything.
+- **`offer plan` shows program stages as `~stage` / `+stage` / `-stage`** —
+  `apply` reconciles `program.stages` by bundle `key`, not by name (see
+  `../config/rename-program-stage.md`). Run `offer plan` before the first apply
+  on an env: a `-stage` row archives that level, and apply refuses it with
+  `[stage/hasActiveApplications]` while an active application sits on it.
+  **Runs** are still matched by display name and only ever added: a renamed run
+  becomes a second run.
+
+## Related
+
+- [Author a SmartForm as code](./author-smartform.md), [Add a workflow node](./add-workflow-node.md)
+- [Manage a contract resolver](../resolver/manage-contract-resolver.md) — the
+  apply → assign → publish order

package/dist/skill/references/offer/set-offer-capacities.md

@@ -0,0 +1,78 @@
+# Set an offer's seat capacities in its bundle
+
+**When to use:** an offer's Schuljahr × Klassenstufe grid (seats per cohort, open or
+closed) should travel with the bundle — a fresh environment gets the whole grid from one
+`offer apply` instead of one `offer capacity set` per cell.
+
+## Prerequisites
+- An offer bundle on disk (`offer export …`) whose `bundle.yaml` has a `program` block.
+- A token with the tenant's offer-configuration rights (a tenant admin has them) for `offer plan` / `offer apply` on the target env.
+- The stage and run keys of the offer (`program.stages[].key`, `program.runs[].key`) —
+  cells sit under a run (by its **bare** key) and are keyed by the **bare** stage key,
+  never by a name (names are `{ de, en }` display text).
+
+## Steps
+
+Each run lists its cells under `capacities`, keyed by stage key:
+
+```yaml
+program:
+  unitKey: primary
+  stages:
+    - { key: grade-1, name: { de: Klassenstufe 1, en: Grade 1 }, gradeLevel: 1 }
+    - { key: grade-2, name: { de: Klassenstufe 2, en: Grade 2 }, gradeLevel: 2 }
+  runs:
+    - key: "2026-27"
+      name: { de: Schuljahr 2026/27, en: School year 2026/27 }
+      startDate: '2026-08-01'
+      endDate: '2027-07-31'
+      capacities:
+        grade-1: { isOpen: true, capacity: 24 }          # 24 seats, accepting
+        grade-2: { isOpen: true, capacity: unlimited }   # no cap
+        # grade-3: { isOpen: false, capacity: null }     # null = unconfigured (clears a stored one)
+```
+
+```bash
+plexus-cli offer validate --dir <bundle>                      # offline: shape + stage keys
+plexus-cli --env <env> offer plan  --dir <bundle>             # one `~cap run×stage from → to` row per changed cell
+plexus-cli --env <env> offer apply --dir <bundle>             # writes exactly those cells
+```
+
+The fastest way to get the block right is to let the live offer write it:
+`plexus-cli --env <env> offer export --slug <offer> --out <bundle>` emits every run with
+all its cells.
+
+## Verify
+```bash
+plexus-cli --env <env> offer plan --dir <bundle>    # no `cap:` rows left = the grid matches
+plexus-cli --env <env> offer show --slug <offer>    # the live grid
+```
+
+## Idempotency / gotchas
+- **A listed cell is authoritative** — both `isOpen` and `capacity`, every apply;
+  `capacity: null` clears a stored capacity. A cell the bundle does **not** list is left
+  alone. A re-apply of an unchanged bundle writes nothing.
+- `capacity` is a whole number ≥ 0, `unlimited`, or `null`. **Unconfigured is not
+  unlimited:** an application to an open cell with `null` fails loud.
+- A run with `capacities` must not also carry a run-level `isOpen` (validation error):
+  the open state lives on each cell. A NEW run with `capacities` is created closed and
+  then opened cell by cell. A run **without** `capacities` keeps the old behaviour — its
+  `isOpen` (default open) seeds every cell of a newly created run, and existing cells
+  are untouched.
+- **Closing an existing Schuljahr = `isOpen: false` on each of its cells.** A run-level
+  `isOpen: false` on an existing run changes nothing and plans no row — a Schuljahr
+  "closed" that way stays open; the real close shows one `~cap … open → closed` row per
+  cell in the plan.
+- For a real tenant the bundle on disk is a fresh `--env prod` export in a scratch dir,
+  never a stale or version-controlled copy — see
+  [edit-live-tenant-offer](./edit-live-tenant-offer.md).
+- A cell naming a stage key that neither `program.stages` nor the live program has is
+  refused before anything is written (`[capacity/unknownStage]`). A stage the same bundle
+  adds plans as `(new)` and is written after the stage exists.
+- `offer run add --capacity` / `offer capacity set` still exist for one-off edits; the
+  next `offer apply` of a bundle that lists the cell sets it back. `offer capacity set
+  --capacity unlimited` is accepted.
+
+## Related
+- [Rename / remove a program stage](../config/rename-program-stage.md) — the stage keys cells use.
+- [Release an offer bundle](./publish-offer-bundle.md).

package/dist/skill/references/offer/staff-input-if-node.md

@@ -0,0 +1,112 @@
+# Branch on a staff input („Eingabe" + `if` node)
+
+**When to use:** the process should take a different path depending on something only
+staff know when they start the application — e.g. a staff member's own child
+(„Mitarbeiterbewerbung") skips the review and goes straight to the fee. Two
+pieces: a **staff input** declared on the workflow (`graph.staffInputs`, a checkbox
+staff tick in „+ Bewerbung"), and an **`if` node** whose condition reads it as
+`$env.staffInput.<key>` and routes `true` / `false`. A family never sets a staff input:
+a self-service start records every declared input as `false`.
+
+In the workflow IDE the same declaration is the header button „Eingaben" (add an
+input with its key, relabel, remove; the key is fixed once set), and the `if` node is a
+diamond reading „if <pill>": the flow enters on the left, `true` leaves at the top,
+`false` at the bottom.
+
+## Prerequisites
+- A bundle on disk (`offer export`, a live tenant's only into a private scratch dir —
+  [Edit a live tenant's offer](./edit-live-tenant-offer.md)). Authoring is offline.
+- The node ids around the branch point: `plexus-cli offer workflow node list --dir <dir>`
+  (here: `form` routes `standard` → `review`, and the fee node is `fee`).
+- A key: one identifier segment, lower-case first letter, letters and digits only
+  (`staffApplication`, not `staff-application`) — it is read as `$env.staffInput.<key>`.
+
+## Rollout order and checks (a live tenant)
+- **Deploy first, publish second.** `if` is a node type of the release: a
+  bundle using it publishes only on a deployment that registers it
+  (`[graph/unknownNodeType]` otherwise; the deploy needs a platform operator).
+- **Running applications stay on their version** — the if node changes the
+  topology, so nobody is re-pinned; an application already past the form keeps
+  its fee step (the waiver „Zahlung überspringen" is the way out for a staff
+  child among them).
+- **The Engage push may read the fee step** (`payment: $node.<fee>.payment`): it
+  passes the gate (`readSkipsAbsentProducer`) and skips the paid fields for a
+  staff child („Zahlungsschritt nicht durchlaufen" in the Übertragungsprotokoll).
+- **Check the assignment rule**: a „+ Bewerbung" start is channel `staff`; a rule
+  row on `$env.applicant.channel == 'staff'` (creator responsible) now applies
+  to every staff child — decide whether that is wanted before publishing.
+- Edit a live tenant's bundle only through [Edit a live tenant's offer](./edit-live-tenant-offer.md)
+  (export into a dated scratch dir, plan, `apply --publish --allow-prod`).
+
+## Steps
+```bash
+# 1. Declare the staff input (type boolean = a checkbox; both label languages required).
+plexus-cli offer workflow staff-input set staffApplication --dir <dir> \
+  --label "Mitarbeiterbewerbung" --label-en "Staff application"
+plexus-cli offer workflow staff-input list --dir <dir>
+
+# 2. Put an if node on the form's edge. `true` (a staff child) goes straight to
+#    the review, `false` to the fee — name both to be explicit.
+plexus-cli offer workflow node add --dir <dir> --type if \
+  --id staffCheck --label "Mitarbeiterbewerbung?" --label-en "Staff application?" \
+  --on-edge form:standard \
+  --condition '$env.staffInput.staffApplication' \
+  --outcomes true:review,false:fee
+
+#    Later: change the condition or re-route an outcome in place.
+plexus-cli offer workflow node set --dir <dir> --id staffCheck --condition '!$env.staffInput.staffApplication'
+plexus-cli offer workflow node set --dir <dir> --id staffCheck --outcomes true:review,false:fee
+
+# 3. Validate, plan, publish.
+plexus-cli offer validate --dir <dir>
+plexus-cli --env staging --tenant <t> offer plan --dir <dir>
+plexus-cli --env staging --tenant <t> offer apply --publish --dir <dir>
+```
+
+## Verify
+```bash
+plexus-cli offer workflow node list --dir <dir>
+#   form        form  … standard→staffCheck
+#   staffCheck  if    true, false   true→review, false→fee
+jq '.graph.staffInputs, (.graph.nodes[] | select(.type=="if"))' <dir>/workflow.json
+
+# After publish: start one test application per answer and see where each stands.
+E="--env staging --tenant <t>"
+plexus-cli $E applications start-test --offer <offer> --run <run> --stage <stage> \
+  --applicant test@example.com --staff-input staffApplication=true
+plexus-cli $E applications show <id>      # after the form: review (true) / fee (false)
+plexus-cli $E applications store <id>     # $env.staffInput.staffApplication = true
+```
+In the cockpit, „+ Bewerbung" on this offer now shows the checkbox „Mitarbeiterbewerbung".
+
+## Idempotency / gotchas
+- **Every staff start sets every declared input.** The cockpit („+ Bewerbung", with or
+  without Stellvertretung), a lead conversion (Interessenten → „In Bewerbung umwandeln")
+  and `applications start-test --staff-input key=true|false` (once per input) are refused
+  with `[staffInput/missingValue]` when one is left out, `[staffInput/unknownKey]` for a key
+  the offer does not declare. A self-service start records each input `false` — there is
+  no applicant-callable way to set one.
+- **Read only by a condition (v1).** A SmartForm, a document binding, a task condition or
+  an assignment rule cannot read `$env.staffInput.*` — `[address/staffInputConditionOnly]`
+  (a form/rule refuses it as an unknown key). Readers: the `if` node's condition, the
+  process-data view, the IDE's „Umgebungsvariablen".
+- **`staff-input set` is idempotent by key:** a second call with the same key relabels in
+  place (`--label-en` alone re-translates; `--label` alone is refused while it would leave a
+  stale English). `staff-input remove <key>` fails loud on an unknown key, and is refused by
+  the gate (`[if/condition]`) while a condition still reads the input.
+- **Publish rules:** `[staffInput/keyFormat]`, `[staffInput/duplicateKey]`,
+  `[staffInput/unknownType]` (only `boolean`), `[i18n/missingTranslation]` (label without a
+  language), `[if/condition]` (no / unparsable condition, or one naming an undeclared input
+  or an unknown `$env` leaf), `[if/unroutedOutcome]` (`true` or `false` goes nowhere),
+  `[address/envCohortBound]` (a condition on stage/run is refused).
+- **The `if` node never parks** and brings no board column; it decides once, on entry.
+  `--condition` is required and never defaulted; it is refused on any other node type.
+- **Running applications keep their version:** the inputs and the branch apply to
+  applications started on the newly published version; already-started ones have the
+  inputs of the version they pinned.
+
+## Related
+- [Add a workflow node](./add-workflow-node.md) · [Insert a node on one edge and rewire it](./insert-and-rewire-node.md)
+- [Edit a workflow node](./edit-workflow-node.md) (`node set --outcomes`)
+- [Start a test application](../applications/start-a-test-application.md) (`--staff-input`)
+- [Name what a node reads](./addresses.md) (`$env` vocabulary)