@smartkomm/plexus-cli 0.0.0-stage → 0.1.1

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)

package/dist/skill/references/offer/author-manifest-meta.md

@@ -0,0 +1,94 @@
+# Author the manifest "meta" layer
+
+**When to use:** configure an offer's manifest settings that aren't the form or the
+workflow — the applicant mode, signature level, application window, total capacity,
+cohort-selection strategy, the `roleInstances` (legal roles like Erziehungsberechtigte),
+and the `leistungen` — entirely from the CLI instead of hand-editing `manifest.json`.
+
+## Prerequisites
+- An offer bundle on disk (`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 manifest set --help`).
+
+## Steps
+```bash
+# Top-level settings. Enum values are validated fail-loud (self|proxy|both,
+# wet_ink|FES|QES, immediate|batch, arrival|manual).
+plexus-cli offer manifest set --dir <bundle> \
+  --applicant-mode both --signature-level FES \
+  --window-start 2026-02-01 --window-end 2026-05-31 --capacity 30
+
+# Selection config (FCFS/committee/Stichtag are emergent from these knobs).
+# Set both required knobs the first time.
+plexus-cli offer manifest set --dir <bundle> \
+  --selection-release batch --selection-waitlist-order manual \
+  --selection-auto-promote --selection-deadline 2026-06-01
+
+# roleInstances — legal/contract roles. --custom-role-id binds the tenant custom-role.
+# A role's (and a service's) label is { de, en }: --label AND --label-en on add.
+plexus-cli offer role add --dir <bundle> --key erzb1 --label "Erziehungsberechtigte:r 1" --label-en "Guardian 1" \
+  --custom-role-id role_eb --min 1 --max 2 --legally-relevant --can-sign
+plexus-cli offer role set --dir <bundle> --key erzb1 --max 3 --requires-evidence
+plexus-cli offer role list --dir <bundle>
+
+# leistungen — selectable/assigned services.
+plexus-cli offer leistung add --dir <bundle> --key betreuung --label "Nachmittagsbetreuung" --label-en "Afternoon care" --selectable-by-applicant
+
+# Display order among the unit's offers (lower = first; "" clears). Handle-level
+# property like the title — lives on bundle.yaml, applied via createManifest.
+plexus-cli offer manifest set --dir <bundle> --sort-order 20
+
+# Validate + publish.
+plexus-cli offer validate --dir <bundle>
+plexus-cli --env <env> offer apply --publish --dir <bundle>
+```
+
+## Verify
+```bash
+plexus-cli offer role list --dir <bundle>   # roleInstances reflect the edits
+plexus-cli offer validate --dir <bundle>    # "local validation clean"
+```
+
+## Idempotency / gotchas
+- **Offer title is a BARE name — never embed the run/year or levels.** The offer
+  `label` (set via `offer init/set --title`) is just the program name, e.g.
+  "Grundschule" / "Primary School". The school-year cycle is a separate entity
+  (`program_runs.name`, e.g. "2026/27") and grade levels are `program_stages` — the UI
+  shows runs nested under the offer (internal sidebar) and as a separate dropdown
+  (external portal), so it **never composes** them into the title. Putting
+  "· Aufnahme 2026/27" in the title makes the cycle show twice. Levels/runs are managed
+  with `offer level …` / `offer run …`, not the title.
+- **`--title` (offer label) is the offer-title SoT — `--program-name` is separate.**
+  `offer set --title` (+ `--title-en`) writes the offer title (`offer_versions.label`), the single source the staff Angebote
+  tree, external portal, and applicant "Meine Bewerbungen" all read. The underlying
+  master-data `programs.name` is a *copy* made at authoring time that only shows in the
+  staff master-data admin; it can drift from the label. Use `offer set --program-name
+  "<bare name>" --program-name-en "<English>"` (→ `programAdmin.updateProgram`) to bring a drifted program name back in
+  line — e.g. after fixing a label that had been authored with a run/year baked in. You
+  almost never need `--program-name`; reach for it only to clean up master-data drift.
+- **`--sort-order` orders offers within a unit** (lower = first); the sibling unit
+  order is set as code via tenant config (`TenantConfigUnitDefinition.sortOrder`). Both
+  apply to the internal Angebote sidebar AND the external `/e` portal; offers/units
+  without a sortOrder fall back to creation-time / alphabetical respectively.
+- **Validate-before-write.** Every mutator runs the real publish gate first; on any
+  error it writes **nothing**.
+- **Enum values are checked client-side, fail-loud.** The manifest publish gate
+  (`validateManifestBlob`) enforces required fields + roleInstances/leistungen *structure*
+  (unique keys, customRoleId, cardinality) but NOT the enum *values* of
+  applicantMode/signatureLevel/selection — so the CLI validates those at the boundary.
+- **`customRoleId` resolution is server-side.** The CLI authors the binding; whether
+  `--custom-role-id` resolves to a real tenant custom-role is checked at runtime, not
+  offline (the bundle has no tenant role catalog).
+- **No graph↔role cross-check.** The static graph carries no reference to a
+  `roleInstance.key` (those are referenced only by runtime persons; approval approvers
+  reference tenant permission *groups*, validated server-side) — so there is nothing
+  offline to cross-validate beyond the structure the manifest gate already enforces.
+- **`manifest set` is additive per-flag.** Pass only the flags you want to change;
+  selection needs both `--selection-release` and `--selection-waitlist-order` present
+  the first time so a half-config is never written.
+
+## Related
+- [Author a SmartForm as code](./author-smartform.md) · [Edit a workflow node](./edit-workflow-node.md).
+- Command reference: `plexus-cli offer manifest --help`, `plexus-cli offer role --help`, `plexus-cli offer leistung --help`.

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

