@smartkomm/plexus-cli 0.0.0-stage → 0.1.0

package/dist/skill/references/config/update-tenant-config.md

@@ -0,0 +1,170 @@
+# Update a tenant's config
+
+**When to use:** change a real tenant's live config-as-code — add or remove a search
+filter, search target, field, list, display group, role binding, result icon, etc. — on
+staging and/or prod, without a reseed and without breaking unrelated config.
+
+## Prerequisites
+
+- `plexus-cli` installed and current (`plexus-cli --help`).
+- A token configured for each target env: a platform-admin token
+  (`_platform.config.manage` to commit), or — for your OWN tenant only — a tenant admin's
+  token holding `administration.config.manage` (see
+  [CLI access for a tenant admin](../users/cli-access-for-tenant-admin.md)). The tenant
+  token cannot change most `tenant.*` settings (modules, `mailLevel`, …), the import
+  source, or add new accounts; that section lists every refusal. A local admin key
+  without a user identity does **not** satisfy the gate.
+- The tenant **slug** (e.g. `test`). `plexus-cli config show` prints the resolved connection.
+- Always **stage on staging first**, verify, then promote to prod.
+
+## Steps
+
+The mechanism is **export → edit the snapshot → dry-run → confirm**. `export` snapshots the
+live config *exactly* (round-trip is identity), so re-applying with one thing changed yields a
+diff of only that one change.
+
+```bash
+# 1. Snapshot the live config (writes config/.dev/<slug>/config.json below the current
+#    directory; keep it private — it holds the tenant's whole config and user roster).
+plexus-cli config export --env staging --tenant <slug>
+
+# 2. Edit config/.dev/<slug>/config.json — make the ONE change (e.g. remove the
+#    searchFilters entry with "key":"nachname"). Leave everything else untouched.
+
+# 3. Dry-run (no --confirm → transaction rolls back, prints the plan).
+plexus-cli config apply --env staging --tenant <slug> \
+  --from snapshot:config/.dev/<slug>/config.json
+
+# 4. Commit once the dry-run shows only your intended change.
+plexus-cli config apply --env staging --tenant <slug> \
+  --from snapshot:config/.dev/<slug>/config.json --confirm
+```
+
+Then repeat 1-4 with `--env prod` (re-export from prod first — never assume prod == staging).
+
+`config set` (surgical single-field edit) is the alternative for changing **one field of one
+existing row**, but it **cannot delete a row** — removing an array element (a filter, a target,
+an option) must go through export → edit → apply.
+
+## Verify
+
+```bash
+# Re-export and confirm the change landed; nothing else moved.
+plexus-cli config export --env staging --tenant <slug>
+```
+
+Read the dry-run plan carefully — it is the safety gate:
+
+- `+ create (all) N` / `~ update (all) N` / `- delete (all) N` / `· unchanged (all) N` aggregate counts.
+- `~ update <target> <key>` — **one row per patched config row, by key** (e.g.
+  `~ update  lists  salutation`, `~ update  admission.fields  geburtsurkunde`). An idempotent
+  row is `· unchanged`, never an update — admission custom fields and derived attributes
+  included, in the dry run too. A deployment older than this row list prints one
+  `~ update (unnamed)` line instead of guessing.
+- `- delete <target> <key>` — **one row per pruned config row, by key** (e.g.
+  `- delete  searchFilters  nachname`). This is exactly what you removed; confirm it matches.
+- `- orphan <target>/<table> <key>` — rows the reconciler will NOT auto-delete (see gotchas).
+- `! no account <email>` — a `foundation.users` entry with no login account. On `--confirm`
+  each of these is **minted a password, printed once** (`+ account <email> password: …`), so
+  read this line before committing in a shared terminal — add `--output creds.csv --quiet` to
+  steer the plaintexts into a file instead. A steady-state tenant usually shows none: an
+  existing account is linked, never re-minted.
+
+- `~ slug units/<key> <from> → <to>` — an existing unit's URL moves (see
+  [Rename a unit's URL](#rename-a-units-url-slug) below). Expect none unless you changed a
+  `slug`.
+
+**Control-run technique** (isolate baseline drift): a fresh *unedited* export re-applied as a
+dry-run should show no `~ update` row; if it does, the named rows are the ones the export
+does not round-trip. To prove your edit added only what you intended, dry-run the unedited export too and
+diff the counts:
+
+```bash
+plexus-cli config export --env staging --tenant <slug> --out /tmp/control.json
+plexus-cli config apply  --env staging --tenant <slug> --from snapshot:/tmp/control.json   # baseline
+```
+
+The difference between the control plan and your edited plan is your change.
+
+## Rename a unit's URL (slug)
+
+A unit's **identity** is its config `key` (stored as `units.configKey`); its **slug** is only
+the URL projection — `/{tenant}/e/units/<slug>` (portal landing + `/bewerben`) and the staff
+`?unit=<slug>` scope. Renaming the unit's `name` never moves the slug; setting `slug` does.
+
+- `slug` absent in config → an existing unit keeps its slug, a new unit derives one from its
+  name. `config export` always emits the live `slug`, so an exported snapshot pins it.
+- `slug` present → create sets it, an existing unit is patched to it.
+- Shape: lowercase `a-z0-9` words joined by single dashes (exactly what the name derivation
+  produces); `tenant` is reserved. Two units in one config may not share a slug (validator),
+  and a slug any other unit of the tenant holds — including a row no longer in config — fails
+  the apply with `[unit/slugTaken]`. Two units may swap slugs in one apply. To take the slug
+  of a unit no longer in config, list that unit again under its key with a new `slug` in
+  the same apply — it moves off like any config unit, no data lost. Only if the old unit
+  should go anyway: remove it first (`apply --confirm --allow-destructive`, deletes its
+  data), then set the slug in a second apply — orphans are deleted only after the
+  reconcile has planned the slugs.
+- A new unit in the same apply never derives a slug another unit just vacated. A unit created
+  in a *later* apply (or via the UI) may — from then on old links open that unit.
+
+Example — the school unit `school` → `school-primary` (**do not run on prod without the
+go of whoever is responsible for production**; this is the recipe, not a pending change):
+
+```bash
+# Unit key from the export (it is the config key, not the slug — may differ).
+plexus-cli config export --env staging --tenant <slug>
+# Dry-run the one-field change; the plan must show exactly one slug row:
+#   ~ slug  units/<unitKey>  school → school-primary (old URL /e/units/school no longer reaches this unit)
+plexus-cli config set --env staging --tenant <slug> --target units --key <unitKey> \
+  --field slug --value school-primary
+# Commit.
+plexus-cli config set --env staging --tenant <slug> --target units --key <unitKey> \
+  --field slug --value school-primary --confirm
+```
+
+**The old URL dies with no redirect.** Before committing, update everything outside the DB
+that links to it: the school's own website "Bewerben" button, QR codes on printed flyers
+(regenerate from the offer's QR dialog), links in mails already sent (a magic link mailed
+before the change points at the old slug and 404s — send a fresh one).
+
+Also held by value, and **not** rewritten by a slug change: a custom field whose automatic
+string has a `unit`/`slug` segment stores the generated text once, so existing records keep
+the old slug (no committed config uses that segment today).
+
+**Cross-env promotes carry slugs.** `export` always emits `slug`, so `apply --from
+env:staging` onto prod moves any prod unit whose slug differs from staging's (e.g. a deduped
+`x-2` vs `x`). The dry run lists each as a `~ slug` row — read them before `--confirm`.
+
+## Idempotency / gotchas
+- The writing run (`--confirm`) needs `--env` on the command line, and a production target
+  `--allow-prod` — decided on the resolved deployment URL, so an alias pointing at prod is prod.
+  The dry-run is unaffected.
+
+- **Removing an array element does NOT need `--allow-destructive`.** The reconciler
+  prunes any config row absent from your snapshot on a plain
+  `apply --confirm`. This covers **search targets, search filters, filter options, result icons,
+  role-field bindings, target requirements, template placeholders** — they show as `- delete`
+  rows. It is **not** a migration.
+- **`--allow-destructive` is only for `orphans`.** Exactly five upsert-only tables —
+  **display-groups, lists, custom_fields, roles, permission_groups** — are *not* auto-pruned;
+  removing one surfaces it as an `orphan` (labelled *would destroy*) and is deleted only with
+  `--confirm --allow-destructive`. This split is deliberate: dropping a field/role/group can
+  orphan dependent data, so it requires the explicit flag.
+- **Changing the *shape* of existing rows (rename a key, change a field type) is a migration,
+  not an apply** — it needs a platform operator, who ships and runs the migration. `apply`
+  only moves config *values* into the shape that already exists.
+- **Removing a filter never touches the underlying data.** E.g. dropping the `nachname` search
+  *filter* leaves `last_name` (a system field) and the free-text search bar (`searchTargets`)
+  intact — only the dedicated filter input disappears.
+- **An export carries `foundation.users`**, so the export → edit → apply loop can mint
+  credentials for anyone in that roster who still lacks an account — see the `! no account`
+  line in the dry-run plan above, and `--output`/`--quiet` in `plexus-cli config apply --help`.
+- This is a live-DB operation; nothing else records it. The `config/.dev/<slug>/config.json`
+  snapshot is your only copy — keep it out of any shared or public place.
+- Cross-env shortcut: `--from env:staging` promotes staging's live config directly to prod
+  without a snapshot file (re-plans against prod's live state).
+
+## Related
+
+- [Onboard / establish a tenant](./onboard-tenant.md) · [Wipe a tenant's config](./wipe-tenant-config.md)
+- Command semantics: `plexus-cli config <verb> --help`.

package/dist/skill/references/config/wipe-tenant-config.md

@@ -0,0 +1,107 @@
+# Wipe a tenant's config
+
+**When to use:** clear a tenant's config target (and optionally its dependent data) — e.g. to
+rebuild a config section from scratch, or to tear down a test tenant. Reprovision afterwards with
+`config apply`.
+
+## Prerequisites
+
+- `plexus-cli` installed; platform-admin token for the target env (`_platform.config.manage`).
+- Know the **target id** from the registry: `plexus-cli config targets --env <env> --tenant <slug>`.
+- Wipe is destructive — **rehearse on staging**, never improvise on prod.
+
+## Steps
+
+```bash
+# Clear-only by default; --confirm required to actually wipe.
+plexus-cli config wipe --env <env> --tenant <slug> --target <id> --confirm
+
+# Heavy tier (the `masterdata` data target, the `foundation` config target, or --target all)
+# additionally requires --allow-destructive and echoes the affected row count.
+plexus-cli config wipe --env <env> --tenant <slug> --target all --confirm --allow-destructive
+
+# Config target with dependent live data → blocked unless --cascade (which also clears the data).
+plexus-cli config wipe --env <env> --tenant <slug> --target masterdata-fields --cascade --confirm
+```
+
+## Verify
+
+```bash
+plexus-cli config targets --env <env> --tenant <slug>   # the wiped target's count should be 0
+# Reprovision exactly those rows:
+plexus-cli config apply --env <env> --tenant <slug> --from snapshot:<path> --confirm
+```
+
+## Idempotency / gotchas
+- The writing run (`--confirm`) needs `--env` on the command line, and a production target
+  `--allow-prod` — decided on the resolved deployment URL, so an alias pointing at prod is prod.
+  The dry-run is unaffected.
+
+- **Dry run first.** Without `--confirm`, `config wipe` prints per table what it would clear
+  (`applications.contracts  would clear 3`) and any block it would hit, and deletes nothing.
+  Each table is counted in its own execution, so it works where `config targets` hits the read cap.
+- **Class memberships (`enrollments`) and leads (`program_interests`) are NOT application data.**
+  Memberships come from master data (manual or import) and live in `contract-setup` with their
+  classes; leads (Interessenten) are recorded before any application and live in `masterdata`.
+  `--target applications` leaves both alone; the dry run lists them under their own target.
+- **Contracts without an application block the applications wipe.** The finance runtime tables
+  are cleared tenant-wide, so a contract created on a party (not by an admission) would go with
+  them. The wipe (and its dry run) refuses with `Blocked: N of M contracts … belong to no
+  application` and deletes nothing.
+- **Two tiers.** Normal target = `--confirm`. **Heavy** (`masterdata` data target, `foundation`
+  config target, or `--target all`) additionally needs `--allow-destructive`.
+- **`--target all` is the teardown.** It deletes every file the tenant's forms name (also the
+  uploads the ledger cannot attribute to one form — every form goes anyway), purges every
+  application, drains every target's
+  tables (manual tasks and contracts without an application included — the applications
+  target's blocks do not apply), then the remaining tenant tables, the tenant's open upload
+  tickets and the tenant row. Nothing of the tenant is left in storage but the **logo**
+  (letters already sent link it).
+- **Files go with their rows.** Every wipe deletes the stored files only its rows held: fonts,
+  template files (once no template, library file, resolver pin or template run still names
+  them), import and export files, party files, comment attachments, signature scans. Only the
+  **logo** stays.
+- **Master data waits for the applications.** `--target masterdata` is blocked
+  (`Blocked: … still has applications`) while the tenant has any application: a form may name
+  the same file as a party value, which cannot be proven otherwise, and once the value is gone
+  no wipe could find the file again. Pass `--cascade` (the applications go first) or wipe
+  `--target applications` before.
+- **Interlock.** Wiping a CONFIG target while dependent DATA exists (e.g. `masterdata-fields`
+  while `values` rows reference those fields) is **blocked** with a bilingual message listing the
+  dependent counts — unless `--cascade`, which then also clears the data.
+- **Reprovision is exact.** After a scoped config wipe, `config apply` recreates exactly those
+  rows (`wipe search` → `apply` round-trips). The gates sit in the backend
+  (fail loud); the CLI adds the UX warnings.
+- **`--target applications` hard-deletes every application of the tenant and everything it
+  owns** — work items (+ comments, assignees, parties), team-owner bindings, feed (events,
+  comments, chat channels, read marks), waitlist entries, notifications about it (+ deliveries,
+  previews), its access-audit rows, the party-timeline activities that point at it, party-role
+  buckets, its form instances (`smart_form_instances`) and file artifacts, its process store, the workflow cursor, and the finance rows that flow from admissions (contracts, lines, snapshots,
+  signatures, payments, invoices, postings) — **and their files**: docRef uploads (single and
+  multi-file) whose upload-ledger row names the form, generated/uploaded file artifacts, chat
+  attachments, contract snapshot PDFs, signed documents. Draft party shells the forms created
+  go too (the soft-delete GC rule); **real master data stays**, as do **manual tasks** (no
+  application) and the **school setup**.
+- **School setup is its own heavy target, `contract-setup`:** contract templates,
+  billing definitions, grants, generators and their article dependencies, ledger accounts, payment methods, classes
+  (`learning_groups`), portal info events and consultation slots. It is maintained in the app,
+  not by config-as-code — **no `config apply` brings it back**. Needs `--allow-destructive`.
+- **How it runs:** a few applications per mutation through one cascade, then the target's
+  tables page by page — never one tenant-sized transaction.
+- **What it cannot prove, so it leaves:** a file referenced by a docRef value WITHOUT an
+  upload-ledger row for that form (dev-seed placeholders, uploads older than the ledger) — it
+  might be shared. Only `--target all` takes those. Pending (never persisted) uploads are
+  reclaimed by the nightly orphan sweep within 7 days.
+- **Verify an applications wipe:** `config targets` shows 0 for every `applications` table
+  (`work_items` counts only application tasks). Tables only the cascade reaches
+  (`notifications*`, `access_audit`, `activities`, `storage_uploads`) are not in that listing —
+  check them with `plexus-cli call` if needed.
+- **Reprovisioning `foundation` mints new passwords.** The wipe took the tenant's users with
+  it, so the re-apply creates their login accounts again and prints each generated password
+  once. Run that re-apply with `--output creds.csv --quiet` if the terminal is shared — see
+  `plexus-cli config apply --help`.
+
+## Related
+
+- [Update a tenant's config](./update-tenant-config.md) · [Onboard / establish a tenant](./onboard-tenant.md)
+- Command semantics: `plexus-cli config wipe --help`.

package/dist/skill/references/export/create-named-export.md

@@ -0,0 +1,47 @@
+# Create a named person export
+
+**When to use:** A tenant needs a reusable XLSX export with selected person fields and the shared search filters.
+
+## Prerequisites
+
+- An operator token with export access to the target tenant in each environment.
+- Review the readable field IDs in `exports:metadata` separately for staging and production; IDs differ between deployments.
+
+## Steps
+
+1. List existing templates before creating a new name:
+
+   ```bash
+   plexus-cli call dataExportTemplates:list --env staging client=<tenant> --json
+   plexus-cli call exports:metadata --env staging client=<tenant> --json
+   ```
+
+2. Choose explicit `dataExportTemplateColumnInput` paths from the metadata. Prefer a small set of ordinary fields and core role/unit columns. Leave `filters=[]` to let a user choose filters at export time.
+
+3. Create on staging first, passing the column array as one JSON argument:
+
+   ```bash
+   plexus-cli call dataExportTemplates:create --kind mutation --env staging client=<tenant> name='<name>' completenessMode=all 'columns=[{"path":{"kind":"core","key":"party.roles"},"headerLabel":"Rollen","pathLabel":"Rollen"}]' --json
+   ```
+
+4. After verification, repeat against `--env prod` with production field IDs. Core paths do not need environment-specific IDs.
+
+## Verify
+
+```bash
+plexus-cli call dataExportTemplates:get --env staging client=<tenant> templateId=<id> --json
+plexus-cli call exports:previewSample --env staging client=<tenant> page=0 'columns=[{"path":{"kind":"core","key":"party.roles"},"headerLabel":"Rollen","pathLabel":"Rollen"}]' --json
+```
+
+Confirm the name, `formatDefault: "xlsx"`, filters, and column paths. Select the named configuration in the browser to check that the preview and XLSX action render. Repeat the read checks on production.
+
+## Idempotency / gotchas
+
+- `create` always inserts a new template. Check `list` first; update an existing template when it has the intended identity.
+- `previewSample` pages through underlying parties, so a rare filter can return zero rows on one page even if later pages contain matches. A full XLSX job scans the whole tenant.
+- The template is independent of tenant config snapshots; `config export/apply` does not carry it between environments.
+
+## Related
+
+- `plexus-cli call --help` and `plexus-cli describe <function>` for the arguments of each function
+- [Update tenant config](../config/update-tenant-config.md)

package/dist/skill/references/feedback/create-and-triage-feedback.md

@@ -0,0 +1,69 @@
+# Create + triage feedback from the CLI
+
+**When to use:** you want to file platform-level feedback without the browser
+(e.g. an agent capturing an issue), assign it to a triage admin, pull the list
+of items assigned to you, and turn an item into a GitHub issue — all from `plexus-cli`.
+
+## Prerequisites
+- `--env local|staging|prod` configured with a platform-operator token
+  (creating/listing need `_platform.feedback.read`; assigning needs
+  `_platform.feedback.manage`).
+- The assignee must be feedback-assignable — see
+  [Make a platform admin assignable to feedback](../users/grant-feedback-assignable.md).
+
+## Steps
+```bash
+# 1. File platform-level feedback (no screenshot — attachments are browser-only).
+plexus-cli --env <env> feedback create \
+  --summary "Board: Spalte 'Klärung' lädt langsam" \
+  --tag <feedbackTagId> \
+  --situation "Beim Öffnen der Klärung-Spalte mit vielen Karten" \
+  --reason "Triage wird ausgebremst"
+#   → prints the new feedbackId
+
+# 2. Assign it to a triage admin (userId, email, or @me for yourself).
+plexus-cli --env <env> feedback assign <feedbackId> ada@example.com
+
+# 3. List everything assigned to me.
+plexus-cli --env <env> feedback list --all-tenants --assignee @me
+
+# 4. File an item as a GitHub issue. If it has a screenshot, save it, host it
+#    yourself as an EXPIRING link, and pass the URL (the CLI uploads nothing).
+plexus-cli --env <env> feedback screenshot <feedbackId> --out ./feedback.webp
+#    → upload ./feedback.webp with your environment's upload tool, presigned,
+#      e.g. 7 days; screenshots can show customer data — never a permanent public URL
+plexus-cli --env <env> feedback to-issue <feedbackId> --type bug \
+  --screenshot-url '<presigned-url>'          # or: --no-screenshot
+```
+
+## Verify
+```bash
+# The item shows the assignee and appears under the @me filter:
+plexus-cli --env <env> feedback list --all-tenants --assignee @me --json
+# Eligible assignees (must include your target):
+plexus-cli --env <env> feedback admins
+```
+
+## Idempotency / gotchas
+- **`feedback create` is platform-level only** — the item is owned by the reserved
+  `_platform` "Plattform" tenant, not a client tenant. Use the in-app feedback
+  button to file *tenant-scoped* feedback.
+- **No screenshot/attachments on `feedback create`** — they require a browser upload;
+  both are optional backend-side, so omitting them is a valid submission.
+- **`feedback to-issue` never drops a screenshot silently:** an item with one is refused
+  until you pass `--screenshot-url <https-url>` or `--no-screenshot`; a URL for an item
+  without a screenshot is refused too. `--dry-run` applies the same rule.
+- **The issue embeds the link you pass.** A presigned link expires, and the image in the
+  issue goes with it — that is the point for customer data; the item itself keeps the
+  original (`feedback screenshot` fetches it again any time).
+- **`feedback screenshot`** refuses an existing `--out` file (`--force` overwrites) and an
+  item without a screenshot; it prints the content type (staging stored WebP when checked).
+- Tags replace the old fixed category field. Use repeatable `--tag <feedbackTagId>`
+  on create, or `feedback tag <feedbackId> <feedbackTagId>` afterwards.
+- `--assignee @me` (and `me`) resolves to the calling operator via `whoAmI`.
+  `feedback assign` fails loud if the target lacks `_platform.feedback.assign`.
+- `--assignee` on `feedback list` requires `--all-tenants` (assignee is platform-only).
+
+## Related
+- [Make a platform admin assignable to feedback](../users/grant-feedback-assignable.md)
+- [Manage feedback tags + bulk-tag items](./manage-feedback-tags.md)

package/dist/skill/references/feedback/manage-feedback-tags.md

@@ -0,0 +1,57 @@
+# Manage feedback tags (incl. visibility) and bulk-tag items
+
+**When to use:** curate the global feedback tag catalog (create / rename / recolor /
+set public-vs-platform visibility / delete), or attach a tag across many feedback
+items at once.
+
+## Prerequisites
+- `--env local|staging|prod` selected (the environment as configured for your CLI, see `plexus-cli --help`).
+- Catalog edits need platform `_platform.feedback.tags`; attach/detach needs board
+  access to the item (the CLI authenticates as a platform admin, so both are covered).
+- `jq` for the bulk loop.
+
+## Steps
+```bash
+# Inspect the catalog (id, name, color, scope). Shows platform-only tags too.
+plexus-cli --env prod feedback tags list
+
+# Create — public (default) or platform-only (triage tags like "Unklar"/"Fehlt").
+plexus-cli --env prod feedback tags create --allow-prod "Rechte" --color 5319e7
+plexus-cli --env prod feedback tags create --allow-prod "Unklar" --color d4c5f9 --visibility platform
+
+# Rename / recolor / re-scope / delete (delete cascades the item links).
+plexus-cli --env prod feedback tags rename --allow-prod  <tagId> "Konfiguration"
+plexus-cli --env prod feedback tags recolor --allow-prod <tagId> fbca04
+plexus-cli --env prod feedback tags visibility --allow-prod <tagId> platform   # or: public
+plexus-cli --env prod feedback tags delete --allow-prod  <tagId>
+
+# Attach / detach a tag on one item.
+plexus-cli --env prod feedback tag --allow-prod   <feedbackId> <tagId>
+plexus-cli --env prod feedback untag --allow-prod <feedbackId> <tagId>
+```
+
+### Bulk-tag: attach one tag to every matching item
+```bash
+TAG=<tagId>
+plexus-cli --env prod feedback list --all-tenants --text "import" --json \
+  | jq -r '.[].id' \
+  | while read -r id; do plexus-cli --env prod feedback tag --allow-prod "$id" "$TAG"; done
+```
+
+## Verify
+```bash
+plexus-cli --env prod feedback tags list                     # scope column reflects the change
+plexus-cli --env prod feedback list --all-tenants --tag <tagId> --json | jq length
+```
+
+## Idempotency / gotchas
+- `feedback tag`/`untag` are idempotent (re-running is a no-op).
+- A non-platform user can attach only **public** tags; the CLI is platform-authed so
+  it can attach platform-only ones too.
+- `feedback list` filters in-memory over rank-paginated pages, so a heavily filtered
+  query may need `--limit` raised to reach older items (iterate to exhaustion).
+- `tags delete` is destructive: it detaches the tag from every item first.
+
+## Related
+- [Create + triage feedback](./create-and-triage-feedback.md) (incl. `feedback to-issue`) ·
+  `feedback link/unlink/links` to cross-reference two feedback items · the board UI's "Tags verwalten" dialog does the same edits.

package/dist/skill/references/finance/change-contract-grant.md

@@ -0,0 +1,36 @@
+# Change a contract grant
+
+Use a line grant for a concession on one contract line. Use an aggregate grant for
+an agreed reduction across eligible contract lines with one combined floor. Plans
+only assemble articles. Prices selected through pricing attributes stay in the tree.
+
+```bash
+plexus-cli --env staging --tenant test contract grant add \
+  --line <lineId> --template <templateKey> --from 2026-11-01 \
+  --evidence '{"decision":"Finance approved"}'
+
+plexus-cli --env staging --tenant test contract grant add-aggregate \
+  --contract <contractId> --template <templateKey> --amount 380 --floor 150 \
+  --period month --from 2026-11-01 \
+  --evidence '{"decision":"Income assessment approved"}'
+
+plexus-cli --env staging --tenant test contract grant end <grantId> --to 2027-07-31
+
+plexus-cli --env staging --tenant test contract grant replace <lineGrantId> \
+  --template <newTemplateKey> --from 2026-12-01 \
+  --evidence '{"decision":"Updated concession"}'
+```
+
+`add` also accepts negotiated line terms: `--name`, `--reason`, and exactly one of
+`--percent` or `--amount`. `replace` replaces line grants. To change an aggregate
+agreement, end it and apply the new explicit terms from the following period.
+
+Finance enters income reductions as absolute amounts. The engine caps the granted
+reduction so the eligible total cannot fall below the agreed floor. Annual amounts
+and floors are entered explicitly; monthly terms are never multiplied by twelve.
+Only eligible lines with the matching price period participate. Supporting evidence
+is required. Backdated changes to already booked periods are refused.
+
+Template edits do not change existing contract grants. Their target lines, rule,
+floor, period and evidence were agreed when applied. Contract snapshots preserve
+signed evidence; booked charges preserve their pricing explanation and accounting.

package/dist/skill/references/finance/record-submission-date.md

@@ -0,0 +1,33 @@
+# Record a missing historical SEPA submission date
+
+**When to use:** The dashboard reports a legacy debit batch without a recorded
+submission date. Use the original transmission receipt, not the execution date.
+
+## Prerequisites
+
+- Tenant-wide finance permission and the original bank transmission evidence.
+- Inspect the target environment before writing. Staging/prod changes require
+  the operator's explicit approval; this recipe is not authorization.
+
+## Steps
+
+```sh
+plexus-cli --env local --tenant test config show
+plexus-cli --env local --tenant test call paymentBatches:recordSubmissionDate --kind mutation client=test batchId=<batch-id> submittedDate=2026-08-31
+```
+
+Use the actual receipt's date and intended tenant/environment. Ordinary new
+submissions already record this date and need no repair.
+
+## Verify
+
+```sh
+plexus-cli --env local --tenant test call financeDashboard:overview client=test
+```
+
+The return count and denominator appear in the original submission month.
+
+## Idempotency / gotchas
+
+An identical date can be replayed. A conflicting date, another tenant's batch,
+a draft batch or a date after execution is refused. Nothing books money.

package/dist/skill/references/interessenten/list-interessenten.md

@@ -0,0 +1,54 @@
+# List a tenant's Interessenten (open leads)
+
+Inspect the CRM funnel's `interesse` stage from the CLI — every OPEN lead
+(program interest) for a tenant, newest first, with the person, Angebot, Stufe
+and Lauf. Read-only; backs ops/debug ("why isn't this lead showing /
+converting?").
+
+There is no stored lead status: a lead is CONVERTED iff an application
+references it (`applications.leadId`) — converted leads appear as Bewerbungen,
+not here — and withdrawn/declined leads are deleted outright.
+
+## Command
+
+```bash
+# All open leads for the active tenant (table)
+plexus-cli interessenten list --env local --tenant <slug>
+
+# Rich JSON
+plexus-cli interessenten list --env local --tenant <slug> --json
+```
+
+- `--tenant <slug>`: overrides the config default. The local dev seed's tenant
+  slug is **`test`** (the committed `test` template); `grundschule-havelland` is
+  a *unit*, not the tenant.
+- `--json`: rich shape (`{ lead, personDisplayName, programName, runName,
+  stageName }`); default is a compact table.
+
+## Example output (table)
+
+```
+name             angebot      stufe           lauf
+Lia Busch        Grundschule  Klassenstufe 6  Schuljahr 2026/27
+Noah Kaiser      Grundschule  Klassenstufe 5  Schuljahr 2026/27
+```
+
+## How it works
+
+Wraps the gated query `api.leads.listForManagement(client)`, which requires the
+**`bewerbungsmanagement.applications.read`** permission (unlike the
+membership-stub `leads.listForTenant`). Leads are real Stammdaten persons with
+the tenant's configured Interessent (lead) role — the Bewerber role is attached
+only at conversion — so a lead here is the same person you'll find in the
+Personen catalog. The free-text note lives on the person as the `notiz` custom
+field, not on the lead row.
+
+## Verify / gotchas
+
+- **`Unknown tenant "<slug>"`** → wrong `--tenant`. Use the tenant slug (`test`
+  locally), not a unit slug.
+- **`Missing required permission: bewerbungsmanagement.applications.read`** →
+  the CLI token's user lacks admission read in that tenant. Grant it (or use a
+  platform-admin token).
+- Empty list on a fresh deployment → seed hasn't run, or every lead was
+  converted (now listed as Bewerbungen) or withdrawn (deleted).

package/dist/skill/references/notifications/debug-mail-delivery.md

@@ -0,0 +1,77 @@
+# Debug a mail delivery
+
+**When:** "no mail arrived", a red `deadLastHour` badge in the platform
+console, or a `backend:convex` GlitchTip issue tagged `area=notifications`.
+
+## 1. Is the sweeper alive, and is anything dead?
+
+```bash
+plexus-cli --env staging notifications sweeper-status
+plexus-cli --env staging notifications list --status dead
+```
+
+`ranAt` older than a few minutes ⇒ the cron is not firing (deploy broke?).
+`deadLastHour > 0` ⇒ go to step 3 with an id from the list.
+
+## 2. Find the delivery for a person
+
+```bash
+plexus-cli --env staging notifications list --to parent@example.org --since 2d
+plexus-cli --env staging notifications list --template account.loginLink --since 24h
+```
+
+For a sign-in problem start with `users login-trail` instead — see
+[Trace why someone could not sign in](./trace-a-login.md).
+
+Statuses: `queued` (waiting / backoff), `sending` (in flight), `sent` (relay
+accepted — NOT "in the inbox"), `skipped` (a successful non-send: recipient
+gone, precondition no longer true, reserved TLD — in `live` every RFC 2606
+address, in `redirect` only `.invalid`), `dead` (gave up).
+
+## 3. Read the evidence
+
+```bash
+plexus-cli --env staging notifications show <deliveryId>
+```
+
+| `errorCode` | Means | Do |
+| --- | --- | --- |
+| `delivery_mode_invalid` / `config_missing` | deployment env is incomplete | needs a platform operator: complete the deployment's mail settings, then `retry` |
+| `smtp_auth` | relay rejected the credentials | needs a platform operator: rotate the relay password in the deployment's settings, then `retry` |
+| `smtp_policy` | relay rejected OUR sender at `MAIL FROM` | `MAIL_FROM_ADDRESS` not allowed for this account — ask the mail admin |
+| `smtp_content` with 4xx at `DATA` | milter (DKIM) hiccup — retried automatically | if it stays: the relay's DKIM key/permissions — ask the mail admin |
+| `smtp_recipient_rejected` | 5xx at `RCPT TO` | the address does not exist — nothing to retry |
+| `recipient_revoked` / `recipient_changed` / `recipient_deleted` | identity changed after enqueue | expected; re-raise the event if still wanted |
+| `never_claimed` | the dispatch action fails BEFORE it can claim | bundle/import problem — needs a platform operator (deployment logs of the action), fix, `retry` |
+| `unknown_outcome` | action died after SMTP began | the recipient MAY have received it; decide, then `retry` |
+
+`lastSmtpCommand` / `lastSmtpResponseCode` / `lastSmtpResponse` carry the raw
+relay line. `possibleDuplicate: true` means attempt N may already have landed.
+
+## 4. Prove the configuration end to end
+
+```bash
+plexus-cli --env staging notifications self-test --to <your-address>
+```
+
+Verifies the connection + credentials, sends one mail, returns the SMTP
+transcript. On staging the mail is redirected like every other; on prod it
+really goes to `--to`.
+
+## 5. Retry
+
+```bash
+plexus-cli --env staging notifications retry <deliveryId>
+```
+
+Only `dead` rows. It is a fresh attempt through the normal claim path — the
+retry budget is widened by exactly one.
+
+## Gotchas
+
+- `sent` = accepted by the relay. The last hop (relay → GMX) is invisible; on
+  staging the platform operator reads the catch-all mailbox.
+- A `451` is not always transient: the relay says `451 4.7.1` for a
+  sender-policy violation and for a broken DKIM key. Look at the COMMAND.
+- Locally nothing is ever sent (`dry`): the mail is in the Dev Rail →
+  `notifications:listDevPreviews`.