@smartkomm/plexus-cli 0.0.0-stage → 0.1.1

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)

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

@@ -0,0 +1,69 @@
+# Make a task close with an appointment („Termin vereinbaren")
+
+**Use it to** turn a workflow-step task such as „Termin für das Kennenlerngespräch
+vereinbaren" into one that is completed by entering an appointment: date,
+time, duration, place and host. Completing it books the appointment at the
+application, mails the family (portal owner) date/time/place with a `termin.ics`
+calendar file, frees the task it
+`blocks`, and lists the appointment under „Anstehende Termine" on the staff dashboard.
+
+## The declaration
+
+On the task (a composed `kind: "task"` in the node's `tasks`):
+
+```json
+{
+  "key": "termin",
+  "kind": "task",
+  "title": { "de": "Termin für das Kennenlerngespräch vereinbaren", "en": "…" },
+  "assign": { "group": "schulverwaltung" },
+  "blocks": { "templateKey": "gespraech" },
+  "result": {
+    "kind": "appointment",
+    "title": { "de": "Kennenlerngespräch", "en": "Introductory talk" },
+    "durationMinutes": 45
+  }
+}
+```
+
+- `result.title` is the **neutral** title the family's letter and every calendar file
+  carry — never a family name.
+- `durationMinutes` (5–480) prefills the dialog; staff may change it per appointment.
+- Publish refuses: an unknown `kind` (`[taskResult/unknownKind]`), a result on an
+  approval (`[taskResult/onApproval]`), a title missing `de` or `en`
+  (`[taskResult/appointmentMissingTitle]`), a bad duration
+  (`[taskResult/appointmentInvalidDuration]`), a stray field
+  (`[taskResult/unknownField]`). `offer validate` catches all of them offline.
+
+## With the CLI
+
+One spelling, the same verb as every other task result — no `:`-separated
+free text, so a title may contain a colon:
+
+```bash
+plexus-cli offer workflow node task add --dir $WORK/$S --node kennenlernen --key termin \
+  --title 'Termin für das Kennenlerngespräch vereinbaren' --team schulverwaltung --due-in-days 3 \
+  --blocks gespraech \
+  --result appointment --duration 45 \
+  --result-title 'Kennenlerngespräch' --result-title-en 'Introductory talk'
+# change later: node task set … --duration 60 / --result-title '…'
+plexus-cli offer workflow node list --dir $WORK/$S
+```
+
+Then the usual live-tenant path ([Edit a live tenant's offer](./edit-live-tenant-offer.md)):
+`offer validate` → `--env prod offer plan` → `--env prod offer apply --allow-prod --publish` → plan
+again until every row is `same`.
+
+## Gotchas
+
+- **Running applications keep their pinned graph.** An application already sitting on
+  the node with an open `termin` row keeps its old declaration until it is re-pinned;
+  new entries into the node get „Termin vereinbaren" in the action bar.
+- **Staff books it from the action bar** („Termin vereinbaren"), like every task; the
+  dialog names every missing field, refuses a slot more than two years ahead, and
+  closes with a toast. In the Testmodus the shortcut „<Aufgabe> (Test): Termin morgen
+  10:00" books through the same verb.
+- **No portal owner, no mail.** An application staff created has no portal account; the
+  appointment is saved and the toast warns „Keine Mail an die Familie …". The same
+  happens when the school's outgoing mail is off.
+- The zone is the tenant's (`Europe/Berlin` for every DACH tenant today).

package/dist/skill/references/offer/task-family-request.md

@@ -0,0 +1,69 @@
+# Let a task ask the family and wait for its answer („Nachforderung")
+
+**Use it to** turn „Nachforderung: auf Unterlagen der Familie warten" from a task the
+team closes by hand into one that asks the family itself and completes itself the
+moment the family sends. The family gets the field in its task „Offene Felder beantworten" in the portal
+(the task letter `applicant.tasksOpen`, the task's deadline, a reminder before it); the
+team's task waits and holds the decision until then. Nobody ticks it off.
+
+## The declaration
+
+On a task that a `spawnTasks` optional action references (and only there; at most
+one such task per action):
+
+```json
+{
+  "key": "unterlagenAnfordern",
+  "kind": "task",
+  "title": { "de": "Nachforderung: auf Unterlagen der Familie warten", "en": "Follow-up: waiting for the family's documents" },
+  "assign": { "group": "bewerbungsteam" },
+  "params": { "dueInDays": 7 },
+  "familyRequest": {
+    "fields": [{ "scope": "node", "owner": "form", "key": "admission", "path": "kind.weitereUnterlagen" }]
+  }
+}
+```
+
+- **What is asked is chosen at the click.** Pressing the action opens a dialog: the
+  presser ticks the fields and writes the text the family reads. The text becomes the
+  note at each asked field — in the portal and in the task letter.
+- Exactly one of `fields` (the fields offered, each a full address
+  `$node.<formNode>.admission.<field>` — one form) or `from` (the form instance
+  `$node.<formNode>.admission`: every file field (`docRef`) of that form is offered). There
+  is no default form: an empty `familyRequest` is refused. A **free upload** is a `docRef` field
+  with `docRefConstraints: { multiple: true }` („Weitere Unterlagen") — the field must
+  exist in the application's form version.
+- `params.dueInDays` is the family's deadline and the task's.
+- Put the action into the decision's `requiresOneOf` if the decision should wait for it.
+
+## CLI
+
+```bash
+plexus-cli offer workflow node task set --dir <dir> --node decision --key unterlagenAnfordern \
+  --due-in-days 7 \
+  --family-request-fields '$node.form.admission.kind.weitereUnterlagen'
+  # or --family-request-from '$node.form.admission': every file field of that form
+plexus-cli offer validate --dir <dir>
+```
+
+Remove with `--clear-family-request`. The task must not carry `result`, `when`,
+`locksEvidence` or `blocks` (and nothing may block it) — `offer validate` names each.
+
+## Verify
+
+1. Cockpit: press the action → the dialog offers the fields; tick one, write the text,
+   „Anfordern" → the task shows the clock (system-closed), the decision buttons read
+   „Wartet auf: …".
+2. Portal `/e`: „Offene Felder beantworten" (field under „Nachzureichen"), the text at the field, „bis <Datum>".
+3. Upload and send as the family → the task is `done`, the decision buttons are free.
+
+## Gotchas
+
+- A field already under an open request, hidden, or printed into a held document is not
+  offered; the trigger refuses it with the reason, and nothing is spawned.
+- An empty or unchanged answer answers nothing (the same file again is no new document):
+  the field stays asked.
+- Withdrawing the request („Zurückziehen") cancels the task; the decision stays held by
+  `requiresOneOf` until another action completes.
+- Rows of applications on an OLDER offer version keep the old task; only applications
+  pinned to the published version get the family request.

package/dist/skill/references/offer/task-result-files.md

@@ -0,0 +1,52 @@
+# Let a task's result carry files
+
+**Use it to** let the person who completes a task attach files to their answer. Example: the
+teacher's trial-day feedback with an English and a maths placement sheet, as PDF or photo.
+
+## The model
+
+- **One switch on the task:** `result.files: true`. It is allowed only on prose results:
+  `freetext`, `recommendation`, or a `choice` without `writes`. Publish refuses it anywhere
+  else (`[taskResult/filesOnKind]`).
+- **Text and files are ONE message** in the chat the result names (`result.chat`). The row
+  keeps no text, and the chat keeps, shows and erases the files (GDPR erasure included).
+- **Up to 20 files per result**.
+  A normal chat message takes 5. Each file may be PDF, JPEG, PNG or WebP of up to 25 MB;
+  an iPhone HEIC photo is converted to JPEG in the browser.
+- **Where the files show:** in the result's message — cockpit → Verlauf/Aktivitäten (the
+  chat's tab); a click opens the file in the viewer. The task itself shows at most how
+  many files its result carries. Never in the „Dokumente" rail:
+  that lists the application's documents, not task attachments. Nothing is
+  copied, so deleting the message removes its files.
+- **Who sees them:** whoever reads the feedback text — the SAME chat rule. In a
+  `team:<group>` chat that means the members of that group plus platform admins. A
+  `tenant_admin` who is in no such group sees neither the text nor the files. Before
+  choosing `team:principals`, check that the readers really hold that group (`plexus-cli
+  users show <email>`).
+
+## CLI
+
+Work in a scratch dir for a real tenant
+([edit-live-tenant-offer.md](./edit-live-tenant-offer.md)).
+
+```bash
+plexus-cli --env prod --tenant <slug> offer export --slug <offer> --out <dir>
+plexus-cli offer workflow node task set --dir <dir> --node decision --key tasterFeedback --files
+plexus-cli offer validate --dir <dir>
+plexus-cli --env prod --tenant <slug> offer plan --dir <dir>   # workflow: change
+# apply only with the school's go (the process owner):
+plexus-cli --env prod --tenant <slug> offer apply --dir <dir> --publish --allow-prod
+```
+
+A new task: `node task add … --result freetext --chat <chat> --files`.
+
+## Verify
+
+1. Open the task in the cockpit. The dialog shows „Dateien (optional)" with the paperclip,
+   which accepts several files at once.
+2. Complete it with two files. Verlauf, tab of the result's chat: one message with the
+   text and both files.
+3. „Dokumente": neither file is listed there.
+4. As staff outside the chat's team: neither the text nor the files show in Verlauf.
+
+Test tenant: Grundschule → „Probetag auswerten" (Schulleitung) takes files.

package/dist/skill/references/offer/template-document-node.md

@@ -0,0 +1,113 @@
+# Generate a letter from a Word template (governedDocument `production: 'template'`)
+
+**Use it to** let a workflow document node (Platzangebot, Bestätigung, Bescheinigung) fill a tenant Word
+template and render the PDF automatically — no resolver, no deploy.
+
+## Prerequisites
+
+- The Word template is uploaded in the tenant's template module (Vorlagen). Its placeholders use
+  `<< input.<feld> >>` (sections `<<#input.<feld>>> … <</input.<feld>>>`).
+- **Exactly one language per letter (required):** every template node declares a
+  required enum field (options `de`, `en`), names it in `template.localeField`, binds it to
+  `$env.applicant.language` (the applicant's language — the default) and wraps each language's
+  text in a section `<<#input.<feld>.de>> … <</input.<feld>.de>>` /
+  `<<#input.<feld>.en>> … <</input.<feld>.en>>`. Exactly one section renders, and `input.*` prints
+  the way that language writes it (numbers, dates, Ja/Yes, prices, names). A node without
+  `localeField` is refused at publish (`[governedDocument/localeFieldMissing]`); a missing section
+  blocks publish and file replacement. The English twin `en.input.*` of the old fixed bilingual
+  letters is gone — a file naming it is `[governedDocument/unknownPlaceholder]`. A German-only
+  school declares one option `de` and binds the field to the fixed value `de`.
+- **Switching a LIVE template to language sections — upload it under a NEW key.** A file
+  replacement is checked against EVERY published node naming the key, archived versions included
+  (`publishedNodesFillingTemplate` — they still carry running applications), and a node published
+  without `localeField` accepts no file at all. So the old key stays with the old versions for
+  good; the sectioned file goes in as a new template:
+  1. upload the sectioned Word file as a new template and give it a new key (§ 1, e.g.
+     `platzangebot-v2`);
+  2. in the exported bundle point `template.key` at it, add the field `sprache` to
+     `template.fields`, set `template.localeField: 'sprache'` and bind it:
+     `plexus-cli offer workflow node set-input --dir <bundle> --node <id> --input sprache --address '$env.applicant.language'`
+     ([Bind a node input](./bind-node-input.md));
+  3. `offer validate` → `plan` → `apply --publish`.
+  Applications pinned to the old version produce no letter any more (the mask names
+  `localeFieldMissing`); a re-pin onto the new version is refused, because the new binding changes
+  the process topology — restart such a (test) application on the new version.
+- The deployment already runs a release that knows template nodes (validators first, then
+  publish); if publish refuses the node type, that needs a platform operator.
+
+## 1. Give the template its stable key
+
+There is no UI field yet — set it through the public mutation (the same `updateMetadata` the UI calls,
+so name / role / file-name pattern must be passed as they are):
+
+```bash
+plexus-cli call templates:list --env staging client=<slug> --json        # id, name, roleId
+plexus-cli call templates:updateMetadata --kind mutation --env staging client=<slug> \
+  templateId=<id> name='Platzangebot' roleId=<roleId> configKey=platzangebot --json
+```
+
+The key is unique per tenant and cannot move while a published process names it.
+
+## 2. Author the node in the bundle (JSON)
+
+`plexus-cli offer workflow node add` cannot create a governedDocument node; edit `workflow.json`
+(export → edit → plan → apply, see [Edit a live tenant's offer](./edit-live-tenant-offer.md)):
+
+```jsonc
+{
+  "id": "platzangebot", "type": "governedDocument", "label": "Platzangebot",
+  "production": "template", "approval": "release", "responseStrategy": "confirm",
+  "responseDueInDays": 14,
+  "template": {
+    "key": "platzangebot",
+    "fields": [
+      { "key": "kind_vorname", "label": "Vorname des Kindes", "type": "string", "required": true },
+      { "key": "datum", "label": "Datum", "type": "date", "processSource": "generatedAt" },
+      { "key": "antwortfrist", "label": "Antwortfrist", "type": "number", "processSource": "responseDueInDays" },
+      { "key": "sprache", "label": { "de": "Sprache des Schreibens", "en": "Language of the letter" },
+        "type": "enum", "required": true,
+        "options": [
+          { "value": "de", "label": { "de": "Deutsch", "en": "German" } },
+          { "value": "en", "label": { "de": "Englisch", "en": "English" } }
+        ] }
+    ],
+    "cockpitFields": [],
+    "localeField": "sprache"
+  },
+  "inputs": {
+    "kind_vorname": {
+      "kind": "binding",
+      "address": { "scope": "node", "owner": "form", "key": "admission", "path": "kind.vorname" }
+    },
+    "sprache": { "kind": "binding", "address": { "scope": "env", "key": "applicant.language" } }
+  }
+}
+```
+
+A bound form field must be exported by the form (`export: true`) and is named by its full address
+(`$node.form.admission.kind.vorname` — bind it with
+`plexus-cli offer workflow node set-input --node platzangebot --input kind_vorname --from form --field kind.vorname`);
+a form that does not run before the node is `[address/notVisible]`, a field it does not export
+`[address/pathNotInTarget]`. An old bundle (`wires`, a binding with `path`) is refused
+— export it again. The deadline alone can be changed
+with `plexus-cli offer workflow node set --id platzangebot --response-due-days 14` (`""` removes it).
+
+## 3. Validate, plan, publish
+
+`plexus-cli offer validate <dir>` checks the node shape offline (including the language field,
+`[governedDocument/localeFieldMissing]`). **Publish** additionally refuses a
+key no template carries (`[governedDocument/unknownTemplate]`) and any placeholder the fields cannot
+fill (`[governedDocument/unknownPlaceholder]`).
+
+## Verify
+
+An application entering the node gets a run in `contract_generation_runs` (producer: the template)
+and a PDF version on the node's slot within seconds; the cockpit's „Überarbeiten" opens the mask.
+
+## Gotchas
+
+- Generation is automatic only while the producer row is open and unblocked; after „Freigabe
+  anfordern" nothing regenerates. A changed template file is caught at submit („nicht mehr aktuell").
+- Replacing the template file is refused while a published node could not fill its placeholders.
+- **CLI gap:** the `template` pin (key, fields, cockpitFields) has no `offer workflow node` verb yet —
+  JSON only.