@smartkomm/plexus-cli 0.0.0-stage → 0.1.0

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.

package/dist/skill/references/signing/connect-a-school.md

@@ -0,0 +1,90 @@
+# Connect a school to its signing provider
+
+Give one tenant its own account at DocuSign or inSign, so its contracts are
+signed through **the school's** account instead of a deployment-wide one, and
+make that account the one its contracts go out through. The day-to-day signing
+commands: [README.md](./README.md).
+
+## When to use it
+
+- A school is going to send contracts for electronic signature for the first time.
+- A school switches provider, rotates its password / HMAC key, or its
+  connection stopped working and you need to see **why**.
+
+## Prerequisites
+
+- **`_platform.config.manage`** for `set`, `activate` and `remove`;
+  `finanzen_vertraege.contracts.manage` for `show` and `test`. Setting up a
+  connection opens a commercial relationship with a provider in the school's
+  name — a platform act, like Stripe Connect.
+- The installation holds `SIGNING_CREDENTIALS_KEY` (otherwise every connection
+  reads `platform_unconfigured` and no secret can be stored). For DocuSign also
+  the platform app: `DOCUSIGN_OAUTH_HOST`, `DOCUSIGN_INTEGRATION_KEY`,
+  `DOCUSIGN_PRIVATE_KEY`. Setting these needs a platform operator; the CLI cannot.
+- The school's account data: DocuSign — the sender's API user id (GUID) and,
+  for callbacks, the Connect HMAC key; inSign — base URL, API user, password,
+  owner id (`foruser`).
+
+## Steps
+
+```bash
+# 1. Where does this school stand?
+plexus-cli signing connection show --env staging --tenant <slug>
+
+# 2a. inSign. The password comes from stdin — NEVER as an argument.
+printf %s "$INSIGN_PASSWORD" | plexus-cli signing connection set --provider insign \
+  --base-url https://insign.<anbieter>.de --username <api-user> --owner-id <owner> \
+  --secret-stdin --env staging --tenant <slug>
+
+# 2b. DocuSign. The HMAC key from a file (or stdin); without one, no callback is
+#     registered and the 15-minute poll is the only return path.
+plexus-cli signing connection set --provider docusign --user-id <GUID> \
+  --redirect-to admin@plexus.swop.schule --secret-file ./hmac.txt \
+  --env staging --tenant <slug>
+
+# 3. Reach the account. DocuSign: on consent_required open the printed
+#    consentUrl ONCE as the school's sender, then test again.
+plexus-cli signing connection test --provider insign --env staging --tenant <slug>
+
+# 4. Make it the provider the school's contracts go out through.
+plexus-cli signing connection activate --provider insign --env staging --tenant <slug>
+
+# 5. Prove it.
+plexus-cli signing connection show --env staging --tenant <slug>
+#    E-Signatur: inSign   ·   state=ready   active=yes
+```
+
+Change a field later with the same `set`; give only what changes plus the
+required fields. A secret not given stays as it is. Remove one with
+`--clear-secret hmacKey` (DocuSign) or `--clear-secret password` (inSign).
+
+## Verify
+
+`state=ready` (or `failing` after an earlier success) and `active=yes` is what
+`signing start` needs. Then send a test revision —
+[README.md](./README.md) → "Send a revision for signature".
+
+## Gotchas
+
+- **Secrets go in through stdin or a file only.** An argument would land in the
+  shell history and in `ps`. `show` prints the secret's name, a fingerprint and
+  when it was set; nothing ever prints the value.
+- **A `production` account is refused outside prod.** inSign: any base URL but
+  the vendor's sandbox host counts as production; DocuSign: the deployment's
+  OAuth host decides.
+- **Demo needs a redirect, production forbids it.** A sandbox account must carry
+  `--redirect-to` (nobody may address a real family from a sandbox whose
+  credentials are public); a production account must not (every contract would
+  land in one mailbox). `set` refuses either mistake.
+- **Switching keeps open Vorgänge where they are.** `activate` on another
+  provider deactivates the old connection in the same step, but every Vorgang
+  already started keeps talking to the account it started on — poll, reconcile,
+  void and its callbacks included. `remove` is refused while one is open.
+- **The account is part of an open Vorgang.** While one is open, changing
+  DocuSign's `--user-id` or inSign's `--base-url` / `--owner-id` is refused;
+  rotating the password or HMAC key is allowed.
+- **`state=unverified` after every change.** Any `set` invalidates the last
+  test; run `test` again before the next contract goes out.
+- **`state=platform_unconfigured`** is about the installation, not the school:
+  `SIGNING_CREDENTIALS_KEY` (or DocuSign's platform app) is missing there.
+- **`remove` is a dry run** unless `--confirm`; the secrets go with the row.

package/dist/skill/references/signing/rotate-the-key.md

@@ -0,0 +1,41 @@
+# Rotate the signing credentials key
+
+## When to use it
+`SIGNING_CREDENTIALS_KEY` (the platform key every school's signing secrets are
+sealed under) must change — routine rotation or a suspected leak.
+
+## Prerequisites
+- Platform right `_platform.config.manage` on the target environment.
+- A platform operator who can change the deployment's environment
+  (`SIGNING_CREDENTIALS_KEY` and its previous slot) and deploy — the CLI cannot.
+
+## Steps
+1. Needs a platform operator: move the current key into the previous slot, set a
+   new current key (`openssl rand -base64 32`), deploy. Nothing breaks in between:
+   envelopes under the old key open through the previous slot.
+2. Re-seal every connection under the new key:
+   ```bash
+   plexus-cli signing connection reseal --env <env>
+   ```
+3. Check the slots:
+   ```bash
+   plexus-cli signing status --env <env>
+   ```
+
+## Verify
+`signing status` shows `sealedPrevious: 0`, `sealedUnknown: 0` and
+`previousSlot: nothing sealed under it — can be removed`. Then the platform
+operator clears the previous slot from the deployment's environment and deploys.
+
+## Idempotency / gotchas
+- `reseal` is idempotent; a second run reports `resealed: 0`. It exits 1 while
+  anything is left under the previous or an unknown key.
+- Never clear the previous slot before `reseal`: every envelope still under it
+  becomes `incomplete` („mit Schlüssel … versiegelt, den … nicht trägt") and
+  DocuSign callbacks of those schools fail until the old key is back.
+- Fingerprints change with the key (they are keyed by it); the secrets do not.
+- A save during the run wins: its envelope is left alone (`changedMeanwhile`).
+
+## Related
+- [Signing commands](./README.md)
+- [Connect a school to its signing provider](./connect-a-school.md)

package/dist/skill/references/stammdaten/purge-deleted-person.md

@@ -0,0 +1,68 @@
+# Hard-delete a person staff deleted
+
+**When to use:** a school (or a data-subject erasure request) needs a person
+gone **for good** — the row, everything that belongs to it, its value history
+and the stored files only it holds. In the app staff can only **soft**-delete
+(„Person löschen“ moves the person to „Gelöschte“, restorable); the hard delete
+exists only here.
+
+## Prerequisites
+- **Env + tenant:** `--env <local|staging|prod> --tenant <slug>`. Prod also needs
+  `--allow-prod` for the writing run.
+- **Auth:** your own platform token with `_platform.config.manage` (the right that
+  commits a tenant wipe). Check with `plexus-cli --env <env> whoami`.
+- **The person is soft-deleted first.** Staff deletes it in the app (Personen →
+  person → trash icon), or it already sits under „Gelöschte“. A person that is
+  not deleted is refused — the two steps are deliberate.
+- **The party id.** List the deleted persons of the tenant:
+  ```bash
+  plexus-cli --env <env> --tenant <slug> stammdaten persons --deleted
+  ```
+
+## Steps
+1. **Plan** (no write — the default):
+   ```bash
+   plexus-cli --env <env> --tenant <slug> stammdaten persons purge <partyId>
+   ```
+   Prints the person, when staff deleted it, the rows per table (the party, its
+   persons row, roles, values and their links, placements, enrollments, search
+   entries, `value_history`, …) and every receipt that refuses the commit.
+2. **Commit** once the plan shows no `Refused` block:
+   ```bash
+   plexus-cli --env <env> --tenant <slug> stammdaten persons purge <partyId> --confirm [--allow-prod]
+   ```
+
+## Verify
+- `plexus-cli --env <env> --tenant <slug> stammdaten persons --deleted` no longer
+  lists the person.
+- Re-running the plan fails with „Der Datensatz wurde nicht gefunden.“
+
+## Idempotency / gotchas
+- **Not reversible.** The soft delete is the reversible step; this one is not.
+- **Refusals (both plan and commit):** a person an application in flight names as
+  Antragsteller:in or binds („gehört zu einer laufenden Bewerbung“) — finish or
+  discard the application first; a person linked to a user account — remove the
+  account's access first.
+- **Receipts block the commit:** a contract, invoice, signature or other
+  `restrict` holder is listed as `table:id ← table:id (column)`. They are records
+  the school must keep; the person then stays soft-deleted.
+- **One transaction.** A person with more rows than the deletion engine's plan
+  limit fails loud instead of half-deleting.
+- **Files:** the plan lists every file the person's values and value history name,
+  and why it stays (`kept … held by`). A file goes only when the upload ledger
+  proves it a party file of this school and nothing else holds it. It stays as
+  `unproven` (no ledger row names this school — a file staff uploaded into a
+  person before upload stamping existed carries no school stamp, nor does one saved
+  more than two hours after its upload; such a file is never re-stamped without
+  proof), `upload:<surface>` (staged for a template, library,
+  brand file, import, chat …), `ledger` (staged for another school), `shared` (claimed again elsewhere after it
+  came in — a logo, a form, a feedback attachment), `form` /
+  `artifact` / `snapshot` / `signature` / `return` (a receipt that holds the file) or
+  `party` (another person's value names it, any school). Note `form`: while the
+  school has ANY application left, a form might hold the file (the fieldMap copy),
+  so it stays — expected, not a bug.
+- `--json` prints the raw report (`rows`, `blockers`, `applied`).
+
+## Related
+- Deleting every person past a school's deletion rule at once:
+  [Delete persons past their school's deletion rule](../retention/erase-due-parties.md).

package/dist/skill/references/stripe/connect-a-school.md

@@ -0,0 +1,107 @@
+# Connect a school to its own Stripe account
+
+Give one tenant a Stripe account of its own, so its families' money lands with
+**the school** rather than in a shared account.
+
+## When to use it
+
+- A school is going to collect money through Plexus for the first time.
+- A school's connection stopped working and you need to see **why** (there are
+  eight distinct reasons, and they need different people to act).
+
+## Prerequisites
+
+- **The school sets Stripe up itself.** A member holding
+  `finanzen_vertraege.contracts.manage` **and** `finanzen_vertraege.payments.connect`
+  presses „Stripe einrichten" on Administration → Integrationen → Stripe, in
+  their own browser. Whoever finishes Stripe's form becomes the owner of the
+  school's Stripe login, so it should be the school's legal representative
+  (Geschäftsführung), and that person needs a Plexus account. **The CLI cannot
+  start it, and neither can a platform admin** (refused even with a
+  membership). Stripe forbids handing onboarding links on, which is why
+  `stripe connect` / `stripe onboarding-link` are gone.
+- The deployment holds the **platform's** Stripe key with Connect enabled (set by
+  a platform operator; the CLI cannot).
+  Accounts are created through **Accounts v2** (`/v2/core/accounts`); a
+  *claimable sandbox* key (`rkcs_…`) cannot create accounts at all.
+- A **real mailbox** for the school, entered in the dialog. Stripe writes to it
+  itself (onboarding, receipts, dispute notices), and that post bypasses
+  Plexus entirely, so `MAIL_DELIVERY_MODE` cannot intercept or redirect it.
+- A school that **already uses Stripe** signs into the form with its existing
+  Stripe login and reuses its company details (networked onboarding). It still
+  gets a new connected account.
+
+## Steps
+
+```bash
+# 1. Where does this school stand?
+plexus-cli stripe status --env staging --tenant <slug>
+#    state=unconnected  → nothing exists yet.
+
+# 2. The school's representative signs in to Plexus and presses
+#    „Stripe einrichten" (Integrationen → Stripe): e-mail for Stripe's post and
+#    country, then „Weiter zu Stripe". Plexus creates the account and the
+#    browser goes straight to Stripe's form. Back in Plexus, the page asks
+#    Stripe at once. If the form is left half done, „Angaben bei Stripe
+#    vervollständigen" on the same page continues it.
+#    Testing URL for the representative (member persona, never the platform
+#    admin deep login, which is refused here):
+#    https://<host>/login?as=<member e-mail>&redirect=/<slug>/admin/integrations/stripe
+
+# 3. Watch it land. The v2.core.account* events refresh the mirror by themselves:
+plexus-cli stripe status --env staging --tenant <slug>
+#    connectedBy=<name> <when>                         → who started it.
+#    card=restricted: requirements_past_due + due=[…] → Stripe still waits.
+#    card=pending                                      → Stripe is checking.
+#    card=active                                       → Stripe has cleared it.
+#    sepa=… (!)  → card works, SEPA-Lastschrift does not: the school enables
+#                  it in its own Stripe dashboard (payment methods).
+
+# 4. The school's own consent. Nothing collects without it, however happy
+#    Stripe is (page: „Einzug freigeben", or with the school's say-so):
+plexus-cli stripe allow --env staging --tenant <slug>
+
+# 5. Prove it:
+plexus-cli stripe status --env staging --tenant <slug>
+#    state=ready
+```
+
+## Verify
+
+`state=ready` is the only state a payment can start from. Then request one
+through the real primitive — see
+[Request a Stripe payment and follow it](./request-and-verify-a-payment.md).
+
+## Gotchas
+
+- **`asked` empty means "never asked".** A seeded connection carries no Stripe
+  verdict on purpose; the first account event or `stripe refresh` fills it.
+- **`error` set means the last read failed** (`stripe refresh` or an event's
+  re-read). It is shown, never interpreted — even "does not have access" does
+  not flip the state to revoked by itself.
+- **A stale `no` is the expensive direction.** The mirror is refreshed by
+  webhook, and a missed delivery leaves a school unable to collect although it
+  may. `plexus-cli stripe refresh` is the way out — there is no equivalent
+  problem in the other direction, because Stripe refuses a charge on an account
+  it has since restricted.
+- **`state=revoked` cannot be fixed here.** The school removed Plexus's access
+  in their own Stripe dashboard. Connecting again is not built;
+  `stripe allow` refuses rather than pretending.
+- **One school, one account, forever.** Once a school has an account, „Stripe
+  einrichten" only continues Stripe's form for it and never creates a second
+  one, because replacing the reference would orphan every open payment pointing
+  at the first account. A double click is harmless: one idempotency key per
+  tenant gives back the same account.
+- **The link died** (reopened, older than a few minutes, opened by a chat
+  preview): Stripe sends the person back with `?onboarding=expired`. The page
+  asks before sending them in again. It never redirects on its own.
+- **`state=platform_unconfigured`** is about the installation, not the school —
+  clearing `stripe_mode` on a deployment removes every `STRIPE_*` variable while
+  the schools' rows stay behind.
+- **`state=closed`** — Stripe closed the account. Onboarding cannot reopen it;
+  only a new account helps, which means replacing the connection (not built).
+- **Two destinations, two secrets** (set by a platform operator): without
+  `STRIPE_WEBHOOK_SECRET` no account event (thin) verifies, without
+  `STRIPE_CONNECT_WEBHOOK_SECRET` no school payment (snapshot) — `/stripe/webhook`
+  answers **503** naming the variable (not 400 — "cannot check" is not "did not
+  check out"); payments then settle only through the 5-minute poll.

package/dist/skill/references/stripe/request-and-verify-a-payment.md

@@ -0,0 +1,78 @@
+# Eine Stripe-Zahlung anfordern und nachverfolgen
+
+Wofür: eine Einmalzahlung über Stripe auslösen und ihren Weg bis `succeeded`
+verfolgen — lokal, auf Staging oder in Produktion. Voraussetzung ist eine
+verbundene Schule: [Schule mit Stripe verbinden](./connect-a-school.md).
+
+Für die Hand statt fürs Skript gibt es dasselbe unter **Administration →
+Integrationen** (`/$tenant/admin/integrations`) — gleiche Funktionen, gleiche
+Rechte, nur mit Knöpfen. Dieses Playbook ist der skriptbare Weg.
+
+Für Zahlungen hat `plexus-cli stripe` (noch) keine eigenen Befehle — die Gruppe
+verbindet nur die Schule; der Zahlungsadapter wird über `plexus-cli call`
+bedient (`plexus-cli functions --grep stripe` listet die Funktionen).
+
+## 0. Verbindung prüfen
+
+```bash
+plexus-cli --env local --json call stripe:status client=<tenant>
+```
+
+`configured: false` nennt in `missing`/`invalid` genau die Variablen, an denen es
+liegt. `mode` sagt, ob echtes Geld im Spiel ist.
+
+## 1. Zahlung anfordern
+
+```bash
+plexus-cli --env local --json call stripe:create --kind mutation \
+  client=<tenant> \
+  amountMinor=18000 \
+  currency=eur \
+  description="Anmeldegebuehr Schuljahr 2026/27" \
+  customerEmail=eltern@beispiel.example \
+  requestKey=admissionFee:<applicationId> \
+  returnPath=/<tenant>/e/bewerbung/<applicationId>
+```
+
+- **`amountMinor` sind CENT**, nicht Euro. 180 € sind `18000`.
+- **`requestKey` leitet sich aus der Sache ab**, für die gezahlt wird — nie aus
+  einem Zeitstempel. Derselbe Schlüssel gibt dieselbe Zeile zurück
+  (`reused: true`), solange ein Versuch läuft oder die Forderung bezahlt ist.
+- **`returnPath` ist ein app-relativer Pfad.** Eine absolute URL wird abgewiesen.
+
+## 2. Zustand lesen
+
+```bash
+plexus-cli --env local --json call stripe:get client=<tenant> stripePaymentId=<id>
+```
+
+`checkoutUrl` ist die Zahlungsseite (nur solange `status: open`). `events` zeigt
+die von Stripe zugestellten, signaturgeprüften Rückrufe.
+
+## 3. Wenn nichts passiert
+
+Zuerst: **das ist normal, bis jemand zahlt.** Danach der Reihe nach:
+
+```bash
+# von Hand abgleichen (der Cron tut es alle 5 Minuten von selbst)
+plexus-cli --env local --json call stripe:reconcileNow --kind mutation \
+  client=<tenant> stripePaymentId=<id>
+```
+
+- `status: requires_session` länger als ein paar Sekunden ⇒ die Aktion ist
+  gescheitert. `error` auf der Zeile nennt Stripes Grund; nach zehn Minuten
+  markiert der Reaper sie als `failed`.
+- `status: processing` ⇒ SEPA. Stripe selbst rät zu **mindestens sechs
+  Werktagen** Geduld, bevor man eine Lastschrift als erfolgreich betrachtet.
+- Keine `events`, obwohl gezahlt wurde ⇒ der Webhook kommt nicht an (das richtet
+  der Plattformbetreiber ein); der Abgleich-Cron holt es trotzdem ein.
+
+## 4. Zurückziehen
+
+```bash
+plexus-cli --env local --json call stripe:cancel --kind mutation \
+  client=<tenant> stripePaymentId=<id> reason="Platz anderweitig vergeben"
+```
+
+Schließt erst die Seite bei Stripe, dann die Zeile. Eine bereits eingegangene
+Zahlung wird dabei **nie** zurückgezogen — der Aufruf gleicht sie stattdessen ab.