@smartkomm/plexus-cli 0.0.0-stage → 0.1.1

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

package/dist/skill/references/offer/declare-node-reads.md

@@ -0,0 +1,99 @@
+# Declare what a document node reads
+
+**When to use:** a contract or offer letter is produced by hand and **uploaded**
+(a school without a contract generator), or a generated contract prints answers it does not bind.
+Such a node binds no form field, so without `reads` a correction on the child's
+name never holds it, and an issued contract does not protect the fields it
+printed. `reads` names those fields, each by its full address
+(`$node.<formNode>.admission.<field>` — the address names WHICH form): the readiness gate holds
+„Freigabe anfordern" / release / issue while one of them has an open correction
+or is empty where the form requires it, and once the document is issued they are
+**consumed** — a correction on them is refused until the document is rescinded.
+
+## Prerequisites
+- An offer bundle on disk: a **fresh export of the target environment**
+  (`offer export`) 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; any older copy can lag behind what is live (fields added
+  later are then refused as unknown).
+- Authoring is offline; `offer plan` / `offer apply` need a token for `--env`.
+- A bundle exported before addresses were introduced carries bare keys and is refused (`[address/bareIdentifier]`,
+  `[graph/retiredField]` for `wires`) — export it again. Model: [Name what a node reads](./addresses.md).
+
+## Steps
+```bash
+# 1. Export what is live (read-only).
+plexus-cli --env staging --tenant <slug> offer export --slug <offer-slug> --out ./bundle
+
+# 2. Declare the fields the document carries (replaces the list). Each entry is
+#    an address of the form node that CREATES the instance (here `form`) —
+#    entered or computed fields (a computed key such as derivedConstellation
+#    expands to the answers it is computed from). --address is repeatable and
+#    comma-separated (single quotes!); --from <formNode> --field <path>,… is the
+#    short form that composes the same addresses:
+plexus-cli offer workflow node set-reads --dir ./bundle --node contract \
+  --from form --field kind.firstMiddleNames,kind.surname,kind.geburtsdatum,derivedConstellation \
+  --address '$node.form.admission.elternteil_1.vorname,$node.form.admission.elternteil_1.nachname'
+
+#    Later edits:
+plexus-cli offer workflow node add-reads    --dir ./bundle --node contract --address '$node.form.admission.kind.homeAddress'
+plexus-cli offer workflow node remove-reads --dir ./bundle --node contract --from form --field kind.homeAddress
+plexus-cli offer workflow node set-reads    --dir ./bundle --node contract --clear
+
+#    A bare key (`--address kind.surname`, or `--field` without `--from`) is
+#    refused with the addresses visible at the node.
+
+# 3. Validate offline, then see what the apply would change.
+plexus-cli offer validate --dir ./bundle
+plexus-cli --env staging --tenant <slug> offer plan --dir ./bundle     # ~ workflow change + ~reads:contract +… (against the live head)
+
+# 4. Publish (a new workflow version).
+plexus-cli --env staging --tenant <slug> offer apply --publish --dir ./bundle
+```
+
+## Verify
+```bash
+plexus-cli offer workflow node list --dir ./bundle          # `reads` column: "30 Felder"
+plexus-cli offer workflow node reads --dir ./bundle --node contract   # every address, „geschrieben" in nodes.contract.reads.<i>
+plexus-cli --env staging --tenant <slug> offer plan --dir ./bundle          # everything "same", no ~reads rows
+plexus-cli --env staging --tenant <slug> offer export --slug <offer-slug> --out ./check
+jq '.graph.nodes[] | select(.id=="contract") | .reads | length' ./check/workflow.json
+```
+
+## Idempotency / gotchas
+- **Only new errors block.** The verb compares the bundle's errors before and
+  after the edit: an error the edit introduces (`[address/pathNotInTarget]` for a field
+  the form lacks, a repeated-block field, a duplicate, `[address/notVisible]` for a form that
+  does not run before the node, `[address/mixedForms]` for two forms in one list, `reads` on a
+  form/end node → `[readiness/readsNotGated]`) writes
+  nothing; an unrelated error the bundle already had (e.g. an undecided
+  assignment row) is printed as `⚠ vorbestehend` and does not stop the edit —
+  `offer apply --publish` will still refuse it.
+- **`add-reads` is rerunnable** (addresses already read are reported, not an error);
+  `remove-reads` fails on an address the node does not read.
+- **One form per list.** A node's `reads` is judged on ONE form instance; a second form's
+  fields in the same list are `[address/mixedForms]`. An adopting form node (`adoptForm`)
+  produces nothing — read the fields at the creating node's address.
+- **What to read:** exactly what the document prints — names, birth date,
+  address of the child and of every party that can sign, the answers that decide
+  who signs (the constellation), start date, fee answers. Not uploads, free text
+  or health data: every read field is **locked** once the document is issued.
+  A read field that the form does not currently require is never awaited.
+- **`[readiness/readsMissesPartyCondition]`** (warning, resolver documents only):
+  the contract's parties depend on answers neither read nor bound — add them
+  (or the computed constellation key).
+- **Running applications keep their pinned version.** Publishing does not give
+  applications already in flight the new `reads`; they stay on the version they
+  were pinned to. Either re-pin them, discard a test application
+  (`plexus-cli --env <env> applications discard-test <id>`, test applications only), or —
+  on a test environment — delete them all:
+  `plexus-cli --env staging config wipe --tenant <slug> --target applications`
+  (dry-run count first, then `--confirm`). A real application has no
+  per-application hard delete; its personal data go only by erasure
+  (`retention apply`, [Erase due applications](../retention/erase-due-applications.md)).
+- **Removing a form field that a node reads** fails the form's publish with
+  `[address/pathNotInTarget]` at the workflow — `remove-reads` it first.
+
+## Related
+- [Name what a node reads](./addresses.md) · [Edit a workflow node](./edit-workflow-node.md) · [Release an offer bundle](./publish-offer-bundle.md)
+- [Wipe tenant config/data](../config/wipe-tenant-config.md)
+- `plexus-cli offer workflow node set-reads --help` — the verb's flags