@@ -0,0 +1,102 @@
+# Author a SmartForm as code
+
+**When to use:** build or change a customer's application form (sections, fields,
+validation/visibility rules, outcomes) entirely from the CLI — then publish a new
+version — without hand-editing `smartforms/<slug>.json`.
+
+## Prerequisites
+- An offer bundle on disk (`offer init …` or `offer export …`).
+- **Authoring is fully offline** — no deployment, no auth. `offer apply --publish`
+  (the publish step) needs an API token of a user who may configure the tenant's offers
+  (a tenant admin — see [Add a tenant admin](../users/add-tenant-admin.md)).
+- An installed, current `plexus-cli` (`plexus-cli offer form --help`).
+
+## Steps
+```bash
+# 0. (If the bundle has no form yet, or you want a second form) scaffold one.
+#    A new form starts with one empty section + a default `standard` outcome.
+plexus-cli offer form add --dir <bundle> --key <form-slug> --label "<Label>" --label-en "<English>"
+
+# 1. Add sections (nest with --parent; gate with --visible-if).
+plexus-cli offer form section add --dir <bundle> [--form <slug>] \
+  --id section.kind --label "Kind" --label-en "Child" [--visible-if "<expr>"]
+
+# 2. Add fields. Types: string|boolean|date|enum|email|tel|address|docRef.
+#    enum options come from exactly ONE source (mutually exclusive):
+#      --enum a,b,c            inline options
+#      --enum-ref <catalog>    static central catalog (konfession, geschlecht, …)
+#      --enum-list-key <list>  tenant custom_field_lists key (runtime-resolved;
+#                              central management — nationalities, languages,
+#                              countries, …). Add --multiple for multi-select.
+plexus-cli offer form field add --dir <bundle> [--form <slug>] \
+  --section section.kind --key kind.vorname --type string --required --bucket kind --label "Vorname" --label-en "First name"
+plexus-cli offer form field add --dir <bundle> --section section.kind \
+  --key kind.geschlecht --type enum --enum-list-key gender --label "Geschlecht" --label-en "Gender"
+plexus-cli offer form field add --dir <bundle> --section section.kind \
+  --key kind.nationalitaeten --type enum --enum-list-key nationalities --multiple --label "Staatsangehörigkeit(en)" --label-en "Nationality(ies)"
+# NB: --enum-list-key requires the list to exist on the tenant BEFORE publish
+#     (config apply the list first) — else the publish gate throws form.unknown-enum-list.
+
+# 3. Attach validation / visibility rules to a field.
+#    "Dieses Feld soll Pflicht sein, wenn …" → --required-if.
+#    "Dieses Feld soll sich ändern"           → --visible-if / --disabled-if.
+plexus-cli offer form field set --dir <bundle> --key kind.nachweis \
+  --required-if "kind.vorname != null"
+
+# 4. Add outcomes (the branch the form emits to the workflow).
+plexus-cli offer form outcome add --dir <bundle> --id sonderfall \
+  --when "kind.konfession == 'sonstige'" --fields kind.vorname
+
+# 4b. (Full depth) effects, repeated (arrays-of-records), and computed fields.
+#     person/organization/relationship/fieldMap materialize parties + links.
+plexus-cli offer form effect add --dir <bundle> --id p.kind --kind person \
+  --bucket kind --policy auto-on-any-write --name-from "kind.vorname,kind.nachname" --role applicant
+plexus-cli offer form repeated add --dir <bundle> --section section.kind \
+  --key geschwister --item-fields "name:string,alter:string" --min 0 --max 5
+plexus-cli offer form computed add --dir <bundle> --section section.kind \
+  --key kind.hasName --expression "kind.vorname != null"
+
+# 5. Validate offline against the REAL publish gate, then publish a new version.
+plexus-cli offer validate --dir <bundle>
+plexus-cli --env <env> offer apply --publish --dir <bundle>
+```
+
+`--form` is optional when the bundle carries exactly one form; with several forms
+it is required (the CLI fails loud listing the choices).
+
+## Verify
+```bash
+plexus-cli offer form list --dir <bundle>            # forms + field/outcome counts + bound?
+plexus-cli offer form show --dir <bundle> --form <s> # per-field type/required/flags
+plexus-cli offer validate --dir <bundle>             # "local validation clean"
+```
+
+## Idempotency / gotchas
+- **Every mutator validates before writing.** On any publish-gate error (or a
+  malformed `--visible-if`/`--when` expression) the command writes **nothing** and
+  prints the issues — the bundle is never left half-edited.
+- **Field-key stability (publish invariant).** `publishSmartForm` lets you **add**
+  fields across versions but **refuses to remove** a field key that a prior published
+  version had. `offer form field rm` / `section rm` warn about this — a later
+  `apply --publish` over an already-published form will be rejected by the server.
+- **Re-publishing = new version.** Each `offer apply --publish` with a changed form
+  definition creates a new `smart_form_versions` row (never edits in place).
+- **Workflows pin the form version.** A published workflow is pinned to the form
+  version that was current at *workflow*-publish time (`smartFormPins`). A new form
+  version does **not** propagate automatically — the workflow must be re-published.
+  `offer apply --publish` over the **whole bundle** re-publishes the workflow too, so
+  the full-bundle path picks up the new form; a standalone form publish would leave
+  existing workflows on the old version.
+- **Effects / repeated / computed fields** are CLI-authorable (`offer form effect|repeated|computed`).
+  The offline gate checks structure + refs + effect-graph + `nameFrom`/`fieldMap.from`
+  resolution; the **catalog-dependent** checks (effect `role` → tenant role, `relKind` →
+  relationship field, fieldMap `to` → custom field) run **server-side** at `apply --publish`
+  and fail loud there if the tenant catalog doesn't have them.
+- An unbound form (no workflow form node binds it yet) is a **warning**, not an error
+  — bind it with `offer workflow node add --type form --form <slug>`.
+
+## Related
+- [Attach a form to a workflow](./attach-form-to-workflow.md) — bind the form to a workflow
+  form node (`offer workflow node add --type form`).
+- [Add a tenant admin](../users/add-tenant-admin.md) — the token `offer apply --publish` needs.
+- Command reference: `plexus-cli offer form --help`.

