@smartkomm/plexus-cli 0.0.0-stage → 0.1.0

package/dist/skill/references/notifications/mail-level.md

@@ -0,0 +1,90 @@
+# Choose which mail a school sends (mail level)
+
+> **Version check first.** A deployment on a release older than the mail level
+> ignores `--field mailLevel` WITHOUT an error and keeps reading the retired
+> `tenant.enabledMailCategories` (`[]` = sign-in only, every category = all).
+> If `config export` shows no `mailLevel`, stop and ask the platform operator.
+> The same skew means a tenant scaffolded with a newer CLI against an older
+> deployment starts at sign-in mail only.
+
+**When to use:** a school wants only the sign-in links for FAMILIES for now
+(„Anmeldelinks ja, alles andere nein"), or is ready for every mail.
+
+**The level is family mail only.**
+Letters to the school's own staff (`audience: "internal"`: new tasks, passed
+deadlines, family messages, mentions) go out at BOTH levels; each staff member
+decides them in „Einstellungen" (personal categories, runbook „Which mail a
+staff member wants"). Do not use the level to quiet staff mail.
+
+**Current stance:** every tenant — prod, staging and the `test` demo tenant —
+runs `loginOnly` until the platform operator decides otherwise. Switching a real
+school to `all` is that decision, not a routine step. Locally, a reseeded `test` tenant is at `loginOnly` too; to see a
+rendered admission, family-task or school-chat letter set it to `all` on your
+own deployment (`--env local`). Staff letters render at both levels.
+
+## What it is
+
+- A school has ONE setting, its **mail level** (`tenant.mailLevel`, required in
+  every tenant config):
+  - `loginOnly` — „An Familien nur Anmeldelinks": to families, sign-in links,
+    the access a school hands out, address confirmations („Bewerbung
+    begonnen/geparkt" included) and security notices about one's own account
+    (e.g. a changed login address).
+  - `all` — „Alle E-Mails": to families additionally admission, family task
+    reminders and the school's chat messages.
+- Every letter still declares a **category** in code (`login`, `security`,
+  `admission`, `tasks`, `schoolMessages`; for staff the personal `staffTasks`,
+  `staffAppointments`, `staffDeadlines`, `familyMessages`, `mentions`). It names
+  the letter in a skipped delivery's reason; a school cannot switch single
+  categories.
+- The `notifications` module must be enabled for `all`; with the module off only
+  sign-in and security mail go out whatever the level says.
+- Refused by `config set` / `config apply`: a missing or unknown level
+  (`[notification/mailLevel]`), `all` without the `notifications` module
+  (`[notification/levelWithoutModule]`), and the retired spellings
+  `tenant.enabledMailCategories` (`[notification/mailCategoriesRetired]`)
+  and `tenant.mailEnabled` (`[notification/mailEnabledRetired]`) — a scratch
+  export from before the mail level must be rewritten, not applied.
+- `MAIL_DELIVERY_MODE` of the deployment stays the outer boundary. Never change
+  it for this.
+
+## Set it (dry run first)
+
+```bash
+# sign-in mail only
+plexus-cli --env staging config set --tenant <slug> --target tenant \
+  --key <slug> --field mailLevel --value loginOnly
+plexus-cli --env staging config set --tenant <slug> --target tenant \
+  --key <slug> --field mailLevel --value loginOnly --confirm
+
+# everything (what the introduction of the level wrote for every school that sent mail)
+plexus-cli --env staging config set --tenant <slug> --target tenant \
+  --key <slug> --field mailLevel --value all --confirm
+```
+
+Through a scratch export instead: `config export` → set
+`"tenant": { …, "mailLevel": "loginOnly" }` → `config apply --from snapshot:…`.
+
+## Verify
+
+- `plexus-cli --env <env> config export --tenant <slug>` shows `mailLevel`
+  (always emitted).
+- Platform rail → **Mandanten** (needs `_platform.config.read`): the column
+  „E-Mails" says „Nur Anmeldelinks" (amber) or „Alle E-Mails" — as the send
+  path answers it, so module off reads „Nur Anmeldelinks" too.
+- Dashboard of the school: banner „Hinweis zur Konfiguration" on top of the
+  page, gap `mailDisabled` („Diese Schule versendet nur Anmeldelinks …") —
+  unless the school hides that notice: `config set --tenant <slug> --target tenant
+  --key <slug> --field hideMailLevelNotice --value true --confirm` (mail-module setting, shown under
+  „notifications" in Platform → Mandanten; the test tenant does). Only this
+  notice goes; a configuration error always shows.
+- A suppressed letter is a row: `plexus-cli --env <env> notifications …` lists it
+  `skipped`, `tenant_delivery_disabled`, last error
+  `the school's mail level does not send "<category>" mail`.
+
+## Gotchas
+
+- A skipped delivery is never re-sent when the level goes back to `all` — the
+  setting decides at enqueue AND at send time, not retroactively.
+- `applicant.accessSent` („Zugang versenden → Per Mail senden") is `login`: it
+  goes out at `loginOnly`.

package/dist/skill/references/notifications/reword-a-letter.md

@@ -0,0 +1,155 @@
+# Reword a letter for one school
+
+**When to use:** a school wants one of the mails Plexus sends in its name to say
+something else — a different opening paragraph, its own sign-off — and you want
+to prove the new words actually reach a rendered mail before anyone relies on it.
+
+## Prerequisites
+
+- `--tenant <slug>` on every command: a letter is reworded **per school**, never
+  platform-wide.
+- Permissions `notifications._self.access` (read) and
+  `notifications.mail.configure` (write). The local CLI bootstrap has both.
+- Locally: a running local development deployment (`--env local`). **Nothing is
+  ever sent from a local deployment** (`MAIL_DELIVERY_MODE=dry`) — the rendered mail
+  lands in `notification_previews`, which is exactly what makes this verifiable.
+
+## Steps
+
+```bash
+# 1. What can this school reword, and what has it already changed?
+plexus-cli --env local --tenant test notifications letters list
+
+# 2. One letter, block by block, with the placeholders the LETTER may use
+#    printed above them — they belong to the letter, not to one paragraph, so a
+#    school may move a value into whichever block it likes. They are an
+#    ALLOWLIST: an undeclared {{x}} is refused, never silently printed. One
+#    marked "(Pflicht)" must appear somewhere in the BODY or the save is refused
+#    — that is what replaced the lock on the two sign-in letters.
+plexus-cli --env local --tenant test notifications letters show applicant.tasksOpen --locale de
+
+# 3. Reword ONE block, in ONE language. Untouched blocks are not written and
+#    keep following the platform text of that language; the other language is
+#    not touched at all (a German rewording never words the English letter).
+plexus-cli --env local --tenant test notifications letters set applicant.tasksOpen --locale de \
+  --slot intro="bei {{schoolName}} warten {{taskCount}} Aufgaben auf Sie."
+plexus-cli --env local --tenant test notifications letters set applicant.tasksOpen --locale en \
+  --slot intro="{{taskCount}} tasks at {{schoolName}} are waiting for you."
+
+#    A paragraph with line breaks belongs in a file, not in a shell argument:
+# plexus-cli --env local --tenant test notifications letters set applicant.tasksOpen --locale de \
+#   --slot-file intro=./intro.txt
+
+# 4. The shared letter frame (greeting, sign-off, sender name) is separate —
+#    it is the same frame for EVERY letter this school sends, worded in both
+#    languages at once (each letter carries its own language's line).
+plexus-cli --env local --tenant test notifications chrome show
+plexus-cli --env local --tenant test notifications chrome set \
+  --closing-de="Herzliche Grüße
+Ihr Grundschul-Team" \
+  --closing-en="Warm regards
+Your primary school team"
+```
+
+## Verify
+
+Reading back the catalog only proves the row was stored. What has to be proven is
+that the words reached a **rendered mail**:
+
+```bash
+# a) The stored deviation
+plexus-cli --env local --tenant test notifications letters list      # "reworded: de, en"
+plexus-cli --env local --tenant test notifications letters show applicant.tasksOpen --locale en
+
+# b) Trigger the letter (for applicant.tasksOpen: open an external task on an
+#    application — e.g. a workflow task addressed to the family), then find its
+#    delivery and read the body that was actually rendered:
+plexus-cli --env local notifications list --limit 20
+plexus-cli --env local notifications show <deliveryId> --json | grep -A12 '"letter"'
+```
+
+`letter.text` (and `letter.html`) carry the reworded sentence, and
+`letter.version.reworded` names the blocks in which the school's wording stood,
+`letter.version.locale` the language it went out in — the RECIPIENT ACCOUNT's
+(`users.language`). To see the English letter go out, the recipient's account
+must have chosen English; the preview in Administration → Benachrichtigungen
+shows either language without one. The same rows are the Dev Rail →
+**Mail** panel, which is the human version of the same check (and the place to
+follow a sign-in link this deployment "sent").
+
+Roll back — one block, or the whole letter:
+
+```bash
+plexus-cli --env local --tenant test notifications letters reset applicant.tasksOpen --locale de --slot intro
+plexus-cli --env local --tenant test notifications letters reset applicant.tasksOpen --locale en --all
+plexus-cli --env local --tenant test notifications chrome set --closing-de="" --closing-en=""   # back to the platform sign-off
+```
+
+The next rendered mail carries the platform text again — no republish, no deploy.
+
+## Idempotency / gotchas
+
+- **A deviation is a delta, not a copy.** Only the blocks a school rewrote are
+  stored. A block left alone keeps following the code, so a later platform
+  improvement to it still reaches that school. Setting a block to *exactly* the
+  platform text therefore stores nothing — the command's `deviating blocks` line
+  is the backend's answer, and it will not list that block.
+- **`set` merges.** Passing `--slot intro=…` does not wipe a deviation on
+  `outro`. The way back is `reset`, which names what to drop.
+- **`reset` without `--slot` needs `--all`.** Dropping every deviation of a
+  letter must be typed, not be what happens when a flag is forgotten.
+- **Some letters have no blocks at all.** The two sign-in letters
+  (`applicant.magicLink`, `applicant.verifyEmail`) are category `login`: the mail
+  that carries a login link is not rewordable by anyone, so it declares nothing
+  to reword. They show `— (not editable)` in the list.
+- **An unknown block or placeholder throws, naming every finding.** Nothing is
+  written — there is no partial save.
+- **`--locale de|en` is required** on `show`, `set` and `reset`: every
+  letter exists in German and English, each worded on its own, and a command
+  that silently picked one would reword the letter you were not looking at. A
+  recipient gets the language of their own account; a school that rewords only
+  the German letter sends its English families the platform's English text —
+  the workshop says so on the letter.
+- **This is configuration, not operational state.** A change made here is
+  exported, diffed and promoted like any other tenant setting — see
+  "Promote the wording to another environment" below. On staging/prod prefer
+  the config route so the change is reviewable; the direct `letters set` is for
+  local exploration and for a one-off correction with the platform operator watching.
+
+## Promote the wording to another environment
+
+The deviations live in the tenant config under `notificationLetters` (identity
+`templateId:locale:scopeKey`) and the frame under
+`tenant.notificationChrome`, so the ordinary config-as-code verbs carry them:
+
+```bash
+# Export → edit → dry-run → confirm, exactly as for any other tenant setting.
+plexus-cli --env staging config export --tenant test --out /tmp/test.json
+# …edit `notificationLetters` / `tenant.notificationChrome` in /tmp/test.json…
+plexus-cli --env staging config apply --tenant test --from snapshot:/tmp/test.json
+plexus-cli --env staging config apply --tenant test --from snapshot:/tmp/test.json --confirm
+
+# One block, without an export round trip. The --key IS the identity triple
+# (templateId:locale:scopeKey) — a letter is worded per language and per scope.
+plexus-cli --env staging config set --tenant test \
+  --target notification-letters --key "applicant.tasksOpen:de:tenant" \
+  --field slots.intro --value "…" --confirm
+```
+
+Two things follow from "a deviation is a delta":
+
+- A letter **absent** from `notificationLetters` is a letter this school does not
+  deviate from, so applying a config without it takes that letter back to the
+  platform text. Removing an entry is how you undo a rewording in config.
+- `config set` **edits an existing entry**; it does not create one. The first
+  deviation for a letter comes from `notifications letters set` or from an
+  edited export.
+
+## Related
+
+- [Debug a mail delivery](./debug-mail-delivery.md) — when the mail did not
+  arrive at all (the operator's log, not the school's wording).
+- [Update a tenant's config](../config/update-tenant-config.md) — the export →
+  edit → dry-run → apply loop these letters travel in.
+- `plexus-cli notifications letters show --help` (and `set`/`reset`) — the letter /
+  block / override commands; a letter showing `— (not editable)` is one a school may not reword.

package/dist/skill/references/notifications/trace-a-login.md

@@ -0,0 +1,50 @@
+# Trace why someone could not sign in
+
+**When:** „I asked for a sign-in link and got nothing", „the link said already
+used", „my new password does not work" — on any environment, after the fact.
+
+## Prerequisites
+
+A platform token with `_platform.users.manage` (sessions name IP addresses) and
+`_platform.notifications.monitor` (the delivery list).
+
+## Steps
+
+```bash
+# Everything the platform still knows about the address, oldest first.
+plexus-cli --env prod users login-trail ada@example.com --since 24h
+
+# Only the login page's letters to that address, with the relay's answer.
+plexus-cli --env prod notifications list --template account.loginLink --to ada@example.com --since 24h
+```
+
+`login-trail` prints one time-ordered list:
+
+| Line | Means |
+| --- | --- |
+| `abgelehnt: <reason>` | the login page sent this KNOWN account no link (`platformAdmin`, `unprovenAddress`, `noSchoolWithOption`) |
+| `Brief account.loginLink: sent — Relay: 250 … queued as <id>` | our relay accepted the mail; the queue id finds it in the relay's log |
+| `Sitzung von <ip> — <browser>` | a sign-in happened. A session seconds after the letter from a foreign network is a **mail scanner** (Exchange Safe Links), not the person |
+| `Passwort gesetzt (zuletzt)` | the credential was last changed then — compare with the failed attempts |
+
+## Reading it (an invented example)
+
+- letter `sent` 09:12:05 → session from `203.0.113.7` at 09:12:29, a network the school
+  does not use → the person got „link already used": the scanner spent it. A link now opens a page first and only
+  its button spends the token, so a scanner no longer uses it up.
+- password set 09:20:41, session from the school's network 09:20:42, failed
+  attempts before: the earlier resets went to **another** account (check the
+  `Passwort gesetzt` line of the account the person actually uses).
+
+## Gotchas
+
+- Not recorded at all (the command lists it under „Nicht erfasst"): rate-limited
+  requests, requests for an address without an account (both only in the
+  function log, minutes), anything older than 30 days, ended sessions, and what
+  happened after our relay (inbox / spam / quarantine / bounce).
+- `sent` in every list means „our relay said 250", never „in the inbox". The
+  console's word for it is „Versendet".
+
+## Related
+
+- [Debug a mail delivery](./debug-mail-delivery.md)

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`.