@smartkomm/plexus-cli 0.0.0-stage → 0.1.1

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.

package/dist/skill/references/test-actions/drive-a-test-application.md

@@ -0,0 +1,69 @@
+# Drive a test application through test mode
+
+**When to use:** walk a test application through an offer from the terminal — load a form
+scenario and submit it, fill the file fields, submit a form — exactly what the cockpit's
+test-mode popover („Testmodus") does. Replaces raw `call workflow:listTestActions` /
+`runTestAction`.
+
+## Prerequisites
+- `--tenant` set, and `--env` named on the command line for `run` (it writes; prod also
+  needs `--allow-prod`); the application is a **test application** (started in test
+  mode) and the caller holds `testActions.run`. Otherwise both verbs refuse with that reason.
+- The application id — start one with `applications start-test`
+  ([Start a test application](../applications/start-a-test-application.md)) or list them with
+  `applications list --offer <slug> --test-only`.
+- The form's scenarios exist — see [Author a form's test scenarios](../offer/author-form-scenarios.md).
+
+## Steps
+```bash
+# What the application's current node(s) offer:
+plexus-cli --env staging --tenant test test-actions list --application <applicationId>
+
+# Load a scenario and submit (files are stubbed with openable PDFs first):
+plexus-cli --env staging --tenant test test-actions run --application <applicationId> \
+  --action load-scenario:joint-reduced-fee
+
+# Only load the values, no submit:
+plexus-cli --env staging --tenant test test-actions run --application <applicationId> \
+  --action load-scenario:joint-reduced-fee --no-auto-submit
+
+# Fill every file field, then submit once the fill has landed:
+plexus-cli --env staging --tenant test test-actions run --application <applicationId> --action auto-fill-files
+plexus-cli --env staging --tenant test test-actions list --application <applicationId>   # submit-form no longer disabled?
+plexus-cli --env staging --tenant test test-actions run --application <applicationId> --action submit-form
+
+# An action that asks a question first (the popover's dialog) runs with its answer as a param —
+# upload the signed copy with the contract terms confirmed:
+plexus-cli --env staging --tenant test test-actions run --application <applicationId> \
+  --action upload-signed-document --param confirmed=true
+
+# Application-wide actions (listed under „(Bewerbung)“), e.g. become responsible:
+plexus-cli --env staging --tenant test test-actions run --application <applicationId> --action takeResponsibility
+```
+
+Without `--node` the CLI asks every current node of the application and runs the action
+on the one that offers it. Two current nodes offering the same action (parallel branches)
+→ it stops and asks for `--node`.
+
+## Verify
+`run` prints the action and the node it ran on. File fills — and the submit a scenario
+does after them — run as a scheduled action and land a moment later; `test-actions list`
+then shows what the next node offers.
+
+## Idempotency / gotchas
+- A disabled action is refused with its reason before the server is asked
+  (`submit-form … disabled: missingRequired (3)` — a required field is still empty).
+- `load-scenario:<id>` submits by default, like the popover's „Automatisch absenden" checkbox;
+  that switch is `--no-auto-submit`, never `--param autoSubmit=…` (refused).
+- `--param key=value` (repeatable) sends the action's params; each value is JSON where it
+  parses (`true`, `3`, `{"a":1}`), else text — quote a number meant as text (`--param note='"007"'`).
+  An action that declares a question (`upload-signed-document`, the contract terms) is refused
+  by the server without `--param confirmed=true`, and refused WITH it when it asks nothing.
+- Not a test application, or no `testActions.run`: refused with that reason (never an empty
+  list). An unknown `--node`: refused with the node id.
+- The UI label of `auto-fill-files` is „File-Felder mit Dummy füllen“.
+- Real applications are never driven this way; the server refuses test actions outside
+  test mode.
+
+## Related
+- [Author a form's test scenarios](../offer/author-form-scenarios.md) · [Use a tenant's test account](../users/use-test-account.md)

package/dist/skill/references/users/add-platform-admin.md