package/dist/skill/references/offer/bind-node-input.md

@@ -0,0 +1,76 @@
+# Bind a node input to an address (form field, task value, derived price, applicant language)
+
+**When to use:** a node's input slot must read a value produced elsewhere — the applicant's
+language for a template letter (`$env.applicant.language`), the tuition a rule set derives
+(`$derived.schulgeld`), a value a task records (`$task.reducedFee.reducedFee`), a form field
+(`$node.form.admission.kind.vorname`) — or carry a fixed value, or go back to its default.
+Replaces hand edits of `inputs` in the bundle's `workflow.json`.
+
+## Prerequisites
+- An offer bundle on disk (`offer export --slug <slug> --out <dir>`). Fully offline: the command
+  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]`: a binding with `path`, `wires`)
+  — export it again.
+- The input is a **slot** the node declares. For a template document (`production: 'template'`)
+  the slots are its `template.fields` — add the field first (bundle or workflow IDE), then bind.
+  `offer workflow node list --dir <dir>` shows the nodes; an unknown slot is refused with the
+  node's slots.
+- The **address** names its producer, which must run on every path before the node — the model
+  and the spelling: [Name what a node reads](./addresses.md). Quote it with single quotes.
+
+## Steps
+```bash
+# The offer letter in the applicant's language (demo tenant `test`: platzangebot, field `sprache`):
+plexus-cli offer workflow node set-input --dir <dir> --node platzangebot --input sprache \
+  --address '$env.applicant.language'
+
+# Tuition: the derived price (sibling discount, then the reduction `reducedFee` records):
+plexus-cli offer workflow node set-input --dir <dir> --node contract --input schulgeld \
+  --address '$derived.schulgeld'
+
+# A form field — full address, or the short form that composes the same address:
+plexus-cli offer workflow node set-input --dir <dir> --node contract --input startDate \
+  --address '$node.form.admission.kind.einschulung'
+plexus-cli offer workflow node set-input --dir <dir> --node contract --input startDate \
+  --from form --field kind.einschulung
+
+# A fixed value (JSON: a text needs its quotes):
+plexus-cli offer workflow node set-input --dir <dir> --node platzangebot --input sprache --literal '"de"'
+
+# Back to the slot's default:
+plexus-cli offer workflow node set-input --dir <dir> --node platzangebot --input sprache --clear
+```
+
+The command prints the cell before and after (`binding $env.applicant.language`, `literal "de"`,
+`— (default)`).
+
+## Verify
+```bash
+plexus-cli offer validate --dir <dir>
+plexus-cli offer workflow node reads --dir <dir> --node contract    # the binding is listed, origin „geschrieben"
+plexus-cli --env staging --tenant <t> offer plan --dir <dir>   # expect: ~ workflow
+```
+
+## Idempotency / gotchas
+- Exactly one of `--address`, `--from`+`--field`, `--literal`, `--clear`. A bare key
+  (`--address applicant.language`, `--address schulgeld`) is refused with the addresses visible at
+  the node — there is no default source and no guessing.
+- A literal is JSON: `"de"`, `3`, `true`, `null`, or a priced item `{"itemKey":…,"grantKeys":[…]}`
+  — and must fit the slot's value type: an option field takes one
+  of its options, a party slot (a roleAssign's `person`) only a binding. This check runs in the
+  verb; the publish gate does not (yet) check literals against their slot type.
+- An end node's outcome cells are set with `offer workflow node set --outcome|--terminal-status|--termination-kind`.
+- `--clear` also removes a cell no slot declares (a dead cell from an old edit).
+- The gate decides whether the address can be read here, before writing: `[address/unknownOwner]`,
+  `[address/unknownKey]`, `[address/pathNotInTarget]` (the form has no such field / the stored value no
+  such leaf), `[address/notVisible]` (the producer does not run on every path before the node),
+  `[address/typeMismatch]` (the value does not fit the slot), `[governedDocument/envNotCovered]`
+  (a language field needs an option per language `$env.applicant.language` can deliver), the
+  uncovered-input contract. An error the bundle already had is named as „vorbestehend" and does
+  not block this edit.
+- Re-running with the same value rewrites the same cell (no change).
+- Nothing reaches a live process until `offer apply --publish`.
+
+## Related
+- [Name what a node reads](./addresses.md) · [Generate a letter from a Word template](./template-document-node.md)
+- [Declare what a document node reads](./declare-node-reads.md) · [Edit a live tenant's offer](./edit-live-tenant-offer.md)