@smartkomm/plexus-cli 0.0.0-stage → 0.1.0

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

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

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

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

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

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

package/dist/skill/references/offer/completeness-check.md

@@ -0,0 +1,137 @@
+# Wait for outstanding documents (completeness check)
+
+**When to use:** a school lets the process run on while documents are still
+missing — the Masernschutz-Nachweis, the birth certificate — and wants it to end
+only once they are there, with a deadline („erst wenn wirklich alle Unterlagen da
+sind, ist es vorbei"). The `completenessCheck` node names SmartForm fields
+(`requires`) and a deadline. Entered with nothing missing it completes at once;
+otherwise the family gets its fields in **one** task „Offene Felder beantworten" due by the
+deadline, the optional guest role is granted, and the node parks until the last
+field arrives (`complete`) or a person decides: „Ohne Nachreichung abschließen"
+(`acceptedIncomplete`) or „Bewerbung ablehnen" (`rejected`). The family's
+withdrawal arrives as `absage`.
+
+## Prerequisites
+- An offer bundle on disk: `offer init` for a new one, or a **fresh export** of
+  the target environment into a private scratch dir (a live tenant's bundle is
+  never kept in a shared or versioned place — the server is its source of truth).
+- The fields exist in the form the bundle's form node pins, as **entered,
+  non-repeated** fields (a computed key or a field inside a repeated group
+  cannot be handed in). Each is named by its full address,
+  `$node.<formNode>.admission.<field>` — the form node that CREATES the
+  instance, in single quotes. A bundle exported before addresses were introduced is
+  refused — export again.
+- For a guest role: a **leaf** role in the tenant's role catalog (e.g.
+  `gasthoerer`) — checked at `offer apply --publish`, not offline.
+- The graph has somewhere to send `rejected` and `absage` (the paths to the
+  end of a rejection and of a withdrawal — an end with `dataDecision: discard`
+  takes the application's records back itself, no discard node needed).
+
+## Steps
+```bash
+# 1. Export what is live (read-only).
+plexus-cli --env staging --tenant <tenant> offer export --slug <offer> --out ./bundle
+
+# 2. Add the check. Every flag below except --guest-role/--person is required:
+#    - at least one --require address (repeatable, comma-separated),
+#    - exactly one deadline: --deadline-days <n> (calendar days after entering)
+#      OR --deadline-until <YYYY-MM-DD> (a fixed due day, tenant zone),
+#    - the `requested` letter (the node type declares it REQUIRED),
+#    - rejected/absage routed to the rejection/withdrawal paths.
+#    `requires` and the guest role's person name the form they read; nothing is
+#    bound implicitly (a bare key is refused with the addresses the node can read).
+plexus-cli offer workflow node add --dir ./bundle --type completenessCheck \
+  --id nachreichen --label "Vollständigkeitsprüfung" --label-en "Completeness check" \
+  --require '$node.form.admission.kind.masernschutz,$node.form.admission.kind.geburtsurkunde' \
+  --deadline-days 14 \
+  --guest-role gasthoerer --person '$node.form.admission.beneficiary' \
+  --notification requested=admission.documentsRequested \
+  --outcomes complete:end,acceptedIncomplete:end,rejected:joinAbsage,absage:endAbsage
+
+#    Later edits:
+plexus-cli offer workflow node add-requires    --dir ./bundle --node nachreichen --address '$node.form.admission.kind.impfpass'
+plexus-cli offer workflow node remove-requires --dir ./bundle --node nachreichen --from form --field kind.impfpass
+plexus-cli offer workflow node set-requires    --dir ./bundle --node nachreichen --from form --field kind.masernschutz
+plexus-cli offer workflow node set --dir ./bundle --id nachreichen --deadline-until 2026-10-15
+plexus-cli offer workflow node set --dir ./bundle --id nachreichen --guest-role ""   # drops role AND person
+plexus-cli offer workflow node set-notification --dir ./bundle \
+  --node nachreichen --event requested --template admission.documentsRequested
+
+# 3. Validate offline, see the difference, publish.
+plexus-cli offer validate --dir ./bundle
+plexus-cli --env staging offer plan --dir ./bundle
+plexus-cli --env staging offer apply --publish --dir ./bundle
+```
+
+## Verify
+```bash
+plexus-cli offer workflow node list --dir ./bundle
+#   nachreichen  completenessCheck  …  complete→…, acceptedIncomplete→…, rejected→…, absage→…
+#   letters: requested→admission.documentsRequested
+jq '.graph.nodes[] | select(.id=="nachreichen") | {requires, deadline, guestRole, inputs}' ./bundle/workflow.json
+plexus-cli offer workflow node reads --dir ./bundle --node nachreichen
+```
+After publish, a fresh application that reaches the node with a field empty
+shows the family task „Offene Felder beantworten" and the board column of the same
+name; a deployment that does not send mail records the letter in Dev Rail
+→ „Mail" instead.
+
+## Idempotency / gotchas
+- **The `requested` letter is required.** Without a binding the family would get
+  no mail about the request, so every write refuses it
+  (`[notification/missingBinding]`) — bind it in the `add` call with
+  `--notification requested=<templateId>`. `--disabled` counts as missing.
+  Offline validation cannot see the letter catalog: a misspelled template id is
+  caught only at `offer apply --publish`.
+- **Deadline rules:** exactly one form. `--deadline-days` is a whole number 0–366
+  (`[completenessCheck/deadlineDays]`); `--deadline-until` must be a real
+  calendar day (`2026-02-30` is refused, `[completenessCheck/deadlineDate]`).
+  Passing both, or neither on `add`, fails before anything is written. Past the
+  deadline nothing happens by itself: the family and the responsible person are
+  told, and a person decides.
+- **Guest role:** `--guest-role` needs `--person`, and `--person` needs
+  `--guest-role` — nothing is defaulted. The person is a party of a form,
+  `$node.form.admission.beneficiary` (the beneficiary the form's contract parties
+  name), read live at that address whenever the role is granted or ended; a form
+  that does not run before the check is `[address/notVisible]`. The role must be a **leaf** tenant
+  role (`[completenessCheck/unknownRole]`, `[completenessCheck/nonLeafRole]`,
+  both at publish). It is granted only when something is missing, ended on
+  `complete` / `rejected` / `absage`, and **kept on `acceptedIncomplete`** — the
+  school still has to know whose documents are outstanding. A role the person
+  already held is never ended.
+- **Entering with nothing missing completes automatically** — no request, no
+  letter, no role; the node passes straight through on `complete`.
+- **Where it lands:** without `--after` the check is spliced in front of the
+  FIRST `end` node in `workflow.json` (every edge into that end now enters the
+  check) — make sure that is the positive end. With `--after <node>` the
+  anchor's FIRST onward edge is the one rerouted; on an anchor with several
+  outcomes (a contract: `signed` + `absage`) that may be the wrong one. Check
+  with `node list` and fix with `node set --outcomes`.
+- **Routing:** `complete`, `rejected` and `absage` must be routed
+  (`[completenessCheck/unroutedOutcome]`); the staff buttons appear only for the
+  outcomes that are wired. Left to the splice default, `rejected`/`absage` run
+  into whatever follows (usually the positive end) — `add` warns about that; route
+  them with `--outcomes`.
+- **`requires` edits:** only a completenessCheck carries `requires`
+  (`*-requires` on another node fails; for fields a decider reads use
+  `*-reads`). Removing the last address is refused (`[completenessCheck/missingRequires]`);
+  two forms in one list are `[address/mixedForms]`, a field the form lacks is
+  `[address/pathNotInTarget]`.
+  Only errors an edit introduces block it.
+- **Hand-authored boards (known CLI gap):** `node add` derives the progress
+  states and appends the check's column „Unterlagen nachreichen"; its
+  `rejected`/`withdrawn` states go into the global `col.abgelehnt` /
+  `col.abgesagt` columns. A bundle whose board already names its own exit
+  columns (e.g. a `c.absage` column labelled „Abgelehnt")
+  then carries two columns with one label, and `node add` refuses the write —
+  for ANY node type with such an event (`waitlist`, `decision`, …), not only this
+  one. Until `node add` can map events onto existing states, author the node in
+  `workflow.json` + the states/columns/wiring in `manifest.json`/`workflow.json`
+  by hand (shape: the Verify `jq` output above) and gate it with `offer validate`
+  / `offer apply --publish`. Scaffolded bundles (`offer init`) are not affected.
+- **Running applications keep their pinned version** — see
+  [Declare what a document node reads](./declare-node-reads.md) for re-pin / wipe.
+
+## Related
+- [Add a workflow node](./add-workflow-node.md) · [Edit a workflow node](./edit-workflow-node.md) · [Release an offer bundle](./publish-offer-bundle.md)
+- [Reword a letter](../notifications/reword-a-letter.md)

package/dist/skill/references/offer/countersign-node.md

@@ -0,0 +1,91 @@
+# Countersign the contract („Unterschrift (intern)")
+
+**When to use:** the school countersigns the admission contract the family signed. A `countersign` node after the contract opens one row „Vertrag gegenzeichnen" for a
+team: the clerk downloads the family's signed copy, signs it for the Träger, uploads the
+scan with the date. That opens the Träger's own Signaturvorgang on the revision the family
+signed and books the Träger („vertreten durch <Mitarbeiter/in>") on it, so the contract is
+signed and the family's portal shows the countersigned paper; it sends the node's
+`countersigned` letter, and the contract's event moves the node along `countersigned`. It replaces
+the retired task result `countersignature` (`--result countersignature` is now an unknown
+kind) and its review host node.
+
+## 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 contract node is a `governedDocument` with `production: "resolver"` and
+  `responseStrategy: "signedUploadChecked"` (the school checks the signed return; only that
+  freezes a revision with declared signers) — `[countersign/sourceNotCheckedContract]`
+  otherwise.
+- A team (permission-group key) that countersigns, e.g. `schulverwaltung`.
+
+## Steps
+```bash
+# 1. The contract's accepting edge (`signed`) and what follows it:
+plexus-cli offer workflow node list --dir <dir>
+
+# 2. Splice the countersignature onto that edge. Required: the team, the contract's
+#    address (a resolver contract is `$node.<contractNode>.contract`) and the
+#    letter (the node type declares it REQUIRED).
+plexus-cli offer workflow node add --dir <dir> --type countersign \
+  --id gegenzeichnung --label "Gegenzeichnung" --label-en "Countersignature" \
+  --on-edge contract:signed \
+  --assign-team schulverwaltung \
+  --title "Vertrag gegenzeichnen" --title-en "Countersign the contract" \
+  --due-in-days 5 \
+  --contract '$node.contract.contract' \
+  --notification countersigned=admission.contractCountersigned
+
+#    Optional: put its board event on an existing state instead of a new
+#    „Gegenzeichnung" column:  --progress countersigning=<stateId>
+
+# 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>
+#   contract        governedDocument … signed→gegenzeichnung
+#   gegenzeichnung  countersign      … countersigned→<old target>
+#                                         letters: countersigned→admission.contractCountersigned
+plexus-cli offer workflow node reads --dir <dir> --node gegenzeichnung   # $node.contract.contract, written in nodes.gegenzeichnung.contract
+jq '.graph.nodes[] | select(.type=="countersign")' <dir>/workflow.json
+```
+After publish, an application whose signed return the school accepted parks on the node;
+the team's queue shows „Vertrag gegenzeichnen", the family's portal „Die Schule zeichnet
+Ihren Vertrag gegen". After the upload the revision reads „3 von 3" and the family gets the
+letter (on a deployment that does not send mail: Dev Rail → „Mail").
+
+## Idempotency / gotchas
+- **The publish rules:** `[countersign/assign]` (no team), `[countersign/dueInDays]` (a whole
+  number ≥ 1), `[countersign/sourceNotCheckedContract]`, `[countersign/twice]` (one
+  countersignature per contract), `[address/missing]` (no `contract`),
+  `[address/unknownKey]` (a resolver contract produces `contract`, not `document`),
+  `[address/notVisible]` (the contract must lie on every path to the node),
+  `[notification/missingBinding]` (no `countersigned` letter; `--disabled` counts as missing).
+  Offline the letter catalog is not loaded: a misspelled template id fails only at
+  `offer apply --publish`.
+- **The letter moved:** `countersigned` is bound on the countersign node, not on the contract.
+  A bundle that still binds it on the contract is refused there (`[notification/unknownEvent]`)
+  — clear it with `node clear-notification --node contract --event countersigned`.
+- **`--title` needs `--title-en`** (every config text is `{ de, en }`); without both the row
+  is titled „Vertrag gegenzeichnen" / „Countersign the contract". `--assign-team`, `--title`,
+  `--title-en` and `--due-in-days` are refused on any other node type.
+- **The row closes only through the countersignature dialog**, never by a bare dispatch: the
+  engine moves the node only on the contract's `signed` event and refuses it while the contract
+  is not signed by every side („Der Vertrag ist noch nicht von allen Seiten unterschrieben."). Withdrawal and „Bewerbung ablehnen" sweep
+  the open row; nothing of the school is booked.
+- **The representative is whoever completes the row** — active staff of the tenant with a
+  name; nobody can book a colleague's signature.
+- **Migrating a bundle with the old shape** (a review „Gegenzeichnung" + task
+  `result: { kind: 'countersignature' }`): remove the task and the review
+  (`node task rm`, `node rm`), add the countersign node as above (team from the old
+  `assign.decision`, title / SLA from the task), move the letter, and re-key the progress
+  wiring from `reviewing` to `countersigning`.
+
+## Related
+- [Name what a node reads](./addresses.md) · [Add a workflow node](./add-workflow-node.md)
+- [Insert a node on one edge and rewire it](./insert-and-rewire-node.md) (`--on-edge`, `--progress`)
+- [Edit a live tenant's offer](./edit-live-tenant-offer.md)

package/dist/skill/references/offer/create-pedagogy-unit.md

@@ -0,0 +1,55 @@
+# Make a new school applyable (create a pedagogy unit)
+
+**When to use:** a brand-new school (or an existing plain unit) needs to host an
+admission offer, but `offer create --unit <unit>` fails because the unit isn't a
+*pedagogy unit* yet (no `pedagogy_units` bridge row). This creates the unit + bridge
+so the external "bewerben" portal can resolve it.
+
+## Prerequisites
+- A configured `plexus-cli` targeting the env (`--env local|staging|prod`).
+- A token with tenant-wide master-data access (creating units) +
+  tenant access (the bridge writer is tenant-gated).
+- An installed, current `plexus-cli` (`plexus-cli offer unit create --help`).
+
+## Steps
+```bash
+# 1a. Brand-new school: create the unit AND its pedagogy bridge in one step.
+#     The name is German AND English.
+plexus-cli --env <env> --tenant <slug> offer unit create --name "Grundschule Neustadt" --name-en "Neustadt Primary School"
+#     (--kind school by default; --parent <unit key> to nest; output prints the unitId)
+
+# --unit takes the unit's config key (`plexus-cli units` lists it) — never its
+# name. A unit made by `offer unit create` has no config key until config-as-code
+# adopts it: address it by its URL slug meanwhile (here: grundschule-neustadt).
+
+# 1b. OR upgrade an EXISTING plain unit to a pedagogy unit (idempotent).
+plexus-cli --env <env> --tenant <slug> offer unit ensure-pedagogy --unit grundschule-neustadt
+
+# 2. Now the offer can link it. (offer create/set --unit also ensures the bridge,
+#    so an existing non-pedagogy unit is upgraded automatically on link.)
+plexus-cli --env <env> --tenant <slug> offer create --slug gs-neustadt --title "Grundschule Neustadt" --title-en "Neustadt Primary School" --unit grundschule-neustadt
+```
+
+## Verify
+```bash
+plexus-cli --env <env> --tenant <slug> units                       # the unit shows pedagogic ✓
+plexus-cli --env <env> --tenant <slug> offer status --slug gs-neustadt   # program/pedagogy links resolve
+```
+
+## Idempotency / gotchas
+- **`ensure-pedagogy` is idempotent** — re-running returns the existing bridge
+  (`created: false`); it never inserts a duplicate.
+- **`offer create/set --unit` ensures-then-links** — you don't strictly need a
+  separate `ensure-pedagogy` step for an existing unit; the link path upgrades it.
+- **A unit needs a tenant legal entity.** `offer unit create` auto-resolves the
+  tenant's first legal entity; a tenant with none will fail loud (set one up first).
+- **Tenant-scoped, fail-loud.** The bridge writer (`programAdmin.ensurePedagogyUnit`)
+  verifies the unit belongs to the tenant; it never bridges a foreign unit.
+- **Config is authoritative for the flag.** Also set it in the tenant config
+  (`plexus-cli config set --tenant <slug> --target units --key <unitKey> --field pedagogyUnit --value true`),
+  or the next `config apply` of a config without it removes the bridge again — or,
+  once an offer is linked, fails with `[unit/pedagogyUnitInUse]`.
+
+## Related
+- [Author the manifest meta layer](./author-manifest-meta.md) · [Author a SmartForm as code](./author-smartform.md).
+- Command reference: `plexus-cli offer unit --help`.