@smartkomm/plexus-cli 0.0.0-stage → 0.1.1

package/dist/skill/references/marketing/demo-video-links.md

@@ -0,0 +1,101 @@
+# Personalised demo video links with viewing statistics
+
+**When to use:** send a named person a link to the public demo video page — to one
+video or to the whole page — and later see whether they opened it, when, how often
+and how long they watched each video. One sentence such as "Link für Erika
+Mustermann zum Video Vorlagen" becomes one `demo link create`.
+
+## Prerequisites
+- A token of a platform operator with `_platform.demoLinks.manage` (every full
+  platform admin holds it). A school's own token cannot create links — needs a
+  platform operator.
+- Getting such a token: an operator holding `_platform.apiTokens.manage` mints one
+  for themselves with `plexus-cli tokens create <name>`, or for you with
+  `plexus-cli tokens create <name> --for <your email>` (then you need
+  `_platform.apiTokens.manage` too — needs a platform operator).
+- `--env prod` for real recipients; every writing command against production also
+  needs `--allow-prod`.
+
+## Steps
+```bash
+# 1. Which videos exist (id, date, title, length) — the id is what --video takes.
+plexus-cli --env prod demo videos
+
+# 2a. One recipient, one video → prints the finished URL.
+plexus-cli --env prod demo link create --allow-prod \
+  --to "Erika Mustermann" --email erika@example.com --video vorlagen --campaign herbst
+
+# 2b. Without --video the link opens the whole page.
+plexus-cli --env prod demo link create --allow-prod --to "Erika Mustermann"
+
+# 2c. Many recipients from a CSV (header row: name, email or E-Mail, video — email and
+#     video optional; a row's video wins over --video). Writes the links as a CSV that
+#     German Excel opens directly (";" separated, umlauts intact).
+plexus-cli --env prod demo link create --allow-prod \
+  --from recipients.csv --video vorlagen --campaign herbst --out links.csv
+
+# Machine-readable (code + url per recipient):
+plexus-cli --env prod demo link create --allow-prod --to "Erika Mustermann" --json
+```
+
+Send each recipient **their own** URL. The link's `?r=<code>` names the recipient;
+the rest of the URL is the page's usual jump to the video.
+
+The recipient CSV must be **UTF-8**: in Excel, *Save as → „CSV UTF-8 (durch
+Trennzeichen getrennt) (*.csv)"*. A file in the older „CSV (Trennzeichen-getrennt)"
+format is refused instead of turning „Müller" into „M�ller". `,` and `;` both work;
+an unknown column or a row with more values than the header (an unquoted comma in a
+name) is refused, naming the row.
+
+## Verify
+```bash
+plexus-cli --env prod demo link list --campaign herbst
+plexus-cli --env prod demo link stats --campaign herbst   # or: demo link stats <code>
+```
+`stats` shows one row per recipient and video:
+- `besuche` — page loads a person engaged with (see the gotchas),
+- `erster` / `letzter` — first and latest visit, German time,
+- `gesehen` — seconds actually played, summed over all visits, / video length,
+- `%` — how much of the video the best single visit actually played. Skipping ahead
+  to the end does not count: someone who drags the slider to the end and stops shows
+  a few seconds and a low `%`.
+
+A recipient who never opened the link shows `0` and `—`.
+
+To stop counting a link (e.g. it was posted publicly by mistake):
+```bash
+plexus-cli --env prod demo link revoke --allow-prod <code>
+```
+The page keeps working for everyone; the statistics recorded so far stay readable.
+
+To erase a link on request (the name, the address and everything recorded):
+```bash
+plexus-cli --env prod demo link delete --allow-prod <code>            # shows what would go
+plexus-cli --env prod demo link delete --allow-prod <code> --confirm  # deletes, cannot be undone
+```
+
+## Idempotency / gotchas
+- **When a visit counts.** Only after the page was visible for 5 seconds or the
+  visitor scrolled, tapped, clicked, typed or pressed play. Mail scanners that only fetch
+  the link (Outlook Safe Links and the like) never count; a scanner that renders the
+  page for a moment rarely does. **A play is the hard signal**: `gesehen` above
+  `0:00` means a person watched. `besuche = 0` right after sending is expected.
+- **A forwarded link counts for the original recipient.** The link knows only whom it
+  was created for; if they forward it, the colleague's viewing is counted under their
+  name. Create a separate link per person.
+- **Every page load is a visit**, a reload too. Switching view or video on the page
+  is not a new visit.
+- **Watching time is counted from playback**, every 10 seconds and when the viewer
+  pauses or leaves: closing the tab abruptly can lose up to 10 seconds.
+- **No cookie, nothing stored in the browser, no session replay** for pages opened
+  through such a link. Visits and playback are deleted after 12 months; the link
+  itself (name, address) stays until `demo link delete`.
+- `create` is not idempotent: running it twice gives the same person two links.
+  `revoke` is: revoking twice keeps the first time.
+- An unknown video id is refused, and the error lists every valid id. A CSV batch is
+  created all or nothing (at most 500 recipients per call).
+- A heavily shared link records at most 30 page loads an hour; beyond that its
+  visits are not counted.
+
+## Related
+- `plexus-cli demo link stats --json` for further processing (e.g. `jq`).

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`.

package/dist/skill/references/notifications/mail-level.md

@@ -0,0 +1,90 @@
+# Choose which mail a school sends (mail level)
+
+> **Version check first.** A deployment on a release older than the mail level
+> ignores `--field mailLevel` WITHOUT an error and keeps reading the retired
+> `tenant.enabledMailCategories` (`[]` = sign-in only, every category = all).
+> If `config export` shows no `mailLevel`, stop and ask the platform operator.
+> The same skew means a tenant scaffolded with a newer CLI against an older
+> deployment starts at sign-in mail only.
+
+**When to use:** a school wants only the sign-in links for FAMILIES for now
+(„Anmeldelinks ja, alles andere nein"), or is ready for every mail.
+
+**The level is family mail only.**
+Letters to the school's own staff (`audience: "internal"`: new tasks, passed
+deadlines, family messages, mentions) go out at BOTH levels; each staff member
+decides them in „Einstellungen" (personal categories, runbook „Which mail a
+staff member wants"). Do not use the level to quiet staff mail.
+
+**Current stance:** every tenant — prod, staging and the `test` demo tenant —
+runs `loginOnly` until the platform operator decides otherwise. Switching a real
+school to `all` is that decision, not a routine step. Locally, a reseeded `test` tenant is at `loginOnly` too; to see a
+rendered admission, family-task or school-chat letter set it to `all` on your
+own deployment (`--env local`). Staff letters render at both levels.
+
+## What it is
+
+- A school has ONE setting, its **mail level** (`tenant.mailLevel`, required in
+  every tenant config):
+  - `loginOnly` — „An Familien nur Anmeldelinks": to families, sign-in links,
+    the access a school hands out, address confirmations („Bewerbung
+    begonnen/geparkt" included) and security notices about one's own account
+    (e.g. a changed login address).
+  - `all` — „Alle E-Mails": to families additionally admission, family task
+    reminders and the school's chat messages.
+- Every letter still declares a **category** in code (`login`, `security`,
+  `admission`, `tasks`, `schoolMessages`; for staff the personal `staffTasks`,
+  `staffAppointments`, `staffDeadlines`, `familyMessages`, `mentions`). It names
+  the letter in a skipped delivery's reason; a school cannot switch single
+  categories.
+- The `notifications` module must be enabled for `all`; with the module off only
+  sign-in and security mail go out whatever the level says.
+- Refused by `config set` / `config apply`: a missing or unknown level
+  (`[notification/mailLevel]`), `all` without the `notifications` module
+  (`[notification/levelWithoutModule]`), and the retired spellings
+  `tenant.enabledMailCategories` (`[notification/mailCategoriesRetired]`)
+  and `tenant.mailEnabled` (`[notification/mailEnabledRetired]`) — a scratch
+  export from before the mail level must be rewritten, not applied.
+- `MAIL_DELIVERY_MODE` of the deployment stays the outer boundary. Never change
+  it for this.
+
+## Set it (dry run first)
+
+```bash
+# sign-in mail only
+plexus-cli --env staging config set --tenant <slug> --target tenant \
+  --key <slug> --field mailLevel --value loginOnly
+plexus-cli --env staging config set --tenant <slug> --target tenant \
+  --key <slug> --field mailLevel --value loginOnly --confirm
+
+# everything (what the introduction of the level wrote for every school that sent mail)
+plexus-cli --env staging config set --tenant <slug> --target tenant \
+  --key <slug> --field mailLevel --value all --confirm
+```
+
+Through a scratch export instead: `config export` → set
+`"tenant": { …, "mailLevel": "loginOnly" }` → `config apply --from snapshot:…`.
+
+## Verify
+
+- `plexus-cli --env <env> config export --tenant <slug>` shows `mailLevel`
+  (always emitted).
+- Platform rail → **Mandanten** (needs `_platform.config.read`): the column
+  „E-Mails" says „Nur Anmeldelinks" (amber) or „Alle E-Mails" — as the send
+  path answers it, so module off reads „Nur Anmeldelinks" too.
+- Dashboard of the school: banner „Hinweis zur Konfiguration" on top of the
+  page, gap `mailDisabled` („Diese Schule versendet nur Anmeldelinks …") —
+  unless the school hides that notice: `config set --tenant <slug> --target tenant
+  --key <slug> --field hideMailLevelNotice --value true --confirm` (mail-module setting, shown under
+  „notifications" in Platform → Mandanten; the test tenant does). Only this
+  notice goes; a configuration error always shows.
+- A suppressed letter is a row: `plexus-cli --env <env> notifications …` lists it
+  `skipped`, `tenant_delivery_disabled`, last error
+  `the school's mail level does not send "<category>" mail`.
+
+## Gotchas
+
+- A skipped delivery is never re-sent when the level goes back to `all` — the
+  setting decides at enqueue AND at send time, not retroactively.
+- `applicant.accessSent` („Zugang versenden → Per Mail senden") is `login`: it
+  goes out at `loginOnly`.

package/dist/skill/references/notifications/reword-a-letter.md

@@ -0,0 +1,155 @@
+# Reword a letter for one school
+
+**When to use:** a school wants one of the mails Plexus sends in its name to say
+something else — a different opening paragraph, its own sign-off — and you want
+to prove the new words actually reach a rendered mail before anyone relies on it.
+
+## Prerequisites
+
+- `--tenant <slug>` on every command: a letter is reworded **per school**, never
+  platform-wide.
+- Permissions `notifications._self.access` (read) and
+  `notifications.mail.configure` (write). The local CLI bootstrap has both.
+- Locally: a running local development deployment (`--env local`). **Nothing is
+  ever sent from a local deployment** (`MAIL_DELIVERY_MODE=dry`) — the rendered mail
+  lands in `notification_previews`, which is exactly what makes this verifiable.
+
+## Steps
+
+```bash
+# 1. What can this school reword, and what has it already changed?
+plexus-cli --env local --tenant test notifications letters list
+
+# 2. One letter, block by block, with the placeholders the LETTER may use
+#    printed above them — they belong to the letter, not to one paragraph, so a
+#    school may move a value into whichever block it likes. They are an
+#    ALLOWLIST: an undeclared {{x}} is refused, never silently printed. One
+#    marked "(Pflicht)" must appear somewhere in the BODY or the save is refused
+#    — that is what replaced the lock on the two sign-in letters.
+plexus-cli --env local --tenant test notifications letters show applicant.tasksOpen --locale de
+
+# 3. Reword ONE block, in ONE language. Untouched blocks are not written and
+#    keep following the platform text of that language; the other language is
+#    not touched at all (a German rewording never words the English letter).
+plexus-cli --env local --tenant test notifications letters set applicant.tasksOpen --locale de \
+  --slot intro="bei {{schoolName}} warten {{taskCount}} Aufgaben auf Sie."
+plexus-cli --env local --tenant test notifications letters set applicant.tasksOpen --locale en \
+  --slot intro="{{taskCount}} tasks at {{schoolName}} are waiting for you."
+
+#    A paragraph with line breaks belongs in a file, not in a shell argument:
+# plexus-cli --env local --tenant test notifications letters set applicant.tasksOpen --locale de \
+#   --slot-file intro=./intro.txt
+
+# 4. The shared letter frame (greeting, sign-off, sender name) is separate —
+#    it is the same frame for EVERY letter this school sends, worded in both
+#    languages at once (each letter carries its own language's line).
+plexus-cli --env local --tenant test notifications chrome show
+plexus-cli --env local --tenant test notifications chrome set \
+  --closing-de="Herzliche Grüße
+Ihr Grundschul-Team" \
+  --closing-en="Warm regards
+Your primary school team"
+```
+
+## Verify
+
+Reading back the catalog only proves the row was stored. What has to be proven is
+that the words reached a **rendered mail**:
+
+```bash
+# a) The stored deviation
+plexus-cli --env local --tenant test notifications letters list      # "reworded: de, en"
+plexus-cli --env local --tenant test notifications letters show applicant.tasksOpen --locale en
+
+# b) Trigger the letter (for applicant.tasksOpen: open an external task on an
+#    application — e.g. a workflow task addressed to the family), then find its
+#    delivery and read the body that was actually rendered:
+plexus-cli --env local notifications list --limit 20
+plexus-cli --env local notifications show <deliveryId> --json | grep -A12 '"letter"'
+```
+
+`letter.text` (and `letter.html`) carry the reworded sentence, and
+`letter.version.reworded` names the blocks in which the school's wording stood,
+`letter.version.locale` the language it went out in — the RECIPIENT ACCOUNT's
+(`users.language`). To see the English letter go out, the recipient's account
+must have chosen English; the preview in Administration → Benachrichtigungen
+shows either language without one. The same rows are the Dev Rail →
+**Mail** panel, which is the human version of the same check (and the place to
+follow a sign-in link this deployment "sent").
+
+Roll back — one block, or the whole letter:
+
+```bash
+plexus-cli --env local --tenant test notifications letters reset applicant.tasksOpen --locale de --slot intro
+plexus-cli --env local --tenant test notifications letters reset applicant.tasksOpen --locale en --all
+plexus-cli --env local --tenant test notifications chrome set --closing-de="" --closing-en=""   # back to the platform sign-off
+```
+
+The next rendered mail carries the platform text again — no republish, no deploy.
+
+## Idempotency / gotchas
+
+- **A deviation is a delta, not a copy.** Only the blocks a school rewrote are
+  stored. A block left alone keeps following the code, so a later platform
+  improvement to it still reaches that school. Setting a block to *exactly* the
+  platform text therefore stores nothing — the command's `deviating blocks` line
+  is the backend's answer, and it will not list that block.
+- **`set` merges.** Passing `--slot intro=…` does not wipe a deviation on
+  `outro`. The way back is `reset`, which names what to drop.
+- **`reset` without `--slot` needs `--all`.** Dropping every deviation of a
+  letter must be typed, not be what happens when a flag is forgotten.
+- **Some letters have no blocks at all.** The two sign-in letters
+  (`applicant.magicLink`, `applicant.verifyEmail`) are category `login`: the mail
+  that carries a login link is not rewordable by anyone, so it declares nothing
+  to reword. They show `— (not editable)` in the list.
+- **An unknown block or placeholder throws, naming every finding.** Nothing is
+  written — there is no partial save.
+- **`--locale de|en` is required** on `show`, `set` and `reset`: every
+  letter exists in German and English, each worded on its own, and a command
+  that silently picked one would reword the letter you were not looking at. A
+  recipient gets the language of their own account; a school that rewords only
+  the German letter sends its English families the platform's English text —
+  the workshop says so on the letter.
+- **This is configuration, not operational state.** A change made here is
+  exported, diffed and promoted like any other tenant setting — see
+  "Promote the wording to another environment" below. On staging/prod prefer
+  the config route so the change is reviewable; the direct `letters set` is for
+  local exploration and for a one-off correction with the platform operator watching.
+
+## Promote the wording to another environment
+
+The deviations live in the tenant config under `notificationLetters` (identity
+`templateId:locale:scopeKey`) and the frame under
+`tenant.notificationChrome`, so the ordinary config-as-code verbs carry them:
+
+```bash
+# Export → edit → dry-run → confirm, exactly as for any other tenant setting.
+plexus-cli --env staging config export --tenant test --out /tmp/test.json
+# …edit `notificationLetters` / `tenant.notificationChrome` in /tmp/test.json…
+plexus-cli --env staging config apply --tenant test --from snapshot:/tmp/test.json
+plexus-cli --env staging config apply --tenant test --from snapshot:/tmp/test.json --confirm
+
+# One block, without an export round trip. The --key IS the identity triple
+# (templateId:locale:scopeKey) — a letter is worded per language and per scope.
+plexus-cli --env staging config set --tenant test \
+  --target notification-letters --key "applicant.tasksOpen:de:tenant" \
+  --field slots.intro --value "…" --confirm
+```
+
+Two things follow from "a deviation is a delta":
+
+- A letter **absent** from `notificationLetters` is a letter this school does not
+  deviate from, so applying a config without it takes that letter back to the
+  platform text. Removing an entry is how you undo a rewording in config.
+- `config set` **edits an existing entry**; it does not create one. The first
+  deviation for a letter comes from `notifications letters set` or from an
+  edited export.
+
+## Related
+
+- [Debug a mail delivery](./debug-mail-delivery.md) — when the mail did not
+  arrive at all (the operator's log, not the school's wording).
+- [Update a tenant's config](../config/update-tenant-config.md) — the export →
+  edit → dry-run → apply loop these letters travel in.
+- `plexus-cli notifications letters show --help` (and `set`/`reset`) — the letter /
+  block / override commands; a letter showing `— (not editable)` is one a school may not reword.

package/dist/skill/references/notifications/trace-a-login.md

@@ -0,0 +1,50 @@
+# Trace why someone could not sign in
+
+**When:** „I asked for a sign-in link and got nothing", „the link said already
+used", „my new password does not work" — on any environment, after the fact.
+
+## Prerequisites
+
+A platform token with `_platform.users.manage` (sessions name IP addresses) and
+`_platform.notifications.monitor` (the delivery list).
+
+## Steps
+
+```bash
+# Everything the platform still knows about the address, oldest first.
+plexus-cli --env prod users login-trail ada@example.com --since 24h
+
+# Only the login page's letters to that address, with the relay's answer.
+plexus-cli --env prod notifications list --template account.loginLink --to ada@example.com --since 24h
+```
+
+`login-trail` prints one time-ordered list:
+
+| Line | Means |
+| --- | --- |
+| `abgelehnt: <reason>` | the login page sent this KNOWN account no link (`platformAdmin`, `unprovenAddress`, `noSchoolWithOption`) |
+| `Brief account.loginLink: sent — Relay: 250 … queued as <id>` | our relay accepted the mail; the queue id finds it in the relay's log |
+| `Sitzung von <ip> — <browser>` | a sign-in happened. A session seconds after the letter from a foreign network is a **mail scanner** (Exchange Safe Links), not the person |
+| `Passwort gesetzt (zuletzt)` | the credential was last changed then — compare with the failed attempts |
+
+## Reading it (an invented example)
+
+- letter `sent` 09:12:05 → session from `203.0.113.7` at 09:12:29, a network the school
+  does not use → the person got „link already used": the scanner spent it. A link now opens a page first and only
+  its button spends the token, so a scanner no longer uses it up.
+- password set 09:20:41, session from the school's network 09:20:42, failed
+  attempts before: the earlier resets went to **another** account (check the
+  `Passwort gesetzt` line of the account the person actually uses).
+
+## Gotchas
+
+- Not recorded at all (the command lists it under „Nicht erfasst"): rate-limited
+  requests, requests for an address without an account (both only in the
+  function log, minutes), anything older than 30 days, ended sessions, and what
+  happened after our relay (inbox / spam / quarantine / bounce).
+- `sent` in every list means „our relay said 250", never „in the inbox". The
+  console's word for it is „Versendet".
+
+## Related
+
+- [Debug a mail delivery](./debug-mail-delivery.md)