@smartkomm/plexus-cli 0.0.0-stage → 0.1.1

package/dist/skill/references/offer/workflow-default-channels.md

@@ -0,0 +1,69 @@
+# Author a workflow's default chat channels
+
+**When to use:** every application of an offer should start with a chat channel
+for a team combination (e.g. „Bewerbungsteam + Schulleitung"), in addition to the
+automatic channel each participating team already gets.
+
+Two kinds of channel exist in every application of a published version:
+
+| kind | where it comes from | editable? |
+|---|---|---|
+| automatic | one per team the process gives work to (`assign`, composed tasks, …) | no — follows the graph |
+| default | `graph.channels` in `workflow.json` | yes — this playbook |
+
+Both are read from the application's **pinned** workflow version at chat time. No
+row is written per application, so a new default channel reaches applications
+started on the next published version; running applications keep the channels
+of their version.
+
+## Prerequisites
+- An offer bundle on disk with a `workflow.json` (`offer export …` or `offer init …`).
+- Authoring is offline; `offer apply --publish` needs a token with the tenant's offer-configuration rights (a tenant admin has them).
+- Members are **permission-group keys** of the tenant (`plexus-cli --env <env> --tenant <t> users groups`
+  → `key`); the applicant group is not a team.
+
+## Steps
+```bash
+# What exists: automatic (read-only) + authored default channels.
+plexus-cli offer workflow channels list --dir <bundle>
+
+# Add one — the key is minted from the German label ONCE (here:
+# bewerbungsteam-schulleitung). The label is German AND English.
+plexus-cli offer workflow channels add --dir <bundle> \
+  --label "Bewerbungsteam + Schulleitung" --label-en "Admissions team + school leadership" \
+  --team bewerbungsteam --team schulleitung
+
+# Rename / re-staff in place — pass the key; a rename never duplicates. A German
+# rename always needs --label-en (the English is never copied from the German,
+# and a channel name without English is refused).
+plexus-cli offer workflow channels add --dir <bundle> --key bewerbungsteam-schulleitung \
+  --label "Aufnahme" --label-en "Admissions" --team bewerbungsteam --team schulleitung
+
+# Remove an authored one by key (verb: `channels rm`).
+
+# Release it.
+plexus-cli offer validate --dir <bundle>
+plexus-cli --env <env> offer apply --publish --dir <bundle>
+```
+
+The same section is editable in the workflow IDE: „Team-Verantwortliche" → tab
+„Kanäle" → „Kanal hinzufügen" (the same team picker as the cockpit chat's „+").
+
+## Verify
+- `offer workflow channels list` shows the entry with source `Standardkanal`.
+- After publish, start an application (e.g. convert an Interessent) and open its
+  cockpit: the chat rail carries a tab with the authored label.
+
+## Gotchas
+- **A single team the process already assigns is refused** (`[channels/duplicatesDerived]`)
+  — it has its automatic channel.
+- **Unknown team** (`[channels/unknownTeam]`) is only caught at `offer apply --publish`
+  (the offline validator has no tenant); the applicant group counts as unknown.
+- A channel's chat identity is its **team set**: a manual „+" channel on the same
+  teams is the same thread, and the authored label wins.
+- A permission group named by a default channel cannot be deleted while any
+  stored workflow version names it (`referenced-by-workflow`).
+
+## Related
+- [Edit a workflow node](./edit-workflow-node.md)
+- `plexus-cli offer workflow channels add --help` · `channels list` · `channels rm --key <key>`

package/dist/skill/references/resolver/manage-contract-resolver.md

@@ -0,0 +1,161 @@
+# Manage a contract generator
+
+**When to use:** Create or revise a tenant's TypeScript contract generator — or a combined generator over several of them — review scenarios, publish it, and pin an offer to that revision.
+
+## Prerequisites
+
+- A configured environment and tenant, with `finanzen_vertraege.contracts.manage`.
+- A contract template with an attached DOCX. Use `generator template upload` if needed.
+- A real tenant's source and configuration live in that tenant's data; work on them in a private scratch directory.
+
+## Steps
+
+Create a blank draft, or copy a concrete published revision:
+
+```bash
+plexus-cli --env local --tenant test generator template list
+plexus-cli --env local --tenant test generator create --key school-contract --name "Schulvertrag" --name-en "School contract" --contract-template-id <id>
+plexus-cli --env local --tenant test generator clone school-contract@2
+plexus-cli --env local --tenant test generator scaffold school-contract --out /tmp/generator.ts
+```
+
+For an existing source, export both the TypeScript and its manifest. Edit the source and the explicit article/grant ID lists in the manifest. Saving checks the exported revision number and refuses concurrent changes.
+
+```bash
+plexus-cli --env local --tenant test generator source export school-contract@3 --out /tmp/generator.ts
+plexus-cli --env local --tenant test generator source save school-contract@3 --file /tmp/generator.ts --manifest /tmp/generator.ts.json
+plexus-cli --env local --tenant test generator scenarios test school-contract@3 --input /tmp/input.json --json
+```
+
+A blank draft can use a manifest containing `id`, `expectedSourceRevision: 0`, `billingItemDefinitionIds` and `grantTemplateIds`. Read its ID with `generator show`. Source must be self-contained and export one default object with `inputSchema`, `parties`, `resolve(config, input)`, `previewDocument(config, input)` and `signatureSpots(config, input)`. Imports and host capabilities are unavailable. The metadata describes conditional fields; the functions may use arbitrary synchronous TypeScript logic.
+
+Review the result, including its signature declarations. Write `/tmp/reviewed.json` with the returned `sourceRevision` as `expectedSourceRevision`, `artifactHash`, and `scenarios: [{ key, input, expected }]`. `expected` is the entire returned `output`, including `contract` and `signatureSpots`. Keep explicit expected results: a test command never approves its observations automatically.
+
+```bash
+plexus-cli --env local --tenant test generator scenarios approve school-contract@3 --file /tmp/reviewed.json
+plexus-cli --env local --tenant test generator seal school-contract@3
+plexus-cli --env local --tenant test generator assign school-contract@3 --offer-version-id <wip-id> --node contract
+```
+
+Publish the WIP offer through the normal offer workflow. Existing applications retain their pinned generator revision. Archiving a revision hides it from new selections while existing pins remain executable.
+
+For one-file export/import on the same environment:
+
+```bash
+plexus-cli --env local --tenant test generator export school-contract@3 --out /tmp/generator.json
+plexus-cli --env local --tenant test generator apply /tmp/generator.json
+```
+
+The export includes source, manifests and reviewed scenarios. Apply saves a draft and checks imported expected results; it does not publish. IDs in this export belong to its environment.
+
+### Offer setup by stable catalog keys
+
+The existing `contract/resolver-setup.json` filename and `resolver` property remain the bundle format. A source-backed setup adds these fields under `resolver`:
+
+- `source`: a TypeScript file relative to the setup file.
+- `billingItemKeys`: every article the generator may emit, including conditional branches.
+- `grantTemplateKeys`: every grant template it may use. These must already exist in the catalog.
+- `scenarios`: reviewed `{ key, input, expected }` cases. A new revision cannot publish without them.
+
+Config and scenario values can use `{ "$billingItem": "article-key" }` and `{ "$grantTemplate": "grant-key" }` to reference declared entries. Prices retain the existing `{ "$config": "preise.key" }` reference. Template names and generator names are `{ de, en }`; `documentPlaceholderKeys` must match the DOCX.
+
+```bash
+plexus-cli --env local --tenant test generator setup plan --file /tmp/offer/contract/resolver-setup.json
+plexus-cli --env local --tenant test generator setup apply --file /tmp/offer/contract/resolver-setup.json
+plexus-cli --env local --tenant test offer plan --dir /tmp/offer
+```
+
+A setup that still names `implementation` can only copy a source already stored in that tenant's database. Ambiguous keys require cloning a concrete revision. New generators need no platform release.
+
+**Known gap — the first revision of a new setup file.** `generator setup apply` refuses a new revision without reviewed `scenarios`, yet their `expected` output only exists once the source is saved on a draft and evaluated there — and the setup file needs it with `{ "$billingItem": … }` / `{ "$grantTemplate": … }` references, not the IDs `generator scenarios test` prints. There is no intended path through the setup file. Today's workaround: give the file one scenario with a placeholder `expected`; `setup apply` creates the draft and saves the source, then the scenario approval re-executes the scenario and refuses the mismatch — the draft and its source stay. Evaluate each scenario input on that draft (`generator scenarios test <key>@<draft revision> --input <input.json> --json`), review the `output`, write it into the file as `expected` with every article/grant ID replaced by its reference, and run `setup apply` again — it overwrites that draft and seals. Alternatively take the documented manual route above (create → `source save` → `scenarios test` → `scenarios approve` → `seal`) and write the setup file from the sealed revision afterwards. Proposed fix: `generator setup apply --draft` (stop after the source save, no scenario requirement) plus `generator setup scenarios --write` (evaluate every scenario input on that draft and write `expected` back into the file with references, for review).
+
+## Combined generator
+
+A combined generator is a declaration, not code: one input mask and ordered parts, each pinning a **sealed** document revision by `key@revision`, mapping every part field to a mask field, an expression or a fixed value, optionally running only `when` an expression holds. It has no source, template, manifest or scenarios.
+
+Seal the part revisions first (the steps above). Then write the declaration file — easiest by exporting an existing combined revision (the test tenant has `school-with-care`) and editing it. The shape (abridged: a real part maps every field its generator requires — the server names each one missing):
+
+```bash
+plexus-cli --env local --tenant test generator combined export school-with-care@1 --out /tmp/combined.json
+```
+
+```json
+{
+  "formatVersion": 1,
+  "kind": "combined",
+  "key": "school-with-lunch",
+  "name": { "de": "Schulvertrag mit Mittagessen", "en": "School contract with lunch" },
+  "description": { "de": "", "en": "" },
+  "inputSchema": { "fields": [
+    { "key": "startDate", "label": { "de": "Beginn", "en": "Start" }, "type": "date", "required": true },
+    { "key": "ganztag", "label": { "de": "Mit Hort", "en": "With after-school care" }, "type": "boolean", "defaultValue": false },
+    { "key": "lateCare", "label": { "de": "Spätbetreuung", "en": "Late care" }, "type": "boolean", "defaultValue": false, "visibleIf": "ganztag == true" }
+  ] },
+  "parts": [
+    { "partKey": "school", "generator": "school-contract@1",
+      "inputs": [ { "field": "startDate", "source": { "from": "field", "field": "startDate" } },
+                  { "field": "admissionFeeMode", "source": { "from": "fixed", "value": "standard" } } ] },
+    { "partKey": "care", "generator": "after-school-care@1", "when": "ganztag == true",
+      "inputs": [ { "field": "pickupTime", "source": { "from": "expression", "expression": "if (lateCare == true) '18:00' else '16:00'" } } ] }
+  ]
+}
+```
+
+A file **without `id`** creates the draft of a new key and saves the declaration in one step; a refused declaration removes that empty draft again, so fix the file and save once more. A file **with `id`** (every export) targets exactly that revision, guarded by its `expectedSourceRevision`:
+
+```bash
+plexus-cli --env local --tenant test generator combined save /tmp/combined.json
+plexus-cli --env local --tenant test generator combined plan school-with-lunch@1 --input /tmp/mask-input.json --strict
+plexus-cli --env local --tenant test generator seal school-with-lunch@1
+```
+
+To revise a sealed combined revision, clone it, export the draft, edit, save, seal:
+
+```bash
+plexus-cli --env local --tenant test generator clone school-with-care@1
+plexus-cli --env local --tenant test generator combined export school-with-care@2 --out /tmp/combined.json
+plexus-cli --env local --tenant test generator combined save /tmp/combined.json
+plexus-cli --env local --tenant test generator seal school-with-care@2
+```
+
+`generator combined create --key … --name … --name-en …` makes an empty draft (no mask, no parts) when you prefer to start from the workspace's editor. `plan` is the sandbox's „Positionen“ tab: which parts run for a mask input, the fields each still misses, and its roster issues; a refused input (a `when` that is no boolean) exits with the refusal. Like `generator test` it is a sandbox and exits 0 with fields missing; `--strict` exits 1 when the input would not generate (a missing field, an undecided part, a roster issue, a part's refusal), each named on stderr — for scripts and checks. The PDFs per part come from the workspace.
+
+Pin it on a contract node like a document generator: the node's `resolver: { key, revision }` in the bundle (or `generator assign`), the reserved Träger as the node literal `inputs.traeger`, then `offer plan` and `offer apply --publish`. Write only `key` and `revision`: `offer plan|apply` stamp the pin from the environment the way publish does (mask, capacities, `parts`), so the node's `$node.<n>.contracts` resolves offline — no hand-made stamp. `offer validate` alone cannot know the kind and warns `[resolver/pinNotStamped]`. One „Erzeugen“ makes one contract per running part (a generation group), issued and signed together in one Vorgang.
+
+- **No change, no write.** `save` of an unedited export prints `outcome: unchanged` and writes nothing; only the names changed → `renamed` (names are renamable at any status); otherwise `saved` (a new `sourceRevision`).
+- **The server judges the declaration.** `save` and `seal` refuse with every gap named — `[generator/combinedDeclaration] …` (a required part field without a source, a type or option that does not fit, a `requiredIf` the mask cannot settle, an impossible roster, a priced mask field no part reads), `[generator/kindChange]` (a key that is already a document generator), the concurrent-save conflict. The CLI prints them verbatim; it does not pre-check.
+- **Parts are pinned, never "newest".** `"generator": "school-contract"` without `@revision` is refused by the file reader. A part must be a sealed document revision when the combined one seals; an archived part blocks the seal, and a part used by a combined revision cannot be archived (`[generator/partInUse]`).
+- **IDs belong to their environment.** An exported `id` only saves on the environment it came from; to bring a declaration to another environment, drop `id`/`expectedSourceRevision`/`revision`/`status` and save it there as a new key (or clone + export there and copy the `inputSchema` and `parts`).
+- `generator export` / `generator source export` on a combined revision refuse and point to `generator combined export`; `show`, `list`, `usages`, `runs`, `clone`, `seal`, `archive`, `restore` and `delete-draft` take either kind.
+
+## Verify
+
+```bash
+plexus-cli --env local --tenant test generator list
+plexus-cli --env local --tenant test generator show school-contract@3 --json
+plexus-cli --env local --tenant test generator usages school-contract@3
+plexus-cli --env local --tenant test generator runs school-contract@3
+```
+
+Also inspect the marked PDF and positions in the contract-template workspace. Scenario evaluation does not require the PDF converter; PDF preview does.
+
+## Idempotency / gotchas
+
+- Source is compiled in a Node action and executed in QuickJS-WASM inside the Convex transaction. No database, network, filesystem, environment, timers, randomness or ambient clock reaches the guest. Input and output are bounded JSON; CPU, memory and stack are bounded.
+- Published source, compiler artifact, interpreter identity, bootstrap hash and execution limits are frozen. A compiler/runtime change requires a reviewed new revision or an explicit audited migration. Display names remain renamable.
+- Saving source/configuration or removing a scenario invalidates approval. A changed DOCX requires renewed review. Publishing rechecks every expected result against current resolved inputs.
+- Optional `articleDecisions` output entries explain inclusion/omission. When supplied, they must cover the declared article manifest exactly and agree with actual lines. The editor shows when explanations are absent.
+- Article reverse links come from the finite manifest, so conditional possibilities remain visible even when an example omits them.
+- Signature captions must exist in the PDF. Publication checks declarations; rendering verifies their locations.
+- Prices still come from the pricing kernel. Override lines need a price version for currency. Grants, parties and payer allocations pass the normal tenant and commercial validation before materialization.
+- Historical signed snapshots are never rewritten during the table/source migration. An unavailable historical source remains explicitly unavailable; it is never re-pinned to different code.
+- Production writes need an explicit environment and `--allow-prod`; this playbook does not authorize them.
+- To build on an existing generator's code (a second school's variant of a contract), start from `generator clone` or `generator source export`. If you author it as several modules, bundle them into the one self-contained source first (e.g. esbuild with `bundle: true, format: "esm", target: "es2020"`) — `generator source save` refuses imports. The guest has no `Intl` and throws on it: replace every `toLocaleString` with hand-written German formatting. Run `generator scenarios test` on the draft before approving.
+- Fee groups are part of a source manifest (`feeGroups`, with bilingual names and article IDs). In a setup file use `resolver.feeGroups: [{ key, name: { de, en }, billingItemKeys }]`; every member must also be in `resolver.billingItemKeys`. Source export/apply round-trips groups. The catalog has no `plans` section; declare article availability in `billingItems[].programs`. Workflow prices use `pricedGroup` and `derive.group`, resolved through pinned generator revisions.
+
+## Related
+
+- `plexus-cli generator <verb> --help` for every verb above
+- [Set up a billing catalog and Word templates](../config/set-up-billing-catalog.md)
+- [Edit a live tenant offer](../offer/edit-live-tenant-offer.md)
+- [Release an offer bundle](../offer/publish-offer-bundle.md)

package/dist/skill/references/retention/erase-due-applications.md

@@ -0,0 +1,99 @@
+# Erase applications past their retention period
+
+**When to use:** on the monthly erasure date (below), or as soon as the weekly
+GlitchTip warning „[retention] applications past their retention period await
+erasure" names a tenant. Plexus erases nothing on its own: an
+application whose retention period has ended stays, with all its personal data,
+until someone runs this recipe.
+
+> **The DSGVO duty behind it.** Storage limitation (Art. 5(1)(e) DSGVO) requires
+> deleting personal data once its purpose and retention period have ended. Since
+> erasure is no longer automatic, it happens only if a person does it, deliberately
+> and regularly:
+>
+> - **Who:** the Plexus platform operator (the maintainer, or whoever holds a
+>   `_platform.tenants.accessAll` token for prod), on behalf of the schools.
+> - **How often:** **monthly**, on the first working day, for **every** tenant on
+>   prod; additionally within a week whenever the weekly warning appears. The
+>   shortest retention period is 180 days, so a monthly run keeps any application at
+>   most about a month past its date.
+> - **Record:** keep the `--json` output of each `apply` run (date, tenant, ids) in
+>   your operations log, one directory per run (e.g. `retention-<date>/`). Plexus
+>   stores no "who erased" row yet: the application only carries `redactedAt`.
+
+## What is due
+
+The rule lives in one place on the server (`retentionDueAt`):
+an application is due when it has ENDED (`endedAt` set) and `RETENTION_DAYS` of its
+classification have passed since. The classification follows its outcome:
+
+| outcome | classification | kept for |
+|---|---|---|
+| approved | admitted | 3650 days (10 years) |
+| rejected | rejected | 180 days |
+| withdrawn | withdrawn | 365 days |
+| expired | expired | 180 days |
+| waitlist | waitlist | 730 days |
+| none | unknown | 365 days |
+
+Test applications and soft-deleted ones („gelöscht") are listed too — both still hold
+personal data. A still-running application is never due, even if soft-deleted.
+
+## Prerequisites
+
+- `plexus-cli` with a platform-operator token for the target env (check the
+  connection with `plexus-cli --env prod config show` and `plexus-cli --env prod whoami`);
+  both functions need `_platform.tenants.accessAll`.
+- The tenant slug (`plexus-cli --env prod platform tenants`).
+
+## Steps
+
+```bash
+# 1. Read-only: what is due in this tenant. Note the number of rows.
+plexus-cli --env prod --tenant <slug> retention plan
+
+# 2. Dry run of the erasure — prints the same list, erases nothing.
+plexus-cli --env prod --tenant <slug> retention apply
+
+# 3. Erase. --expect is the count from step 1: if the server now finds a different
+#    number of due applications, nothing is erased and you read the plan again.
+mkdir -p retention-$(date +%F)
+plexus-cli --env prod --allow-prod --tenant <slug> retention apply --confirm --expect <n> --json \
+  > retention-$(date +%F)/<slug>.json
+```
+
+Repeat for every tenant `platform tenants` lists.
+
+## Verify
+
+```bash
+plexus-cli --env prod --tenant <slug> retention plan   # → no rows
+```
+
+An erased application keeps its row and its decision log (`application_events`);
+its answers, documents, chat texts, access log and stored mail bodies are gone, and
+`redactedAt` is set (server function `_redactApplicationCore` holds the full list).
+
+## Gotchas
+
+- **Erasure cannot be undone.** Read the plan first; there is no restore.
+- **The server decides, not the list.** `retention:eraseDue` refuses an application
+  that is not due, belongs to another tenant, or is already erased. A refusal stops the
+  run; its message (stderr, not the `--json` file) names the ids erased before it —
+  copy them into the record, rerun `plan` and continue.
+- **A different count erases nothing.** Someone ended an application between `plan` and
+  `apply`, or another operator erased some — read `plan` again and confirm the new count.
+- **Writes need `--env` named; prod needs `--allow-prod`** (`retention apply` is a
+  `confirm` command, its dry run counts as a read).
+- **One request for one person** (Art. 17, a family asks to be erased now) is not this
+  recipe: that is „Bewerbung löschen" on the single application
+  (`admission.redactApplication`), independent of any period.
+
+## Related
+
+- Weekly report: `retentionDueReport` (server cron „retention due report",
+  Mondays 03:00 UTC) — a GlitchTip `warning`, `area: admission.retention`, tags
+  `tenantSlug`, `dueCount`, `testDueCount`; a tenant whose read failed reports as an
+  `error` with `errorClass: scanFailed`.
+- What an erasure removes from the access log is defined in the platform's logging
+  concept (Protokollierungskonzept, § 6); ask the platform operator for it.

package/dist/skill/references/retention/erase-due-parties.md

@@ -0,0 +1,107 @@
+# Delete persons past their school's deletion rule
+
+**When to use:** together with the monthly erasure of applications
+([erase-due-applications.md](./erase-due-applications.md)), or as soon as the
+weekly GlitchTip warning „[retention] persons past their tenant's deletion rule
+await erasure" names a tenant. Plexus deletes nobody on its own: a
+school switches a deletion rule on („Rollen" → „Löschregel"), and a person the
+rule reaches stays, with all its data, until someone runs this recipe.
+
+> **The duty behind it.** A school that switched the rule on has decided that
+> master data without an active role is kept only for its waiting period
+> (storage limitation, Art. 5(1)(e) DSGVO). Since deletion is not automatic,
+> it happens only if a person does it:
+>
+> - **Who:** the Plexus platform operator (whoever holds a
+>   `_platform.config.manage` token for prod — the right of the other person
+>   hard delete, `stammdaten persons purge`).
+> - **How often:** **monthly**, on the first working day, for every tenant with a
+>   rule; additionally within a week whenever the weekly warning appears.
+> - **Record:** keep the `--json` output of each `apply` run in
+>   your operations log, one directory per run (e.g. `retention-<date>/`). A deleted person
+>   leaves a `party_role_events` row per role it held (actor: the operator) —
+>   and nothing else; the run's output is the record of who it was.
+
+## What is due
+
+The rule (`tenants.partyRetention`: waiting period in days, optionally a former
+leaf role) and the deadline live in one place on the server (`retentionDeadlineFor`): a person with no active or future
+role, not a draft, is due the waiting period after the latest of its creation,
+its last role change, its last role end and the rule's save time.
+
+Due is not deletable. The hard delete (rule `retention`) refuses a person that
+
+- any application names or binds — finished and erased ones included,
+- is linked to a user account,
+- a receipt holds (contract, invoice, signature, …),
+- has more than 1000 history rows or 200 role periods.
+
+`plan` asks the server this for every due person and shows the reason as
+`blocked: …`; `apply` skips those. Blocked persons stay due — the weekly warning
+counts them apart (`blockedCount`) and raises nothing for them alone.
+
+## Prerequisites
+
+- `plexus-cli` with a platform-operator token holding `_platform.config.manage`
+  (check with `plexus-cli --env prod whoami`).
+- The tenant slug (`plexus-cli --env prod platform tenants`). A tenant without a
+  switched-on rule answers `plan` with „hat keine eingeschaltete Löschregel".
+
+## Steps
+
+```bash
+# 1. Read-only: who is due, and who of them may be deleted. Count the
+#    `would-erase` rows (blocked ones do not count).
+plexus-cli --env prod --tenant <slug> retention parties plan
+
+# 2. Dry run — the same list, deletes nothing.
+plexus-cli --env prod --tenant <slug> retention parties apply
+
+# 3. Delete. --expect is the would-erase count from step 1: if the server now
+#    finds a different number of deletable persons, nothing is deleted.
+mkdir -p retention-$(date +%F)
+plexus-cli --env prod --allow-prod --tenant <slug> retention parties apply --confirm --expect <n> --json \
+  > retention-$(date +%F)/<slug>-parties.json
+```
+
+## Verify
+
+```bash
+plexus-cli --env prod --tenant <slug> retention parties plan   # → only blocked rows, or none
+```
+
+A deleted person is gone with its values, relationships, unit placements, value
+and role history and the stored files only it held (the party-file rule; a file another person or a form still
+names stays).
+
+## Gotchas
+
+- **Deletion cannot be undone.** Read the plan first; there is no restore.
+- **The server decides, not the list.** `partyRetention:eraseDue` refuses a person
+  of another tenant, one not (yet) due, a switched-off rule, and every block above.
+  A refusal stops the run; its message (stderr) names the persons deleted before it
+  — copy them into the record, rerun `plan` and continue.
+- **A different count deletes nothing — but the count is not the list.** A role ended,
+  the rule changed or another operator ran it between `plan` and `apply` — read `plan`
+  again. If one person dropped out and another became due in between, the count still
+  matches and `apply` deletes the newcomer: the server still checks each one is due.
+- **One person too large for one transaction stops the whole plan.** A deletion plan
+  above the relation engine's budget (`MAX_PLAN_ROWS` rows or the index-read cap) is
+  a bug-class error, not a block — `plan` aborts with `[relations] deletion plan
+  exceeds …` naming the person, and the weekly report marks the tenant `scanFailed`.
+  Review that person by hand (`stammdaten persons purge` after a soft delete, or
+  split its data) before the rest can run.
+- **Soft-deleted persons („gelöscht")** are due like any other and marked so.
+- **One person now** (staff deleted someone and the family asks for erasure) is
+  not this recipe: [`stammdaten persons purge`](../stammdaten/purge-deleted-person.md).
+- **Writes need `--env` named; prod needs `--allow-prod`.**
+
+## Related
+
+- Weekly report: `partyRetentionDueReport` (server cron „party retention
+  due report", Mondays 03:20 UTC) — a GlitchTip `warning`, `area: stammdaten.retention`,
+  tags `tenantSlug`, `dueCount` (deletable), `blockedCount`, `testDueCount` (persons only
+  test applications name or bind; today always blocked); a tenant whose read failed
+  reports as an `error` with `errorClass: scanFailed`. It shares its shape with the
+  applications' report.
+- The rule and its UI: „Rollen" → „Löschregel" in the school's settings.

package/dist/skill/references/roles/migrate-parent-assignments.md

@@ -0,0 +1,31 @@
+# Migrate direct assignments from a parent role
+
+Use this when a tenant already has direct assignments to a role that has children.
+The party detail marks these assignments invalid. Choose a descendant leaf whose
+meaning fits the existing records; create a neutral leaf through the tenant
+configuration first if the existing leaves imply facts you cannot verify.
+
+1. On staging, inspect `admin:roleConfiguration` and obtain the source and
+   destination role IDs. Check the source count with
+   `admin:roleAssignmentMigrationImpact` (counts above 2,000 are capped).
+2. Dry-run and apply the tenant configuration for any new destination role using
+   [Update a tenant's config](../config/update-tenant-config.md). Add a search
+   filter option if staff need to find the migrated parties.
+3. Once the app revision containing `admin:migrateRoleAssignmentsBatch` is live,
+   call it repeatedly until it returns `{"migrated":0}`:
+
+   ```bash
+   plexus-cli call admin:migrateRoleAssignmentsBatch --kind mutation --env staging \
+     client=<tenant> sourceRoleId=<parent-role-id> targetRoleId=<leaf-role-id> --json
+   ```
+
+   Each call moves at most 50 assignments, preserves dates and unit scope, and
+   writes role-change events. It rejects a target outside the source subtree,
+   a target with children, or overlapping assignments already on the target.
+   If a call fails, inspect the conflict rather than retrying it unchanged.
+4. Verify source count is zero, spot-check affected party details and search,
+   then repeat the configuration and migration against production. Export
+   production's own configuration first; never apply a staging snapshot blindly.
+
+The command requires `administration.roles.manage` for the tenant. Run it under
+an authenticated operator so each event records who made the change.

package/dist/skill/references/signing/README.md

@@ -0,0 +1,113 @@
+# Signing (e-signature) — `plexus-cli signing …`
+
+The CLI surface of the **Signaturvorgang**: one frozen contract revision
+(`contract_snapshots`) ↔ one process at a provider, driven by a fixed backend
+state machine. Two remote providers, `docusign` and `insign`, plus the paper
+path. Setting up a school's provider account:
+[connect-a-school.md](./connect-a-school.md); rotating the platform key:
+[rotate-the-key.md](./rotate-the-key.md).
+
+Every command needs `--tenant <slug>` and a caller holding
+`finanzen_vertraege.contracts.manage` on that tenant (the platform operator
+tokens do; `plexus-cli whoami` shows who you are).
+
+## The school's connection
+
+A provider account belongs to the SCHOOL, not to the deployment: each
+tenant has at most one connection per provider and at most ONE active one — the
+provider its contracts go out through. Setting one up is a platform act; the
+recipe is [connect-a-school.md](./connect-a-school.md). The `test` tenant gets an
+inSign sandbox connection out of the box, active, redirected to
+`admin@plexus.swop.schule`.
+
+```bash
+plexus-cli signing connection show --env local --tenant test                  # no network
+plexus-cli signing connection test --provider insign --env local --tenant test # reaches the account
+```
+
+`show` prints `E-Signatur: <Anbieter>|keine`, then one row per provider: `state`
+(`platform_unconfigured ▸ incomplete ▸ unverified ▸ failing ▸ ready`), whether it
+is active, the environment, the non-secret settings, the redirect, which secrets
+are held (name · fingerprint · when — never the value), the last test and what
+keeps it from `ready`. `test` reaches the account (DocuSign: JWT grant → token →
+userinfo, and on `consent_required` the URL the school's sender must open once;
+inSign: server version + owner), records the result on the connection and exits
+1 when it fails. A contract goes out only through a connection a test has
+reached since its last change (`ready`, or `failing` after an earlier success).
+
+## Send a revision for signature
+
+```bash
+plexus-cli signing list  --env local --tenant test                      # existing requests
+plexus-cli signing start --env local --tenant test --snapshot <contract_snapshots id>
+plexus-cli signing show  <signingRequestId> --env local --tenant test
+```
+
+`start` validates (an active connection that has been tested, PDF, latest
+revision, every declared signer has an e-mail — and for inSign a DISTINCT one
+each, no open request on the revision, not already signed), inserts the request
+as `pending` with the connection stamped on it, and schedules the provider call.
+A few seconds later `show` reads `sent` + the `providerRef`; a refusal reads
+`failed` with the provider's own message (DocuSign: `ANCHOR_TAB_STRING_NOT_FOUND`
+when the PDF lacks the `/unterschrift:<role>:<n>/` markers; inSign: "refused the
+signer invitation").
+
+There is no `--provider`: the school's active connection decides, and a Vorgang
+keeps talking to the account it started on even after the school switches.
+
+On a demo/sandbox account every recipient is redirected to the connection's
+redirect address (`show` prints the original address per signer). For inSign the
+redirect is sub-addressed per recipient (`…+s1@`, `…+s2@`), because it
+identifies an external user BY the address.
+
+## Bring the answer back
+
+```bash
+plexus-cli signing reconcile <signingRequestId> --env local --tenant test
+plexus-cli signing show      <signingRequestId> --env local --tenant test
+```
+
+`reconcile` re-reads the process from its provider and applies it — the return
+path on local dev (no public webhook). On staging/prod the callback + the
+15-minute poll cron do this without anyone; `reconcile` is for "now". A
+`completed` process stores the signed PDF + the completion certificate
+(DocuSign's Certificate of Completion, inSign's Signaturprotokoll — URLs in
+`show`) and writes one `signatures` row per signer, dated by the PROVIDER.
+
+## Correct course
+
+```bash
+plexus-cli signing void   <signingRequestId> --reason "Neuer Vertrag folgt" --env local --tenant test
+plexus-cli signing resend <signingRequestId> --party <partyId>              --env local --tenant test
+```
+
+`void` ends the request (`voided`) and the row keeps YOUR reason, whether or not
+the provider records one of its own. The contract may then be regenerated /
+re-frozen and sent again. While a request is open, freezing a new revision is
+refused (regeneration freeze).
+
+`resend` reminds one recipient on DocuSign. inSign has no per-recipient resend —
+it reminds every open recipient of the session at once, which is what the caller
+means anyway.
+
+## Verify
+
+- `signing show` → `status`, per-signer `status`/`signedAt`, artefact URLs, the
+  provider webhook `receipt …` rows recorded for the request (evidence, not business
+  events — the contract's history is `contract_events`).
+- `plexus-cli call contractSnapshots:listRevisions '{"client":"test","contractId":"…"}'`
+  → `signerCount` / `signedAt` reflect the written `signatures`.
+
+## Gotchas
+
+- `--snapshot` takes the **contract_snapshots** id (the revision), not the
+  contract id. `signing list --contract <id>` shows the requests of a contract.
+- A request on an older revision (not the contract's latest) is refused — freeze first, then start.
+- The DocuSign demo account watermarks documents ("Demonstration Document Only")
+  and may sit in a US region: never put real family data through it. inSign's
+  sandbox is worse in one respect — its credentials are PUBLISHED by the vendor,
+  which is why a sandbox connection cannot be saved without a redirect address.
+- `signing start` answers "hat keinen Anbieter … aktiviert" or "nicht erfolgreich
+  getestet": run `signing connection show`, then `signing connection test`.
+- An inSign process that has expired still reads `sent`: inSign cannot report
+  expiry, and guessing would end a Vorgang that is still live. Withdraw it.