@smartkomm/plexus-cli 0.0.0-stage → 0.1.0

package/dist/skill/.managed-by-plexus-cli

@@ -0,0 +1 @@
+b0828b779f68e43815116c5103ec6d7e6d29bd7aae08a1da060ceda112fc809a

package/dist/skill/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: plexus-cli
+description: "Cli: drives a school's Plexus tenant (school administration — admissions, forms, workflows, letters, contracts, users) from the shell with `plexus-cli`, as the person whose API token it uses. Use when a Plexus tenant must be inspected or set up from the terminal: an admission offer (form, workflow, capacities), a letter's wording, test applications, users, exports — or when plexus-cli is named. Every task has a recipe under references/; each recipe states whether a school's tenant token suffices or a platform operator is needed."
+---
+
+# plexus-cli
+
+`plexus-cli` operates a Plexus tenant through the platform's public API. Every
+call runs as the person who minted the token, with exactly that person's rights —
+the CLI adds no authority of its own. A school's agent works with a **tenant
+token**: what the school's admin may do in the app, the CLI may do; everything
+else the platform operator does.
+
+## Connect
+
+1. In the app: **Einstellungen → API-Token**, create a token (`plx_…`). It carries
+   your rights in every tenant you can reach; keep it like a password. Every call
+   checks the right to manage API tokens again; the change that takes it away
+   revokes the token (401 „… wurde am <Datum> widerrufen“) — mint a new one.
+2. Configure the environment once, either in `~/.config/agent-tools/plexus.yml`:
+
+   ```yaml
+   plexus:
+     default_tenant: <slug>
+     environments:
+       prod: { convex_url: "https://db.plexus.swop.schule", site_url: "https://actions.db.plexus.swop.schule", token: "plx_…" }
+   ```
+
+   or as environment variables `PLEXUS_ENV`, `PLEXUS_CONVEX_URL`, `PLEXUS_SITE_URL`,
+   `PLEXUS_TOKEN`, `PLEXUS_TENANT`.
+3. Check: `plexus-cli config show` (resolved connection, no network) and
+   `plexus-cli --env prod whoami` (who the token is).
+
+## Rules that always hold
+
+- **Name the environment on every write.** A writing command refuses without
+  `--env` on the command line, and production additionally needs `--allow-prod`.
+- **Plan before apply.** Every declarative change has a dry run — `offer plan`,
+  `catalog plan`, `config apply` without `--confirm`, a command's own `--dry-run`.
+  Read it, then apply the same input. Never apply what you did not plan.
+- **Export, edit, re-import — never retype live state.** `offer export` /
+  `config export` into a private scratch directory, edit there, `plan`, `apply`.
+  The live tenant is the source of truth; a file you keep is a copy.
+- **Fail loud means stop.** A refusal names its reason (`[area/code] …`); fix the
+  input. Do not work around it with `call`.
+- **Unsure what a command takes?** `plexus-cli <command> --help`; the callable
+  backend surface: `plexus-cli functions`, `plexus-cli describe <fn>`.
+
+## What a tenant token can do — and what it cannot
+
+A school's admin token reaches its own tenant and no other: admission offers
+(forms, workflows, tasks, letters bound to nodes, capacities, publishing), letter
+wording and the letter's salutation and sign-off, test applications, contract
+grants, the billing catalog, exports, prospects, and the tenant config of its own
+tenant — `config export`, `config targets`, `config set`, and `config apply
+--from snapshot:…` or `--from env:…`. Every config write needs the config right
+held tenant-wide. A change to the permission groups also needs the right to
+manage permissions, and a change to who sits in which group needs the right to
+manage users. The tenant admin holds all three.
+
+A tenant-scoped `config apply` or `config set` refuses (`FORBIDDEN`, naming the
+field) when the change would:
+
+- create a tenant, apply the built-in blueprint (the default without `--from`),
+  or delete anything (`--allow-destructive`);
+- change a `tenant.*` setting other than `branding`, `brandingAssets` and
+  `notificationChrome`, for example modules, the default applicant group, the mail
+  level, sign-in by link, or the terms;
+- change the import `source`;
+- name a user in `foundation.users` who is not already an active member of
+  this tenant with a login, so it never creates an account;
+- put a `_platform.*` right into a permission group.
+
+Copy those values unchanged from `config export`. Changing them is the operator's
+job.
+
+These need the **platform operator** (a `_platform.*` right). Ask them; do not
+try: creating, onboarding or wiping a tenant (`config wipe`, `config prune-offers`,
+`config apply --scope platform`), `offer hard-delete`, the settings listed above,
+the `branding …` and `files put|remove` commands (a school sets its branding and
+library files through `config apply` or in the app), issuing a token for someone
+else (`tokens create --for`), every `users` command except `users groups`
+(the school changes memberships in the app or through `foundation.users`), the mail
+delivery monitor (`notifications list|show|retry|self-test`), Stripe Connect and
+e-signature connections, contract resolvers (contract logic is platform code),
+retention runs, feedback triage, worker jobs and migrations. A command without
+the right answers with a refusal. It never makes a partial change.
+
+## Setting up a school
+
+The usual order, each step its recipe below:
+
+1. The operator creates the tenant, its config and the first admin
+   (`config/onboard-tenant.md`, `users/add-tenant-admin.md`) — Plattform.
+2. Offers: create the pedagogy unit and the offer, author the form, attach it to
+   the workflow, add the steps (decision, documents, tasks), set capacities —
+   `offer/…`. Validate offline with `offer validate --dir <bundle>` at any time.
+3. Letters: reword what the school sends (`notifications/reword-a-letter.md`).
+4. Try it: start and drive a test application
+   (`applications/start-a-test-application.md`, `test-actions/drive-a-test-application.md`).
+5. Publish (`offer/publish-offer-bundle.md`) — `offer plan` first.
+
+## References
+
+Recht: **Mandant** = a tenant admin's token suffices for every step ·
+**Mandant + Plattform** = the core works with the tenant token; the steps the recipe
+names as operator steps need the platform operator · **Plattform** = the recipe as a
+whole is the operator's (ask them; do not try).
+
+| Recipe | Recht | Purpose |
+|---|---|---|
+| [accounts/email-changes.md](references/accounts/email-changes.md) | Mandant + Plattform | See who changed an account's sign-in address (the tenant-wide view needs a platform admin for --user). |
+| [applications/inspect-process-store.md](references/applications/inspect-process-store.md) | Mandant | Show what an application's process produced and what it still waits for. |
+| [applications/start-a-test-application.md](references/applications/start-a-test-application.md) | Mandant | Start a test application in the terminal, drive it and discard it. |
+| [audit/answer-access-request.md](references/audit/answer-access-request.md) | Plattform | Answer an Art. 15 request: who looked at this application? |
+| [config/attach-a-template.md](references/config/attach-a-template.md) | Mandant + Plattform | Put a template into the file library and attach it to a form field (`files put` and `files remove` need the operator; a school adds the file through `config apply` or the app). |
+| [config/init-tenant.md](references/config/init-tenant.md) | Plattform | Generate and apply a minimal valid tenant config without an existing source. |
+| [config/onboard-tenant.md](references/config/onboard-tenant.md) | Plattform | Set up or refresh a real tenant's config from a snapshot or another environment. |
+| [config/rename-program-stage.md](references/config/rename-program-stage.md) | Mandant | Rename, add, reorder or retire a grade without losing applications. |
+| [config/set-tenant-branding.md](references/config/set-tenant-branding.md) | Mandant + Plattform | Give the application portal colours, radius and fonts; upload logo and WOFF2 fonts (the `branding …` commands need the operator; a school uses `config apply`). |
+| [config/set-tenant-terms.md](references/config/set-tenant-terms.md) | Plattform | Switch a school from „Bewerbung" to „Anmeldung" throughout with one setting. |
+| [config/set-up-billing-catalog.md](references/config/set-up-billing-catalog.md) | Mandant + Plattform | Load articles, packages, reduction tiers and Word templates by stable keys (catalog plan/apply). |
+| [config/update-tenant-config.md](references/config/update-tenant-config.md) | Mandant | Change the live config by export → edit → dry run → confirm. |
+| [config/wipe-tenant-config.md](references/config/wipe-tenant-config.md) | Plattform | Empty one config target, optionally with dependent data, or take a tenant down. |
+| [export/create-named-export.md](references/export/create-named-export.md) | Mandant | Create a reusable XLSX person export template. |
+| [feedback/create-and-triage-feedback.md](references/feedback/create-and-triage-feedback.md) | Plattform | File platform feedback, assign it, list it, and file it as a GitHub issue with its screenshot. |
+| [feedback/manage-feedback-tags.md](references/feedback/manage-feedback-tags.md) | Plattform | Maintain the feedback tag catalogue and tag many items at once. |
+| [finance/change-contract-grant.md](references/finance/change-contract-grant.md) | Mandant | Change a running contract's grants or reductions from a month on. |
+| [finance/record-submission-date.md](references/finance/record-submission-date.md) | Mandant | Record a missing historic submission date of a SEPA direct debit. |
+| [interessenten/list-interessenten.md](references/interessenten/list-interessenten.md) | Mandant | List a tenant's prospects. |
+| [notifications/debug-mail-delivery.md](references/notifications/debug-mail-delivery.md) | Plattform | Clear up a failed mail delivery: status, error code, self-test, retry. |
+| [notifications/mail-level.md](references/notifications/mail-level.md) | Plattform | Set whether a school sends families only sign-in links or all mail. |
+| [notifications/reword-a-letter.md](references/notifications/reword-a-letter.md) | Mandant + Plattform | Reword a school's letter per language and check the rendered letter. |
+| [notifications/trace-a-login.md](references/notifications/trace-a-login.md) | Plattform | Trace why someone could not sign in. |
+| [offer/add-workflow-node.md](references/offer/add-workflow-node.md) | Mandant | Insert a node (approval, form, contract, collectPayment, end …) into the workflow. |
+| [offer/addresses.md](references/offer/addresses.md) | Mandant | How a node reads by full address ($node…, $task…, $derived…, $env…), which flag sets which field, and the gate codes. |
+| [offer/appointment-task.md](references/offer/appointment-task.md) | Mandant | Give a booked appointment its appointment task (held by the host, due N days after the end). |
+| [offer/assignment-rule.md](references/offer/assignment-rule.md) | Mandant + Plattform | Change, test and publish who is responsible per slot; replace a person who leaves (`users unset-group` needs the operator; a school removes the membership in the app). |
+| [offer/attach-form-to-workflow.md](references/offer/attach-form-to-workflow.md) | Mandant | Bind an existing or new SmartForm to a form node. |
+| [offer/author-form-scenarios.md](references/offer/author-form-scenarios.md) | Mandant | Add a form's test scenarios and $env variables. |
+| [offer/author-manifest-meta.md](references/offer/author-manifest-meta.md) | Mandant | Set the manifest settings, role instances and services of an offer. |
+| [offer/author-smartform.md](references/offer/author-smartform.md) | Mandant | Build a SmartForm from scratch with the CLI and publish it. |
+| [offer/bind-node-input.md](references/offer/bind-node-input.md) | Mandant | Bind a node's input slot to an address, a literal or the default. |
+| [offer/completeness-check.md](references/offer/completeness-check.md) | Mandant | Wait for outstanding documents, with a deadline and a guest role. |
+| [offer/countersign-node.md](references/offer/countersign-node.md) | Mandant + Plattform | Add the school's countersignature of the contract (needs a sealed contract resolver). |
+| [offer/create-pedagogy-unit.md](references/offer/create-pedagogy-unit.md) | Mandant | Make a unit something families can apply to. |
+| [offer/declare-node-reads.md](references/offer/declare-node-reads.md) | Mandant + Plattform | Declare which form fields a document node reads and locks. |
+| [offer/edit-live-tenant-offer.md](references/offer/edit-live-tenant-offer.md) | Mandant + Plattform | Change a live offer: fresh export → change → plan → apply → plan shows all same (resolver and signing steps need the operator). |
+| [offer/edit-smartform.md](references/offer/edit-smartform.md) | Mandant | Change a SmartForm in detail (properties, order, English texts). |
+| [offer/edit-workflow-node.md](references/offer/edit-workflow-node.md) | Mandant | Rename, rewire, rebind or reroute a node. |
+| [offer/engage-push-node.md](references/offer/engage-push-node.md) | Mandant + Plattform | Insert the Engage transfer node that pushes an accepted application to Engage SMIS once. |
+| [offer/insert-and-rewire-node.md](references/offer/insert-and-rewire-node.md) | Mandant | Put a step onto exactly one edge and onto an existing board state. |
+| [offer/node-tasks.md](references/offer/node-tasks.md) | Mandant | Add, change or remove the tasks a node spawns: result kind, blockers, condition, evidence. |
+| [offer/optional-assessment.md](references/offer/optional-assessment.md) | Mandant | An optional assessment with files and an „Einschätzung einholen“ action. |
+| [offer/publish-offer-bundle.md](references/offer/publish-offer-bundle.md) | Mandant | Publish a bundle or stage it internally, and verify it is really live. |
+| [offer/set-offer-capacities.md](references/offer/set-offer-capacities.md) | Mandant | Maintain seat quotas per school year × grade in bundle.yaml. |
+| [offer/staff-input-if-node.md](references/offer/staff-input-if-node.md) | Mandant | A staff input plus an if node that branches on it. |
+| [offer/task-appointment-result.md](references/offer/task-appointment-result.md) | Mandant | A task that ends with an appointment (mail with .ics to the family). |
+| [offer/task-family-request.md](references/offer/task-family-request.md) | Mandant | A task asks the family for data and closes itself on the answer. |
+| [offer/task-result-files.md](references/offer/task-result-files.md) | Mandant | A task result with up to 20 files. |
+| [offer/template-document-node.md](references/offer/template-document-node.md) | Mandant | Produce a letter from a Word template with a template node. |
+| [offer/workflow-default-channels.md](references/offer/workflow-default-channels.md) | Mandant | Fixed team chat channels for every application of an offer. |
+| [resolver/manage-contract-resolver.md](references/resolver/manage-contract-resolver.md) | Plattform | Create, test, seal, assign and revise a contract resolver. |
+| [retention/erase-due-applications.md](references/retention/erase-due-applications.md) | Plattform | Erase applications past their retention period (retention plan/apply). |
+| [retention/erase-due-parties.md](references/retention/erase-due-parties.md) | Plattform | Hard-delete persons the school's deletion rule has reached (retention parties plan/apply). |
+| [roles/migrate-parent-assignments.md](references/roles/migrate-parent-assignments.md) | Mandant | Move direct assignments from a parent role onto a leaf role. |
+| [signing/README.md](references/signing/README.md) | Mandant | Send a contract revision for e-signature, reconcile, withdraw, remind (connecting the provider is Plattform). |
+| [signing/connect-a-school.md](references/signing/connect-a-school.md) | Plattform | Connect a school to its own DocuSign or inSign account. |
+| [signing/rotate-the-key.md](references/signing/rotate-the-key.md) | Plattform | Rotate the signing credentials key and reseal every connection. |
+| [stammdaten/purge-deleted-person.md](references/stammdaten/purge-deleted-person.md) | Plattform | Delete a soft-deleted person for good. |
+| [stripe/connect-a-school.md](references/stripe/connect-a-school.md) | Plattform | Connect a school to its own Stripe account. |
+| [stripe/request-and-verify-a-payment.md](references/stripe/request-and-verify-a-payment.md) | Mandant | Request a Stripe payment through call and follow it to succeeded (needs a connected school). |
+| [test-actions/drive-a-test-application.md](references/test-actions/drive-a-test-application.md) | Mandant | Play a test application through with test-mode actions. |
+| [users/add-platform-admin.md](references/users/add-platform-admin.md) | Plattform | Create a tenant-less platform admin with a login. |
+| [users/add-platform-user.md](references/users/add-platform-user.md) | Plattform | Create a platform user with limited _platform.* rights. |
+| [users/add-tenant-admin.md](references/users/add-tenant-admin.md) | Plattform | Create a ready admin login for a tenant and hand over the credentials. |
+| [users/change-login-email.md](references/users/change-login-email.md) | Plattform | Change an account's sign-in address. |
+| [users/cli-access-for-tenant-admin.md](references/users/cli-access-for-tenant-admin.md) | Mandant + Plattform | Give a school's administrator a CLI token for exactly their tenant (minting it themselves suffices; issuing it for them with `tokens create --for` needs the operator). |
+| [users/delete-permission-group.md](references/users/delete-permission-group.md) | Mandant | Delete an orphaned permission group. |
+| [users/grant-cross-tenant-access.md](references/users/grant-cross-tenant-access.md) | Plattform | Give every user of every tenant access to the test tenant. |
+| [users/grant-feedback-assignable.md](references/users/grant-feedback-assignable.md) | Plattform | Make a platform admin assignable for feedback. |
+| [users/set-password.md](references/users/set-password.md) | Plattform | Set or regenerate an existing user's password. |
+| [users/use-test-account.md](references/users/use-test-account.md) | Mandant + Plattform | Play a school's application process as an applicant with a test account. |
+| [worker-ops/debug-worker-jobs.md](references/worker-ops/debug-worker-jobs.md) | Plattform | Investigate and clean up stuck or failed imports and worker jobs. |
+| [worker-ops/verify-migrations.md](references/worker-ops/verify-migrations.md) | Plattform | Check after a deploy that the migrations ran (migrations status). |