@@ -0,0 +1,59 @@
+# Add a platform admin
+
+**When to use:** you need a **tenant-less platform operator** (full `_platform.*`
+set, reaches every tenant) with a working login — e.g. onboarding a new operator or
+agent.
+
+## Prerequisites
+- **Env:** target with `--env <local|staging|prod>`. **No `--tenant`** — a platform
+  admin is tenant-less by definition.
+- **Auth:** your **own platform-admin token** (needs `_platform.users.manage`); a
+  Convex admin key is **not** sufficient. Confirm with
+  `plexus-cli --env <env> whoami`.
+- **Inputs:** the new admin's email + display name. The email must **not** already
+  have tenant access (the `_platform.* XOR tenant-access` invariant).
+- **Tooling:** an installed `plexus-cli`; `plexus-cli users --help` lists the user
+  commands.
+
+## Steps
+```bash
+plexus-cli --env <env> users provision-platform-admin <email> \
+  --name "Vorname Nachname" \
+  --output creds.csv --quiet
+```
+
+- The server **generates the password and returns it once**. `--output creds.csv`
+  captures the `email,password` row; `--quiet` keeps it out of stdout. To set a known
+  password, pass `--password "…"`.
+
+## Verify
+```bash
+plexus-cli --env <env> users show <email>
+```
+
+Success: a `platform: …` line lists the full `_platform.*` permission set and the
+user has **no** tenant rows. `plexus-cli --env <env> platform users` lists them too.
+
+## Hand the credentials over
+
+Same three-line format as every other credential handover — URL, email, password,
+bare, one block per account. See
+[Add a tenant admin](./add-tenant-admin.md) → "Hand the credentials over".
+
+## Idempotency / gotchas
+- **Idempotent — re-running rotates the password** (does not duplicate the account).
+- **Refuses an email that already has tenant access** (the `_platform.* XOR
+  tenant-access` invariant). For a per-tenant account use
+  [Add a tenant admin](./add-tenant-admin.md) instead.
+- Contrast `users create <email> --platform-admin`, which also mints a credential
+  (no verb leaves an identity that cannot log in) but takes **no display
+  name** and never rotates an existing password. `provision-platform-admin` is the
+  named path, and re-running it deliberately resets the login.
+- Runtime-only account — **not** part of the demo seed (real personal passwords
+  never are); a destructive reseed won't recreate it. Re-run if ever reseeded.
+
+## Related
+- [Add a tenant admin](./add-tenant-admin.md) — the per-tenant twin (`users provision`).
+- Command reference: `plexus-cli users provision-platform-admin --help` and
+  `plexus-cli users create --help` (the create-vs-provision distinction above).
+- Connection and token: `plexus-cli config show`, `plexus-cli whoami`.

package/dist/skill/references/users/add-platform-user.md

