@smartkomm/plexus-cli 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,69 @@
+# Make a task close with an appointment („Termin vereinbaren")
+
+**Use it to** turn a workflow-step task such as „Termin für das Kennenlerngespräch
+vereinbaren" into one that is completed by entering an appointment: date,
+time, duration, place and host. Completing it books the appointment at the
+application, mails the family (portal owner) date/time/place with a `termin.ics`
+calendar file, frees the task it
+`blocks`, and lists the appointment under „Anstehende Termine" on the staff dashboard.
+
+## The declaration
+
+On the task (a composed `kind: "task"` in the node's `tasks`):
+
+```json
+{
+  "key": "termin",
+  "kind": "task",
+  "title": { "de": "Termin für das Kennenlerngespräch vereinbaren", "en": "…" },
+  "assign": { "group": "schulverwaltung" },
+  "blocks": { "templateKey": "gespraech" },
+  "result": {
+    "kind": "appointment",
+    "title": { "de": "Kennenlerngespräch", "en": "Introductory talk" },
+    "durationMinutes": 45
+  }
+}
+```
+
+- `result.title` is the **neutral** title the family's letter and every calendar file
+  carry — never a family name.
+- `durationMinutes` (5–480) prefills the dialog; staff may change it per appointment.
+- Publish refuses: an unknown `kind` (`[taskResult/unknownKind]`), a result on an
+  approval (`[taskResult/onApproval]`), a title missing `de` or `en`
+  (`[taskResult/appointmentMissingTitle]`), a bad duration
+  (`[taskResult/appointmentInvalidDuration]`), a stray field
+  (`[taskResult/unknownField]`). `offer validate` catches all of them offline.
+
+## With the CLI
+
+One spelling, the same verb as every other task result — no `:`-separated
+free text, so a title may contain a colon:
+
+```bash
+plexus-cli offer workflow node task add --dir $WORK/$S --node kennenlernen --key termin \
+  --title 'Termin für das Kennenlerngespräch vereinbaren' --team schulverwaltung --due-in-days 3 \
+  --blocks gespraech \
+  --result appointment --duration 45 \
+  --result-title 'Kennenlerngespräch' --result-title-en 'Introductory talk'
+# change later: node task set … --duration 60 / --result-title '…'
+plexus-cli offer workflow node list --dir $WORK/$S
+```
+
+Then the usual live-tenant path ([Edit a live tenant's offer](./edit-live-tenant-offer.md)):
+`offer validate` → `--env prod offer plan` → `--env prod offer apply --allow-prod --publish` → plan
+again until every row is `same`.
+
+## Gotchas
+
+- **Running applications keep their pinned graph.** An application already sitting on
+  the node with an open `termin` row keeps its old declaration until it is re-pinned;
+  new entries into the node get „Termin vereinbaren" in the action bar.
+- **Staff books it from the action bar** („Termin vereinbaren"), like every task; the
+  dialog names every missing field, refuses a slot more than two years ahead, and
+  closes with a toast. In the Testmodus the shortcut „<Aufgabe> (Test): Termin morgen
+  10:00" books through the same verb.
+- **No portal owner, no mail.** An application staff created has no portal account; the
+  appointment is saved and the toast warns „Keine Mail an die Familie …". The same
+  happens when the school's outgoing mail is off.
+- The zone is the tenant's (`Europe/Berlin` for every DACH tenant today).

package/dist/skill/references/offer/task-family-request.md

@@ -0,0 +1,69 @@
+# Let a task ask the family and wait for its answer („Nachforderung")
+
+**Use it to** turn „Nachforderung: auf Unterlagen der Familie warten" from a task the
+team closes by hand into one that asks the family itself and completes itself the
+moment the family sends. The family gets the field in its task „Offene Felder beantworten" in the portal
+(the task letter `applicant.tasksOpen`, the task's deadline, a reminder before it); the
+team's task waits and holds the decision until then. Nobody ticks it off.
+
+## The declaration
+
+On a task that a `spawnTasks` optional action references (and only there; at most
+one such task per action):
+
+```json
+{
+  "key": "unterlagenAnfordern",
+  "kind": "task",
+  "title": { "de": "Nachforderung: auf Unterlagen der Familie warten", "en": "Follow-up: waiting for the family's documents" },
+  "assign": { "group": "bewerbungsteam" },
+  "params": { "dueInDays": 7 },
+  "familyRequest": {
+    "fields": [{ "scope": "node", "owner": "form", "key": "admission", "path": "kind.weitereUnterlagen" }]
+  }
+}
+```
+
+- **What is asked is chosen at the click.** Pressing the action opens a dialog: the
+  presser ticks the fields and writes the text the family reads. The text becomes the
+  note at each asked field — in the portal and in the task letter.
+- Exactly one of `fields` (the fields offered, each a full address
+  `$node.<formNode>.admission.<field>` — one form) or `from` (the form instance
+  `$node.<formNode>.admission`: every file field (`docRef`) of that form is offered). There
+  is no default form: an empty `familyRequest` is refused. A **free upload** is a `docRef` field
+  with `docRefConstraints: { multiple: true }` („Weitere Unterlagen") — the field must
+  exist in the application's form version.
+- `params.dueInDays` is the family's deadline and the task's.
+- Put the action into the decision's `requiresOneOf` if the decision should wait for it.
+
+## CLI
+
+```bash
+plexus-cli offer workflow node task set --dir <dir> --node decision --key unterlagenAnfordern \
+  --due-in-days 7 \
+  --family-request-fields '$node.form.admission.kind.weitereUnterlagen'
+  # or --family-request-from '$node.form.admission': every file field of that form
+plexus-cli offer validate --dir <dir>
+```
+
+Remove with `--clear-family-request`. The task must not carry `result`, `when`,
+`locksEvidence` or `blocks` (and nothing may block it) — `offer validate` names each.
+
+## Verify
+
+1. Cockpit: press the action → the dialog offers the fields; tick one, write the text,
+   „Anfordern" → the task shows the clock (system-closed), the decision buttons read
+   „Wartet auf: …".
+2. Portal `/e`: „Offene Felder beantworten" (field under „Nachzureichen"), the text at the field, „bis <Datum>".
+3. Upload and send as the family → the task is `done`, the decision buttons are free.
+
+## Gotchas
+
+- A field already under an open request, hidden, or printed into a held document is not
+  offered; the trigger refuses it with the reason, and nothing is spawned.
+- An empty or unchanged answer answers nothing (the same file again is no new document):
+  the field stays asked.
+- Withdrawing the request („Zurückziehen") cancels the task; the decision stays held by
+  `requiresOneOf` until another action completes.
+- Rows of applications on an OLDER offer version keep the old task; only applications
+  pinned to the published version get the family request.

package/dist/skill/references/offer/task-result-files.md

@@ -0,0 +1,52 @@
+# Let a task's result carry files
+
+**Use it to** let the person who completes a task attach files to their answer. Example: the
+teacher's trial-day feedback with an English and a maths placement sheet, as PDF or photo.
+
+## The model
+
+- **One switch on the task:** `result.files: true`. It is allowed only on prose results:
+  `freetext`, `recommendation`, or a `choice` without `writes`. Publish refuses it anywhere
+  else (`[taskResult/filesOnKind]`).
+- **Text and files are ONE message** in the chat the result names (`result.chat`). The row
+  keeps no text, and the chat keeps, shows and erases the files (GDPR erasure included).
+- **Up to 20 files per result**.
+  A normal chat message takes 5. Each file may be PDF, JPEG, PNG or WebP of up to 25 MB;
+  an iPhone HEIC photo is converted to JPEG in the browser.
+- **Where the files show:** in the result's message — cockpit → Verlauf/Aktivitäten (the
+  chat's tab); a click opens the file in the viewer. The task itself shows at most how
+  many files its result carries. Never in the „Dokumente" rail:
+  that lists the application's documents, not task attachments. Nothing is
+  copied, so deleting the message removes its files.
+- **Who sees them:** whoever reads the feedback text — the SAME chat rule. In a
+  `team:<group>` chat that means the members of that group plus platform admins. A
+  `tenant_admin` who is in no such group sees neither the text nor the files. Before
+  choosing `team:principals`, check that the readers really hold that group (`plexus-cli
+  users show <email>`).
+
+## CLI
+
+Work in a scratch dir for a real tenant
+([edit-live-tenant-offer.md](./edit-live-tenant-offer.md)).
+
+```bash
+plexus-cli --env prod --tenant <slug> offer export --slug <offer> --out <dir>
+plexus-cli offer workflow node task set --dir <dir> --node decision --key tasterFeedback --files
+plexus-cli offer validate --dir <dir>
+plexus-cli --env prod --tenant <slug> offer plan --dir <dir>   # workflow: change
+# apply only with the school's go (the process owner):
+plexus-cli --env prod --tenant <slug> offer apply --dir <dir> --publish --allow-prod
+```
+
+A new task: `node task add … --result freetext --chat <chat> --files`.
+
+## Verify
+
+1. Open the task in the cockpit. The dialog shows „Dateien (optional)" with the paperclip,
+   which accepts several files at once.
+2. Complete it with two files. Verlauf, tab of the result's chat: one message with the
+   text and both files.
+3. „Dokumente": neither file is listed there.
+4. As staff outside the chat's team: neither the text nor the files show in Verlauf.
+
+Test tenant: Grundschule → „Probetag auswerten" (Schulleitung) takes files.

package/dist/skill/references/offer/template-document-node.md

@@ -0,0 +1,113 @@
+# Generate a letter from a Word template (governedDocument `production: 'template'`)
+
+**Use it to** let a workflow document node (Platzangebot, Bestätigung, Bescheinigung) fill a tenant Word
+template and render the PDF automatically — no resolver, no deploy.
+
+## Prerequisites
+
+- The Word template is uploaded in the tenant's template module (Vorlagen). Its placeholders use
+  `<< input.<feld> >>` (sections `<<#input.<feld>>> … <</input.<feld>>>`).
+- **Exactly one language per letter (required):** every template node declares a
+  required enum field (options `de`, `en`), names it in `template.localeField`, binds it to
+  `$env.applicant.language` (the applicant's language — the default) and wraps each language's
+  text in a section `<<#input.<feld>.de>> … <</input.<feld>.de>>` /
+  `<<#input.<feld>.en>> … <</input.<feld>.en>>`. Exactly one section renders, and `input.*` prints
+  the way that language writes it (numbers, dates, Ja/Yes, prices, names). A node without
+  `localeField` is refused at publish (`[governedDocument/localeFieldMissing]`); a missing section
+  blocks publish and file replacement. The English twin `en.input.*` of the old fixed bilingual
+  letters is gone — a file naming it is `[governedDocument/unknownPlaceholder]`. A German-only
+  school declares one option `de` and binds the field to the fixed value `de`.
+- **Switching a LIVE template to language sections — upload it under a NEW key.** A file
+  replacement is checked against EVERY published node naming the key, archived versions included
+  (`publishedNodesFillingTemplate` — they still carry running applications), and a node published
+  without `localeField` accepts no file at all. So the old key stays with the old versions for
+  good; the sectioned file goes in as a new template:
+  1. upload the sectioned Word file as a new template and give it a new key (§ 1, e.g.
+     `platzangebot-v2`);
+  2. in the exported bundle point `template.key` at it, add the field `sprache` to
+     `template.fields`, set `template.localeField: 'sprache'` and bind it:
+     `plexus-cli offer workflow node set-input --dir <bundle> --node <id> --input sprache --address '$env.applicant.language'`
+     ([Bind a node input](./bind-node-input.md));
+  3. `offer validate` → `plan` → `apply --publish`.
+  Applications pinned to the old version produce no letter any more (the mask names
+  `localeFieldMissing`); a re-pin onto the new version is refused, because the new binding changes
+  the process topology — restart such a (test) application on the new version.
+- The deployment already runs a release that knows template nodes (validators first, then
+  publish); if publish refuses the node type, that needs a platform operator.
+
+## 1. Give the template its stable key
+
+There is no UI field yet — set it through the public mutation (the same `updateMetadata` the UI calls,
+so name / role / file-name pattern must be passed as they are):
+
+```bash
+plexus-cli call templates:list --env staging client=<slug> --json        # id, name, roleId
+plexus-cli call templates:updateMetadata --kind mutation --env staging client=<slug> \
+  templateId=<id> name='Platzangebot' roleId=<roleId> configKey=platzangebot --json
+```
+
+The key is unique per tenant and cannot move while a published process names it.
+
+## 2. Author the node in the bundle (JSON)
+
+`plexus-cli offer workflow node add` cannot create a governedDocument node; edit `workflow.json`
+(export → edit → plan → apply, see [Edit a live tenant's offer](./edit-live-tenant-offer.md)):
+
+```jsonc
+{
+  "id": "platzangebot", "type": "governedDocument", "label": "Platzangebot",
+  "production": "template", "approval": "release", "responseStrategy": "confirm",
+  "responseDueInDays": 14,
+  "template": {
+    "key": "platzangebot",
+    "fields": [
+      { "key": "kind_vorname", "label": "Vorname des Kindes", "type": "string", "required": true },
+      { "key": "datum", "label": "Datum", "type": "date", "processSource": "generatedAt" },
+      { "key": "antwortfrist", "label": "Antwortfrist", "type": "number", "processSource": "responseDueInDays" },
+      { "key": "sprache", "label": { "de": "Sprache des Schreibens", "en": "Language of the letter" },
+        "type": "enum", "required": true,
+        "options": [
+          { "value": "de", "label": { "de": "Deutsch", "en": "German" } },
+          { "value": "en", "label": { "de": "Englisch", "en": "English" } }
+        ] }
+    ],
+    "cockpitFields": [],
+    "localeField": "sprache"
+  },
+  "inputs": {
+    "kind_vorname": {
+      "kind": "binding",
+      "address": { "scope": "node", "owner": "form", "key": "admission", "path": "kind.vorname" }
+    },
+    "sprache": { "kind": "binding", "address": { "scope": "env", "key": "applicant.language" } }
+  }
+}
+```
+
+A bound form field must be exported by the form (`export: true`) and is named by its full address
+(`$node.form.admission.kind.vorname` — bind it with
+`plexus-cli offer workflow node set-input --node platzangebot --input kind_vorname --from form --field kind.vorname`);
+a form that does not run before the node is `[address/notVisible]`, a field it does not export
+`[address/pathNotInTarget]`. An old bundle (`wires`, a binding with `path`) is refused
+— export it again. The deadline alone can be changed
+with `plexus-cli offer workflow node set --id platzangebot --response-due-days 14` (`""` removes it).
+
+## 3. Validate, plan, publish
+
+`plexus-cli offer validate <dir>` checks the node shape offline (including the language field,
+`[governedDocument/localeFieldMissing]`). **Publish** additionally refuses a
+key no template carries (`[governedDocument/unknownTemplate]`) and any placeholder the fields cannot
+fill (`[governedDocument/unknownPlaceholder]`).
+
+## Verify
+
+An application entering the node gets a run in `contract_generation_runs` (producer: the template)
+and a PDF version on the node's slot within seconds; the cockpit's „Überarbeiten" opens the mask.
+
+## Gotchas
+
+- Generation is automatic only while the producer row is open and unblocked; after „Freigabe
+  anfordern" nothing regenerates. A changed template file is caught at submit („nicht mehr aktuell").
+- Replacing the template file is refused while a published node could not fill its placeholders.
+- **CLI gap:** the `template` pin (key, fields, cockpitFields) has no `offer workflow node` verb yet —
+  JSON only.

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,159 @@
+# 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.
+
+## 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
+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. 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 apply --publish`. 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.