package/dist/skill/references/accounts/email-changes.md

@@ -0,0 +1,46 @@
+# Read who changed a login address
+
+**When to use:** a school asks „wer hat die Anmelde-Adresse dieser Familie
+geändert?", a family says „ich bekomme keine Links mehr", a suspected takeover
+(someone signed in on an address staff set), or a data-subject request (Art. 15)
+about an address.
+
+Every change of a login address by someone other than the holder — staff in the
+Stammdaten, the platform operator — is one row in `account_email_changes`:
+when, which account, from → to, who, whether the old address was proven, and
+when the first session on the new address began. Read-only; the command never
+writes and needs no `--allow-prod`.
+
+## Steps
+
+```bash
+# 1. The school's own review: every change its staff made, newest first.
+#    Needs administration.users.manage in the tenant (a platform admin has it).
+plexus-cli --env <env> --tenant <slug> accounts email-changes
+
+# 2. Everything about ONE address — current, previous or new, all tenants,
+#    the operator's changes included (platform-admin). The data-subject view:
+#    the employee is shown as „Schule" / „Plattformbetrieb" — named only for an
+#    operator holding the opt-in right _platform.audit.readActor (misuse check).
+plexus-cli --env <env> accounts email-changes --user <email>
+```
+
+Columns: `at` · `account` (the address NOW; „(gelöscht)" when the account is
+gone, „(kein Zugang mehr)" in a school's view of an account that left it, masked
+after erasure) · `from` · `to` · `by` · `oldProven` · `firstSession` (the first sign-in
+after the change, `—` if none yet) · `redacted` (`ja` = the account's last
+application in that school was erased, or the change is older than 180 days;
+addresses are masked, the rest is kept).
+
+## Verify
+The same changes are on the application timeline as „Anmelde-Adresse geändert"
+and „Erste Anmeldung nach Adressänderung" (cockpit → Aktivitäten), and in the
+UI: Administration → „Anmelde-Adressen" (school), Plattform → Benutzer (all).
+
+## Gotchas
+- Only third-party changes are rows. A visitor adopting the address they typed,
+  or a staff member changing their OWN address, leaves none.
+- An operator change has no tenant: step 1 does not show it, step 2 does.
+- After masking (erasure, or 180 days) the addresses are `f…@…`, so `--user`
+  with the OLD address no longer finds the row; the account's current address
+  still does.