package/dist/skill/references/offer/edit-live-tenant-offer.md

@@ -0,0 +1,144 @@
+# Edit a live tenant's offer (prod is the source of truth)
+
+**Use it to** change anything about a live tenant's offer — close a Schuljahr, change
+capacities, edit the form, the workflow, the assignment rule, the resolver setup — and
+be sure prod ends up exactly as you meant, with nothing else rolled back.
+
+## The rule
+
+A live tenant's offer bundles and config exist **only on the server**. Prod is their
+only source of truth; there is no other copy that a deploy would apply. A copy kept
+somewhere else drifts: editing an old copy to close a Schuljahr changes nothing on prod,
+and applying it later can roll prod back. So every edit starts from a **fresh prod
+export** and ends with a **plan that shows only your change**.
+
+Working copies live in a **private scratch directory** (a temp dir, or a dated folder
+you keep for the session) — never in a shared or versioned place: a live tenant's
+bundle carries the school's data.
+
+## Steps
+
+```bash
+WORK=$(mktemp -d)                             # any private scratch dir
+T=<slug>; S=<offer-slug>                      # tenant slug, manifest slug
+
+# 1. Export what is live. ALWAYS pass --env (the default is prod) and --out
+#    (the default is ./offers/<tenant>/<slug> of the current directory).
+plexus-cli --env prod offer export --tenant $T --slug $S --out $WORK/$S
+#    The export has NO contract/ (resolver-setup.json + DOCX): to change the
+#    resolver setup, copy contract/ from the last rollout's working copy and
+#    prove it equals prod — every row `same`:
+#      plexus-cli --env prod resolver setup plan --tenant $T --file $WORK/$S/contract/resolver-setup.json
+cp -a $WORK/$S $WORK/$S.orig                  # keep the untouched export for the diff
+
+# 2. Edit bundle.yaml / manifest.json / workflow.json / smartforms/*.json in $WORK/$S
+#    (or with the offer verbs: offer form …, offer workflow node …, --dir $WORK/$S).
+diff -ru $WORK/$S.orig $WORK/$S               # exactly your change, nothing else
+
+# 3. Offline gate, then the remote diff. Read every row.
+#    The offline gate cannot see the tenant's catalog: a `pricedItem` task whose
+#    article is not assigned to the offer's program passes here and is refused
+#    only by the live publish ([taskResult/pricedItemNotInProgram]) —
+#    check the assignment under Finanzen → Artikel first.
+#    Nor does it run the signature-anchor rules: [contract/missingSignatureAnchors]
+#    and [contract/undeclaredPartyRole] come from the sealed revision's code + config against
+#    the form: the seal (`resolver setup apply`) checks the resolver names anchors at all,
+#    only the live publish checks every signer of the form. A green validate or plan proves
+#    nothing there. Changing the resolver: publish on staging first (below).
+plexus-cli offer validate --dir $WORK/$S
+plexus-cli --env prod offer plan --tenant $T --dir $WORK/$S
+
+# 4. Apply. --publish when the form or workflow changed (plan's `publish` row says
+#    PENDING); capacities, stages and runs need no publish.
+plexus-cli --env prod offer apply --allow-prod --tenant $T --dir $WORK/$S [--publish]
+
+# 5. Converged: every row `same`, publish `up to date`.
+plexus-cli --env prod offer plan --tenant $T --dir $WORK/$S
+```
+
+Tenant config (Stammdaten shape, roles, units, …) follows the same shape with the
+`config` verbs: `plexus-cli --env prod config export --tenant $T` into the scratch dir →
+edit → `config apply` (dry-run first) → `--confirm --allow-prod`. Recipe:
+[Update a tenant's config](../config/update-tenant-config.md).
+
+## Staging
+
+Staging gets a live tenant's offer **only by an explicit copy from prod** — nothing flows
+there on its own:
+
+```bash
+plexus-cli --env prod    offer export --tenant $T --slug $S --out $WORK/$S
+plexus-cli --env staging offer plan   --tenant $T --dir $WORK/$S
+plexus-cli --env staging offer apply  --tenant $T --dir $WORK/$S --publish
+```
+
+To try a change on staging first, apply the edited copy there, check it, then run the
+prod plan from the same directory — the prod plan still has to show only your change.
+
+A prod offer whose contract node uses `eSignature` publishes **externally** on the staging
+mirror only once the mirror tenant has an active signing connection a test reached
+(`[signing/noActiveProvider]`; `--stage internal` needs none — its test applications run on
+the simulator). On staging that connection is always the provider's sandbox with a
+redirect, never the school's production account; setting it up needs a platform operator.
+
+## What the address rows in `offer plan` mean
+
+Against the **live head** (not the draft), `offer plan` lists what the bundle changes at the
+addresses — display only, never a finding, the exit code stays 0:
+
+```
+~  address:$task.rang.rang          Knoten pruefung → freigabe     # the task moved to another node
++  address:$task.rang.rangSchule    neu (freigabe)                 # a key renamed = one added …
+-  address:$task.rang.rang          entfernt (pruefung)            # … and one removed
+~  reads:vertrag                    +$node.form.admission.kind.nachname −$node.form.admission.kind.vorname
+!  pinned                           3 Anmeldungen (2 echt, 1 Test) auf Fassung 7 bleiben auf ihrer Version — Umpinnen nur per Migration mit Abbildung
+```
+
+- Renaming a key or moving a task is **allowed** in a new version. Every application keeps
+  running on the version it pinned; the new version applies to applications started after the
+  publish.
+- The `pinned` row counts the applications on the live head. They are **not** moved: an
+  identity re-pin refuses a version whose addresses differ (topology hash). Moving them needs
+  a migration with a mapping (old address → new address) — that is platform code, not a CLI
+  verb; ask a platform operator before you publish if those applications must follow.
+- No rows at all: the bundle produces and reads the same addresses as the live head.
+
+## Gotchas
+
+- **Stop if the plan shows more than your change.** Extra rows mean prod moved since
+  your export, or your copy was not a fresh export. Re-export; never apply an older copy
+  (an earlier export, a backup): it can be behind prod in one place and ahead in
+  another, and apply rolls prod back where it is behind.
+- **A change that needs new platform code ships in two steps.** A resolver implementation,
+  a node type or a validator reaches prod with a platform release; only then apply the
+  bundle that uses it. Before the release, `offer plan --env prod` refuses it (e.g.
+  `extra field taxTreatment`, an unknown implementation key). Keep the edited copy in your
+  private scratch dir with a note saying which release it waits for.
+- **An export from before node ids lost their dots is refused** (`[graph/nodeIdFormat]` on
+  ids like `n.form`): prod data was already renamed on the server. Export again — never
+  rename ids by hand in an old copy.
+- **A config export from before the file-reference rename is refused**
+  (`[config/fileRefRenamed]`): its library files still say `fileName` / `size` and its brand
+  files `size` (now `filename` / `sizeBytes`). Pull a fresh `config export` — never rename
+  the keys by hand in an old copy. A CLI that already uses the new names refuses a server
+  that does not yet (`[cli/serverPredatesFileRef]`): use the CLI version that matches the server.
+- **`offer export` leaves out `contract/`.** The resolver setup file and its DOCX are
+  bundle data that exists only in the last rollout's working copy, not in the export. An
+  edit of the resolver setup starts from that copy, and `resolver setup plan` must show
+  every row `same` BEFORE you change anything — else the copy is not what prod runs.
+- **The signature-anchor rules are server-side only.** Every resolver names a line
+  for every party the form lets sign; a resolver that does not is refused at publish with
+  `[contract/missingSignatureAnchors]`, a form role the resolver does not declare with
+  `[contract/undeclaredPartyRole]`. `offer validate` and `offer plan` do not run them; the
+  seal checks only that the resolver names anchors at all, the publish checks every signer
+  of the form. A resolver change therefore goes through staging first (`offer apply
+  --publish` there), then prod.
+- **Close a Schuljahr per cell:** `capacities.<stage>.isOpen: false` on each cell of the
+  run. A run-level `isOpen` is only read when apply creates a new run
+  ([set-offer-capacities](./set-offer-capacities.md)).
+
+## Related
+
+- [Release an offer bundle](./publish-offer-bundle.md) — `offer status`, `--publish`, `--stage internal`
+- [Set an offer's seat capacities](./set-offer-capacities.md)
+- [Manage a contract resolver](../resolver/manage-contract-resolver.md) — `resolver setup plan|apply` before `offer apply --publish`

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

@@ -0,0 +1,121 @@
+# Edit a SmartForm in depth
+
+**When to use:** change an existing form beyond adding things — edit a field's
+validation/visibility/enum/docRef/consent props, edit an effect's wiring, reorder
+fields or sections, reparent a section, or edit/remove a repeated or computed field —
+then publish a new version.
+
+## Prerequisites
+- An offer bundle on disk carrying the form (`offer export …` or `offer init …`).
+- 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 form --help`).
+
+## Steps
+```bash
+# Form-level: rename / change school.
+plexus-cli offer form set --dir <bundle> --form <slug> --label "Neuer Titel" --label-en "New title"
+
+# Field: edit ANY editable prop (use "" to clear an expression / value).
+plexus-cli offer form field set --dir <bundle> --key kind.vorname \
+  --bucket kind --placeholder "Max" --placeholder-en "Max" --required-if "kind.nachname != null"
+plexus-cli offer form field set --dir <bundle> --key kind.geschlecht --enum-ref geschlecht   # swap inline→catalog
+plexus-cli offer form field set --dir <bundle> --key kind.nachweis --doc-mime application/pdf --doc-max-size 9000000
+plexus-cli offer form field set --dir <bundle> --key kind.attest --required-for sonderfall    # outcome-scoped required
+# Boolean as an explicit Ja | Nein answer (nothing preselected; drop any --default first,
+# publish refuses one: config.yesno-default). "" returns to the checkbox.
+plexus-cli offer form field set --dir <bundle> --key kind.allergien --presentation yesNo --default ""
+
+# Outcome: edit its output shape (replace; "" clears).
+plexus-cli offer form outcome set --dir <bundle> --id standard \
+  --fields kind.vorname,kind.nachname --effect-refs p.kind:applicant
+
+# Effect: edit per-kind props.
+plexus-cli offer form effect set --dir <bundle> --id p.kind --identity keyed --identity-key-from kind.vorname,kind.nachname
+plexus-cli offer form effect set --dir <bundle> --id rel.kindmutter --from p.kind --to p.mutter --rel-kind kind
+
+# Repeated / computed: set + rm (add via `offer form repeated|computed add`).
+plexus-cli offer form repeated set --dir <bundle> --key geschwister --max 3 --unique-by name
+plexus-cli offer form computed set --dir <bundle> --key kind.voll --expression "kind.vorname != null && kind.nachname != null"
+
+# Reorder + reparent (relative anchors; reparent with --parent "" → top-level).
+plexus-cli offer form field move   --dir <bundle> --key kind.nachname --before kind.vorname
+plexus-cli offer form field move   --dir <bundle> --key kind.ausweis --section section.kind --after kind.foto   # into another section
+plexus-cli offer form section move --dir <bundle> --id section.kind --to-top
+plexus-cli offer form section set  --dir <bundle> --id section.eltern --parent section.kind
+
+# Section visibility: only these teams / permission groups (plus admins
+# and the family) read the section's values; everyone else sees „Nur für …
+# sichtbar". Comma-separated keys; "" clears.
+plexus-cli offer form section set  --dir <bundle> --id section.financialDocs --visible-to finanzen
+
+# Validate + publish (publishing re-versions the form).
+plexus-cli offer validate --dir <bundle>
+plexus-cli --env <env> offer apply --publish --dir <bundle>
+```
+
+### English texts
+
+A SmartForm text is ONE field holding `{ de, en }` — `label`, `placeholder`,
+`helpText`, `description`; there is no `localized…` twin. Every verb that writes a German
+text takes the English in the same call: `--label-en` (form, section, field, outcome,
+repeated, scenario), `--placeholder-en`, `--help-text-en`, `--declaration-label-en` on
+fields and `--description-en` on scenarios.
+
+```bash
+plexus-cli offer form field add --dir <bundle> --section section.kind --key kind.vorname --type string \
+  --label Vorname --label-en "First name" --placeholder "z. B. Anna" --placeholder-en "e.g. Anna"
+plexus-cli offer form section set --dir <bundle> --id section.kind --label-en "Child"   # English only
+```
+
+**The rule:** a new text without its English is refused at the command
+(`[i18n/missingTranslation]`) — the reader's language picks the text with no fallback
+to German, so the publish gate refuses it anyway. The CLI never copies the German into
+`en`. Changing the German of a text whose English is a real translation refuses unless
+you pass the new English too; an English that is blank (a migrated text) or a copy of
+the German becomes blank, and `offer validate` names it until it is translated.
+`--label-en ""` is refused. A field, repeated block or outcome added without any label
+is named by its key in both languages (an identifier, not a German text).
+
+## Verify
+```bash
+plexus-cli offer form show --dir <bundle> --form <slug>   # props/order/repeated/computed reflect the edits
+plexus-cli offer validate --dir <bundle>                  # "local validation clean"
+```
+
+## Idempotency / gotchas
+- **Validate-before-write.** Every mutator runs the real publish gate first; on any
+  error (bad expression, unknown enum-ref, wrong-kind effect flag, reparent cycle,
+  move anchor missing) it writes **nothing**.
+- **Clearing.** Expression/string props clear with `""`; `--required-for ""`, `--map`
+  (fieldMap) replaces; repeated `--min/--max -1` clears; `--unique-by ""` clears.
+- **Per-kind effect flags fail loud.** Passing `--org-kind` to a `person` effect (etc.)
+  is rejected — no silent drop.
+- **Catalog checks stay server-side.** Effect `role`/`relKind`, fieldMap `to`, and a
+  custom-field target resolve against the **tenant catalog** at `apply --publish`, not
+  offline. `enum-ref` is the one catalog the CLI carries, so it's checked offline.
+- **Reorder is sibling-scoped.** `field move` reorders within the field's section;
+  `section move` reorders among siblings. `field move --section <id>` moves a field into
+  another section unchanged — same key, so its values and every address that names it stay
+  valid; never rm + add, which drops the field's settings and trips the field-key
+  gate. The anchor then names a field of the TARGET section; a section left empty stays
+  until `section rm`. Into a `--visible-to` section only an unbound field may move
+  (`section.visibleTo-party` refuses a `cf_value`). Moving a section under a new parent =
+  `section set --parent`.
+- **`--visible-to` is judged at publish.** `offer validate` checks the shape, nesting,
+  party-bound fields (`cf_value` → `section.visibleTo-party`) and expressions outside the
+  section that read its keys (`section.visibleTo-read-outside`); whether the key names a
+  team or permission group of the school (`section.visibleTo-unknown`) is checked only at
+  `apply --publish`. It applies to applications on the NEW revision — existing ones keep
+  the definition they were pinned to.
+- **Removing a field/section/repeated breaks publish stability.** `publishSmartForm`
+  refuses to drop a field key a prior published version had — the `rm` commands warn.
+- **Re-publishing = a new version.** `offer apply --publish` after edits cuts a new
+  `smart_form_versions` row (and the full-bundle path re-pins the workflow).
+
+## Related
+- [Author a SmartForm as code](./author-smartform.md) — the add-from-scratch flow.
+- [Author a form's test scenarios and context](./author-form-scenarios.md).
+- [Edit a workflow node](./edit-workflow-node.md) — rebind which form a node uses.
+- Command reference: `plexus-cli offer form --help`.