@smartkomm/plexus-cli 0.0.0-stage → 0.1.1

package/dist/skill/references/offer/add-workflow-node.md

@@ -0,0 +1,268 @@
+# Add a workflow node to an offer bundle
+
+**When to use:** an offer's admission workflow needs another step (an approval
+gate, a waitlist holding node, a selection terminus, another form, …) and you want
+the graph + progress board kept in sync automatically — instead of hand-editing
+`workflow.json` (graph + `progressWiring.mappings`) and `manifest.json`
+(`progressLayout` states + columns) in lockstep.
+
+## Prerequisites
+- **Env / scope:** none for authoring — `offer workflow node add|rm|list` and
+  `offer workflow show` are **offline** (read/write the on-disk bundle, no
+  deployment). Only the final `offer apply --publish` is online and needs
+  `--env <env>` + a token with offer config rights (`plexus-cli --env <env> whoami`).
+- **A bundle on disk:** scaffold one with `offer init`, or `offer export` an
+  existing offer into a directory.
+- **Tooling:** an installed, current `plexus-cli` (`plexus-cli offer workflow node add --help`).
+- **Both languages:** a node's label is ONE `{ de, en }` field — `--label` AND
+  `--label-en` are required (as `--reason` + `--reason-en` on a collectPayment
+  node and `<id>:<Deutsch>:<English>` per `--decision-outcomes` entry).
+- **Supported types:** `form`, `decision`, `review`, `setFlag`, `approval`, `waitlist`,
+  `roleAssign`, `join`, `collectPayment`, `completenessCheck`, `countersign`, `engagePush`, `if`, `end`
+  (the list `offer workflow node add --help` prints). `decision` is the
+  configurable-decision builder (ATS primitives — assign-decision, composed
+  tasks, artifacts, decision-as-task); `approval` is a **deprecated alias** for
+  `decision` (maps `--decision-outcomes` → outcomes). `setFlag` flips an external
+  flag on the form instance it names (`--flag-key` + `--target '$node.<formNode>.admission'`).
+  `countersign` („Unterschrift (intern)") is the
+  school's countersignature of a checked contract — see
+  [Countersign the contract](./countersign-node.md).
+  `if` („Wenn") routes on one DSL expression over `$env` (`--condition
+  '$env.staffInput.<key>'`, outcomes `true` / `false` — route both with
+  `--outcomes`) — see [Branch on a staff input](./staff-input-if-node.md).
+  `completenessCheck` waits for outstanding documents (`--require`,
+  `--deadline-days`|`--deadline-until`, `--notification requested=…`, optional
+  `--guest-role` + `--person`) — see
+  [Wait for outstanding documents](./completeness-check.md). The folded
+  `governedDocument` (offer letter / contract) cannot be added by the CLI yet.
+  A `form` node binds a SmartForm via `--form` / `--new-form` (see
+  [Attach a form to a workflow](./attach-form-to-workflow.md)).
+- **Letters with the node:** `--notification <event>=<templateId>` (repeatable)
+  binds a letter in the same call — required when the type declares the event
+  required (completenessCheck `requested`, countersign `countersigned`), since
+  `add` validates before writing.
+- **Addresses with the node**: every flag that reads another node's data
+  takes a full address naming its producer, in single quotes — `--reads` /
+  `--require` (`'$node.<formNode>.admission.<field>'`), `--person`
+  (`'$node.<formNode>.admission.beneficiary'`), `--target` / `--adopt-form`
+  (`'$node.<formNode>.admission'`), `--contract`, engagePush `--form` / `--payment`.
+  A bare key is refused with the addresses visible at the new node; `add` binds
+  NOTHING implicitly. Bundles exported before addresses were introduced (with `wires`) are refused —
+  export again. See [Name what a node reads](./addresses.md).
+
+### Payment gate (`collectPayment`)
+`--article <key>` and `--settlement online|separate` are **required** (no
+default); both are written as the node's parameters (`inputs.article`,
+`inputs.settlement` — the editor lists them under „Parameter"). The article is
+a LINK: the key (`billing_item_definitions.configKey`) of a `one_time`
+article assigned to the offer's program (Finanzen → Artikel, directly or through
+an offered package). Amount, currency and the Stripe line name are read from the
+article at runtime — the node stores no amount, and publish refuses `amount` /
+`currency` on it (`[collectPayment/retiredField]`) as well as an unknown,
+non-one-time or out-of-program article. A price change in Finanzen applies to
+the next payment without a republish. `online`: the family gets a „Zahlung leisten" request row and pays
+through Stripe Checkout; the process responsible can also close it
+„Ohne Online-Zahlung abschließen" with a required reason (e.g. on an
+installation without Stripe). `separate`: the school bills
+the fee outside Plexus — nothing is asked of the family (no row, no letter; the
+portal says „Die Anmeldegebühr wird separat abgerechnet."), and the process
+responsible closes the step in the cockpit with **„Zahlung überspringen"**
+(optional comment, feed entry „Zahlung übersprungen", nothing booked). The
+routing edge is `paid` either way. Switch an existing node with
+`offer workflow node set --id <node> --settlement separate` (or
+`--article <key>` to charge another article); a `requested`
+letter bound on a `separate` node is refused (`[notification/unknownEvent]`).
+Applications already parked on the node stay on the version they are pinned
+to — moving them onto the new version after `apply --publish` needs a platform
+operator.
+
+### Terminal, fan-in, and role nodes
+- **`end --outcome <outcome> --data-decision <commit|discard>`** authors a
+  terminal node's application outcome (`approved` | `rejected` | `withdrawn` |
+  `waitlist` | `expired`; default `approved`) and — required, no default —
+  whether the application's data is kept (`commit`) or discarded (`discard`)
+  at this end (the outcome is only a label and never decides it). It
+  writes the `terminalStatus` / `applicationOutcome` / `dataDecision` /
+  `terminationKind` literal inputs the end executor reads (fixing the old gap
+  where every CLI-authored end recorded `approved`), and contributes **one**
+  outcome-aware terminal column (e.g. a rejected end adds a red *Abgesagt*
+  column, not a misleading green *Eingeschrieben*). A second end is inserted
+  isolated — wire predecessors to it with `join --from` or `node set --outcomes`.
+  Override the ledger label with `--terminal-status`, the kind with
+  `--termination-kind`.
+- **`join --from <nodeId>:<outcome>,…`** authors an explicit XOR fan-in
+  convergence. Each `--from` pair reroutes that source node's outcome onto the
+  join; the join's own onward edge defaults to the end node (override with
+  `--outcomes done:<target>`). Multi-input into a join is the one legal
+  many-to-one shape (the publish gate rejects multi-input on non-join nodes).
+- **`roleAssign --role <key>`** grants a person-lifecycle role. `--role` is
+  validated **offline** against the manifest's declared `roleInstances` (fail
+  loud if absent — declare it first with `offer role add`). `--mode`
+  is `add` (default) | `remove` | `replace`; `--person '<address>'` is required —
+  the party that gets the role, a party leaf of a form
+  (`--person '$node.form.admission.beneficiary'`). Never defaulted.
+
+### Configurable decision node (`decision`)
+The `decision` node is the **one configurable decision node** (it replaced the old
+`approval` node; `--type approval` is refused as an unknown type). By default it
+declares the type outcomes `approved` / `rejected` / `waitlisted`. To author a
+**custom** outcome set (with your own ids + labels), pass `--decision-outcomes
+<id>:<Deutsch>:<English>,…` (an outcome's label is `{ de, en }` — both languages
+are required) and route each with `--outcomes`:
+
+```bash
+# Inquiry decision: direkt aufnehmen / zum Interview / absage.
+plexus-cli offer workflow node add --dir ./demo \
+  --type decision --id decisionInquiry --label "Erstentscheidung" --label-en "Initial decision" --after form \
+  --decision-outcomes 'direkt:"Direkt aufnehmen":"Admit directly",interview:"Zum Interview":"To the interview",absage:"Absage":"Rejection"' \
+  --outcomes 'direkt:formApplication,interview:interview,absage:joinAbsage' \
+  --assign-decision zulassung --decision-as-task 'Erstentscheidung treffen'
+```
+
+Each entry becomes a `NodeOutcome {id,label}` on `node.outcomes`
+(first = `isDefault`); the backend executor + publish gate + cockpit UI all validate
+and render decisions against whatever set the node declares. `--decision-outcomes` is
+decision-only (fails loud on any other type). Outcomes whose id maps to a known
+semantic (`direkt`/`accepted`→granted, `absage`/`rejected`→rejected,
+`warteliste`/`waitlisted`→waitlisted) drive the roster chip + annotation mirror; any
+other id (e.g. `interview`) is a real routing decision with no typed annotation.
+Route each declared outcome to a target that exists — the publish gate checks coverage.
+
+#### ATS lifecycle primitives on a decision node
+A decision node carries the full offer-lifecycle authoring surface:
+
+- **`--assign-decision <groupKey>`** — the permission group whose members hold the
+  synthesized decision Work-Item (= may pick the routing outcome, in ONE act).
+  Pairs with `--decision-as-task` (each requires the other — fails loud). Absent
+  = super-user-only decide (the instance's responsible).
+- **`--comment-required <id>[,<id>]`** — authored outcome ids that require a decider comment.
+- **`--task …`** (repeatable) — a composed task the node spawns on enter,
+  instantiating a code-owned kind (the kind carries the behaviour: actions,
+  close protocol, respawn, gate default):
+  - `key:task:title:group[:dueInDays]` — an internal check task (trivial `complete`).
+  - `key:approval:title:group[:revisionGroup]` — an approval; gates the node by
+    default. With **`--task-on-reject spawnRevision`** a rejecting verdict
+    spawns a revision back to `revisionGroup` (then REQUIRED — fails loud).
+    (`binds` is DELETED — the offer arc is node-internal; use the
+    `offer` node type for the prepare/approve arc.)
+- **`--artifact key:type:visibility:label`** (repeatable) — a versioned artifact SLOT
+  (`visibility` = `internal` | `external`). Each slot exposes a `<key>Uploaded` node-export.
+- **Assignment rule** (GRAPH-level, no flag) — who becomes responsible and who owns
+  each team is `graph.assignmentRules` in the same `workflow.json`; `node add/set` do
+  not touch it. A node that gives work to a team the rule has no slot for makes
+  `offer validate` / publish refuse with `[assignment/slotMissing]` — add a
+  `team:<key>` list in the bundle or in the workflow editor („Team-Verantwortliche").
+  Recipe: `playbooks/offer/assignment-rule.md`.
+- **`--decision-as-task title[:dueInDays]`** — surface the decision as a
+  first-class queue Work-Item. Requires `--assign-decision` (and vice versa).
+  Combining with gating approval tasks is fine: the HARD node gate blocks a
+  non-rejecting advance server-side while gate-effective rows are open.
+
+```bash
+# Offer create-phase (mirrors the grundschule createOffer node): external artifact,
+# a prepare task, a finance approval gate with a ping-pong revision on reject, and
+# the Schulleitung send-offer decision row (hard-gated on the finance approval).
+plexus-cli offer workflow node add --dir ./demo \
+  --type decision --id createOffer --label "Angebot erstellen" --label-en "Prepare offer" --after form \
+  --decision-outcomes 'offerReady:"Angebot freigegeben",absage:"Angebot abgebrochen"' \
+  --assign-decision schulleitung --decision-as-task 'Angebot versenden:3' \
+  --artifact 'offer:offer:external:Angebotsschreiben' \
+  --task 'prepareOffer:checkTask:Angebotsschreiben vorbereiten:schulleitung:5' \
+  --task 'offerApproval:approval:Angebot freigeben:finanzen:offer:offerUploaded:schulleitung' \
+  --task-on-reject spawnRevision
+
+# Task-driven selection decision (grundschule approvalSchulleitung), gate-less:
+plexus-cli offer workflow node add --dir ./demo \
+  --type decision --id freigabe --label "Freigabe" --label-en "Approval" --after form \
+  --decision-outcomes 'approved:Freigegeben,rejected:Abgelehnt,waitlisted:Warteliste' \
+  --assign-decision schulleitung \
+  --comment-required rejected \
+  --decision-as-task 'Über Freigabe entscheiden:5'
+```
+
+All of the above is validated by the REAL publish gate on `offer validate`; the CLI adds
+fail-loud cross-checks at the flag boundary (undeclared bound artifact, `spawnRevision`
+without `revisionGroup`, `decision-as-task` ⇔ `assign-decision` pairing).
+
+## Steps
+```bash
+# 1. Scaffold a minimal linear offer (start → form → end).
+plexus-cli offer init --slug demo --title "Demo Schule" --title-en "Demo School" --tenant test --responsible sekretariat --out ./demo
+
+# 2. Inspect the graph.
+plexus-cli offer workflow node list --dir ./demo
+plexus-cli offer workflow show --dir ./demo
+
+# 3. Insert a decision gate between the form and the end node.
+#    --outcomes routes each declared outcome; any omitted outcome defaults to
+#    where --after currently points (here end), splicing into the chain.
+plexus-cli offer workflow node add --dir ./demo \
+  --type decision --id approval --label "Freigabe" --label-en "Approval" --after form \
+  --assign-decision freigeber --decision-as-task 'Freigabe entscheiden' \
+  --outcomes approved:end,rejected:end
+
+# 4. Validate offline against the REAL publish gate (add already ran it; this is
+#    the explicit re-check / CI gate).
+plexus-cli offer validate --dir ./demo
+
+# 5. Apply + publish (online). Needs --env + a token; cuts new versions on diff.
+plexus-cli --env <env> --tenant test offer apply --dir ./demo --publish
+```
+
+- **`--id`** is optional — defaults to the type, numbered from 2 when taken
+  (`approval`, `approval2`, …; `makeNodeId`). An id you pass must be a dot-free
+  identifier (`^[a-z][A-Za-z0-9]*$`, e.g. `decisionInquiry`) — `offer validate`
+  refuses anything else as `[graph/nodeIdFormat]`.
+- **`--after <nodeId>`** inserts after that node and rewires its onward edge(s)
+  to the new node. Omit it to insert immediately before the end node.
+- **`--type form`** binds a SmartForm — `--form <slug>` (existing) or
+  `--new-form --form <slug>` (scaffold + bind). See the dedicated playbook.
+- **Remove** a node (rewires predecessors onto its single successor, strips its
+  progress entries, re-validates; refused while an address elsewhere names it):
+  ```bash
+  plexus-cli offer workflow node rm --dir ./demo --id approval
+  ```
+
+## Verify
+```bash
+plexus-cli offer workflow node list --dir ./demo   # the node appears, routing is wired
+plexus-cli offer validate --dir ./demo             # exit 0 = publish gate clean
+```
+
+For the approval example, `offer validate` exits 0 with **no manual manifest
+edit**: `offer workflow node add` materialised the `approval.released` process
+state, its board column, and the `(approval, released) → process/approval.released`
+wiring mapping. A decision that reads nothing of the form names no address
+(`offer workflow node reads --dir ./demo --node approval` lists nothing). After `offer workflow node rm`, the graph returns to the linear
+`form → end` shape and validation passes again.
+
+## Idempotency / gotchas
+- **`add` validates before writing.** Any error-severity issue from the real
+  publish gate (`runWorkflowValidators` etc.) blocks the write and exits 1 — the
+  bundle is left untouched. A failed `add` never leaves a half-spliced bundle.
+- **Splice defaults can over-route.** Every declared outcome you DON'T name in
+  `--outcomes` defaults to the anchor's current onward target. Inserting a
+  multi-outcome node (endauswahl, approval) after a node that points at the end
+  node routes *all* its outcomes to the end node — pass `--outcomes` to fan them
+  out (e.g. `warteliste:waitlist`).
+- **Nothing is bound implicitly.** A node reads a form only at the address it
+  names (`$node.<formNode>.admission.<field>`), and the producer must run on every
+  path before it (`[address/notVisible]` otherwise). A `form` node's `smartForm` is
+  written as a `{ kind: "literal", value: <slug> }`; with
+  `--adopt-form '$node.<formNode>.admission'` it continues that instance instead
+  (`adoptForm` holds the address; the adopting node produces nothing — later
+  nodes still read the creator's address). Explicit-by-default, matching `offer init`.
+- **`rm` refuses** to remove the start (`eventTrigger`) or `end` node, a node with
+  multiple distinct successors (ambiguous splice), and a node any address elsewhere
+  still names (its form instance, document, contract, payment, or a value one of
+  its tasks writes) — the refusal lists every naming place (config path +
+  address); edit those first. Orphans surface at re-validate and block the write.
+- **Progress labels/tones** come from one built-in default table, shared with the
+  `offer init` scaffold. An event with no default falls back to its name +
+  neutral tone and prints a warning.
+
+## Related
+- [Attach a form to a workflow](./attach-form-to-workflow.md) — the `--type form` flow.
+- [Author a SmartForm as code](./author-smartform.md) — build the form itself.
+- `plexus-cli offer --help` — the full `offer …` command reference; `offer validate`
+  runs the same publish-gate validators as `offer workflow node add`.

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

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

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

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