package/dist/skill/references/applications/inspect-process-store.md

@@ -0,0 +1,61 @@
+# Inspect an application's process store
+
+**When to use:** see what the process of ONE application has produced and what it is still
+waiting for — a form instance, a document, a contract with its current revision, a payment,
+a value a task wrote (`$task.<task>.<key>`), a derived price (`$derived.<key>`) and the
+application's facts (`$env.applicant.language`). Typical questions: why a contract input is
+empty, why a price „wartet", which revision a contract node points at, whether a task value
+counts after a re-open. Replaces raw `call processStoreView:get`.
+
+## Prerequisites
+- `--tenant`; the token's user holds `bewerbungsmanagement.applications.manage` (the query is
+  staff-only: it shows every value whatever its `audience`).
+- The application id (`applications list --offer <slug>`).
+- Read-only: no `--env` guard, works against prod with the usual token.
+
+## Steps
+```bash
+E="--env staging --tenant test"
+
+# One row per address: state, what it holds, producing node, when written.
+plexus-cli $E applications store <applicationId>
+
+# The same as JSON, keyed by the canonical address — the shape the cockpit's
+# „Prozessdaten" block (Graph tab, manage grant) shows.
+plexus-cli $E applications store <applicationId> --json
+```
+
+## Reading it
+- **Every address of the PINNED graph** is listed — the application's own version, not the
+  live head: `$node.<node>.<key>` for each node result, `$task.<task>.<key>` for each value a
+  task writes, `$derived.<key>` for each derived price, then `$env.*`.
+- **State is resolved, never the newest row:**
+  - `present` — the producer's result; for a task value the entry of the task row that is
+    currently effective (`writtenByTaskId`, `writtenAt`); for a price the computed value.
+  - `pending` — not there yet. A task value or a price names the reason („… ist noch offen",
+    „… ist noch nicht erreicht"); a `$node` result that its node has not written yet has none.
+    A form instance in `draft` is `present` with `state: draft`.
+  - `absent` — none is coming: the writing task is not owed (its condition is false), or the
+    application has no applicant account (`$env.applicant.language`).
+- **Refs are resolved live:** `form` → instance and its state; `document` → the slot and its
+  newest file; `contract` → contract id, current revision (`revisionNumber`) and
+  `contractStatus` (`signed` / `inSignature` / `withdrawn` / `draft` / `active`, derived in that precedence).
+
+## Verify
+- A completed store-writing task shows `present` with its `writtenByTaskId`; re-open it and
+  the address turns `pending` — the old entry stays as history but no longer counts.
+
+## Gotchas
+- **Never hand the output to the family.** It carries internal values (a need-based tier,
+  a reduction) that no family surface shows.
+- **A redacted application is refused** („Die Daten dieser Bewerbung wurden gelöscht.") —
+  its process data are deleted; the view never answers with an empty store.
+- **Texts are German** (reasons, producer labels) — they are the resolvers' own texts.
+- **Forbidden** for a member with only `applications.read`: the view needs the manage grant.
+- A `bug` naming `[process]` (a ref whose target is gone, a done task without its entry) is a
+  data defect, not a display problem — report it to the platform operator with the
+  application id and the address.
+
+## Related
+- [Start a test application and drive it end to end](./start-a-test-application.md)
+- [Addresses in a workflow](../offer/addresses.md) — what the addresses mean and who may read them

package/dist/skill/references/applications/start-a-test-application.md

@@ -0,0 +1,66 @@
+# Start a test application and drive it end to end
+
+**When to use:** check an offer from the terminal the way a family would go through it —
+start a test application, load a form scenario and submit, run the next step's actions,
+look at the result, throw the application away. Replaces raw `call
+admission:staffStartApplicationForParty` / `workflow:runTestAction` / `admission:discardTest`.
+
+## Prerequisites
+- `--env` named on the command line for every writing verb (`start-test`, `discard-test`,
+  `test-actions run`) — the configured default is not enough. Prod additionally needs
+  `--allow-prod`, and there a test application starts only for the tenant's test account
+  (`test@example.com`, see [Use a tenant's test account](../users/use-test-account.md)).
+- `--tenant`; the token's user holds `bewerbungsmanagement.applications.manage` and
+  `bewerbungsmanagement.testActions.run` — the server asks for both to start in test mode,
+  and the second for every test action.
+- The applicant: an existing account of this school (`--applicant <login address>`) or its
+  party id (`--party`). Creating an account has no verb (it needs the cockpit's password flow).
+- School year and level by **key or id** — never by name (`applications start-test` lists
+  both when one does not match).
+
+## Steps
+```bash
+E="--env staging --tenant test"
+
+# 1. Start (always test mode); prints the application id and what test mode offers now.
+plexus-cli $E applications start-test --offer grundschule-havelland \
+  --run <runKey|runId> --stage klasse-1 --applicant test@example.com
+#    An offer that declares staff inputs needs each one, once:
+#      --staff-input staffApplication=false   (see ../offer/staff-input-if-node.md)
+
+# 2. Load a scenario and submit (file fields are stubbed first; runs asynchronously).
+plexus-cli $E test-actions run --application <id> --action load-scenario:standard
+
+# 3. See where it stands and what the next node offers; run an action there.
+plexus-cli $E applications show <id>
+plexus-cli $E test-actions list --application <id>
+plexus-cli $E test-actions run --application <id> --action takeResponsibility
+
+# 4. Throw it away.
+plexus-cli $E applications discard-test <id>
+```
+
+Reading verbs (no `--env` needed beyond the usual resolution):
+```bash
+plexus-cli $E applications list --offer grundschule-havelland [--test-only]
+plexus-cli $E applications counts --offer grundschule-havelland
+```
+
+## Verify
+- `applications show <id>` prints `test: ja`, the current nodes and the status.
+- After step 2, `test-actions list` shows the next node's actions (the submit lands a moment
+  after `run` returns — file fills are a scheduled action).
+- After step 4, `applications list --offer … --test-only` no longer lists it.
+
+## Idempotency / gotchas
+- `start-test` creates a new application on every call; `discard-test` on a real application
+  is refused by the server.
+- `--run`/`--stage` match a key or an id only; a display name is refused with the list of
+  what exists. A closed school year is refused.
+- Without `--version` the application runs on the offer's live generation (as in the cockpit).
+- On prod: `--allow-prod`, and only `--applicant test@example.com` — a test run must never land
+  in a real family's portal.
+
+## Related
+- [Drive a test application through test mode](../test-actions/drive-a-test-application.md) ·
+  [Author a form's test scenarios](../offer/author-form-scenarios.md)

package/dist/skill/references/audit/answer-access-request.md

@@ -0,0 +1,115 @@
+# Answer a data-subject access request: who viewed this application?
+
+**When to use:** an applicant (or their parent) asks *"who looked at my child's
+application, and when?"* — an Art. 15 DSGVO request — and you must produce the
+privileged-access report for one application. Also the starting point for an
+anlassbezogene misuse check ("what did this employee open?").
+
+> The report answers **"who opened the applicant-portal view of this application"**,
+> plus platform-operator tenant entries and reads of the log itself. It is **not** a
+> complete record of everyone who read the data — ordinary cockpit reads are
+> deliberately not logged (a documented Abwägung in the platform's
+> Protokollierungskonzept, § 3 — the platform operator provides it).
+> Never phrase an answer as "nobody accessed your file" on the strength of an empty
+> report.
+
+## Prerequisites
+- `plexus-cli --env staging|prod|local` configured with a **platform-operator** token;
+  the audit rights are `_platform.*`, so a tenant admin token cannot run this.
+- `_platform.audit.read` — the default, identity-free report.
+- `_platform.audit.readActor` — **only** for `--with-actor` / `--actor`. It is an
+  **opt-in** right, deliberately excluded from the default full-admin grant; grant it
+  with
+  `plexus-cli --env <env> users set-platform-permission <email> --permission _platform.audit.readActor --on`.
+- The **application id** (`j…` Convex id). Two ways to get one:
+  - from the cockpit URL of the Vorgang, or
+  - `plexus-cli --env <env> call admission:list client=<slug> paginationOpts='{"numItems":25,"cursor":null}' --json`
+    (needs `bewerbungsmanagement.applications.read` in that tenant — a
+    `_platform.tenants.accessAll` operator has it).
+
+## Steps
+```bash
+# 1. The answer the data subject is owed: date + purpose, NO employee named.
+plexus-cli --env prod audit access --allow-prod --application <applicationId>
+
+# 1a. Same report as machine-readable evidence for the file.
+plexus-cli --env prod audit access --allow-prod --application <applicationId> --json
+```
+
+Only where naming the employee is genuinely required (internal misuse check, works
+council / DSB escalation — not the default answer to the applicant):
+
+```bash
+# 2. Same rows, with the acting employee's email. Needs _platform.audit.readActor.
+plexus-cli --env prod audit access --allow-prod --application <applicationId> --with-actor
+
+# 3. The other direction: what did this employee access in this tenant?
+plexus-cli --env prod audit access --allow-prod --actor <employee-email> --tenant <slug>
+```
+
+**Also owed in the same answer — changes of the person's login address.**
+If staff or the operator ever changed the address the person signs in with, that
+is personal data about them too. It is read-only; unlike step 1 this read is not
+recorded as `audit_read` (Protokollierungskonzept § 12):
+
+```bash
+# 4. Every change naming the address the person gives you (current or old).
+#    The employee is shown as „Schule" / „Plattformbetrieb" — like step 1;
+#    named only with _platform.audit.readActor.
+plexus-cli --env prod accounts email-changes --user <their-address>
+```
+Recipe and columns: [`accounts/email-changes.md`](../accounts/email-changes.md).
+
+Output columns: `at` (ISO timestamp) · `purpose` (fixed German purpose text per
+event type) · `actor` (only in the `readActor` projections).
+
+## Verify
+```bash
+# The read you just performed is ITSELF logged as an `audit_read` row (M43.21.06).
+# It shows up under YOUR account, not under the application:
+plexus-cli --env prod audit access --allow-prod --actor <your-operator-email> --tenant <slug>
+```
+Expect one `audit_read` row ("Auskunft und Kontrolle: Einsicht in dieses
+Zugriffsprotokoll") per report you ran. Needs `_platform.audit.readActor`; without it,
+take the absence of an error on step 1 as the confirmation.
+
+## Idempotency / gotchas
+- **These commands WRITE.** Every projection is a Convex *mutation*, because each read
+  of the log records an `audit_read` row in the same transaction. Running the report
+  five times to "just check" leaves five rows on prod. It is not a read-only probe.
+- **Pass exactly one of `--application` / `--actor`.** Passing both or neither fails
+  loud (`plexus audit access: pass exactly one of --application <id> or --actor <email>.`)
+  rather than silently preferring a mode — the two answer different questions and
+  carry different rights.
+- **`--actor` is tenant-scoped and needs a tenant**: `--tenant <slug>`, else
+  the configured default tenant / `PLEXUS_TENANT`; without any of them it fails
+  loud. The underlying index is cross-tenant, so scoping is what stops one query from
+  returning every tenant's records.
+- **An unknown `--actor` email throws** (`No Plexus identity for "…"`). It never
+  returns an empty list — "this person accessed nothing" is the one answer an
+  accountability search must not invent for an address it simply does not know.
+- **The per-application report only ever contains portal views.** `operator_entry` and
+  `audit_read` rows carry no application by design; they surface only via `--actor`.
+- **Truncation is announced, not hidden.** The report caps at 500 rows (the actor
+  search additionally scans at most 4 000 rows); a cut-off prints
+  `warning: the report was truncated — older rows are not shown.` to **stderr** (so it
+  never pollutes `--json` stdout). Treat a truncation warning as "this answer is
+  incomplete", not as a formatting detail.
+- **Retention is 180 days.** Access rows older than that are gone, and all rows for an
+  application are deleted when that application is redacted/erased. An empty report may
+  simply mean the accesses aged out — say so in the answer instead of implying nobody
+  looked.
+- **Do not hand `--with-actor` output to the data subject by default.** The identity of
+  the individual staff member is generally not part of what Art. 15 owes (CJEU
+  *Pankki S*, C-579/21); the default projection exists precisely so the standard answer
+  omits it. See § 7 of the Protokollierungskonzept before disclosing a name.
+- On a local development deployment the seeded tenant (`test`) will normally have
+  no access rows at all.
+
+## Related
+- Concept + legal reasoning (the primary compliance artefact): the platform's
+  Protokollierungskonzept — ask the platform operator.
+- Granting the opt-in actor right: [Add a platform user](../users/add-platform-user.md) ·
+  [Make a platform admin assignable to feedback](../users/grant-feedback-assignable.md)
+  (same `users set-platform-permission` mechanism).
+- Command reference: `plexus-cli audit access --help`.

package/dist/skill/references/config/attach-a-template.md

@@ -0,0 +1,117 @@
+# Attach a blank template (Vorlage) to a form field
+
+**When to use:** a school wants to offer a blank document on an upload field — a
+reference form, a GDPR consent, a health record — that the family downloads,
+fills in or signs, and uploads back at the same field. Or a template changed and
+every form that offers it should show the new version.
+
+The file lives in the tenant's **file library** (`tenant_files`, UI: Daten →
+Dateien) under a stable **key**. A form field names the key only; label, file
+name and type are read from the library. Replacing the file (same key) updates
+every form at once — no republish.
+
+## Prerequisites
+
+- `plexus-cli` installed; a platform-admin token with `_platform.config.manage`
+  for the target env (listing needs `_platform.config.read`).
+- The `files` commands and the `fileKey` attachment shape must be **live** on
+  the target env before an offer that uses them is published (a platform
+  operator rolls a release out to staging, then prod). An offer published before
+  that fails with `[config.attachment-source]` or `[form.unknown-attachment-file]`.
+- Allowed types: PDF, DOCX, DOC, ODT, XLSX, JPG, PNG; max 20 MB.
+
+## Steps
+
+1. **Put the file into the library** (create — a new key needs `--label` AND
+   `--label-en`: the label is shown in the reader's language):
+
+   ```bash
+   plexus-cli --env staging --tenant test files put referenzformular ./Referenzformular.pdf \
+     --label "Vorlage: Referenzformular" --label-en "Template: reference form"
+   ```
+
+   `put` on an existing key **replaces** the file (keeps the key and the label
+   unless `--label` / `--label-en` is given). `--label-en` alone translates the
+   stored German; a German change over a real English is refused without
+   `--label-en`. Identical bytes and label are a no-op.
+
+2. **Attach it to the field** in the offer bundle — a fresh export of the live
+   offer in a scratch directory of your own (production is the source of truth
+   for a real tenant's offer, so always start from a fresh export; see
+   [edit-live-tenant-offer](../offer/edit-live-tenant-offer.md)):
+
+   ```bash
+   WORK=$(mktemp -d)   # a scratch directory
+   plexus-cli --env prod --tenant <slug> offer export --slug <offer-slug> --out $WORK/<offer-slug>
+   plexus-cli offer form field attach --dir $WORK/<offer-slug> \
+     --key kind.referenz --file-key referenzformular
+   # an inline link in the label instead of a download chip:
+   #   --render inlineLink --label "Referenzformular"
+   ```
+
+3. **Validate and publish** the bundle as usual (`offer validate`, `offer plan`,
+   `offer apply --publish`). Publish checks the key against the target tenant's
+   library.
+
+## Declarative path (config-as-code)
+
+The library is part of the tenant config (`files`):
+
+```jsonc
+"files": [
+  {
+    "key": "referenzformular",
+    "label": { "de": "Vorlage: Referenzformular" },
+    "filename": "Referenzformular.pdf",
+    "mimeType": "application/pdf",
+    "sha256": "…",          // recomputed from `path` by the CLI
+    "sizeBytes": 48213,      // recomputed from `path` by the CLI
+    "path": "files/referenzformular/Referenzformular.pdf"
+  }
+]
+```
+
+- `config export` downloads every file to `files/<key>/<filename>` beside
+  `config.json` and writes `path`. Swap a file on disk and `config apply --from
+  snapshot:…` uploads it (the file on disk decides the hash).
+- `apply` uploads **only** files whose hash the target does not hold; a dry run
+  uploads nothing and lists them as `~ file files/<key>`.
+- A file absent from `files` is reported as an **orphan** (`- orphan
+  foundation/tenant_files`) and removed only with `--allow-destructive` — then
+  still refused with `[file/inUse]` while any form version (archived included)
+  names it. A file uploaded on the Daten page is therefore never lost to an
+  older snapshot.
+- A dry run also names changed files whose bytes the source cannot supply
+  (`NO bytes in this source`) — the commit would fail `[file/contentMissing]`.
+- `--from env:<src>` downloads changed files from the source env and uploads them
+  to the target.
+
+## Verify
+
+```bash
+plexus-cli --env staging --tenant <slug> files list      # key, file, sha256, usedBy
+```
+
+Open a draft application on the portal: the field shows a „Vorlage …" download
+chip (or, for a document field, a „Vorlage" button inside the upload box). A
+key the library no longer holds renders as **„Vorlage fehlt (<key>)"** — never
+as a missing chip.
+
+## Gotchas
+
+- **Remove:** `plexus-cli files remove <key>` is refused while a form uses the
+  key; the error names `offer rN (status) / form / field` for each use. Detach
+  first (`offer form field detach --key … --file-key …`), republish, and note that
+  **archived** offer versions still count — applications pin them.
+- Replacing or removing a file deletes its previous bytes in the same step (a
+  blank template has no audit value; the family's signed upload is the record).
+  Exception: a file the migration adopted from an old form attachment shares its
+  bytes with a document template (`ownsStorage: false`) — those go only once no
+  document template, resolver pin or template run of the tenant names them.
+- The raw `storageId` attachment shape is retired; a stale bundle carrying one
+  fails publish with `[config.attachment-source]` naming the fix.
+
+## Related
+
+- UI: Daten → Dateien (upload, replace, delete).
+- [Update a tenant's config](./update-tenant-config.md).