@@ -0,0 +1,59 @@
+# Add a platform user
+
+**When to use:** you need a **tenant-less platform operator** with a limited,
+explicit `_platform.*` permission set and a working login.
+
+## Prerequisites
+- **Env:** target with `--env <local|staging|prod>`. **No `--tenant`** — a platform
+  user is tenant-less by definition.
+- **Auth:** your **own platform-admin token** (needs `_platform.users.manage`); a
+  Convex admin key is **not** sufficient. Confirm with
+  `plexus-cli --env <env> whoami`.
+- **Inputs:** the user's email, display name, and exact platform permissions. The
+  email must **not** already have tenant access (the `_platform.* XOR tenant-access`
+  invariant).
+- **Tooling:** an installed `plexus-cli`; `plexus-cli users --help` lists the user
+  commands.
+
+## Steps
+```bash
+plexus-cli --env <env> users provision-platform-user <email> \
+  --name "Vorname Nachname" \
+  --permission _platform.schema.read \
+  --output creds.csv --quiet
+```
+
+- Repeat `--permission` for every `_platform.*` permission the user should hold.
+- The server **generates the password and returns it once**. `--output creds.csv`
+  captures the `email,password` row; `--quiet` keeps it out of stdout. To set a known
+  password, pass `--password "..."`.
+
+## Verify
+```bash
+plexus-cli --env <env> users show <email>
+```
+
+Success: a `platform: ...` line lists exactly the requested `_platform.*`
+permissions and the user has **no** tenant rows.
+
+## Hand the credentials over
+
+Same three-line format as every other credential handover — URL, email, password,
+bare, one block per account. See
+[Add a tenant admin](./add-tenant-admin.md) → "Hand the credentials over".
+
+## Idempotency / gotchas
+- **Idempotent — re-running rotates the password** and resets the platform
+  permission list to exactly the repeated `--permission` values.
+- **Refuses an email that already has tenant access** (the `_platform.* XOR
+  tenant-access` invariant). A limited platform user cannot also be a tenant user.
+- For full platform operators, use [Add a platform admin](./add-platform-admin.md)
+  instead. That command grants the full `_platform.*` set.
+- Runtime-only account — **not** part of the demo seed (real personal passwords
+  never are); a destructive reseed won't recreate it. Re-run if ever reseeded.
+
+## Related
+- [Add a platform admin](./add-platform-admin.md) — full `_platform.*` operators.
+- [Set (rotate) a user's password](./set-password.md) — rotate an existing
+  credential without changing access.
+- Connection and token: `plexus-cli config show`, `plexus-cli whoami`.

package/dist/skill/references/users/add-tenant-admin.md

@@ -0,0 +1,75 @@
+# Add a tenant admin
+
+**When to use:** a staff member should administer **one tenant** with a working
+login — a ready-to-use account (credential + full tenant-admin access), not just a
+permission grant.
+
+## Prerequisites
+- **Env / tenant:** target with `--env <local|staging|prod>` **and** `--tenant <slug>`
+  (this is tenant-scoped). Run `plexus-cli --env <env> tenants` to see the slugs you
+  reach.
+- **Auth:** a token whose identity may manage users in that tenant (a platform-admin
+  token, or tenant access with `_platform.users.manage`). Confirm with
+  `plexus-cli --env <env> whoami`.
+- **Inputs:** the new user's email + display name.
+- **Tooling:** an installed `plexus-cli`; `plexus-cli users --help` lists the user
+  commands.
+
+## Steps
+```bash
+plexus-cli --env <env> --tenant <slug> users provision <email> \
+  --name "Vorname Nachname" --group tenant_admin \
+  --output creds.csv --quiet
+```
+
+- `--group tenant_admin` is the **default**, so it may be omitted; it's shown here to
+  be explicit. Pass a different permission-group key (see
+  `plexus-cli --env <env> --tenant <slug> users groups`) for a non-admin staff account.
+- The server **generates the password and returns it once**. `--output creds.csv`
+  appends the `email,password` row to a file; `--quiet` keeps it out of stdout. To set
+  a known password instead, pass `--password "…"` (and drop `--quiet` if you want to
+  see it echoed).
+
+## Verify
+```bash
+plexus-cli --env <env> users show <email>
+```
+
+Success: the user lists the `<slug>` tenant with groups `tenant_admin, applicant`.
+(`users show` is a global lookup across every tenant the user belongs to — no
+`--tenant` needed; the email match is case-insensitive.)
+
+## Hand the credentials over — always this format
+
+Three bare lines, nothing else: URL, email, password. No table, no markdown link,
+no labels. One block per account, so the recipient can copy each line straight
+into the login form.
+
+```
+https://plexus.swop.schule/
+ada@example.com
+<the generated password>
+```
+
+Use the app URL of the env you provisioned in. Write the URL bare: a markdown link renders as a terminal escape
+sequence, and the address never reaches the visible text.
+
+## Idempotency / gotchas
+- **Re-running rotates the password** (it re-provisions the credential) and re-emits
+  it — re-run only if you intend to reset the login.
+- The password is shown **once**; if you didn't capture it, re-run with `--output …`
+  to mint a fresh one.
+- This both **grants tenant access and creates a login credential** — contrast
+  `users add` / `users set-group`, which only adjust access and group membership for
+  a user who already exists. `users add` REFUSES an unknown address (it
+  has no name or password channel, so any identity it created could never log in);
+  provision the account first, here.
+- The backend lowercases the email; the login address is the lowercased form.
+- Runtime-only account — it is **not** part of the demo seed, so a destructive reseed
+  won't recreate it; re-run this playbook if the tenant is ever reseeded.
+
+## Related
+- [Add a platform admin](./add-platform-admin.md) — the tenant-less platform twin
+  (`users provision-platform-admin`).
+- Command reference: `plexus-cli users --help`.
+- Connection and token: `plexus-cli config show`, `plexus-cli whoami`.